## 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:

| Agrupamento | O que traz |
|---|---|
| Total por moeda | Receita total em R$ por moeda — **nunca soma moedas diferentes** |
| Por origem | Receita por `source` do pedido: `manual`, `webhook`, `api`, `payments`, `commerce` |
| Por gateway | Receita por gateway de dinheiro (asaas, mercado_pago, hotmart, nativo, catálogo…) |
| Por vendedor | Receita por dono do pedido (o vendedor creditado) |
| Por afiliado | Receita por afiliado atribuído (atribuição dupla) |

### 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:

| `unified_revenue_ledger` | `orders_registry` | Quem credita | Resultado |
|---|---|---|---|
| Desligado | qualquer | Caminho legado (cobrança/comércio) | idêntico ao anterior |
| Ligado | Ligado | `order.paid` (o pedido) — legado suprimido | uma vez, no pedido |
| Ligado | Desligado | Legado (nenhum pedido é produzido) | uma vez, na cobrança/comércio |

### 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:

| Modo | O que faz |
|---|---|
| `off` (padrão) | Nenhum crédito automático — a venda externa fica sem vendedor até uma atribuição manual |
| `last_conversation` | Credita o agente que atendeu o comprador por último (a última conversa do contato) |
| `distribution` | Credita conforme as regras de distribuição ativas (as mesmas da distribuição de leads) |

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](/hc/ajuda/articles/sales-gamification-affiliate-program-pt-br)
- [Painéis e relatórios de vendas](/hc/ajuda/articles/sales-gamification-paineis-e-relatorios-de-vendas-pt-br)
- [Visão geral de Vendas e Gamificação](/hc/ajuda/articles/sales-gamification-overview-pt-br)