Integração básica

Este guia percorre uma integração completa do Repass, do primeiro recurso até a comissão chegar a um payout. É mais profundo que o Quickstart: além dos passos do caminho feliz, ele explica o que acontece em cada transição (atribuição, snapshot de regra, hold, fechamento de ciclo e o gate fiscal) e como observar tudo isso pela API. O Repass é multi-tenant: cada recurso é escopado pela sua organização. Toda a integração server-to-server usa uma API key com prefixo rstr_ no header Authorization: Bearer, contra a base URL https://api.userepass.com. Antes de começar, vale conhecer as convenções da API: IDs são opacos (prefixo de tipo + ULID), dinheiro é sempre inteiro em centavos e percentuais em basis points (10000 bps = 100%).

Os modelos de cobrança mais sofisticados (recorrência, tiers, clawback) ficam fora do escopo deste guia básico, mas estão linkados em cada passo. Aqui montamos a espinha dorsal: um afiliado que divulga, uma venda atribuída e uma comissão paga.

O fluxo completo

Cada passo emite eventos imutáveis a cada mudança de estado, então a história inteira é auditável e pode ser entregue por webhooks.

Pré-requisitos

Tenha uma organização e uma API key admin

A organização é o seu tenant. Gere uma API key server-to-server (formato rstr_…) no painel da organização; ela herda a role do membro dono. Os passos abaixo incluem operações sensíveis (aprovar afiliado, fechar ciclo de payout), então use uma key com role admin ou owner.A key é mostrada uma única vez. Guarde-a em local seguro. Detalhes em Autenticação.

Exporte a key

export REPASS_KEY="rstr_..."
export REPASS_BASE="https://api.userepass.com"

Nunca exponha uma rstr_ em frontend ou repositório público: ela é uma credencial de servidor com os poderes do membro dono. Para ambientes de homologação e produção, use keys distintas; veja Ambientes.

Passos

Crie o programa

Um Programa concentra a configuração de todo o ciclo: moeda (BRL, imutável após criação), modelo e janela de atribuição, holdDays (carência da comissão, default 30) e approvalMode dos afiliados.

cURL

curl -X POST "$REPASS_BASE/programs" \
  -H "Authorization: Bearer $REPASS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: prog-integracao-001" \
  -d '{
    "name": "Programa de Indicações",
    "currency": "BRL",
    "attributionModel": "last_click",
    "approvalMode": "manual"
  }'

Resposta 201

{
  "id": "prog_01J9ZP6Q8X3K7M2N4R5T6V7W8Y",
  "name": "Programa de Indicações",
  "currency": "BRL",
  "attributionModel": "last_click",
  "approvalMode": "manual",
  "holdDays": 30,
  "status": "active"
}

O programa nasce active. O status só muda pelos endpoints de ação (pause / activate / archive), nunca por PATCH. Veja Programas e regras para todos os campos de configuração.

Publique uma regra de comissão

Sem uma regra vigente, a conversão até é atribuída, mas a comissão não tem como ser calculada. Crie a primeira versão da regra de comissão do programa: neste guia, um percentual simples sobre cada cobrança.O percentage é informado em decimal (0 a 100, passo 0,01) e equivale a um valor em basis points (percentage × 100): 20.0% corresponde a 2000 bps. A regra é imutável: alterar significa publicar uma nova versão; aplicar uma nova regra ao passado só via Reprocessamento.

cURL

curl -X POST "$REPASS_BASE/programs/prog_01J9ZP6Q8X3K7M2N4R5T6V7W8Y/commission-rules" \
  -H "Authorization: Bearer $REPASS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rule-integracao-001" \
  -d '{
    "type": "percentage",
    "percentage": 20.0,
    "recurrence": { "kind": "one_time" }
  }'

Resposta 201

{
  "id": "cmrl_01J9ZQA1B2C3D4E5F6G7H8J9K0",
  "programId": "prog_01J9ZP6Q8X3K7M2N4R5T6V7W8Y",
  "version": 1,
  "type": "percentage",
  "percentage": 20.0,
  "recurrence": { "kind": "one_time" }
}

recurrence controla por quais ciclos de cobrança a comissão é paga. one_time (default) comissiona só a primeira cobrança; lifetime, months:N e decreasing cobrem assinaturas recorrentes. Para faixas por volume (tiered), que exigem uma faixa-base minCount: 0, veja Programas e regras.

Recrute e aprove um afiliado

O Afiliado é identificado por e-mail dentro do programa. Com approvalMode: "manual", ele nasce pending e precisa de aprovação explícita.

cURL (criar)

curl -X POST "$REPASS_BASE/programs/prog_01J9ZP6Q8X3K7M2N4R5T6V7W8Y/affiliates" \
  -H "Authorization: Bearer $REPASS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: aff-integracao-001" \
  -d '{ "email": "[email protected]", "name": "Parceiro Exemplo" }'

Resposta 201

{
  "id": "aff_01J9Z3M2P0RD8K4VC1XN6YHTBE",
  "programId": "prog_01J9ZP6Q8X3K7M2N4R5T6V7W8Y",
  "email": "[email protected]",
  "name": "Parceiro Exemplo",
  "status": "pending",
  "tier": null
}

Aprovar muda pending → approved. Nesse momento o Repass cria automaticamente um Link default para o afiliado. Você não precisa criar o primeiro link à mão.

cURL (aprovar)

curl -X POST "$REPASS_BASE/affiliates/aff_01J9Z3M2P0RD8K4VC1XN6YHTBE/approve" \
  -H "Authorization: Bearer $REPASS_KEY" \
  -H "Content-Type: application/json"

Resposta 200

{
  "id": "aff_01J9Z3M2P0RD8K4VC1XN6YHTBE",
  "status": "approved"
}

O afiliado pode precisar aceitar uma versão dos termos do programa antes de divulgar. A máquina de estados completa (pending, approved, paused, rejected, banned) e o efeito de cada transição sobre comissões e payouts estão em Afiliados.

Gere um link rastreável

Cada afiliado pode ter vários Links. O token é único globalmente e imutável; você pode informar um subId opcional para segmentar a divulgação (campanha, canal). O destinationUrl precisa estar na whitelist de domínios da organização (GET/PUT /settings/destination-domains).

cURL

curl -X POST "$REPASS_BASE/affiliates/aff_01J9Z3M2P0RD8K4VC1XN6YHTBE/links" \
  -H "Authorization: Bearer $REPASS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: link-integracao-001" \
  -d '{
    "destinationUrl": "https://app.exemplo.com/signup",
    "subId": "newsletter"
  }'

Resposta 201

{
  "id": "link_01J9Z3N7R2SF9M5WD2YP4ZKUCG",
  "affiliateId": "aff_01J9Z3M2P0RD8K4VC1XN6YHTBE",
  "token": "k3y9q2",
  "destinationUrl": "https://app.exemplo.com/signup",
  "subId": "newsletter",
  "status": "active"
}

Cupons sincronizados com o gateway de pagamento são uma forma alternativa de atribuição, sem clique, úteis para divulgação offline ou em vídeo. Veja Links e cupons.

Instrumente o tracking

O afiliado divulga a URL pública de redirect https://api.userepass.com/t/{token}. Quando um visitante a acessa, o Repass registra o Clique (identidade do visitante, geolocalização, detecção de bot, janela de expiração), seta um cookie first-party repass_vid e responde 302 para o destino, anexando o repass_cid na query.

Redirect público (chamado pelo visitante)

curl -i "$REPASS_BASE/t/k3y9q2?sub=campanha-junho"
# HTTP/1.1 302 Found
# Location: https://app.exemplo.com/signup?repass_cid=...
# Set-Cookie: repass_vid=...; Path=/; HttpOnly

Para casar a venda ao clique mais tarde, propague essa identidade no seu produto. Há dois sinais que você pode capturar no signup/checkout e enviar de volta na conversão:

clickId: o identificador do clique (derivável do repass_cid); o sinal mais forte e direto.
visitorId: o valor do cookie repass_vid, que casa por identidade de visitante mesmo sem o clickId.

Quando o usuário se identifica (ex.: cria a conta), você pode opcionalmente vincular o visitorId ao e-mail (hasheado) para casar conversões cross-device:

POST /track/identify

curl -X POST "$REPASS_BASE/track/identify" \
  -H "Content-Type: application/json" \
  -d '{
    "visitorId": "vis_01J9Z3P9T4UG0N6XE3ZQ5ALVDH",
    "emailHash": "sha256:9c1185a5c5e9fc54612808977ee8f548b2258d31"
  }'

As rotas /t/{token}, /track/click e /track/identify são públicas (não usam a API key). São chamadas pelo navegador do visitante ou pelo seu frontend. A engine de atribuição usa todos esses sinais em cascata (clickId → visitorId → emailHash → fingerprint) para decidir a qual afiliado a venda pertence.

Ingira a conversão server-to-server

Quando a venda acontece, registre a Conversão via POST /conversions. A API roda atribuição e o score de fraude de forma síncrona e devolve a decisão completa na resposta.Informe o clickId quando o tiver; caso contrário, mande os identificadores que você capturou (visitorId, e-mail do cliente) para o matching multi-sinal. O sourceEventId é a sua chave de idempotência por fato de negócio: o mesmo sourceEventId retorna a conversão já existente, com Idempotent-Replay: true.

cURL

curl -X POST "$REPASS_BASE/conversions" \
  -H "Authorization: Bearer $REPASS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceEventId": "order_8842",
    "type": "sale",
    "amountCents": 9990,
    "customer": { "email": "[email protected]" },
    "visitorId": "vis_01J9Z3P9T4UG0N6XE3ZQ5ALVDH"
  }'

A resposta é um envelope { attributed, deduplicated, replayed, conversion }. Quando uma conversão nova é criada, vem 201 com attributed: true e a conversão completa (com seus snapshots) em conversion.

Resposta 201 (atribuída)

{
  "attributed": true,
  "deduplicated": false,
  "replayed": false,
  "conversion": {
    "id": "conv_01J9Z3Q5V6WH1P7YF4AR6BMWEI",
    "affiliateId": "aff_01J9Z3M2P0RD8K4VC1XN6YHTBE",
    "type": "sale",
    "amountCents": 9990,
    "status": "pending",
    "matchMethod": "visitor_id",
    "attributionSnapshot": { "model": "last_click", "windowDays": 30 },
    "ruleSnapshot": { "version": 1, "type": "percentage", "percentageBps": 2000 },
    "fraudSnapshot": { "score": 0.1, "decision": "approved" }
  }
}

Se o matching não encontra um afiliado, a API responde 200 com attributed: false e conversion: null, e não persiste nada: sem afiliado não há vínculo a registrar. Isso é esperado e não é um erro: significa que a venda não veio de um afiliado.

Resposta 200 (sem atribuição)

{
  "attributed": false,
  "deduplicated": false,
  "replayed": false,
  "conversion": null
}

Atribuição, regra e fraude são congelados em snapshots na conversão no momento do registro. Mudar a regra ou a chave PIX depois não altera o que já foi calculado. Em produção, conversões normalmente chegam pelo webhook do seu gateway de pagamento ou por /ingest/custom; veja Ingestão e o guia Conversões server-to-server.

Acompanhe a comissão até a aprovação

Ao registrar uma conversão atribuída, o Repass cria automaticamente a Comissão do primeiro ciclo de cobrança. Liste as comissões filtrando pela conversão.

cURL

curl "$REPASS_BASE/commissions?conversion_id=conv_01J9Z3Q5V6WH1P7YF4AR6BMWEI" \
  -H "Authorization: Bearer $REPASS_KEY"

Resposta 200

{
  "data": [
    {
      "id": "comm_01J9Z3R1X8YJ2Q8ZG5BS7CNXFJ",
      "conversionId": "conv_01J9Z3Q5V6WH1P7YF4AR6BMWEI",
      "affiliateId": "aff_01J9Z3M2P0RD8K4VC1XN6YHTBE",
      "type": "standard",
      "billingCycle": 1,
      "amountCents": 1998,
      "status": "pending",
      "holdUntil": "2026-07-13T00:00:00.000Z"
    }
  ],
  "hasMore": false
}

A comissão nasce pending com holdUntil = occurredAt + holdDays × 24h (aqui, 30 dias). O detalhe (GET /commissions/{id}) traz o campo calculation aberto (base, percentual em bps, versão da regra aplicada) que reconstrói “por que esse valor?”. No exemplo, 9990 × 2000 bps = 1998 centavos (half-up no centavo).A transição pending → approved acontece automaticamente ao fim do hold, desde que a conversão de origem esteja approved (fraude resolvida) e o afiliado não esteja banned. Você também pode aprovar antecipadamente uma comissão pending com POST /commissions/{id}/approve (aplica as mesmas guardas, exceto a do holdUntil).

O saldo agregado do afiliado (pendente, aprovado não pago, clawbacks, projeção do próximo payout) está em GET /affiliates/{id}/balance. O ciclo de vida completo da comissão (clawback, bônus, void, multi-touch) está em Comissões.

Feche o ciclo e pague (payout)

Comissões approved e não pagas de um afiliado são agregadas em um único Payout no fechamento de ciclo. O fechamento tem dry-run por padrão: sempre inspecione a prévia antes de efetivar.Use POST /payouts/preview (ou POST /payouts/run sem dryRun) para ver quem recebe, quanto, e quais afiliados estão bloqueados, sem persistir nada.

cURL (prévia)

curl -X POST "$REPASS_BASE/payouts/preview" \
  -H "Authorization: Bearer $REPASS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "programId": "prog_01J9ZP6Q8X3K7M2N4R5T6V7W8Y" }'

Para efetivar, repita com dryRun: false explícito. Isso cria os payouts scheduled e reserva as comissões (define payoutId), de modo que um segundo run não duplica nem dupla-cobra.

cURL (efetivar)

curl -X POST "$REPASS_BASE/payouts/run" \
  -H "Authorization: Bearer $REPASS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-2026-07-01" \
  -d '{
    "programId": "prog_01J9ZP6Q8X3K7M2N4R5T6V7W8Y",
    "dryRun": false
  }'

Resposta 200 (run dryRun=false)

{
  "dryRun": false,
  "totals": { "eligibleAmountCents": 1998, "eligibleCount": 1, "blockedCount": 0 },
  "eligible": [
    {
      "affiliateId": "aff_01J9Z3M2P0RD8K4VC1XN6YHTBE",
      "affiliateName": "Parceiro Exemplo",
      "method": "pix",
      "amountCents": 1998,
      "commissionCount": 1
    }
  ],
  "blocked": [],
  "payouts": [
    {
      "id": "pay_01J9Z4T0Z9AB1CD2EF3GH4JK5L",
      "affiliateId": "aff_01J9Z3M2P0RD8K4VC1XN6YHTBE",
      "status": "scheduled",
      "method": "pix",
      "amountCents": 1998,
      "commissionCount": 1
    }
  ]
}

dryRun tem default true. Um POST /payouts/run sem corpo (ou sem dryRun) não cria payouts: apenas calcula a prévia. Envie dryRun: false explicitamente para fechar o ciclo.

O payout nasce scheduled com o destino (chave PIX) snapshotado. A liquidação via PIX acontece automaticamente (scheduled → processing → completed) e, ao concluir, marca todas as comissões incluídas como paid, emitindo payout.completed e um commission.paid por comissão.

Acompanhe o status

curl "$REPASS_BASE/payouts/pay_01J9Z4T0Z9AB1CD2EF3GH4JK5L" \
  -H "Authorization: Bearer $REPASS_KEY"

Pronto: você levou uma indicação do clique à comissão paga. O afiliado recebeu via PIX e cada passo deixou um rastro auditável no event store.

O que muda quando a nota fiscal é exigida

Quando a política fiscal da organização exige NF (nfMode: "affiliate_uploads"), todo afiliado passa pelo gate de nota fiscal antes da liquidação: o fechamento cria uma invoice (inv_…) pending junto do payout, e a liquidação só ocorre depois que a NF fica validated. Enquanto isso, o payout permanece scheduled. Os detalhes da política nfMode, do upload e do gate de validação estão em Fiscal.

Observabilidade: eventos e webhooks

Toda mudança de estado emite um Evento. O fluxo deste guia produz, na ordem aproximada: program.created, commission_rule.created, affiliate.created, affiliate.approved, link.created, click.recorded, conversion.created, commission.created, commission.approved, payout.created e payout.completed (+ commission.paid). Você pode consultar o histórico via GET /events (filtros por type, aggregate_id, período) ou assinar eventos em tempo real configurando um webhook de saída: entregas são assinadas com HMAC e idempotentes (deduplique pelo id do evento).

Histórico de um afiliado

curl "$REPASS_BASE/events?aggregate_type=affiliate&aggregate_id=aff_01J9Z3M2P0RD8K4VC1XN6YHTBE" \
  -H "Authorization: Bearer $REPASS_KEY"

Idempotência e erros

Todo POST aceita o header Idempotency-Key (escopo por organização + usuário): repetir a mesma chave com o mesmo corpo devolve a resposta original com Idempotent-Replay: true. A ingestão de conversões tem uma camada extra de idempotência de negócio pelo sourceEventId. Veja Idempotência. Erros seguem um envelope único { "error": { "type", "code", "message", "param?" } } com status HTTP semântico:

Exemplo de erro 404

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "Affiliate not found."
  }
}

O mapeamento completo de códigos está em Erros.

Próximos passos

Integrar Stripe

Webhook + metadata repass_cid para atribuir cada venda ao afiliado.

Conversões server-to-server

O fluxo completo de matching multi-sinal, atribuição e fraude.

Refund e clawback

Como estornos e chargebacks geram comissões negativas auditáveis.

Reprocessar mudança de regra

Aplicar uma nova versão de regra retroativamente, com dry-run obrigatório.

Multi-touch e atribuição

Dividir a comissão entre vários afiliados que tocaram a jornada.

Introdução

Convenções da API

Conceitos

Webhooks & Eventos

Guias

Integração básica

O fluxo completo

Pré-requisitos

Passos

O que muda quando a nota fiscal é exigida

Observabilidade: eventos e webhooks

Idempotência e erros

Próximos passos

Integrar Stripe

Conversões server-to-server

Refund e clawback

Reprocessar mudança de regra

Multi-touch e atribuição

​O fluxo completo

​Pré-requisitos

​Passos

​O que muda quando a nota fiscal é exigida

​Observabilidade: eventos e webhooks

​Idempotência e erros

​Próximos passos

Integrar Stripe

Conversões server-to-server

Refund e clawback

Reprocessar mudança de regra

Multi-touch e atribuição

O fluxo completo

Pré-requisitos

Passos

O que muda quando a nota fiscal é exigida

Observabilidade: eventos e webhooks

Idempotência e erros

Próximos passos