Ledger unificado de ingresos: conteo único de ventas por origen, gateway, vendedor y afiliado

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:

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:

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:

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
• Paneles e informes de ventas
• Visión general de Ventas y Gamificación