Idempotência

Operações mutáveis da API exigem o header Idempotency-Key para garantir que uma operação não seja executada mais de uma vez em caso de retentativas de rede.

Por que usar?

Em sistemas distribuídos, uma requisição pode falhar por diversos motivos (timeout, queda de conexão) após o servidor já ter processado a operação. Ao repetir a requisição com a mesma Idempotency-Key, o servidor reconhece a duplicidade e retorna o resultado da operação original sem executá-la novamente.

Endpoints que exigem Idempotência

O header Idempotency-Key é obrigatório em todos os métodos POST, PUT e PATCH, incluindo:

• Transferências PIX Out
• Geração de QR Code dinâmico
• Solicitações de devolução

Como funciona

1. Primeira requisição: O cliente envia a requisição com uma Idempotency-Key única (recomendamos o uso de UUID v4). O servidor processa a operação e armazena o resultado.
2. Requisições subsequentes (mesma chave):
   • Se o payload for idêntico, o servidor retorna o resultado armazenado anteriormente (HTTP 200/201/202).
   • Se o payload for diferente, o servidor retorna um erro de conflito (HTTP 409 idempotency_conflict).

Expiração

As chaves de idempotência são armazenadas por um período de 24 horas. Após esse período, a chave expira e uma nova requisição com a mesma chave será tratada como uma nova operação.

Boas Práticas

• Geração de chaves: Utilize identificadores universalmente únicos (UUID). Não tente reutilizar chaves entre diferentes tipos de operações.
• Retentativas: Implemente uma estratégia de retry com backoff exponencial para erros de rede (5xx), sempre mantendo a mesma Idempotency-Key.
• Tratamento do 409: Se você receber um 409 idempotency_conflict, verifique se está tentando enviar uma operação diferente com uma chave que já foi utilizada para outro propósito.