Idempotência

O que é e como funciona a Idempotência no Pagar.me

Idempotência é a possibilidade de gerar requisições idênticas em um período de tempo que tenham uma única resposta.

Por exemplo, quando uma loja gera duas requisições, em um curto período de tempo, gerando dois pedidos idênticos, a idempotência permite que a aplicação devolva para a loja a resposta de ok para as solicitações e gere apenas uma transação.

A API Pagar.me suporta Idempotência para proporcionar a criação de pedidos sem o risco de criar transações duplicadas. Essa funcionalidade é útil quando, por exemplo, há algum erro durante o processo de comunicação entre a loja e a nossa API e não há resposta sobre a criação de um pedido.

Para utilizar a Idempotência, o lojista deve enviar a Idempotency-key no header das requisições. Essa chave deve ser gerada pelo lojista e expirará 24 horas após o envio do primeiro pedido contendo essa Idempotency-key. Vale lembrar que a chave é escrita no formato case-sensitive, fazendo com que letras maiúsculas façam a diferença na criação

🚧

Tamanho da Idempotency-key

Apesar do Pagar.me não impor um limite ao tamanho dessa chave, nos recomendamos fortemente que não sejam enviadas chaves muito longas para não comprometer o tempo de resposta da aplicação.

A Idempotência no Pagar.me funciona através do armazenamento da idempotency-key de uma transação e do status retornado para a criação desse pedido. Com essas informações e independentemente do retorno para essa transação (capturada, autorizada, falha), nós salvaremos esses dados para garantir que as requisições que forem realizadas em até 24 horas desde a criação do primeiro pedido, não sejam criadas em duplicidade. Assim, os pedidos enviados com a mesma chave terão como resposta uma única transação.

❗️

Requisições com mesma chave e conteúdos distintos no body

É muito importante ressaltar que caso duas requisições sejam enviadas com a mesma chave no header e com conteúdos diferentes no body, a API ainda assim criará apenas um pedido.

Como as chaves Idempotency-key não são geradas pelo Pagar.me e ela não tem gerência sobre as mesmas, elas podem ser utilizadas por lojas, métodos e endpoints diferentes.

Cenários de erro

Em alguns casos, pode ser que duas ou mais requisições sejam enviadas em um período muito curto de tempo. Assim, é possível que uma segunda requisição seja enviada para a aplicação antes mesmo da resposta da primeira. Nesses cenários, será retornado o código 409 - Conflict para a segunda requisição, indicando que já há um chamado em aberto para a mesma idempotency-key.

Nos casos em que a requisição falha por algum motivo e a API retorna um tipo de erro 400, informando que há um problema com o request, o comportamento do Pagar.me será de não gravar as chaves para que o lojista corrija a requisição e a envie novamente. O mesmo acontece para casos em que é retornado qualquer espécie de erro 500.

🚧

Ambiente de sandbox

Para o ambiente de testes, a idempotência tem duração de 5 minutos.