Tema
Idempotência
Rede lenta, tempo esgotado, botão clicado duas vezes: o seu sistema pode mandar a mesma cobrança duas vezes. A API protege a criação de cobranças para que isso não gere duas cobranças.
Vale para POST /billing/charges e para os apelidos POST /invoices e POST /invoicesv2.
O cabeçalho Idempotency-Key
Mande uma chave única por cobrança que o seu sistema quer criar:
http
POST /billing/charges
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Content-Type: application/json
Idempotency-Key: pedido-12345- Texto livre, até 255 caracteres. Acima disso:
422. - Use um valor ligado ao seu registro, como o número do pedido (
pedido-12345), ou um UUID gerado e guardado antes da primeira tentativa. - A chave vale para a sua conta e não expira.
O que acontece em cada caso
| Situação | Resposta |
|---|---|
| Chave nova | A cobrança é criada normalmente (201). |
| Mesma chave, mesmos dados, primeira chamada concluída | A API repete a primeira resposta (mesmo status e mesmo corpo), sem criar outra cobrança. Vem o cabeçalho Idempotent-Replayed: true. |
| Mesma chave, mesmos dados, primeira chamada ainda em andamento | 409 — Esta cobrança já está sendo criada. Aguarde a conclusão. |
Mesma chave, mesmos dados, primeira chamada terminou com erro 5xx | 409 — Esta cobrança já foi enviada e o resultado está em verificação. Confira a lista de cobranças antes de tentar de novo. |
Mesma chave, mesmos dados, primeira chamada recusada com 4xx (ex.: 422) | A chamada é processada de novo. Se você mudar o corpo para corrigir, use uma chave nova. |
| Mesma chave, dados diferentes | 422 — Esta Idempotency-Key já foi usada com outros dados. Gere uma nova chave para uma nova cobrança. |
"Mesmos dados" quer dizer o mesmo corpo JSON. A ordem dos campos e espaços no começo ou no fim dos textos não fazem diferença.
Sem o cabeçalho
Sem Idempotency-Key, a API compara o corpo da chamada com as cobranças criadas pela sua conta nos últimos 2 minutos:
- corpo igual dentro de 2 minutos: responde como repetição (tabela acima);
- depois de 2 minutos: cria uma cobrança nova.
Duas cobranças iguais de propósito
Precisa criar duas cobranças idênticas (mesmo cliente, valor e vencimento) em menos de 2 minutos? Mande uma Idempotency-Key diferente em cada uma. Com o cabeçalho, só a chave decide se é repetição.
Como tentar de novo com segurança
- Gere a chave antes da primeira tentativa e guarde-a junto com o pedido.
- Em erro de rede, tempo esgotado ou
5xx: tente de novo com a mesma chave e o mesmo corpo. - Recebeu
409? Espere alguns segundos. Depois consulte a lista (GET /billing/charges) antes de tentar outra vez. - Recebeu
422por dados inválidos? Corrija e mande de novo com uma chave nova (o corpo mudou; com a chave antiga a resposta seria422de chave já usada com outros dados). - Nunca reaproveite uma chave para outra cobrança.
js
import { randomUUID } from 'node:crypto';
async function createChargeWithRetry(order, maxAttempts = 3) {
// Generate once and store it with the order before the first attempt
order.idempotencyKey ??= randomUUID();
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const token = await getValidToken();
let response;
try {
response = await fetch('https://v1.api.fastgivr.com.br/billing/charges', {
method: 'POST',
headers: {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
'Idempotency-Key': order.idempotencyKey,
},
body: JSON.stringify(order.chargePayload),
});
} catch (networkError) {
if (attempt === maxAttempts) throw networkError;
await new Promise((resolve) => setTimeout(resolve, attempt * 2000));
continue;
}
const body = await response.json();
if (response.status === 200 || response.status === 201) return body.data;
if (response.status === 409 || response.status >= 500) {
if (attempt === maxAttempts) throw new Error(`Check the charge list before retrying: HTTP ${response.status}`);
await new Promise((resolve) => setTimeout(resolve, attempt * 2000));
continue;
}
throw new Error(`Charge refused: HTTP ${response.status} ${body.message ?? ''}`);
}
}Outras chamadas
Consultar (GET) e alterar (PUT) não têm essa proteção, e não precisam: repetir a mesma consulta ou a mesma alteração dá o mesmo resultado.