Idempotência

Redes falham. Se a sua chamada de criação de cobrança expirar por tempo, você não sabe se a cobrança foi criada. Com o header Idempotency-Key você pode repetir a chamada com segurança: a cobrança é criada uma única vez.

Idempotency-Key: pedido-1001

Regras

• Obrigatório nos endpoints de criação (POST /pix, POST /payments, POST /withdrawals). Sem o header a API responde 400 BAD_REQUEST.
• A chave deve ter de 8 a 200 caracteres. Use um valor estável do seu lado, como o id do pedido, ou um UUID gerado uma vez por tentativa de negócio.
• A chave vale por organização e por endpoint.
• Mesma chave, mesmo corpo: a API devolve a resposta original, sem criar nada novo, com o header Idempotent-Replayed: true.
• Mesma chave, corpo diferente: erro 409 CONFLICT. Use uma chave nova para uma operação nova.
• Requisição ainda em processamento: se você repetir enquanto a primeira chamada não terminou, recebe 409 e deve tentar de novo em instantes.

Exemplo de repetição segura

async function criarPix(pedido) {
  for (let tentativa = 1; tentativa <= 3; tentativa++) {
    try {
      const res = await fetch("https://seventyonepay.online/api/v1/pix", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.SEVENTYONE_API_KEY}`,
          "Content-Type": "application/json",
          "Idempotency-Key": `pedido-${pedido.id}`, // mesma chave em todas as tentativas
        },
        body: JSON.stringify(pedido.corpo),
      });
      if (res.status < 500 && res.status !== 409 && res.status !== 429) return res.json();
    } catch {
      // falha de rede: tenta de novo com a MESMA chave
    }
    await new Promise((r) => setTimeout(r, 500 * tentativa));
  }
  throw new Error("Não foi possível confirmar a criação da cobrança");
}