Referência da API

Contrato da API pública (rascunho v0.3, 28/09/2026). Todas as mensagens voltadas a pessoas (title, detail dos erros) são em português do Brasil (D20). Identificadores técnicos (campos, enums, tipos de evento) seguem a convenção de mercado em inglês.

Autenticação

Cada unidade (CNPJ) tem suas próprias chaves de API, por ambiente: Authorization: Bearer sk_live_... (produção) ou Bearer sk_sandbox_... (sandbox). A unidade é sempre derivada da chave — nunca é enviada no corpo da requisição. Chaves de sandbox existem a partir da aprovação jurídica; chaves de produção, após a ativação da unidade.

Valores monetários

Sempre string decimal com duas casas e ponto, em reais (BRL): "123.45". Nunca número de ponto flutuante.

Datas

ISO 8601 em UTC (2026-09-28T20:15:00Z).

Idempotência

Toda requisição POST que cria ou altera recurso exige o cabeçalho Idempotency-Key (até 128 caracteres, recomenda-se UUID v4). A mesma chave com o mesmo corpo devolve a resposta original (com Idempotent-Replayed: true) por 24 horas; com corpo diferente retorna 422 idempotency-key-reused; enquanto a primeira requisição estiver em processamento retorna 409 idempotency-key-in-progress.

Paginação

Por cursor: limit (1–100, padrão 20), starting_after ou ending_before (ID de objeto). Resposta: { "object": "list", "data": [...], "has_more": true, "next_cursor": "..." }. Ordenação estável por data de criação decrescente.

Limites de requisição

Proteções técnicas aplicadas por unidade: taxa de requisições, requisições simultâneas e cotas diárias de cobranças (quantidade e valor, dia no horário de Brasília). Ao excedê-las a API responde 429 com Retry-After e X-RateLimit-Reason (global-rate, concurrency ou quota-daily; na cota diária o code é quota-exceeded e o Retry-After vai até a meia-noite). Cobrança acima do valor permitido por cobrança responde 403 amount-above-limit. Os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset acompanham as respostas autenticadas (janela de 10 segundos). Os valores dos limites não são publicados e podem mudar sem aviso; para ampliá-los, fale com o seu gerente.

Bloqueio de acesso

Por segurança, o acesso de uma integração pode ser bloqueado temporariamente (unidade, chave ou operação). Nesse caso qualquer chamada responde 403 access-blocked; não repita automaticamente — fale com o seu gerente.

Versionamento

Por data, no cabeçalho opcional Api-Version (ex.: 2026-09-28). Sem o cabeçalho, vale a versão fixada na chave de API no momento da sua criação. Adições de campos e de valores de enum não são consideradas quebra de compatibilidade: clientes devem ignorar campos desconhecidos.

Confirmação de pagamento

Uma cobrança só é marcada como paid depois que a plataforma confirma o Pix junto ao banco (endToEndId). Nunca libere mercadoria com base em comprovante enviado pelo pagador: use o evento charge.paid (verificando a assinatura) ou consulte GET /v1/charges/{id}.

Webhooks

Os eventos são enviados por POST (JSON) no padrão Standard Webhooks: webhook-id (id do evento, evt_... — use para deduplicar, é o mesmo em todas as tentativas), webhook-timestamp (Unix, segundos) e webhook-signature = v1,<base64(HMAC-SHA256(segredo, "{id}.{timestamp}.{corpo}"))>, em que a chave HMAC é o segredo whsec_... decodificado de base64. Durante as 24 h seguintes a uma rotação o cabeçalho traz duas assinaturas separadas por espaço; aceite a requisição se qualquer uma conferir. Recuse timestamps com mais de 5 minutos de diferença. Responda 2xx em até 10 segundos; qualquer outro resultado (inclusive redirecionamento) conta como falha e é repetido após 5 s, 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 8 h, 12 h, 24 h e 24 h (cerca de 3,5 dias). Esgotadas as tentativas, o endpoint passa a degraded até a próxima entrega bem-sucedida (por exemplo, um reenvio manual em POST /events/{id}/redeliver); se outra série de tentativas se esgotar ainda em degraded, ele é disabled e o contato do parceiro recebe um e-mail. Reative com PATCH /webhook_endpoints/{id} (status: active). A entrega é "pelo menos uma vez" e sem garantia de ordem: trate data.object como o estado no momento do evento e, antes de liberar mercadoria, confirme em GET /v1/charges/{id}.