{"id":1501,"date":"2025-04-18T15:43:17","date_gmt":"2025-04-18T15:43:17","guid":{"rendered":"https:\/\/mugnos-it.com\/?p=1501"},"modified":"2025-06-03T00:47:47","modified_gmt":"2025-06-03T00:47:47","slug":"voce-sabe-como-implementar-idempotencia-em-apis-sync-e-async","status":"publish","type":"post","link":"https:\/\/mugnos-it.com\/pt\/voce-sabe-como-implementar-idempotencia-em-apis-sync-e-async\/","title":{"rendered":"Voc\u00ea sabe como implementar Idempot\u00eancia em APIs Sync e Async?"},"content":{"rendered":"
\n\t\t\t\t
\n\t\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t
\n\t\t\t\t\t\t\t\t\t\n

<\/p>\n\n\n\n

J\u00e1 imaginou um usu\u00e1rio clicando v\u00e1rias vezes no bot\u00e3o de pagamento e sendo cobrado m\u00faltiplas vezes? Ou ent\u00e3o um script de infraestrutura rodando de novo e criando recursos duplicados? J\u00e1 passei por isso\u2026 e a causa sempre era a mesma: falta de idempot\u00eancia<\/strong>.
<\/p>\n\n\n\n

Duplica\u00e7\u00e3o de requisi\u00e7\u00f5es \u00e9 algo comum de acontecer principalmente em arquiteturas distribuidos. Implementar valida\u00e7\u00f5es de requisi\u00e7\u00f5es duplicadas \u00e9 essencial para evitar bugs e falhas. Em resumo: idempot\u00eancia garante que executar uma a\u00e7\u00e3o v\u00e1rias vezes sempre leve ao mesmo resultado final,<\/strong> ou seja, chega de reprocessar e causar entradas duplicadas em seus softwares.
<\/p>\n\n\n\n

Logo de cara, \u00e9 importante entender que alguns servi\u00e7os de mensageria n\u00e3o garantem idempot\u00eancia nativamente<\/strong>, o que significa que uma mesma mensagem pode ser entregue mais de uma vez. Em comunica\u00e7\u00f5es s\u00edncronas isso tamb\u00e9m acontece, mecanismos de retry e timeouts<\/strong> podem gerar requisi\u00e7\u00f5es duplicadas, j\u00e1 que o cliente pode n\u00e3o receber uma resposta e tentar novamente. Sem um controle adequado, isso pode resultar em processamentos repetidos<\/strong> e at\u00e9 inconsist\u00eancias nos dados<\/strong>.

Olha aqui um exemplo de um servi\u00e7o excepcional da AWS, o AWS SQS:

Filas Standard garantem a entrega de mensagens pelo menos uma vez, por\u00e9m, por causa da arquitetura altamente distribu\u00edda, mais de uma c\u00f3pia de uma mensagem pode ser entregue e as mensagens \u00e0s vezes podem chegar fora de ordem. Apesar disso, as filas padr\u00e3o fazem o poss\u00edvel para manter a ordem em que as mensagens s\u00e3o enviadas.<\/strong><\/em> https:\/\/docs.aws.amazon.com\/pt_br\/AWSSimpleQueueService\/latest\/SQSDeveloperGuide\/standard-queues.html<\/a><\/p>\n\n\n\n

Mas antes de falarmos sobre como implementar a idempot\u00eancia, \u00e9 fundamental entender o conceito de chave forte<\/strong> ou chave de idempot\u00eancia<\/strong>. Basicamente, essa chave \u00e9 um identificador \u00fanico associado a uma opera\u00e7\u00e3o, garantindo que, caso a mesma solicita\u00e7\u00e3o seja enviada mais de uma vez, o sistema reconhe\u00e7a e trate como uma \u00fanica execu\u00e7\u00e3o.
<\/p>\n\n\n\n

Em APIs s\u00edncronas<\/strong>, essa chave geralmente<\/strong> \u00e9 enviada no cabe\u00e7alho da requisi\u00e7\u00e3o (mas as vezes \u00e9 um concate de varios valores do payload), como um UUID<\/strong> (Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000<\/code>) ou um hash gerado a partir do corpo da requisi\u00e7\u00e3o<\/strong> (exemplo: SHA-256(\"user123-100USD-2024-02-10\")<\/code>).
<\/p>\n\n\n\n

J\u00e1 em sistemas ass\u00edncronos<\/strong>, a chave pode ser o pr\u00f3prio ID \u00fanico da mensagem<\/strong>, como um MessageId<\/code> em um servi\u00e7o de mensageria (MessageId: msg-abc-123<\/code>) ou um identificador customizado gerado pelo produtor antes do envio (Order-Id: 987654321<\/code> ou Order-Id: action-user-date-hour<\/code> ).
<\/p>\n\n\n\n

Sem uma chave forte bem definida, n\u00e3o h\u00e1 como garantir a idempot\u00eancia de forma eficaz.<\/p>\n\n\n\n

Bom, agora q vc entende o que \u00e9 a chave de idempotencia, vamos falar um pouco de como usa-las:<\/p>\n\n\n\n

\n\n\n\n

1. Idempot\u00eancia em APIs Sync \/ S\u00edncronas (RESTful)<\/strong><\/h3>\n\n\n\n

Para evitar que um mesmo pedido seja processado mais de uma vez em uma API de pagamento, voc\u00ea pode implementar da seguinte forma:<\/p>\n\n\n\n

1\ufe0f\u20e3 O cliente<\/strong> gera um Idempotency-Key<\/code> \u00fanico para cada requisi\u00e7\u00e3o e envia no cabe\u00e7alho ou at\u00e9 mesmo no corpo do Payload .
<\/p>\n\n\n\n

2\ufe0f\u20e3 O servidor<\/strong> verifica se essa chave j\u00e1 foi processada antes:<\/p>\n\n\n\n