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

| El afiliado es | Cuándo usarlo |
|---|---|
| **Un agente** | Alguien del equipo que además refiere ventas de otra cartera |
| **Un contacto** | Un cliente que se volvió socio y ahora refiere a otros |
| **Una empresa** | Una agencia, reventa o clínica socia — sus contactos pueden heredar el vínculo |
| **Un socio externo** | Alguien que la cuenta no conoce: solo correo/código (p. ej. un afiliado de Hotmart) |

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

| Campo | Qué es |
|---|---|
| `name` | Nombre del afiliado (obligatorio) |
| `user_id` / `contact_id` / `organization_id` | **Quién es el afiliado** — un agente, un contacto o una empresa. Son **mutuamente excluyentes**: llenar más de uno se rechaza |
| `inherit_to_org_contacts` | Solo para empresa: al activarlo, los contactos de esa empresa heredan el afiliado en los pedidos **nuevos** |
| `email` / `external_ref` | Correo y/o código externo (ucode de Hotmart). **Únicos por cuenta** — por ahí identifica el reconciliador al socio |
| `referral_code` | Código de referido — autogenerado, único por cuenta, **público**, hecho para compartir |
| `portal_token` | Credencial **privada** del informe del afiliado. Separada del código y **rotable** |
| `commission_percent` | **Comisión (%)** — porcentaje de comisión (0–100); vacío cuando un plan lo define |
| `commission_amount` | **Comisión fija (R$)** — importe fijo pagado por venta, en lugar del porcentaje. Opcional: déjalo vacío para usar el porcentaje |
| `plan_id` | Plan de comisión que sustituye al porcentaje y al importe fijo |
| `status` | `active`, `paused` o `archived` — **solo activo acumula comisión** |
| `metadata` | Datos libres (ej.: la afiliación de Hotmart preservada) |

> **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](/hc/ajuda/articles/sales-gamification-unified-revenue-ledger-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)