Idempotência

Em sistemas distribuídos e redes não confiáveis, é comum que requisições se percam ou que a resposta não chegue ao cliente, mesmo que o servidor tenha processado o pedido. A Idempotência garante que repetir a mesma requisição múltiplas vezes tenha o mesmo efeito que fazê-la apenas uma vez.

Por que usar?

Imagine que você envie uma requisição para "Pagar Boleto". Se a conexão cair antes da resposta, você não sabe se pagou ou não. Se tentar de novo sem idempotência, pode pagar duas vezes. Com idempotência, o servidor reconhece que é a mesma tentativa e retorna o sucesso da primeira, sem cobrar novamente.

Como implementar (Header Idempotency-Key)

A API da QuettaCode suporta idempotência em operações críticas (POST, PATCH) através do header Idempotency-Key.

1. O cliente gera uma chave única (ex: um UUID v4) para a operação.
2. O cliente envia a requisição com o header: Idempotency-Key: a1b2c3d4-uuid-unico
3. O servidor processa e salva o resultado associado a essa chave.
4. Se o cliente enviar a mesma requisição com a mesma chave:
   • O servidor NÃO reprocessa a operação.
   • O servidor retorna a mesma resposta que retornou (ou retornaria) na primeira vez.

Expiração

As chaves de idempotência são armazenadas temporariamente (ex: 24 horas). Após esse período, uma nova requisição com a mesma chave será tratada como nova.

Onde usar?

Recomendamos usar em todas as operações de Criação (POST) e Pagamento, especialmente:

• Envio de Mensagens (para evitar duplicidade).
• Criação de Cobranças.
• Agendamentos.