Ledger unificado de receita: contagem única de vendas por origem, gateway, vendedor e afiliado

Visão geral

O ledger unificado de receita é o registro nativo, em R$, de toda venda paga — não importa a origem. Uma cobrança paga na conversa, um pedido de catálogo do WhatsApp, uma venda do Hotmart, um pedido manual ou um pedido via API convergem para um único pedido canônico (o registro de pedidos do CRM). No momento em que esse pedido é pago, a Conversa Labs credita o vendedor (dono do pedido) uma única vez: pontos de gamificação, comissão e a receita que aparece no relatório.

Antes disso, cada caminho de dinheiro creditava de forma diferente (ou não creditava): uma venda de catálogo ou do Hotmart podia não render pontos nem comissão a ninguém, enquanto uma cobrança creditava o autor. O ledger unificado resolve isso com um único eixo de receita e contagem exatamente uma vez — a mesma venda nunca é contada em dobro.

Pré-requisitos

• Módulo Vendas & Gamificação habilitado na conta.
• Recurso unified_revenue_ledger ativado na conta (é dark-ship, padrão desligado — o operador ativa). Com ele desligado, o comportamento é idêntico ao anterior.
• Registro de pedidos do CRM (orders_registry) ativado para que cobranças e pedidos de comércio também convirjam ao pedido único — é o que suprime o crédito legado e garante a contagem única.
• Permissão de gestão de vendas (sales_manage) — ou administrador — para ler o ledger e exportar.
• Vendas pagas reais fluindo (cobranças, catálogo, Hotmart, pedidos manuais), para haver o que contabilizar.

Passo a passo

1. Ative o recurso unified_revenue_ledger (e o orders_registry) na conta.
2. Garanta vendas fluindo por qualquer origem — a convergência é automática pelos alimentadores de pedido.
3. Abra a visão de Receita no painel/TELÃO de Vendas.
4. Escolha o período (o padrão são os últimos 30 dias).
5. Leia os agrupamentos — total por moeda, por origem, por gateway, por vendedor e por afiliado.
6. Exporte em CSV para conciliar a receita fora da plataforma.

Configurações & opções

O que o ledger agrupa

Sobre os pedidos pagos do período (por paid_at), a receita é somada e agrupada:

Contagem exatamente uma vez (sem duplicidade)

O crédito acontece no eixo do pedido quando existe um pedido, e no caminho legado apenas quando nenhum pedido é produzido:

Atribuição do vendedor (fallback)

O dono do pedido é resolvido em cascata: negócio → contato → responsável → criador. Uma cobrança sem negócio ainda atribui ao usuário que a criou (campo de criador na cobrança), então nenhuma venda paga fica "sem dono".

Atribuição de vendas externas ao vendedor

Vendas externas (catálogo, Hotmart, Kiwify e outros gateways) chegam a partir do gateway e, muitas vezes, para um contato comprador que não está na carteira de ninguém. Sem uma regra, essa venda paga ficaria "sem vendedor". A configuração por conta external_attribution_mode decide como o vendedor é resolvido automaticamente nesse caso:

Quando o modo resolve um vendedor, a carteira do comprador é reivindicada de forma durável para esse vendedor — assim, as próximas vendas do mesmo contato já entram com dono. O padrão é off: nenhum crédito automático até você escolher explicitamente last_conversation ou distribution.

Reatribuição manual do vendedor. Um gestor (permissão de gestão de vendas) pode, a partir do pedido, vincular uma venda externa a um vendedor ou mover o crédito entre agentes. A troca reverte os pontos e a comissão do dono anterior e credita o novo dono; o crédito do afiliado não é afetado. Deixar o vendedor em branco desvincula o pedido. Toda mudança é auditada (evento order_reattributed), preservando o histórico de quem foi creditado e por quê.

Estorno (clawback)

Quando um pedido é estornado, o crédito é revertido na origem do pedido — para o vendedor e para o afiliado —, mantendo o ledger fiel ao dinheiro efetivamente recebido.

Exportação CSV

Uma linha por pedido pago, com as colunas: order_id, paid_at, source, gateway, owner_id, affiliate_id, amount, currency. Os valores estão em unidades maiores (ex.: 4970.50 = R$ 4.970,50).

Permissões e visibilidade

• Ler o ledger e exportar exigem a permissão de gestão de vendas.
• A leitura respeita o isolamento por vendedor: sob carteira/privacidade, um gestor vê apenas a sua cascata; um vendedor, apenas a própria carteira.

Casos de uso

• O gestor lê a receita em R$ por vendedor para reconhecer quem mais vendeu no período.
• O financeiro exporta o CSV para conciliar a receita paga com o extrato de comissões.
• A liderança compara a receita por origem (Hotmart × catálogo × cobrança) e por gateway.
• A receita por afiliado alimenta o acompanhamento do programa de afiliados (atribuição dupla).

Dicas, limites e boas práticas

• O dinheiro está em unidades maiores (decimal), a mesma convenção de Pagamentos/Catálogo — nunca divida por 100.
• O ledger nunca soma moedas diferentes: cada moeda é uma linha.
• Ativar o recurso credita as vendas daqui para frente — não há reprocessamento retroativo automático. Para reprocessar histórico do Hotmart, use o backfill do operador.
• Ative ambos os recursos (unified_revenue_ledger + orders_registry): é essa combinação que suprime o caminho legado e evita a contagem em dobro.

Solução de problemas

• Ledger vazio: não há pedidos pagos no período, ou o recurso está desligado. Confirme a ativação e a existência de vendas pagas.
• Números em dobro: o orders_registry provavelmente está desligado, então o caminho legado e o do pedido creditam juntos. Ative o registro de pedidos.
• Vendedor aparece como nulo: o pedido não teve dono resolvido (sem negócio, contato, responsável ou criador). Verifique a atribuição na origem.
• Venda externa sem vendedor ou creditada ao vendedor errado: se external_attribution_mode está off, vendas externas ficam sem dono — escolha last_conversation ou distribution, ou faça a reatribuição manual (gestão de vendas) a partir do pedido.
• Estorno não refletido: o evento de estorno do pedido não foi disparado. Confirme o fluxo de reembolso no gateway/Pagamentos.
• Exportação bloqueada: falta a permissão de gestão de vendas. Peça a um administrador.

Veja também

• Programa de afiliados: atribuição dupla, comissão e portal
• Painéis e relatórios de vendas
• Visão geral de Vendas e Gamificação