📘

O que você vai aprender com este artigo?

• O que é Idempotência: Conceito e importância da idempotência em APIs.
• Como usar uma chave de idempotência: Práticas para implementação e uso em suas requisições API.

O que é Idempotência?

Idempotência em uma API refere-se à capacidade de executar múltiplas requisições idênticas em um curto período de tempo com a garantia de que apenas uma única requisição será processada com sucesso. Isso é especialmente útil para evitar efeitos colaterais indesejados quando uma mesma requisição é enviada mais de uma vez devido a problemas de rede ou outras falhas.

Por exemplo, imagine que um ecommerce realiza uma requisição para criar uma fatura, mas, devido a uma falha de rede, a mesma requisição é enviada duas vezes com os mesmos dados. Com o uso de uma chave de idempotência, apenas uma das requisições será processada, evitando a duplicação de pedidos.

Como usar uma chave de idempotência?

A chave de idempotência é gerada pelo próprio lojista e deve ser incluída no header da requisição, utilizando o parâmetro Idempotency-Key. As APIs que aceitam esse recurso são

• Criar fatura
• Criar assinatura
• Transferência para Terceiros
• Criar Pedido de Pagamento
• Criar cliente
• Cobrança direta

Se várias requisições forem enviadas com a mesma chave de idempotência no mesmo instante, apenas uma será processada com sucesso. Para as demais, será retornado o erro 409 (Conflito).

Recipe 🧪

Veja, na prática, como montar uma requisição com Chave de Idempotência: