> ## Documentation Index
> Fetch the complete documentation index at: https://userepass.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> O que é o Repass e as superfícies da plataforma: painel, portal white-label, API, SDK, CLI e servidor MCP.

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

<CardGroup cols={2}>
  <Card title="Painel do gestor" icon="gauge-high">
    App web onde a organização gerencia programas, afiliados, comissões, payouts e fiscal.
  </Card>

  <Card title="Portal do afiliado (white-label)" icon="palette">
    Área do afiliado com a marca e o domínio do próprio cliente: links, comissões, saldo, payouts e envio de nota fiscal.
  </Card>

  <Card title="API, SDK e CLI" icon="code">
    API REST completa, com SDK TypeScript oficial e CLI para automação e integração server-to-server.
  </Card>

  <Card title="Servidor MCP" icon="robot">
    As operações expostas a agentes de IA via Model Context Protocol, com níveis de risco e confirmação.
  </Card>
</CardGroup>

## O ciclo que o Repass resolve

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

1. **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.
2. **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.
3. **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.
4. **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.
5. **Pagar (payout)**: fechamento de ciclo agregando comissões aprovadas menos clawbacks, com bloqueios de elegibilidade, execução via PIX e recibo.
6. **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.
7. **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.                                                                                       |

<Note>
  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.
</Note>

## 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).

```mermaid theme={null}
erDiagram
    programa ||--o{ afiliado : "recruta"
    programa ||--o{ regra_comissao : "versiona"
    afiliado ||--o{ link : "divulga"
    afiliado ||--o{ cupom : "possui"
    link ||--o{ clique : "gera"
    clique ||--o{ conversao : "atribui (clique)"
    cupom ||--o{ conversao : "atribui (cupom)"
    afiliado ||--o{ conversao : "ganha"
    conversao ||--o{ comissao : "origina (por ciclo)"
    comissao }o--o| payout : "liquidada em"
    afiliado ||--o{ payout : "é pago via"
    payout ||--o| nota_fiscal : "exige NF (nfMode)"
```

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](/docs/convencoes/ids-e-recursos).

<Note>
  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ã".
</Note>

## 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.

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor V as Visitante
    participant T as /t/{token}
    participant GW as Gateway (Stripe)
    participant ING as /ingest/stripe/{orgId}
    participant CONV as Conversão + atribuição + fraude
    participant COMM as Comissão
    participant PAY as Payout
    participant WH as Webhook de saída
    participant EXT as Sistema externo

    V->>T: GET /t/{token}
    T-->>V: 302 destino (+ cookie de visitante)
    Note over V,GW: cliente compra; gateway dispara webhook
    GW->>ING: POST /ingest/stripe/{orgId} (assinado)
    ING->>CONV: evento normalizado (venda)
    CONV->>CONV: matching + modelo de atribuição + score de fraude
    alt sem afiliado
        CONV-->>ING: 200 attributed:false (não persiste)
    else atribuído
        CONV->>COMM: cria conversão + comissão do ciclo 1
    end
    Note over COMM,PAY: fim do hold + fechamento de ciclo
    COMM->>COMM: aprova comissões em hold
    PAY->>PAY: agrega aprovadas − clawbacks, checa elegibilidade
    PAY->>PAY: executa PIX, marca comissões paid
    Note over WH,EXT: eventos entregues a sistemas externos
    WH->>EXT: POST assinado (Repass-Signature)
    EXT-->>WH: 2xx → entregue (senão retry com backoff)
```

Uma conversão server-to-server, sem passar pelo gateway, é registrada diretamente:

<CodeGroup>
  ```bash cURL theme={null}
  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": "cliente@exemplo.com" },
      "clickId": "clk_01HZX..."
    }'
  ```

  ```json Resposta theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>

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

## Diferenciais

<CardGroup cols={2}>
  <Card title="Regras versionadas e imutáveis" icon="lock">
    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.
  </Card>

  <Card title="Atribuição multi-touch" icon="route">
    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.
  </Card>

  <Card title="Eventos e auditoria" icon="database">
    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.
  </Card>

  <Card title="Reprocessamento com dry-run" icon="rotate">
    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.
  </Card>
</CardGroup>

## Mapa de módulos

<CardGroup cols={2}>
  <Card title="Programas e regras" icon="sitemap" href="/docs/conceitos/programas-e-regras">
    Programa, regras de comissão versionadas, tiers e ciclo de vida.
  </Card>

  <Card title="Afiliados" icon="users" href="/docs/conceitos/afiliados">
    Cadastro, máquina de estados, modos de aprovação, perfil de pagamento e dados fiscais.
  </Card>

  <Card title="Links e cupons" icon="link" href="/docs/conceitos/links-e-cupons">
    Links de rastreamento com token único e cupons sincronizados com o gateway.
  </Card>

  <Card title="Tracking" icon="crosshairs" href="/docs/conceitos/tracking">
    Redirect `/t/{token}`, registro de clique, identidade de visitante, geo e bot filtering.
  </Card>

  <Card title="Atribuição" icon="route" href="/docs/conceitos/atribuicao">
    Os cinco modelos, matching multi-sinal e o conflito entre cupom e clique.
  </Card>

  <Card title="Conversões e fraude" icon="shield-halved" href="/docs/conceitos/conversoes-e-fraude">
    Atribuição, dedupe/upgrade, score de fraude determinístico e fila de revisão.
  </Card>

  <Card title="Comissões" icon="calculator" href="/docs/conceitos/comissoes">
    Cálculo inteiro, recorrência, tiers, split, estados e clawback.
  </Card>

  <Card title="Payouts" icon="money-bill-transfer" href="/docs/conceitos/payouts">
    Fechamento de ciclo, bloqueios de elegibilidade, preview/run e execução PIX.
  </Card>

  <Card title="Fiscal" icon="file-invoice" href="/docs/conceitos/fiscal">
    Política `nfMode` e fluxo de nota fiscal (upload + validação) antes da liquidação.
  </Card>

  <Card title="Reprocessamento" icon="rotate" href="/docs/conceitos/reprocessamento">
    Recálculo retroativo com dry-run obrigatório e dupla confirmação.
  </Card>

  <Card title="Eventos" icon="database" href="/docs/conceitos/event-store">
    Consulta de eventos via API e taxonomia de eventos.
  </Card>

  <Card title="Ingestão" icon="inbox-in" href="/docs/conceitos/ingestao">
    Evento normalizado gateway-agnóstico, Stripe e `/ingest/custom`.
  </Card>
</CardGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
    Sua primeira chamada à API, do programa ao tracking.
  </Card>

  <Card title="Autenticação" icon="key" href="/docs/autenticacao">
    API keys `rstr_...` para integração server-to-server, papéis e multi-tenancy por organização.
  </Card>

  <Card title="Integração básica" icon="plug" href="/docs/guias/integracao-basica">
    Guia ponta a ponta de uma integração: programa, afiliado, link e primeira conversão.
  </Card>

  <Card title="Integrar Stripe" icon="credit-card" href="/docs/guias/integrar-stripe">
    Webhook + metadata `repass_cid` para atribuir cada venda ao afiliado.
  </Card>
</CardGroup>