Programa de afiliados: atribución dual, códigos de referido, comisión y portal

Visión general

El programa de afiliados convierte a quien refiere ventas en una entidad nativa con comisión propia. Un afiliado puede ser cuatro cosas, y el vínculo es de identidad (quién es el socio), nunca de pago — el receptor siempre es el registro del afiliado:

Cada afiliado recibe un código de referido único (público, hecho para compartir) y un token de informe aparte (privado, rotable).

Lo central es la atribución dual: un mismo pedido pagado acredita al vendedor (dueño) en el extracto del usuario y al afiliado — en el mismo ledger de comisión, sin colisión. Así el vendedor sigue recibiendo sus puntos y comisión, y el afiliado recibe la comisión de referido, sobre la misma venta, sin doble conteo.

Requisitos previos

• Módulo Ventas y Gamificación habilitado en la cuenta.
• Recurso affiliate_program activado en la cuenta (dark-ship, por defecto apagado).
• Recurso unified_revenue_ledger activado — la comisión del afiliado se acumula en el momento en que el pedido se paga (el mismo eje del ledger unificado). Sin él, no hay acumulación de comisión de afiliado.
• Permiso de gestión de ventas (sales_manage) — o administrador — para gestionar afiliados.

Paso a paso

1. Activa affiliate_program (y unified_revenue_ledger) en la cuenta.
2. Crea un afiliado: en "Este afiliado es" elige si es un agente, un contacto, una empresa o un socio externo; luego define la comisión (porcentaje, importe fijo por venta o plan).
3. Comparte el código/enlace de referido con el afiliado.
4. Atribuye el referido por cualquiera de estas vías: marca "Referido por" en el contacto, usa la acción de automatización "Definir afiliado del contacto", envía affiliate_id en el pedido, activa la herencia por empresa, o deja que el reconciliador case el split de la venta.
5. La venta pagada acredita al vendedor y al afiliado automáticamente.
6. El afiliado sigue su desempeño por el portal (por token); el gestor lee el informe en el panel.

Configuración y opciones

Campos del afiliado

Formato del importe: los campos de comisión aceptan coma o punto como separador decimal — 25,00 y 25.00 son lo mismo, y el separador de miles es opcional (1.250,50). Un valor fuera de rango (un porcentaje mayor que 100, un importe negativo) se rechaza al instante, con el motivo junto al campo.

Cómo se atribuye una venta al afiliado

En cascada, de lo más explícito a lo más genérico. Gana el primer escalón que responda, y un afiliado ya grabado en el pedido nunca se sobrescribe:

1. affiliate_id enviado en el pedido — lo aceptan la API del CRM, el ingest público y las automatizaciones. El id siempre se verifica contra los afiliados activos de esta cuenta: un id de otra cuenta se descarta.
2. "Referido por" en el contacto — el referido duradero de la persona.
3. Afiliado de la empresa principal del contacto — solo cuando ese afiliado activó inherit_to_org_contacts. Vale únicamente para la empresa principal y solo de ahí en adelante: activar la opción no reacredita pedidos anteriores.
4. Split externo reconciliado — casa el ucode/correo del split (Hotmart/Kiwify) con un afiliado existente, incluso por el correo del contacto o la empresa vinculada.
5. Sin coincidencia → el split entra en la cola de reconciliación en vez de desaparecer.

Splits sin afiliado registrado

Cuando la pasarela informa una comisión para alguien que la cuenta no tiene registrado, ese split se registra en una cola visible — con nombre, correo/ucode, el importe informado y el pedido de origen. Antes ese caso simplemente desaparecía dentro de la metadata: el único síntoma era una comisión que nunca aparecía.

Abre "Splits sin registro" en la pantalla de Afiliados y decide: Registrar (abre el formulario ya rellenado con los datos del split) o Descartar. La cola nunca crea un afiliado por su cuenta — pagar a alguien a partir de un nombre no verificado llegado en un webhook es justo el riesgo que esta confirmación evita.

Atribución dual sin colisión

El ledger de comisión distingue el tipo de receptor (vendedor vs. afiliado). Un pedido pagado escribe dos filas — la del vendedor y la del afiliado — sin mezclarse. El extracto de un vendedor nunca suma las filas del afiliado.

Comisión del afiliado

La comisión se resuelve por venta, en este orden de precedencia — del más preciso al más genérico:

1. El importe reportado por la fuente — cuando la venta vino de Hotmart o Kiwify, la propia plataforma informa cuánto le pagó realmente a ese afiliado. Ese valor es autoritativo y entra en el ledger tal cual, para que el extracto nunca difiera de lo que el afiliado realmente recibió.
2. El plan de comisión — cuando el afiliado tiene uno.
3. Comisión fija (R$) — el importe fijo definido en el afiliado.
4. Comisión (%) — el porcentaje sobre el importe pagado del pedido.

Por qué la fuente va primero: en un programa de afiliados externo la plataforma ya calculó y pagó el split, así que aplicar nuestro porcentaje encima produciría un número que no coincide con la realidad.

Un afiliado externo recibe comisión y portal, pero no gana puntos de gamificación (los puntos exigen un usuario).

Extracto del afiliado

El afiliado tiene extracto propio, con el mismo ciclo que el del vendedor: acumulado → aprobado → pagado. Se cierra por período y por moneda — un extracto es un documento a pagar y se paga en una sola moneda, así que los movimientos en BRL y en USD generan extractos separados en lugar de un total que no existe.

El extracto de un afiliado y el de un vendedor son registros independientes, aun cuando sus números de identificación coincidan. En la lista de extractos, el filtro de tipo de receptor separa ambos ledgers.

Portal del afiliado

Página pública y de solo lectura, abierta con el token de informe — sin sesión y sin account_id. Muestra solo su propio desempeño: pedidos atribuidos (paginados, con filtro de período), ingresos y comisión agrupados por moneda, y los extractos cerrados — sin PII de contactos. Un token inválido, rotado o una cuenta con el recurso apagado devuelven 404.

El token no es el código de referido. El código es público — va en enlaces y materiales — y sigue válido para siempre; el token es la credencial privada del informe financiero. Usa Rotar en el registro del afiliado para invalidar de inmediato todo enlace de informe ya compartido: ningún referido deja de funcionar, porque el código no cambia.

Los afiliados creados antes de esta versión empiezan con el token igual a su código de referido público — así ningún enlace ya entregado se rompió en la migración. Mientras eso sea cierto, cualquiera que conozca el código puede abrir el informe, y el registro muestra el aviso "este enlace sigue siendo el código público". Rota el token de esos afiliados para emitir un enlace realmente privado.

Archivar, restaurar y eliminar definitivamente

La lista predeterminada muestra afiliados actuales; usa el filtro de estado para revisar socios activos, pausados o archivados. Archivar detiene nuevas atribuciones y comisiones, pero conserva las referencias, pedidos y estados existentes; Restaurar vuelve a activar al socio. Eliminar definitivamente solo aparece para un afiliado archivado y solo funciona cuando no hay historial de referencias, pedidos, conciliación o financiero; la confirmación es explícita y no se puede deshacer.

Casos de uso

• Materializar un afiliado de Hotmart a partir del split preservado en la venta (reconciliación por ucode/correo).
• Registrar un agente interno como afiliado que refiere ventas de otra cartera.
• Compartir un enlace de referido para captar referidos rastreables.
• El afiliado abre el portal y sigue su comisión acumulada casi en tiempo real.

Consejos, límites y buenas prácticas

• Un afiliado externo no gana puntos de gamificación — solo comisión + portal.
• Solo los afiliados activos acumulan; un afiliado pausado/archivado no acumula nada.
• Pagar al afiliado (Pix/transferencia) está fuera del alcance v1 — el módulo hace acumulación + informe + portal.
• El referral_code es público — compártelo sin problema. Lo que abre el informe financiero es el token de informe, privado y rotable en cualquier momento.
• La herencia por empresa es opt-in por afiliado y solo vale hacia adelante — activarla no reacredita nada del pasado.
• Al fusionar contactos, el referido del contacto absorbido lo adopta el principal cuando este aún no tiene uno; un contacto que ya tenía referido conserva el suyo.
• Un reembolso también revierte la comisión del afiliado, en el origen del pedido.

Solución de problemas

• Afiliado no acreditado: el unified_revenue_ledger puede estar apagado, el pedido puede no tener afiliado atribuido, o el afiliado no está activo. Verifica los tres.
• El portal devuelve 404: token erróneo/antiguo, o el recurso affiliate_program está apagado en la cuenta.
• El afiliado de Hotmart no casó: el split entró en "Splits sin registro". Abre la cola y usa Registrar — el formulario llega ya rellenado con el correo/ucode exactos que envió la pasarela.
• La comisión aparece como "sin moneda": son movimientos anteriores a la separación por moneda. Su moneda real es desconocida y no se inventa; los movimientos nuevos llevan la moneda del pedido.
• Se rechazó la eliminación definitiva: todavía existe historial de referencias, pedidos, conciliación o financiero. Mantén al afiliado archivado; conservar ese historial es intencional.

Ver también

• Ledger unificado de ingresos: conteo único de ventas
• Paneles e informes de ventas
• Visión general de Ventas y Gamificación