Vender com afiliado

Um afiliado divulga o seu produto e recebe comissão pelas vendas que traz. No checkout da PagPolar, o link do afiliado cuida disso sozinho. Quando a venda é feita pela API, é você que informa o afiliado.

Use este guia quando o seu sistema sabe qual afiliado trouxe o cliente. A venda em si segue o guia do meio de pagamento. Aqui você só acrescenta um campo: affiliate_identifier.

Visão geral

O diagrama mostra como a API decide se a venda fica com o afiliado.

Os detalhes de cada pergunta estão em Quando o código é ignorado.

Antes de começar

• Um produto com o programa de afiliados ligado no painel e pelo menos um afiliado aprovado.
• Uma oferta desse produto. Veja Criar produto e oferta.
• Uma cobrança funcionando sem afiliado. Veja o Início rápido.
• Um token de acesso. Veja Autenticação; os exemplos em Node.js assumem a variável accessToken.

Rotas que aceitam o código

O campo affiliate_identifier é opcional e vale nestas quatro rotas:

Passo a passo

curl -X POST "https://api.pagpolar.com/v1/payments/pix" \
  -H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>" \
  -H "Idempotency-Key: 8d3f1a2b-5c6d-4e7f-9a0b-1c2d3e4f5a6b" \
  -H "Content-Type: application/json" \
  -d '{
    "offer_identifier": "<CODIGO_DA_OFERTA>",
    "affiliate_identifier": "<CODIGO_DO_AFILIADO>",
    "external_reference": "PEDIDO-2001",
    "customer": {
      "name": "Maria Silva",
      "email": "cliente@exemplo.com",
      "document": "<CPF_DO_CLIENTE>",
      "phone": "<TELEFONE_DO_CLIENTE>"
    }
  }'

import { randomUUID } from 'node:crypto';

const response = await fetch('https://api.pagpolar.com/v1/payments/pix', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Idempotency-Key': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    offer_identifier: '<CODIGO_DA_OFERTA>',
    affiliate_identifier: '<CODIGO_DO_AFILIADO>',
    external_reference: 'PEDIDO-2001',
    customer: {
      name: 'Maria Silva',
      email: 'cliente@exemplo.com',
      document: '<CPF_DO_CLIENTE>',
      phone: '<TELEFONE_DO_CLIENTE>',
    },
  }),
});

console.log(response.status, await response.json());

Quando o código é recusado

A API confere o formato antes de tudo. Se o formato está errado, a resposta é 400 e nada é criado: nem venda, nem registro da Idempotency-Key. Corrija e envie de novo com a mesma chave.

Venda sem afiliado? Não envie o campo. Os outros erros da cobrança não mudam com o afiliado: veja os erros comuns a todas as rotas e o guia do meio de pagamento.

Quando o código é ignorado

Com o formato certo, a API procura o afiliado. Em qualquer uma das situações abaixo, a venda é criada normalmente, sem afiliado, e a resposta continua 201:

Oferta informada na hora e comissão

Você pode cobrar sem criar a oferta antes, enviando offer no lugar de offer_identifier. Veja Ofertas, planos e ofertas ocultas.

Com afiliado, cuidado:

• Se offer cria uma oferta nova, ela não está na lista de ofertas liberadas de ninguém. A comissão só vale se o afiliado puder divulgar todas as ofertas do produto.
• Se offer reaproveita uma oferta que já existe e já está liberada para o afiliado, a comissão vale.

Comissão na assinatura

Em POST /plans/offer/{id}/subscribe, o afiliado recebe a comissão da primeira cobrança. Nas renovações, ele só continua recebendo se a afiliação estiver com todas as recorrências ligada. Sem essa opção, depois do primeiro ciclo a parte dele volta para você.

Eventos de webhook deste fluxo

Não existe evento próprio de afiliado. Os eventos da venda chegam como numa venda sem afiliado, como TRANSACTION_CREATED e TRANSACTION_PAID.

Na venda criada pela API, source.channel é API, com ou sem afiliado. O valor AWARD é outra coisa: uma venda gerada como prêmio para o afiliado. Veja Canal da venda.

Próximos passos