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

# Configuração

> Inicialização do client, base URL, timeout, retries, fetch customizado, idempotência e opções por requisição.

## Inicialização

O construtor aceita a chave de forma posicional ou um objeto de configuração.

<CodeGroup>
  ```ts Chave posicional theme={null}
  import { Repass } from "@repass/sdk";

  const repass = new Repass("rstr_...");
  ```

  ```ts Objeto de configuração theme={null}
  import { Repass } from "@repass/sdk";

  const repass = new Repass({
    apiKey: "rstr_...",
    baseUrl: "https://api.userepass.com",
    timeout: 60_000,
    maxRetries: 2,
  });
  ```

  ```ts Da variável de ambiente theme={null}
  import { Repass } from "@repass/sdk";

  // Sem argumento, lê process.env.REPASS_API_KEY
  const repass = new Repass();
  ```
</CodeGroup>

Se nenhuma chave for passada nem encontrada em `REPASS_API_KEY`, o construtor lança um `RepassError` com `code: "missing_api_key"`.

## Opções do client

<ParamField path="apiKey" type="string">
  Chave da organização (`rstr_…`). Default: `process.env.REPASS_API_KEY`. Determina o tenant no servidor.
</ParamField>

<ParamField path="baseUrl" type="string" default="https://api.userepass.com">
  URL base da API.
</ParamField>

<ParamField path="timeout" type="number" default="60000">
  Tempo máximo por requisição, em milissegundos. Ao estourar, a requisição é abortada e lança `RepassTimeoutError`.
</ParamField>

<ParamField path="maxRetries" type="number" default="2">
  Retentativas em `429`, `5xx` e falhas de rede, com backoff exponencial e jitter (respeita `Retry-After`).
</ParamField>

<ParamField path="fetch" type="(url, init) => Promise<Response>">
  Implementação de `fetch` a usar. Default: `globalThis.fetch`. Útil para testes ou runtimes específicos.
</ParamField>

<ParamField path="headers" type="Record<string, string>">
  Headers padrão enviados em todas as requisições.
</ParamField>

<ParamField path="authScheme" type="&#x22;bearer&#x22; | &#x22;api-key&#x22;" default="bearer">
  Como a chave é enviada: `bearer` (`Authorization: Bearer …`) ou `api-key` (header `x-api-key`).
</ParamField>

## Opções por requisição

Todo método aceita um `options` final do tipo `RequestOptions`, que sobrepõe os defaults do client para aquela chamada:

<ParamField path="idempotencyKey" type="string">
  Valor do header `Idempotency-Key`. Recomendado em POSTs sensíveis (ver abaixo).
</ParamField>

<ParamField path="signal" type="AbortSignal">
  Aborta a requisição quando o signal dispara (compõe com o `timeout`).
</ParamField>

<ParamField path="timeout" type="number">
  Sobrescreve o timeout só para esta requisição.
</ParamField>

<ParamField path="maxRetries" type="number">
  Sobrescreve o número de retentativas só para esta requisição.
</ParamField>

<ParamField path="headers" type="Record<string, string>">
  Headers extras só para esta requisição.
</ParamField>

```ts Exemplo theme={null}
const controller = new AbortController();

await repass.payouts.run(
  { affiliateIds: ["aff_..."] },
  { idempotencyKey: "payout-run-2026-06", timeout: 120_000, signal: controller.signal },
);
```

## Idempotência e retries

POSTs aceitam o header `Idempotency-Key` (escopo por organização + usuário, TTL de 24h): repetir a mesma chave com o mesmo corpo devolve a resposta original. Veja [Idempotência](/docs/convencoes/idempotencia).

* Passe `options.idempotencyKey` para controlar a chave explicitamente, **recomendado** em operações de efeito colateral pesado, como `payouts.run` ou `reprocess.execute`.
* Quando `maxRetries > 0`, o SDK **gera automaticamente** uma chave para POSTs sem chave, tornando o retry seguro (não duplica o efeito).

<Note>
  Requisições idempotentes por natureza (`GET`, `PUT`, `DELETE`) são re-tentadas livremente. `POST`/`PATCH` só são re-tentados quando há chave de idempotência. Uploads multipart (`invoices.submit`) nunca são re-tentados automaticamente.
</Note>

## ID da requisição

Quando a API retorna o header de request id, ele fica disponível em `error.requestId` nos erros, útil para suporte. Veja [Erros](/docs/sdk/erros).