Primeiro o que precisa ser escrito; o resto vem depois. Quando o pedido é concluído e você sabe que veio de um afiliado, o seu backend chama isto:

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

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

É só isso de obrigatório. O merchantSlug da URL identifica você, então não há API Key para administrar. Informar cliques é opcional: sem isso você perde a estatística de cliques e mais nada.

Primeiro ponto que quebra: pedido contado duas vezes

Webhook de pagamento repete. Timeout do gateway repete. A sua própria lógica de retry repete. Se cada repetição criar uma conversão nova, você paga duas comissões por uma venda, e costuma descobrir isso só no fechamento do mês.

O Afflixo deduplica pelo seu orderId dentro do seu programa. Enviar o mesmo orderId de novo devolve a conversão que já existe, com a comissão dela, em vez de criar outra. Repetir é seguro, e não é preciso nenhum cabeçalho extra.

A única condição é o orderId ser único no seu sistema. O seu número de pedido normalmente já é. Se a sua loja reaproveita numeração depois de um cancelamento, resolva isso antes, senão a deduplicação vai tratar dois pedidos diferentes como o mesmo.

Segundo ponto que quebra: a atribuição some

O código do afiliado é procurado nesta ordem:

  1. affiliateCode no corpo da requisição.
  2. O cabeçalho x-affiliate-code.
  3. O cookie affiliate_ref, gravado pelo link de afiliado.

Se nenhum dos três aparecer, a requisição é recusada com 400, porque não há a quem creditar. Isso é proposital: melhor um erro visível do que uma atribuição errada em silêncio.

Na prática quem falha é o terceiro, e falha bastante por aqui. Checkout com Pix ou boleto costuma sair do site e voltar; se a volta cai em outro domínio, ou se o cliente finaliza a compra em outro aparelho, o cookie não está mais lá.

O jeito confiável é não depender dele: leia o código do parâmetro da URL assim que o visitante entra, guarde na sua própria sessão ou no registro do pedido, e mande explicitamente como affiliateCode na confirmação.

Sobre a moeda

O campo currency é guardado, mas nada é convertido. A comissão sai direto do número que você manda em amount. Como o Afflixo acerta em dólar, converta o valor antes de enviar se você fatura em real, senão um valor em reais vai ser contado como dólar.

Regras de comissão

Três ajustes cobrem quase tudo: percentual, valor fixo, e uma taxa colocada num afiliado específico. Você define um padrão para o programa e troca onde precisar; se existirem os dois, vale a taxa do afiliado. O alcance é separado da taxa: só o primeiro pedido, os primeiros N pedidos, ou uma janela de tempo.

Pagamentos

O afiliado pede, você aprova, e paga pelo meio que já usa. O Afflixo só guarda o status para que nada seja aprovado duas vezes, e não movimenta dinheiro. Esse limite é de propósito.

O que não existe hoje: comissão em vários níveis, domínio próprio por loja, pagamento automático por PayPal ou Stripe, e acerto em moeda diferente do dólar. A especificação completa está na documentação para desenvolvedores.