Documentação técnica de integração

A Parceiroos acompanha uma venda do primeiro clique até a comissão paga. O afiliado divulga um link de tracking; a plataforma registra o clique e envia o visitante ao anunciante; o anunciante confirma a venda de volta; a conversão percorre seus status e se transforma em comissão. Tudo o que vem a seguir descreve as peças desse circuito.

1. 01
   Clique

   O tráfego entra por https://SEU-DOMINIO/click?offer=…&aff=…. A plataforma grava o clique, cria um click_id e redireciona para a página do anunciante com esse identificador.

2. 02
   Conversão

   Com a venda confirmada, o anunciante informa a plataforma por postback server-to-server, pixel ou container JavaScript. O click_id e um ID único da transação acompanham toda chamada.

3. 03
   Status

   A conversão nasce PENDING, pode passar por VALIDATING e termina em APPROVED, DECLINED ou PAID. Cada mudança pode disparar o postback de saída do afiliado.

4. 04
   Pagamento

   Conversões aprovadas entram no financeiro e são pagas ao afiliado segundo a política do programa.

#Endereços da plataforma

A venda só existe para a Parceiroos quando o anunciante a confirma. Há três métodos. O postback server-to-server é o mais preciso e o primeiro a considerar; pixel e container JavaScript dependem do navegador do comprador e atendem quem não tem acesso ao backend.

#Antes de tudo: o click_id

Ao redirecionar o visitante, a plataforma anexa o identificador do clique à URL de destino. Esse valor precisa sobreviver até a confirmação da venda: cookie, sessão ou campo oculto do pedido. Sem click_id não há atribuição, e a conversão é recusada.

• O postback aceita o clique em click_id, e também em clickId, clickid, cid, p1 e sub1.
• Nas integrações por pixel e container, o handle.js captura e guarda o click_id sozinho.
• Um click_id inventado não passa: a conversão é recusada.

#Postback server-to-server

O backend do anunciante chama a plataforma no instante em que a venda é confirmada, por exemplo na aprovação do pagamento.

https://SEU-DOMINIO/postback?token=SEU_TOKEN&click_id={CLICK_ID}&txn_id={TXN_ID}&saleAmount=VALOR_DA_VENDA&currency=BRL

• POST aceita JSON ou application/x-www-form-urlencoded; os campos podem ir no corpo ou na query string.
• A resposta é 200 com um JSON de confirmação. Uma transação repetida devolve DUPLICATE_TRANSACTION e não cria registro.
• Uma chamada por venda, sempre do servidor. Reenviar o mesmo txn_id é seguro.

#Pixel de imagem

Sem backend. O script de captura vai em todas as páginas, ou ao menos na landing page; a tag de imagem, apenas na página de obrigado. A imagem dispara a conversão ao carregar.

<!-- Em toda página (ou ao menos na landing page) -->
<script src="https://SEU-DOMINIO/js/platform/handle.js"></script>

<!-- Apenas na página de obrigado / confirmação -->
<img style="display:none;" src="https://SEU-DOMINIO/postback?token=SEU_TOKEN&click_id={CLICK_ID}&txn_id={TXN_ID}&currency=BRL&offer_id=ID_DA_OFERTA&saleAmount=VALOR_DA_VENDA">

#Container JavaScript

Na página de obrigado, o objeto window.PLATFORM_PIXEL recebe os dados reais do pedido e o pixel.js faz o resto: lê o objeto, recupera o click_id guardado pelo handle.js e envia a conversão.

<!-- Em toda página (ou ao menos na landing page) -->
<script src="https://SEU-DOMINIO/js/platform/handle.js"></script>

<!-- Apenas na página de obrigado / confirmação -->
<script>
  window.PLATFORM_PIXEL = {
    token: "SEU_TOKEN",
    clickId: "{CLICK_ID}",
    txnId: "{TXN_ID}",
    value: "VALOR_DA_VENDA",
    valueParam: "saleAmount",
    currency: "BRL",
    offerId: "ID_DA_OFERTA",
    network: "https://SEU-DOMINIO"
  };
</script>
<script src="https://SEU-DOMINIO/js/platform/pixel.js"></script>

#Ciclo de vida da conversão

#Link de tracking

Todo link de divulgação passa por https://SEU-DOMINIO/click. O painel entrega o link pronto na página de cada oferta; a estrutura é simples o bastante para ser montada à mão.

https://SEU-DOMINIO/click?offer=ID_PUBLICO_DA_OFERTA&aff=SEU_CODIGO&sub1=campanha-a&sub2=criativo-3

#Postback de saída

A URL do sistema do afiliado é cadastrada em Integrações → Postback. Quando uma conversão entra em um status assinado em Quando disparar seu postback, a Parceiroos renderiza a URL com as macros e a chama por HTTP GET ou POST. O padrão dispara apenas em APPROVED.

https://meu-tracker.com/postback?cid={click_id}&payout={payout}&status={status}&sub1={sub1}

• As macros aceitam os dois delimitadores, {macro} e [macro]; a URL pode ser colada do jeito que a rede documenta.
• Uma macro desconhecida sai literal, sem substituição: um erro de digitação aparece no log em vez de virar um parâmetro vazio.
• Todo valor é codificado para URL. Um valor opcional inexistente vira string vazia, nunca 0.00.

#Macros disponíveis

Um tracker, uma rede ou o backend de um parceiro precisa de duas coisas: o token de clique dele no link de tracking e esse mesmo token de volta no postback de saída. O catálogo de macros também é publicado em JSON em https://SEU-DOMINIO/api/postback-macros, pronto para ser encaminhado.

#Exemplo completo: rede externa

O exemplo usa uma rede fictícia que documenta o postback dela com os campos [click_token], [action_id], [price] e [total]. Os nomes mudam de rede para rede; o mecanismo não.

1. 01
   Link de tracking

   A rede coloca o token dela em sub1; o valor fica guardado com o clique.

2. 02
   URL de postback

   Em Integrações → Postback, a URL da rede entra com os campos dela trocados pelas macros. Em Quando disparar seu postback, os status que devem notificá-la.

3. 03
   O que a rede recebe

   A URL final, já renderizada, fica no log de postback de saída.

https://SEU-DOMINIO/click?offer=ID_PUBLICO&aff=CODIGO&sub1=[click_token]

https://rede-exemplo.com/postback/ID_DA_CONTA?token={sub1}&action_id={conversion_id}&price={payout}&total={sale_amount}

https://rede-exemplo.com/postback/ID_DA_CONTA?token=cca6a691-8ded-6ddf-e979-01503768f7eb.76066&action_id=cnv_7d21b93a4f6c&price=1.00&total=10.00

#Como o sale_amount é preenchido

{payout} é a comissão e sempre existe. {sale_amount} é o valor do pedido e só existe quando o anunciante o envia no postback de entrada em sale_amount, saleAmount, total_price, totalPrice, order_value ou total. Outro nome pode ser mapeado em Integrações → Postback do anunciante. Se a rede exige um número, {payout} serve nos dois campos.

Uma rede de afiliados pode ocupar dois lugares no seu programa. Como afiliada, ela envia tráfego e recebe a conversão pelo postback de saída. Como anunciante, você roda as ofertas dela: o destino da oferta é o link de afiliado da rede, com o seu {click_id} no sub-ID, e o postback dela entrega a venda no seu postback de entrada. Cada guia abaixo cobre as direções que a rede oferece.

ActionpayAfiliado · AnuncianteAdmitadAfiliado · AnuncianteAwinAfiliado · AnuncianteCJ AffiliateAfiliado · AnuncianteImpactAfiliado · AnuncianteRakuten AdvertisingAfiliado · AnuncianteAfilioAfiliado · AnuncianteLomadeeAfiliado · AnunciantePlataformas de checkoutAnunciante

Actionpay

Rede CPA com operação forte na América Latina e no Leste Europeu.

Testado na plataforma

A rede envia tráfegoEla é afiliada do seu programaA rede é o anuncianteVocê roda ofertas dela

A rede é cadastrada como afiliado do seu programa. O token de clique dela viaja no seu link de tracking e volta na URL de postback de saída.

A Actionpay envia tráfego com [click].[source] no link e recebe a conversão no endpoint dela.

https://SEU-DOMINIO/click?offer=ID_PUBLICO&aff=CODIGO_DA_REDE&actionpay=[click].[source]

https://apypp.com/ok/AIM_ID.png?actionpay={actionpay}&apid={conversion_id}&price={payout}&totalPrice={sale_amount}

Campo da rede → macro da plataforma

Campo da rede	Macro	Observação
AIM_ID	—	ID numérico do programa, fornecido pela Actionpay. Fixo na URL.
[click].[source]	{actionpay}	Token do clique. Entra no link e volta idêntico.
apid	{conversion_id}	ID da conversão na plataforma.
price	{payout}	Comissão da conversão.
totalPrice	{sale_amount}	Valor do pedido. Vazio quando o anunciante não informa.

• A rede entra como afiliado do programa; o código dela vai em aff.
• A URL de postback é cadastrada em Integrações → Postback do afiliado, com os status que devem notificar a rede.
• O token também pode viajar em sub1 e voltar em {sub1}; o resultado é o mesmo.

A Parceiroos expõe um servidor Model Context Protocol. Com uma chave, o assistente do anunciante lista as ofertas, gera o snippet com token e ID reais, aplica no projeto e confirma se as conversões chegaram. O escopo é sempre o das ofertas do dono da chave.

→ tools/list
← list_offers · get_offer · generate_integration · verify_integration

→ tools/call list_offers { limit: 20 }
← { count: 3, offers: [{ publicId: "OF-2Z9K", name: "Conta Digital", status: "ACTIVE" }, …] }

→ tools/call generate_integration { offerId: "OF-2Z9K", method: "POSTBACK" }
← GET /postback?token=••••••&click_id={CLICK_ID}&txn_id={TXN_ID}&saleAmount=…

→ tools/call verify_integration { offerId: "OF-2Z9K" }
← { hasConversions: true, latest: { txnId: "TX-88213", status: "APPROVED" } }

Authorization: Bearer mcp_••••••••••••

→ tools/list
← list_offers · get_offer · generate_integration · verify_integration

→ tools/call list_offers { limit: 20 }
← { count: 3, offers: [{ publicId: "OF-2Z9K", name: "Conta Digital", status: "ACTIVE" }, …] }

→ tools/call generate_integration { offerId: "OF-2Z9K", method: "POSTBACK" }
← GET /postback?token=••••••&click_id={CLICK_ID}&txn_id={TXN_ID}&saleAmount=…

→ tools/call verify_integration { offerId: "OF-2Z9K" }
← { hasConversions: true, latest: { txnId: "TX-88213", status: "APPROVED" } }

Authorization: Bearer mcp_••••••••••••

→ tools/call generate_integration { offerId: "OF-2Z9K", method: "POSTBACK" }

claude mcp add --transport http plataforma https://SEU-DOMINIO/api/mcp --header "Authorization: Bearer mcp_SUA_CHAVE"

1. 01
   Chave

   Configurações → API & MCP → Criar chave. A chave (prefixo mcp_) é exibida uma única vez.

2. 02
   Cliente

   O comando abaixo no terminal do projeto que recebe a integração, ou a configuração JSON genérica.

3. 03
   Pedido

   No assistente: “liste minhas ofertas e gere a integração por postback da oferta X”. Aplicado o snippet, um segundo pedido verifica.

#Conectar um cliente

claude mcp add --transport http plataforma https://SEU-DOMINIO/api/mcp --header "Authorization: Bearer mcp_SUA_CHAVE"

{
  "mcpServers": {
    "plataforma": {
      "type": "http",
      "url": "https://SEU-DOMINIO/api/mcp",
      "headers": {
        "Authorization": "Bearer mcp_SUA_CHAVE"
      }
    }
  }
}

#Ferramentas disponíveis

• Transporte: Streamable HTTP, sem estado, resposta única em JSON (JSON-RPC 2.0).
• Autenticação: header Authorization: Bearer mcp_… em toda chamada. Chaves são revogáveis a qualquer momento.
• Sem cliente MCP, a página da oferta gera um prompt completo para qualquer assistente.