O que é idempotency-key e pra quê ele serve?

A chave de idempotência (idempotency key) é um conceito técnico importante na realização de transações via API, seja para operações de pagamento, transferência de fundos ou geração de boletos. Ela é um UUID (Universally Unique Identifier) aleatório gerado por quem utiliza a API e enviado como um cabeçalho (header) na requisição.

Em nossas APIs transacionais, o idempotency key é obrigatório no cabeçalho (header). É possível consultar mais sobre os parâmetros obrigatórios de cada uma das APIs disponíveis através de nossa documentação.

Por que é importante usar o idempotency-key?

A principal função do idempotency key é garantir que uma determinada operação seja executada de forma idempotente, ou seja, que sua repetição não cause efeitos adicionais ou indesejados no sistema. Em outras palavras, mesmo que a mesma requisição seja enviada múltiplas vezes, o resultado final será o mesmo, sem duplicação de registros ou processamento desnecessário.

Existem algumas situações em que a idempotência é importante:

• Prevenção de duplicação: Caso uma requisição seja enviada pelo cliente e a resposta não seja recebida a tempo, ele pode tentar enviar a mesma 

requisição novamente. Se a chave de idempotência estiver presente na segunda requisição, entenderemos que se trata de uma tentativa de repetição e não será criado um novo registro ou transação, evitando duplicações indesejadas.

• Falhas de comunicação: Em ambientes de rede instáveis, é possível que ocorram falhas na comunicação entre o cliente e o servidor. Nesses casos, o cliente pode reenviar uma requisição anterior, e o uso do idempotency key permitirá entendermos que se trata de uma duplicação intencional e não de uma nova solicitação.

Ao utilizar o idempotency key, a API e o cliente podem trabalhar de forma mais segura e robusta, evitando resultados indesejados e garantindo que as transações sejam executadas apenas uma vez, mesmo em situações de falhas de rede, atrasos ou problemas de processamento. Dessa forma, é possível aumentar a confiabilidade do sistema e melhorar a experiência do usuário ao evitar erros causados por duplicação de registros ou operações desnecessárias.