Introdução

O Repass é uma plataforma SaaS multi-tenant de gestão de programas de afiliados. O cliente do Repass é uma organização (a empresa que vende um produto ou serviço, tipicamente uma assinatura recorrente) que quer recrutar afiliados, rastrear as indicações deles, calcular comissões corretamente, pagar os afiliados e cumprir as obrigações fiscais, tudo de forma auditável. É uma plataforma API-first, AI-first e agent-native: além da API REST, oferece um painel web para o gestor, um portal do afiliado white-label (domínio e marca do próprio cliente), SDK e CLI oficiais, um servidor MCP que expõe as operações a agentes de IA e recursos assistidos por IA, como a extração automática de dados de notas fiscais. Esta documentação cobre a superfície programável do produto: API, SDK, CLI e MCP.

Superfícies da plataforma

Painel do gestor

App web onde a organização gerencia programas, afiliados, comissões, payouts e fiscal.

Portal do afiliado (white-label)

Área do afiliado com a marca e o domínio do próprio cliente: links, comissões, saldo, payouts e envio de nota fiscal.

API, SDK e CLI

API REST completa, com SDK TypeScript oficial e CLI para automação e integração server-to-server.

Servidor MCP

As operações expostas a agentes de IA via Model Context Protocol, com níveis de risco e confirmação.

O ciclo que o Repass resolve

O Repass cobre o ciclo completo, ponta a ponta, da economia de indicação:

Atrair e gerenciar afiliados: cadastro, aprovação (automática, manual ou por whitelist de domínio), aceite de termos, classificação por tier e perfil de pagamento.
Rastrear a divulgação: links de rastreamento com token único e cupons sincronizados com o gateway de pagamento, registrando cada clique com identidade do visitante, geolocalização e detecção de bot.
Atribuir conversões: quando uma venda acontece (recebida do gateway via webhook ou registrada via API), o Repass decide a qual afiliado a venda pertence, resolve o conflito entre cupom e clique e roda um score de fraude determinístico.
Calcular comissão: aritmética 100% inteira (centavos / basis points), regras versionadas e imutáveis, recorrência, tiers por volume e split multi-touch. Cada cobrança de uma assinatura recorrente gera uma comissão por ciclo.
Pagar (payout): fechamento de ciclo agregando comissões aprovadas menos clawbacks, com bloqueios de elegibilidade, execução via PIX e recibo.
Cumprir o fiscal: fluxo de nota fiscal (upload + validação) definido pela política nfMode da organização, com o pagamento bloqueado até a NF ser validada.
Auditar e integrar: todo fato de negócio vira um evento, consultável via API e entregue a sistemas externos por webhooks de saída assinados.

Glossário de domínio

Estes termos aparecem em toda a documentação. A terminologia canônica é sempre a coluna Termo.

Termo	Significado
Organização	O tenant do Repass, a empresa cliente. Tudo é escopado por organização (multi-tenancy).
Programa	Um programa de afiliados dentro da organização: define moeda (BRL), modelo e janela de atribuição, política de cupom, base de comissão, hold e modo de aprovação.
Regra de comissão	Versão imutável de como calcular comissão (percentual / fixo / tiered + recorrência). Versionada por programa: só cria nova versão, nunca edita.
Tier	Faixa nomeada do programa (ex.: bronze/prata/ouro) que aponta para uma versão de regra.
Afiliado	O parceiro que divulga (pessoa jurídica). Tem status, tier, perfil de pagamento e dados fiscais (CNPJ).
Termos	Versões de termos do programa que o afiliado aceita.
Link	Link de rastreamento com token único global, destino e subId. Resolvido na rota pública `/t/{token}`.
Cupom	Código de desconto vinculado a um afiliado, sincronizado com o gateway; método de atribuição alternativo ao clique.
Clique	Registro de um acesso ao link: visitante, fingerprint, IP/geo, device, referrer, janela de expiração e flag de bot.
Conversão	A venda atribuída a um afiliado, com snapshots de atribuição, regra e fraude. Sem afiliado, não há conversão persistida.
Comissão	Valor devido ao afiliado por uma cobrança. Tipos: standard, clawback, bonus, adjustment. Uma por ciclo de cobrança.
Clawback	Comissão negativa criada por estorno ou chargeback.
Payout	Pagamento agregado a um afiliado num ciclo (aprovadas − clawbacks), com destino snapshotado.
Nota fiscal	Obrigação fiscal que nasce com o payout quando a política `nfMode` a exige; precisa ser validada antes da liquidação.
Atribuição	A decisão de a qual afiliado uma conversão pertence, segundo o modelo configurado no programa.
Reprocessamento	Recálculo retroativo de comissões de um programa num intervalo, com dry-run obrigatório.
Evento	Fato de negócio imutável. Toda mudança de estado emite eventos, consultáveis via API.
Webhook	Assinatura externa que recebe eventos, com entrega assinada (HMAC) e retry.

Dinheiro é sempre inteiro em centavos (amountCents) e percentuais em basis points (*Bps, onde 100 bps = 1%). Não há ponto flutuante no modelo. Isso elimina erros de arredondamento.

Modelo de entidades

As entidades de negócio se encadeiam do programa até o pagamento. Toda entidade pertence a uma organização (omitida abaixo por clareza). Cada entidade tem um identificador único com prefixo + ULID: prog_, aff_, link_, coup_, conv_, comm_, pay_, inv_, evt_, whep_. Os prefixos tornam o tipo do recurso óbvio nos payloads e nas mensagens de erro. Veja IDs e recursos.

A conversão é o vínculo entre afiliado e venda. Se o matching não encontra afiliado, a API responde 200 {"attributed": false} sem persistir nada. Não existe conversão “órfã”.

Fluxo end-to-end

O diagrama abaixo segue uma indicação da vida inteira: o visitante clica no link, o gateway confirma a venda, a conversão é atribuída e checada por fraude, a comissão é calculada e aprovada, o payout fecha o ciclo, a NF é validada quando o regime exige e o evento é entregue a um sistema externo via webhook. Uma conversão server-to-server, sem passar pelo gateway, é registrada diretamente:

curl https://api.userepass.com/conversions \
  -H "Authorization: Bearer rstr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "programId": "prog_01HZX...",
    "type": "subscription_created",
    "amountCents": 19900,
    "sourceEventId": "order_4821",
    "customer": { "id": "cust_8842", "email": "[email protected]" },
    "clickId": "clk_01HZX..."
  }'

{
  "attributed": true,
  "deduplicated": false,
  "replayed": false,
  "conversion": {
    "id": "conv_01HZX...",
    "affiliateId": "aff_01HZX...",
    "amountCents": 19900,
    "currency": "BRL",
    "status": "pending",
    "matchMethod": "click_id",
    "createdAt": "2026-06-13T12:30:00.000Z"
  }
}

Para a referência completa de campos e respostas de cada endpoint, veja a aba Referência da API.

Diferenciais

Regras versionadas e imutáveis

Uma regra de comissão nunca é editada: só se cria uma nova versão. Cada conversão guarda um snapshot da regra, da atribuição e da fraude, congelando o cálculo no momento da venda.

Atribuição multi-touch

Cinco modelos de atribuição (last/first click, linear, time decay, position based) com matching multi-sinal por clique, visitante, hash de e-mail e fingerprint, mais conflito cupom×clique e split entre afiliados.

Eventos e auditoria

Todo fato de negócio vira um evento imutável. É a fonte de auditoria, consultável via API, e o que alimenta os webhooks de saída.

Reprocessamento com dry-run

Recálculo retroativo de comissões sobre os snapshots congelados, com dry-run obrigatório e dupla confirmação por token antes de qualquer ajuste ser aplicado.

Mapa de módulos

Programas e regras

Programa, regras de comissão versionadas, tiers e ciclo de vida.

Afiliados

Cadastro, máquina de estados, modos de aprovação, perfil de pagamento e dados fiscais.

Links e cupons

Links de rastreamento com token único e cupons sincronizados com o gateway.

Tracking

Redirect /t/{token}, registro de clique, identidade de visitante, geo e bot filtering.

Atribuição

Os cinco modelos, matching multi-sinal e o conflito entre cupom e clique.

Conversões e fraude

Atribuição, dedupe/upgrade, score de fraude determinístico e fila de revisão.

Comissões

Cálculo inteiro, recorrência, tiers, split, estados e clawback.

Payouts

Fechamento de ciclo, bloqueios de elegibilidade, preview/run e execução PIX.

Fiscal

Política nfMode e fluxo de nota fiscal (upload + validação) antes da liquidação.

Reprocessamento

Recálculo retroativo com dry-run obrigatório e dupla confirmação.

Eventos

Consulta de eventos via API e taxonomia de eventos.

Ingestão

Evento normalizado gateway-agnóstico, Stripe e /ingest/custom.

Próximos passos

Quickstart

Sua primeira chamada à API, do programa ao tracking.

Autenticação

API keys rstr_... para integração server-to-server, papéis e multi-tenancy por organização.

Integração básica

Guia ponta a ponta de uma integração: programa, afiliado, link e primeira conversão.

Integrar Stripe

Webhook + metadata repass_cid para atribuir cada venda ao afiliado.

Convenções da API

Conceitos

Webhooks & Eventos

Guias

Introdução

Superfícies da plataforma

Painel do gestor

Portal do afiliado (white-label)

API, SDK e CLI

Servidor MCP

O ciclo que o Repass resolve

Glossário de domínio

Modelo de entidades

Fluxo end-to-end

Diferenciais

Regras versionadas e imutáveis

Atribuição multi-touch

Eventos e auditoria

Reprocessamento com dry-run

Mapa de módulos

Programas e regras

Afiliados

Links e cupons

Tracking

Atribuição

Conversões e fraude

Comissões

Payouts

Fiscal

Reprocessamento

Eventos

Ingestão

Próximos passos

Quickstart

Autenticação

Integração básica

Integrar Stripe

​Superfícies da plataforma

Painel do gestor

Portal do afiliado (white-label)

API, SDK e CLI

Servidor MCP

​O ciclo que o Repass resolve

​Glossário de domínio

​Modelo de entidades

​Fluxo end-to-end

​Diferenciais

Regras versionadas e imutáveis

Atribuição multi-touch

Eventos e auditoria

Reprocessamento com dry-run

​Mapa de módulos

Programas e regras

Afiliados

Links e cupons

Tracking

Atribuição

Conversões e fraude

Comissões

Payouts

Fiscal

Reprocessamento

Eventos

Ingestão

​Próximos passos

Quickstart

Autenticação

Integração básica

Integrar Stripe

Superfícies da plataforma

O ciclo que o Repass resolve

Glossário de domínio

Modelo de entidades

Fluxo end-to-end

Diferenciais

Mapa de módulos

Próximos passos