Início › Documentação › App do LB Phone · origen_billing

App do LB Phone · origen_billing

origen_billingapp é a aplicação complementar do LB Phone para o origen_billing. Oferece uma experiência de faturação completa diretamente no telemóvel, sem necessidade de comandos.

Dependências

Instalação

1. server.cfg

Adiciona origen_billingapp depois de origen_billing e lb-phone:

ensure lb-phone
ensure origen_billing
ensure origen_billingapp

2. Idioma

Abre config.lua e define o idioma. Tem de corresponder a um ficheiro em locales/:

Config.Language = 'en'  -- 'en' | 'es'

Como funciona

A app regista-se no LB Phone quando o recurso arranca e volta a registar-se automaticamente se o lb-phone for reiniciado. A interface comunica exclusivamente através de callbacks NUI → eventos do servidor → exports de telemóvel do origen_billing → evento do cliente que devolve a resposta à interface do telemóvel.

UI (NUI)
  └─▶ NUI Callback (client.lua)
        └─▶ Server Event (origen_billingapp:server:*)
              └─▶ origen_billing Phone Export
                    └─▶ TriggerClientEvent → origen_billingapp:client:response
                          └─▶ exports['lb-phone']:SendCustomAppMessage

Não há lógica de negócio no origen_billingapp. É uma ponte pura.

Funcionalidades por função

Todos os jogadores: As minhas faturas

• Ver todas as faturas pendentes (pagamento por banco + numerário)
• Pagar uma fatura diretamente a partir do telemóvel
• Receber uma notificação push quando chega uma fatura nova

Funcionários (jobs autorizados)

• Consultar o catálogo de produtos do seu job
• Enviar uma fatura nova a um jogador próximo (valor manual ou a partir do catálogo)

Chefes

• Lista paginada de faturas da empresa com pesquisa e filtros (estado, intervalo de valores, intervalo de datas)
• Cancelar qualquer fatura da empresa
• Estatísticas da empresa (total, pendentes, pagas, canceladas, receitas, comissões, média)
• Painel com KPI e um gráfico de série temporal diária para um intervalo de datas personalizado
• Gestão completa de produtos: criar, editar, ativar/desativar, eliminar

Exports de telemóvel (origen_billing)

A app usa os seguintes exports registados no origen_billing. Também podem ser chamados a partir de outros recursos.

GetPhoneAppBootstrap(source) → table

Carrega numa só chamada todos os dados necessários para abrir a app. Devolve permissões, faturas pendentes, produtos do catálogo e, para os chefes, faturas da empresa, estatísticas e produtos.

local data = exports['origen_billing']:GetPhoneAppBootstrap(source)
-- {
--   success         = true,
--   permissions     = { canInvoice, isBoss, jobName, jobLabel },
--   myInvoices      = { ... },
--   catalogProducts = { ... },
--   companyInvoices = { ... },  -- nil if not boss
--   companyMeta     = { page, pageSize, total, totalPages },
--   companyStats    = { ... },
--   companyProducts = { ... },
-- }

GetPhonePermissions(source) → table

Devolve as permissões atuais do jogador. É chamada quando o job do jogador muda.

local res = exports['origen_billing']:GetPhonePermissions(source)
-- { success = true, permissions = { canInvoice, isBoss, jobName, jobLabel } }

GetPhoneMyInvoices(source) → table

Devolve as faturas pendentes do jogador.

local res = exports['origen_billing']:GetPhoneMyInvoices(source)
-- { success = true, invoices = { ... } }

PayPhoneInvoice(source, invoiceId, paymentMethod) → table

Paga uma fatura. paymentMethod é 'bank' ou 'cash'.

local res = exports['origen_billing']:PayPhoneInvoice(source, 12, 'bank')
-- { success = true|false, reason = 'error_code' }

GetPhoneProducts(source) → table

Devolve o catálogo de produtos ativos do job do jogador.

local res = exports['origen_billing']:GetPhoneProducts(source)
-- { success = true, products = { { id, name, description, price }, ... } }

SendPhoneInvoice(source, payload) → table

Cria uma fatura a partir do telemóvel. payload.items é opcional: se for omitido, cria-se uma fatura de uma só linha a partir de payload.amount e payload.description.

local res = exports['origen_billing']:SendPhoneInvoice(source, {
    targetId    = 'ABC12345',
    amount      = 500,
    description = 'Service fee',
    notes       = '',
    items       = {
        { name = 'Oil change', price = 150, quantity = 1, product_id = 5 },
    },
})
-- { success = true, invoiceId = 42 }

GetPhoneCompanyInvoicesPage(source, filters) → table

Devolve uma lista paginada e filtrada de faturas da empresa. Apenas chefes.

local res = exports['origen_billing']:GetPhoneCompanyInvoicesPage(source, {
    search    = 'John',
    status    = 'pending',  -- 'all' | 'pending' | 'paid' | 'cancelled'
    minAmount = 100,
    maxAmount = 1000,
    dateFrom  = '2025-01-01',
    dateTo    = '2025-12-31',
    page      = 1,
    pageSize  = 10,
})
-- { success, invoices, meta = { page, pageSize, total, totalPages }, stats = { ... } }

GetPhoneCompanyStats(source) → table

Devolve as estatísticas globais da empresa do jogador. Apenas chefes.

local res = exports['origen_billing']:GetPhoneCompanyStats(source)
-- { success, stats = { total, pending, paid, cancelled, totalSociety, totalCommissions, avgAmount } }

GetPhoneCompanyDashboardLite(source, dateFrom, dateTo) → table

Devolve KPI e uma série temporal diária para um intervalo de datas. Apenas chefes.

local res = exports['origen_billing']:GetPhoneCompanyDashboardLite(source, '2025-01-01', '2025-01-31')
-- {
--   success    = true,
--   kpis       = { total, pending, paid, cancelled, totalRevenue, totalSociety, totalCommissions, avgAmount },
--   timeSeries = { { day, totalAmount, paidAmount }, ... },
-- }

CancelPhoneCompanyInvoice(source, invoiceId) → table

Cancela uma fatura da empresa. Quem chama tem de ser chefe do job que a emitiu.

local res = exports['origen_billing']:CancelPhoneCompanyInvoice(source, 42)
-- { success = true|false, reason = 'error_code' }

GetPhoneCompanyProducts(source) → table

Devolve todos os produtos da empresa do jogador (incluindo os inativos). Apenas chefes.

local res = exports['origen_billing']:GetPhoneCompanyProducts(source)
-- { success, products = { { id, name, description, price, active, created_at }, ... } }

CreatePhoneCompanyProduct(source, data) → table

Cria um produto novo para a empresa. Apenas chefes.

local res = exports['origen_billing']:CreatePhoneCompanyProduct(source, {
    name        = 'Oil change',
    description = 'Full synthetic',
    price       = 150,
})
-- { success = true, productId = 7 }

UpdatePhoneCompanyProduct(source, data) → table

Atualiza um produto existente. Apenas chefes.

local res = exports['origen_billing']:UpdatePhoneCompanyProduct(source, {
    id          = 7,
    name        = 'Oil change (premium)',
    description = 'Full synthetic + filter',
    price       = 200,
})
-- { success = true|false }

TogglePhoneCompanyProduct(source, productId) → table

Alterna um produto entre ativo e inativo. Apenas chefes.

local res = exports['origen_billing']:TogglePhoneCompanyProduct(source, 7)
-- { success = true, active = false }

DeletePhoneCompanyProduct(source, productId) → table

Elimina um produto de forma permanente. Apenas chefes.

local res = exports['origen_billing']:DeletePhoneCompanyProduct(source, 7)
-- { success = true|false }