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

# Ambientes, headers e convenções

> Base URL, headers padrão, X-Correlation-ID, datas, dinheiro e códigos HTTP.

## Base URL (produção)

```
https://api.clearpago.com.br
```

`TODO: URL de sandbox` — se existir, documente aqui após confirmação com a equipe.

## Headers

| Header             | Obrigatório              | Descrição                                                        |
| ------------------ | ------------------------ | ---------------------------------------------------------------- |
| `Authorization`    | Sim (rotas autenticadas) | `Bearer <seu_api_token>`                                         |
| `Content-Type`     | Sim em `POST` com corpo  | `application/json`                                               |
| `X-Correlation-ID` | Recomendado              | UUID ou string de rastreio; ecoado na resposta quando aplicável. |

## Datas e fusos

Use **ISO 8601** / **RFC 3339** em **UTC**, por exemplo: `2026-04-01T12:00:00.000Z`.

## Valores monetários

* **Requisições (request):** valores em **reais (BRL)** com campo numérico típico `value` ou `refundValue` (número em ponto flutuante, conforme exemplos oficiais).
* **Respostas (response):** com frequência em **centavos** — por exemplo `valueCents`, `refundValueCents` — para evitar erro de ponto flutuante.

Mantenha essa regra em parsers e testes: **não** compare float de BRL com campo em centavos sem conversão explícita.

## Códigos HTTP

| Código | Significado                                             |
| ------ | ------------------------------------------------------- |
| `200`  | Sucesso em `GET` e em webhooks recebidos pelo parceiro. |
| `201`  | Recurso criado.                                         |
| `400`  | Validação de payload.                                   |
| `401`  | Token ausente ou inválido.                              |
| `404`  | Recurso não encontrado.                                 |
| `409`  | Conflito (ex.: `externalId` duplicado).                 |
| `422`  | Regra de negócio violada.                               |
| `500`  | Erro interno.                                           |

## Listagens: paginação e filtros (padrão documentado)

`GET` de listas usam **página** e **limite** (máximo **100**), e filtros de data **inclusivos** em `YYYY-MM-DD` como `start_date` / `end_date` onde a rota suportar.

Filtros de `status` documentados variam por recurso; estados adicionais podem surgir no **detalhe** `GET .../{id}` (ex.: `DISPATCHED`, `PROVIDER_RESULT_UNKNOWN`).

## Envelope de erro (típico)

```json theme={null}
{
  "error": "descrição",
  "status": 400
}
```

Detalhes e troubleshooting: [Tratamento de erros](/errors/error-handling).

## Referência cruzada

* [Mapa de rotas e parâmetros](/api-reference/create-cash-in) — páginas de referência por endpoint.