Idempotência

Como usar o cabeçalho Idempotency-Key para repetir chamadas à API da SinapsePay com segurança, sem criar cobranças ou devoluções em dobro.

Todo POST exige o cabeçalho Idempotency-Key: um texto seu, de até 255 caracteres, que identifica aquele pedido.

Idempotency-Key: pedido-1042

Repetir o mesmo pedido com a mesma chave devolve a mesma resposta (mesmo status e a cobrança atual), sem criar nada de novo. Caiu a conexão no meio? Repita sem medo.
Exceção a favor de você: um PIX criado com 202 (ainda emitindo) que o banco já emitiu responde 201 na repetição, com o copia e cola.
Usar a mesma chave com um corpo diferente é recusado (422, campo Idempotency-Key): a chave identifica um pedido só.
A chave vale por 24 horas.
Sem o cabeçalho: 400 IDEMPOTENCY_KEY_REQUIRED.

Dica: use algo que já identifique a operação no seu sistema, como pedido-1042 para criar e devolucao-1042-1 para devolver.