# Vender com afiliado URL: https://staging.pagpolar.com/docs/guias/jornadas/vender-com-afiliado > Credite a venda ao afiliado certo enviando affiliate_identifier na cobrança, e saiba quando o código é recusado ou ignorado. 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. ```mermaid flowchart TD A[Cobrança com affiliate_identifier] --> B{PAO seguido de 10 dígitos?} B -->|Não| C[400: nada é criado] B -->|Sim| D{Código de um afiliado deste produto, com afiliação valendo?} D -->|Não| X[Venda criada sem afiliado] D -->|Sim| E{O afiliado pode receber a comissão?} E -->|Não| X E -->|Sim| F{A oferta está liberada para o afiliado?} F -->|Não| X F -->|Sim| G[Venda criada com a comissão do afiliado] ``` Os detalhes de cada pergunta estão em [Quando o código é ignorado](#codigo-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](/docs/guias/jornadas/criar-produto-e-oferta). * Uma cobrança funcionando sem afiliado. Veja o [Início rápido](/docs/guias/inicio-rapido). * Um token de acesso. Veja [Autenticação](/docs/guias/fundamentos/autenticacao#obter-o-token); 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: | Rota | O que faz | | ---------------------------------- | ----------------- | | `POST /payments/pix` | Venda por PIX. | | `POST /payments/boleto` | Venda por boleto. | | `POST /payments/credit-card` | Venda no cartão. | | `POST /plans/offer/{id}/subscribe` | Assinatura. | ## Passo a passo 1. **Consiga o código do afiliado** O código do afiliado tem o formato `PAO` seguido de 10 dígitos, como `PAO0123456789`. Cada afiliação tem um código próprio. Um afiliado de dois produtos tem dois códigos diferentes. O afiliado encontra o código no painel dele: 1. Ele abre **Afiliação → Minhas afiliações**. 2. Abre a afiliação do seu produto. 3. Na seção **Meus links de divulgação**, cada link termina com `?ref=` seguido do código. O código é o valor depois de `ref=`. > **A lista de afiliados não mostra o código** > > Na sua tela **Afiliação → Afiliados**, cada afiliado aparece com nome e e-mail, sem o código. Peça o código ao afiliado, ou leia do link de divulgação dele. Pela API não existe cookie nem regra de primeiro ou último clique. Vale o código que você enviar. Decidir qual afiliado creditar é tarefa do seu sistema. 2. **Envie ** `affiliate_identifier` na cobrança Acrescente o campo no corpo da cobrança. O exemplo usa PIX. Nas outras três rotas, o campo é o mesmo. #### cURL ```bash curl -X POST "https://api.pagpolar.com/v1/payments/pix" \ -H "Authorization: Bearer " \ -H "Idempotency-Key: 8d3f1a2b-5c6d-4e7f-9a0b-1c2d3e4f5a6b" \ -H "Content-Type: application/json" \ -d '{ "offer_identifier": "", "affiliate_identifier": "", "external_reference": "PEDIDO-2001", "customer": { "name": "Maria Silva", "email": "cliente@exemplo.com", "document": "", "phone": "" } }' ``` #### Node.js ```js 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: '', affiliate_identifier: '', external_reference: 'PEDIDO-2001', customer: { name: 'Maria Silva', email: 'cliente@exemplo.com', document: '', phone: '', }, }), }); console.log(response.status, await response.json()); ``` | Campo | Obrigatório | O que é | | ---------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- | | `affiliate_identifier` | Não | Código do afiliado: `PAO` em letras maiúsculas, seguido de exatamente 10 dígitos. Espaços no começo e no fim são removidos. | A resposta é igual à de uma venda sem afiliado, como em [Vender com PIX ou boleto](/docs/guias/jornadas/vender-com-pix-ou-boleto). Contrato completo: [`POST /payments/pix`](/docs/referencia/vendas/create-pix-payment), [`POST /payments/boleto`](/docs/referencia/vendas/create-boleto-payment), [`POST /payments/credit-card`](/docs/referencia/vendas/create-credit-card-payment) e [`POST /plans/offer/{id}/subscribe`](/docs/referencia/assinaturas/create-subscription). > **A API não avisa se o afiliado foi creditado** > > Se o código não se aplica, a venda é criada assim mesmo, sem afiliado e sem erro. A resposta da cobrança, `GET /sales/{identifier}` e os webhooks não trazem dados do afiliado. Para conferir, use o painel, como no próximo passo. 3. **Confira no painel** Abra **Afiliação → Afiliados** e a aba **Vendas**. Ela lista as vendas feitas por afiliados, com o afiliado e a comissão. Se a venda não aparece ali, o código foi ignorado. Veja os motivos na próxima seção. ## 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. | Você envia | Resposta | | -------------------------------------------- | ----------------------------------------------------------------------------- | | `PAO0123456789` | Aceito. | | `" PAO0123456789 "` (com espaços nas pontas) | Aceito. Os espaços são removidos. | | `pao0123456789` (letras minúsculas) | `400 invalid_request` com `message` vazia | | `PAO123` (menos de 10 dígitos) | `400 invalid_request` com `message` vazia | | `null` | `400 invalid_request` com `message` vazia | | `""` (texto vazio) | `400 invalid_request` com `O campo affiliate_identifier não pode estar vazio` | 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](/docs/guias/fundamentos/erros#erros-comuns) 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`: | Situação | O que conferir | | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | O código não existe. | Copie o código de novo do link de divulgação. | | O código é de uma afiliação de **outro produto**. | O código vale só para o produto da afiliação. Use o código do afiliado para o produto desta oferta. | | A afiliação não está ativa: pendente ou recusada. | Aprove o afiliado no painel. | | A afiliação foi encerrada e o prazo de carência já venceu. | Depois de banir ou remover um afiliado, o código ainda gera comissão durante a carência. Por padrão, a carência é de 3 dias. Depois dela, não gera mais. | | O programa de afiliados do produto está desligado. | Ligue o programa na aba **Afiliados** da configuração do produto. | | O código é de uma afiliação da **sua própria conta**. | Uma conta não recebe comissão das próprias vendas. | | O afiliado não tem conta de recebimento criada, ou a verificação de identidade dele foi recusada. | O afiliado precisa concluir o cadastro para receber. | | A comissão do afiliado está zerada. | Ajuste a comissão no painel. | | A oferta não está liberada para o afiliado. | Libere a oferta para o afiliado, ou libere todas as ofertas do produto. | | Falha interna ao consultar o afiliado. | A venda nunca falha por causa do afiliado. Confira no painel e fale com o suporte informando o `request_id`. | ## 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](/docs/guias/conceitos/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. > **Afiliado com lista de ofertas: crie a oferta antes** > > Crie a oferta antes com `POST /offers`, libere para o afiliado no painel e cobre com `offer_identifier`. ## 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`](/docs/webhooks/eventos/transaction-created) e [`TRANSACTION_PAID`](/docs/webhooks/eventos/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](/docs/webhooks/formato-do-evento#source). ## Próximos passos - [Vender com PIX ou boleto](/docs/guias/jornadas/vender-com-pix-ou-boleto) — O fluxo completo da venda por PIX ou boleto. - [Vender com cartão de crédito](/docs/guias/jornadas/vender-com-cartao) — O fluxo completo da venda no cartão. - [Formato do evento](/docs/webhooks/formato-do-evento) — Leia o payload dos webhooks da venda.