## Visión general

El **ledger unificado de ingresos** es el registro nativo, en R$, de **toda** venta pagada — sin
importar el origen. Un cobro pagado en la conversación, un pedido de catálogo de WhatsApp, una venta de
Hotmart, un pedido manual o un pedido vía API convergen a **un único pedido canónico** (el registro de
pedidos del CRM). En el momento en que ese pedido se paga, Conversa Labs acredita al **vendedor (dueño del
pedido) una sola vez**: puntos de gamificación, comisión y los ingresos que aparecen en el informe.

Antes de esto, cada camino de dinero acreditaba distinto (o no acreditaba): una venta de catálogo o de
Hotmart podía no dar puntos ni comisión a nadie, mientras que un cobro acreditaba a su autor. El ledger
unificado lo resuelve con **un único eje de ingresos** y **conteo exactamente una vez** — la misma venta
nunca se cuenta dos veces.

## Requisitos previos

- Módulo **Ventas y Gamificación** habilitado en la cuenta.
- Recurso **`unified_revenue_ledger`** activado en la cuenta (es dark-ship, por defecto **apagado** — el
  operador lo activa). Con él apagado, el comportamiento es idéntico al anterior.
- **Registro de pedidos del CRM** (`orders_registry`) activado para que cobros y pedidos de comercio
  también converjan al pedido único — es lo que suprime la acreditación heredada y garantiza un conteo
  único.
- Permiso de **gestión de ventas** (`sales_manage`) — o administrador — para leer el ledger y exportar.
- **Ventas pagadas reales fluyendo** (cobros, catálogo, Hotmart, pedidos manuales) para que haya algo que
  contar.

## Paso a paso

1. **Activa el recurso** `unified_revenue_ledger` (y `orders_registry`) en la cuenta.
2. **Asegura ventas fluyendo** por cualquier origen — la convergencia es automática por los
   alimentadores de pedido.
3. **Abre la vista de Ingresos** en el panel/telón de Ventas.
4. **Elige el período** (por defecto, los últimos 30 días).
5. **Lee los agrupamientos** — total por moneda, por origen, por gateway, por vendedor y por afiliado.
6. **Exporta a CSV** para conciliar los ingresos fuera de la plataforma.

## Configuración y opciones

### Qué agrupa el ledger

Sobre los pedidos **pagados** del período (por `paid_at`), los ingresos se suman y se agrupan:

| Agrupamiento | Qué trae |
|---|---|
| Total por moneda | Ingresos totales por moneda — **nunca suma monedas distintas** |
| Por origen | Ingresos por `source` del pedido: `manual`, `webhook`, `api`, `payments`, `commerce` |
| Por gateway | Ingresos por gateway de dinero (asaas, mercado_pago, hotmart, nativo, catálogo…) |
| Por vendedor | Ingresos por dueño del pedido (el vendedor acreditado) |
| Por afiliado | Ingresos por afiliado atribuido (atribución dual) |

### Conteo exactamente una vez (sin duplicidad)

La acreditación ocurre **en el eje del pedido** cuando existe un pedido, y en el camino heredado solo
cuando no se produce ningún pedido:

| `unified_revenue_ledger` | `orders_registry` | Quién acredita | Resultado |
|---|---|---|---|
| Apagado | cualquiera | Camino heredado (cobro/comercio) | idéntico al anterior |
| Encendido | Encendido | `order.paid` (el pedido) — heredado suprimido | una vez, en el pedido |
| Encendido | Apagado | Heredado (no se produce pedido) | una vez, en el cobro/comercio |

### Atribución del vendedor (fallback)

El dueño del pedido se resuelve en cascada: **negocio → contacto → responsable → creador**. Un cobro sin
negocio aún se atribuye al usuario que lo creó (campo de creador del cobro), de modo que ninguna venta
pagada queda "sin dueño".

### Atribución de ventas externas al vendedor

Las ventas **externas** (catálogo, Hotmart, Kiwify y otros gateways) llegan desde el gateway y, muchas
veces, a un contacto comprador que **no está en la cartera de nadie**. Sin una regla, esa venta pagada
quedaría "sin vendedor". La configuración por cuenta **`external_attribution_mode`** decide cómo se
resuelve el vendedor automáticamente en ese caso:

| Modo | Qué hace |
|---|---|
| `off` (por defecto) | Ningún crédito automático — la venta externa queda sin vendedor hasta una atribución manual |
| `last_conversation` | Acredita al agente que atendió al comprador por última vez (la última conversación del contacto) |
| `distribution` | Acredita según las reglas de distribución activas (las mismas de la distribución de leads) |

Cuando el modo resuelve un vendedor, la **cartera del comprador se reivindica de forma durable** para ese
vendedor — así, las próximas ventas del mismo contacto ya entran con dueño. El valor por defecto es
**`off`**: ningún crédito automático hasta que elijas explícitamente `last_conversation` o `distribution`.

**Reatribución manual del vendedor.** Un **gestor** (permiso de gestión de ventas) puede, desde el
pedido, **vincular una venta externa a un vendedor** o **mover el crédito entre agentes**. El cambio
**revierte los puntos y la comisión del dueño anterior** y acredita al nuevo dueño; el **crédito del
afiliado no se ve afectado**. Dejar el vendedor en blanco **desvincula** el pedido. Todo cambio queda
**auditado** (evento `order_reattributed`), preservando el registro de quién fue acreditado y por qué.

### Reembolso (clawback)

Cuando un pedido se reembolsa, el crédito se **revierte en el origen del pedido** — para el vendedor **y**
para el afiliado —, manteniendo el ledger fiel al dinero efectivamente recibido.

### Exportación CSV

Una fila por pedido pagado, con las columnas: `order_id`, `paid_at`, `source`, `gateway`, `owner_id`,
`affiliate_id`, `amount`, `currency`. Los valores están en **unidades mayores** (ej.: `4970.50` =
R$ 4.970,50).

### Permisos y visibilidad

- Leer el ledger y exportar exigen el permiso de **gestión de ventas**.
- La lectura respeta el **aislamiento por vendedor**: bajo cartera/privacidad, un gestor ve solo su
  cascada; un vendedor, solo su propia cartera.

## Casos de uso

- El gestor lee los ingresos por vendedor para reconocer quién más vendió en el período.
- Finanzas exporta el CSV para conciliar los ingresos pagados con el extracto de comisiones.
- La dirección compara los ingresos por **origen** (Hotmart × catálogo × cobro) y por **gateway**.
- Los ingresos por **afiliado** alimentan el seguimiento del programa de afiliados (atribución dual).

## Consejos, límites y buenas prácticas

- El dinero está en **unidades mayores** (decimal), la misma convención de Pagos/Catálogo — nunca
  dividas por 100.
- El ledger **nunca suma monedas distintas**: cada moneda es una fila.
- Activar el recurso acredita las ventas **de aquí en adelante** — no hay reprocesamiento retroactivo
  automático. Para reprocesar el historial de Hotmart, usa el backfill del operador.
- Activa **ambos** recursos (`unified_revenue_ledger` + `orders_registry`): esa combinación es la que
  suprime el camino heredado y evita el conteo doble.

## Solución de problemas

- **Ledger vacío**: no hay pedidos pagados en el período, o el recurso está apagado. Confirma la
  activación y la existencia de ventas pagadas.
- **Números duplicados**: el `orders_registry` probablemente está **apagado**, así que el camino heredado
  y el del pedido acreditan juntos. Activa el registro de pedidos.
- **El vendedor aparece como nulo**: el pedido no tuvo dueño resuelto (sin negocio, contacto, responsable
  ni creador). Verifica la atribución en el origen.
- **Venta externa sin vendedor o acreditada al vendedor equivocado**: si `external_attribution_mode` está
  en `off`, las ventas externas quedan sin dueño — elige `last_conversation` o `distribution`, o haz la
  reatribución manual (gestión de ventas) desde el pedido.
- **Reembolso no reflejado**: el evento de reembolso del pedido no se disparó. Confirma el flujo de
  reembolso en el gateway/Pagos.
- **Exportación bloqueada**: falta el permiso de **gestión de ventas**. Pídelo a un administrador.

## Ver también

- [Programa de afiliados: atribución dual, comisión y portal](/hc/ajuda/articles/sales-gamification-affiliate-program-es)
- [Paneles e informes de ventas](/hc/ajuda/articles/sales-gamification-paineis-e-relatorios-de-vendas-es)
- [Visión general de Ventas y Gamificación](/hc/ajuda/articles/sales-gamification-overview-es)