Pular para o conteúdo principal
Um aspecto fundamental da confiabilidade do Midaz é garantir que as operações sejam seguras para retentativa e nunca processadas mais de uma vez. Seja ao lidar com transações ou criar entidades, sua integração deve ser resiliente, mesmo diante de falhas de rede, timeouts ou interrupções temporárias. Esta página explica como o Midaz protege contra duplicações usando chaves de idempotência, e como você pode implementá-las para lidar com retentativas no seu sistema com confiança.

​
Tornando as retentativas seguras

Em sistemas reais, falhas em requisições de API são comuns. Talvez ocorra um timeout de rede. Talvez seu serviço caia logo após enviar uma requisição. Nesses casos, é natural tentar novamente, mas como você pode ter certeza de que o Midaz não processará a mesma operação duas vezes? É aí que as chaves de idempotência entram em ação. Ao anexar uma chave única a cada requisição, você está dizendo ao Midaz: “Esta é a mesma operação. Se você já a processou, não faça novamente.” O Midaz armazena essa chave temporariamente e a utiliza para determinar se a requisição é nova, já foi concluída ou ainda está sendo processada. Isso protege seu sistema contra duplicatas enquanto oferece controle total sobre sua estratégia de retentativa.

​
Idempotência no Midaz

O Midaz usa chaves de idempotência para garantir que as operações sejam seguras para retentativa e nunca processadas mais de uma vez. Para isso, sua requisição deve incluir dois headers:
  • X-Idempotency: a chave única que identifica a requisição.
  • X-TTL: o tempo de vida (em segundos) que o Midaz deve armazenar essa chave em cache.
Veja o que acontece nos bastidores:
  1. Quando uma nova chave chega, o Midaz a marca como pending, processa a requisição e armazena a resposta completa em cache.
  2. Se a mesma chave for usada novamente dentro da janela de TTL:
    1. Se a operação ainda estiver em execução, o Midaz retorna um 409 Conflict com X-Idempotency-Replayed: false.
    2. Se estiver concluída, o Midaz retorna exatamente a mesma resposta, incluindo headers e corpo, com X-Idempotency-Replayed: true.
Este modelo funciona em todos os endpoints do Midaz e oferece uma maneira segura e previsível de construir fluxos de trabalho com retentativa, seja ao lidar com pagamentos, jobs em segundo plano ou transações de alto volume.

​
Resumo do fluxo

A Figura 1 mostra o ciclo de vida completo de uma requisição idempotente:
Como funciona:
  • Se a requisição não incluir uma chave de idempotência existente, o Midaz cria uma nova, processa a requisição, armazena a resposta e a retorna com X-Idempotency-Replayed: false.
  • Se a chave já existir:
    • Se a operação ainda estiver em execução, o Midaz retorna um 409 Conflict com X-Idempotency-Replayed: false.
    • Se a operação estiver concluída, o Midaz ignora a execução e retorna a resposta em cache com X-Idempotency-Replayed: true.
Esse comportamento garante que cada requisição seja tratada de forma segura, previsível e sem duplicação, mesmo quando retentada.

​
Exemplo de requisição

Veja como enviar uma requisição idempotente para criar uma transação: 
POST /v1/transactions
X-Idempotency: 7fb8e1d098cd4730bb932d038b3b8651
X-TTL: 60
Content-Type: application/json

{
  "amount": 1000,
  "source": "wallet_A",
  "destination": "wallet_B",
  "asset": "USD"
}
Se a requisição for bem-sucedida e você enviá-la novamente dentro de 60 segundos, o Midaz retornará o resultado em cache com: 
X-Idempotency-Replayed: true
Se você enviá-la novamente enquanto a original ainda estiver sendo processada, você receberá: 
HTTP/1.1 409 Conflict
X-Idempotency-Replayed: false

​
Geração de chaves

Você gera a chave X-Idempotency do seu lado. A chave deve ser determinística, ou seja, se a mesma operação for retentada, a chave permanece a mesma. Uma estratégia simples e eficaz é criar um hash baseado nos campos-chave que definem a operação. Por exemplo:
  • Valor da transação
  • Origem e destino
  • Código do asset
Aqui está um exemplo rápido em Python: 
import hashlib

def generate_idempotency_key(amount, source, destination, asset):
    raw = f"{amount}:{source}:{destination}:{asset}".lower()
    return hashlib.md5(raw.encode()).hexdigest()

​
Prevenindo duplicação de entidades

Para alguns endpoints, você não precisa de chaves de idempotência para evitar duplicação. O Midaz aplica restrições de unicidade em recursos críticos como Contas e Ledgers. Se você tentar criar uma entidade com um nome que já existe, o sistema bloqueia a requisição e retorna um erro descritivo. Isso garante que seus dados permaneçam limpos, sem ambiguidade e fáceis de gerenciar, mesmo quando vários serviços estão operando em paralelo ou quando retentativas ocorrem automaticamente.

​
FAQ

O Midaz trata a requisição como nova toda vez. Isso significa que retentativas podem resultar em operações duplicadas.
Não. As chaves devem ser restritas a uma única operação e endpoint.
Apenas o TTL da primeira requisição é utilizado. Alterá-lo depois não tem efeito.
Sim. O Midaz repete a resposta completa, incluindo headers e corpo, para requisições concluídas.
A janela padrão é de 300 segundos (5 minutos), mas você pode personalizá-la até o limite permitido por endpoint.