Empecemos por lo que hay que escribir; lo demás viene después. Cuando un pedido se completa y sabes que vino de un afiliado, tu backend llama a esto:

POST /api/<merchantSlug>/track/conversion
Content-Type: application/json

{
  "orderId": "ORD-12345",
  "amount": 99.00,
  "currency": "USD",
  "affiliateCode": "ABC123"
}

Eso es todo lo obligatorio. El merchantSlug de la URL te identifica, así que no hay ninguna API Key que gestionar. Reportar clics es opcional: si no lo haces pierdes las estadísticas de clics y nada más.

Primer punto de rotura: pedidos duplicados

Los webhooks de pago se reintentan. Un timeout de la pasarela se reintenta. Tu propia lógica de reintentos se reintenta. Si cada reintento crea una conversión nueva, acabas pagando dos comisiones por una venta, y normalmente te enteras al cuadrar a fin de mes.

Afflixo deduplica por tu orderId dentro de tu programa. Enviar otra vez el mismo orderId te devuelve la conversión que ya existe con su comisión, en lugar de crear una segunda. Reintentar es seguro y no hace falta ninguna cabecera adicional.

La única condición es que el orderId sea único en tu sistema. Tu número de pedido suele serlo. Si tu tienda reutiliza numeración tras una anulación, arregla eso primero, porque si no la deduplicación tomará dos pedidos distintos por el mismo.

Segundo punto de rotura: la atribución se pierde

El código del afiliado se busca en este orden:

  1. affiliateCode en el cuerpo de la petición.
  2. La cabecera x-affiliate-code.
  3. La cookie affiliate_ref, que deja el enlace de afiliado.

Si no aparece por ninguna vía, la petición se rechaza con un 400, porque no hay a quién abonar la comisión. Es a propósito: mejor un error visible que una atribución silenciosamente equivocada.

En la práctica la que falla es la tercera, y en España y Latinoamérica falla más que en otros sitios, porque muchos checkouts salen a una pasarela externa y vuelven. Si la vuelta ocurre en otro dominio, o el cliente termina la compra en otro dispositivo, la cookie ya no está.

La forma fiable de resolverlo: lee el código del parámetro de la URL en cuanto el visitante entra, guárdalo en tu propia sesión o en el registro del pedido, y mándalo de forma explícita como affiliateCode al confirmar. Así la atribución no depende de que la cookie sobreviva al viaje.

Sobre la moneda

El campo currency se guarda, pero no se convierte nada. La comisión sale directamente del número que mandas en amount. Como Afflixo liquida en dólares, convierte tú el importe antes de enviarlo si facturas en euros, pesos o reales; si no, un importe local acabará contado como dólares.

Reglas de comisión

Tres ajustes cubren casi todo: porcentaje, importe fijo, y una tarifa puesta sobre un afiliado concreto. Defines un valor por defecto para el programa y lo sobrescribes donde haga falta; si existen los dos, manda el del afiliado. El alcance va aparte de la tarifa: solo el primer pedido, los primeros N pedidos, o una ventana de tiempo.

Pagos

El afiliado solicita, tú apruebas, y pagas por el medio que ya usas. Afflixo solo guarda el estado para que nada se apruebe dos veces, y no mueve dinero. Ese límite es deliberado.

Lo que no hay hoy: comisiones a varios niveles, dominio propio por comercio, pagos automáticos por PayPal o Stripe, y liquidación en otra moneda que no sea el dólar. La especificación completa está en la documentación para desarrolladores.