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

# Ambientes e limites

> URLs base, versionamento e limites de uso da API.

A API do Repass atende todas as contas sob o mesmo conjunto de endpoints, e o isolamento entre elas é resolvido pela autenticação: cada chamada carrega exatamente uma conta. Esta página reúne o que você precisa para apontar seu cliente ao ambiente certo, entender como a API é versionada e como o consumo é limitado.

## URL base

Todos os endpoints autenticados ficam sob a mesma origem. Não há prefixo de caminho por ambiente: o que muda é apenas o host.

| Ambiente | URL base                    |
| -------- | --------------------------- |
| Produção | `https://api.userepass.com` |

Prefixe todos os caminhos desta documentação com a URL base. Por exemplo, `POST /conversions` é, na prática, `POST https://api.userepass.com/conversions`.

```bash cURL theme={null}
curl https://api.userepass.com/health
```

Autentique cada requisição com uma chave de API no header `Authorization`. As chaves têm o prefixo `rstr_`:

```bash cURL theme={null}
curl https://api.userepass.com/programs \
  -H "Authorization: Bearer rstr_..."
```

Para o detalhamento dos métodos de autenticação (sessão e chave de API), veja [Autenticação](/docs/autenticacao).

## Versionamento

Não há versionamento por caminho de URL nem por header de versão: os endpoints vivem na raiz do host (`/programs`, `/conversions`, `/payouts`, …), sem prefixo `/v1`. Evoluções compatíveis (novos endpoints e novos campos opcionais em respostas) são aplicadas no lugar.

<Info>
  Trate as respostas como **aditivas**: novos campos podem aparecer com o tempo, então ignore o que você não conhece em vez de falhar na desserialização.
</Info>

## Health check

`GET /health` é um endpoint público, sem autenticação e sem efeitos colaterais. Use-o em load balancers e monitoramento para verificar se a API está no ar. Responde sempre `200`:

```bash cURL theme={null}
curl https://api.userepass.com/health
```

```json theme={null}
{ "status": "ok" }
```

## Limites de uso

O Repass aplica limites de consumo **por chave de API**, não por conta ou por endereço IP. Quando o limite está habilitado em uma chave, ela tem uma cota de requisições dentro de uma janela de tempo deslizante; ao estourar a cota, as requisições daquela chave são recusadas até a janela renovar.

Os limites são configurados na própria chave de API:

* **Cota**: número máximo de requisições dentro da janela.
* **Janela**: duração da janela em que a cota é contada (por padrão, 24 horas).

Como o limite é por chave, emitir chaves distintas para integrações distintas isola o consumo de uma da outra.

<Note>
  O limite vive na chave de API e é gerenciado junto da chave (veja [Autenticação](/docs/autenticacao)). A API não expõe headers HTTP de rate limit (do tipo `RateLimit-*` ou `Retry-After`) nas respostas. Não dependa deles. Para integrações de alto volume, dimensione a cota da chave ao seu tráfego esperado.
</Note>

### Idempotência sob retry

Limites e falhas transitórias tornam o retry inevitável em integrações sérias. Para que repetir um `POST` não crie recursos duplicados (um Programa a mais, uma Comissão a mais), envie o header `Idempotency-Key`: o Repass faz replay da resposta original (com o header `Idempotent-Replay: true`) em vez de reexecutar a operação.

```bash cURL theme={null}
curl -X POST https://api.userepass.com/programs \
  -H "Authorization: Bearer rstr_..." \
  -H "Idempotency-Key: 9f1c2e7a-3b4d-4f56-8a90-1c2d3e4f5a6b" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Programa de Afiliados" }'
```

O detalhe completo (escopo da chave, TTL, replay, conflitos) está em [Idempotência](/docs/convencoes/idempotencia).

<Note>
  O registro de Conversões em server-to-server (`POST /conversions`) tem idempotência de negócio própria e permanente: reenvios com o mesmo `sourceEventId` retornam a Conversão original com `Idempotent-Replay: true`, sem depender do header `Idempotency-Key`. As rotas públicas de ingestão (`/ingest/`, `/t/`, `/track/`) ficam de fora do header `Idempotency-Key` por esse mesmo motivo. Valores monetários trafegam em centavos e percentuais em basis points.
</Note>

## Onde os limites se aplicam

```mermaid theme={null}
sequenceDiagram
    participant C as Cliente
    participant API as API Repass

    C->>API: POST /conversions (Authorization: Bearer rstr_...)
    Note over API: 1. Resolve a chave de API → conta
    Note over API: 2. Verifica a cota da chave (janela de tempo)
    alt Dentro da cota
        API-->>C: 2xx, operação processada
    else Cota estourada
        API-->>C: erro, requisição recusada até a janela renovar
    end
```

## Próximos passos

<CardGroup cols={2}>
  <Card title="Autenticação" icon="key" href="/docs/autenticacao">
    Como autenticar com sessão e com chave de API `rstr_`.
  </Card>

  <Card title="Idempotência" icon="rotate" href="/docs/convencoes/idempotencia">
    Retry seguro de POSTs com `Idempotency-Key`.
  </Card>

  <Card title="Erros" icon="triangle-exclamation" href="/docs/convencoes/erros">
    Envelope de erro único e mapeamento HTTP.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
    Primeira chamada à API, do zero.
  </Card>
</CardGroup>