Idempotência das APIs

O que é Idempotência?

No mundo da arquiteturas e integração de sistemas, a comunicação entre serviços é uma necessidade comum, mas que não está livre de desafios. Um dos principais problemas é a falha na comunicação: o que acontece se você enviar uma requisição e não receber uma resposta? Imagine o cenário onde essa requisição perdida é uma tentativa de pagamento de um débito veicular ou Pix. As consequências de uma falha como essa podem ser significativas, levando à duplicação de pagamentos ou à falta de registro de uma transação importante.

Para mitigar esse tipo de problema, uma solução eficaz é a utilização de chaves de idempotência. Uma chave de idempotência é um identificador único que assegura que realizar a mesma operação repetidamente terá o mesmo efeito que fazê-lo apenas uma vez. Isso significa que, independentemente de quantas vezes uma requisição seja enviada, se todas elas possuírem a mesma chave de idempotência, o sistema tratará as tentativas subsequentes como duplicatas da primeira e evitará a execução de operações múltiplas.

O uso de chaves de idempotência é uma estratégia inteligente para garantir a consistência e a confiabilidade das transações em sistemas distribuídos. Ao implementar essa abordagem, é possível reenviar uma requisição sem o risco de efeitos colaterais, como a duplicação de um pagamento. Isso não só protege contra falhas de comunicação, mas também oferece uma experiência de usuário mais estável e confiável, assegurando que operações críticas, como pagamentos e transferências, sejam processadas de forma segura e eficiente.

Como funciona a idempotência na Celcoin?

Dependendo do conjunto de APIs, a varíavel de idempotência assume os seguintes nomes:

• ClientCode (Para BaaS e Pix)
• ClientRequestId (Para Débito Veicular)
• externalNSU e externalTerminal (Para Pagamento de Contas)

Para garantir que existe a proteção contra transações duplicadas, o cliente deverá sempre utilizar um mecanismo de geração de códigos únicos de idempotencia.

Sugestão para tratamento de erros

• Em caso de erro 500 nas operações que suportem idempotência:
  • Repetir a requisição utilizando o mesmo código único de idempotência. Caso a transação tenha sido executada com sucesso na primeira vez, o endpoint não permitirá que a requisição seja duplicada, ou;
  • Utilizar os nossos endpoints de consulta de status, requisitando uma busca pelo código único de idempotência utilizado na requisição da transação.