Convenções

Regras transversais que valem para toda a API.

Valores monetários

Todos os valores são inteiros em centavos de Real (BRL).

Exibição	Na API
R$ 19,90	1990
R$ 1,00	100
R$ 0,01	1

Isso evita erros de arredondamento de ponto flutuante.

Datas e fuso

• Formato ISO‑8601 em UTC (ex.: 2026-06-03T14:25:00.000Z).
• Converta para o fuso do usuário apenas na exibição.

Identificadores

• IDs são opacos (não derive lógica do formato).
• Sempre persista o id retornado para reconciliação.

Idempotência

Operações que criam dinheiro/efeito (ex.: POST /v1/pix, POST /v1/withdraw) aceitam o header Idempotency-Key (recomendado: um UUID por tentativa lógica).

• Reenviar a mesma chave retorna o mesmo resultado, sem duplicar a operação.
• Reuso de chave com payload diferente retorna conflito (IDEMPOTENCY_CONFLICT).

Sempre envie Idempotency-Key em criação de cobrança e saque. É a sua proteção contra cliques duplos, retries de rede e reenvios.

Paginação

Listagens aceitam parâmetros de página/limite e filtros por período. Verifique a Referência da API para os parâmetros exatos de cada rota.

Cabeçalhos padrão

Header	Uso
Authorization	Bearer <API_TOKEN> (obrigatório)
Content-Type	application/json
Idempotency-Key	Recomendado em operações de escrita