Skip to main content

Idempotência

A idempotência evita que uma mesma intenção de operação seja processada mais de uma vez quando a requisição precisa ser reenviada.

Na prática, isso significa que você pode repetir uma chamada de criação com a mesma idempotencyKey sem gerar uma nova operação duplicada.

Para que serve​

Use idempotência sempre que houver chance de a mesma requisição ser enviada novamente por motivo técnico, como:

  • timeout na resposta
  • falha momentânea de rede
  • retry automático do cliente HTTP
  • reenvio manual da mesma chamada

Esse comportamento é especialmente importante em operações financeiras, porque evita que o integrador crie duas transações, dois depósitos ou dois saques por acidente.

Como usar​

O fluxo recomendado é simples:

  1. gere uma idempotencyKey única para a operação
  2. envie essa chave junto com a requisição de criação
  3. se a mesma operação precisar ser reenviada, reutilize a mesma chave
  4. se for uma operação nova, gere uma nova chave
Regra prática

Se a intenção de negócio é a mesma, reutilize a mesma idempotencyKey. Se a intenção mudou, crie uma chave nova.

O que a plataforma faz​

Do ponto de vista de quem integra, a plataforma reconhece que a mesma chave representa a mesma operação dentro do mesmo contexto da integração.

Isso permite que um retry não vire uma nova operação por engano.

Se a primeira tentativa ainda estiver em processamento, a segunda chamada pode aguardar o resultado da operação original antes de responder.

idempotencyKey vs externalCode​

Esses dois campos têm papéis diferentes:

  • idempotencyKey: identifica uma tentativa única de operação e protege contra duplicidade técnica
  • externalCode: é a sua referência de negócio para localizar a operação no seu sistema

Eles podem ser usados juntos, mas um não substitui o outro.

Quando gerar uma nova chave​

Gere uma nova idempotencyKey quando:

  • o pedido mudou
  • o valor mudou
  • o destinatário mudou
  • a operação é outra, mesmo que pareça parecida

Não reutilize a mesma chave para intenções diferentes.

Exemplo prático​

Primeira tentativa​

{
  "amount": 500,
  "paymentMethod": "PIX",
  "externalCode": "PEDIDO-123",
  "idempotencyKey": "b7f9c2d8-8f59-4a55-8c3c-8a6a4f9d1f2d"
}

Retry da mesma operação​

Se a chamada anterior não teve resposta clara, reenviando o mesmo payload com a mesma idempotencyKey a plataforma deve tratar isso como a mesma operação.

{
  "amount": 500,
  "paymentMethod": "PIX",
  "externalCode": "PEDIDO-123",
  "idempotencyKey": "b7f9c2d8-8f59-4a55-8c3c-8a6a4f9d1f2d"
}

Boas práticas​

  • use a idempotencyKey nos POST de criação
  • mantenha a mesma chave enquanto estiver tentando concluir a mesma operação
  • gere uma chave nova para cada nova intenção de negócio
  • não use a chave como substituta de externalCode
  • trate timeout e retry do seu cliente como cenários esperados

Onde isso é aplicado​

Na nossa API, esse conceito aparece principalmente nos endpoints de criação:

Em resumo​

Idempotência é o que permite reexecutar a mesma intenção sem criar duplicidade.

Para o integrador, a regra principal é:

  • mesma operação, mesma idempotencyKey
  • operação nova, nova idempotencyKey