Idempotência na integração de pedidos: por que importa
A API do marketplace vai cair no meio do envio. O que decide se isso vira um pedido duplicado ou um não-evento é uma chave de deduplicação.
· 4 min de leitura
O que é idempotência na integração de pedidos
Você envia um pedido para o marketplace. A conexão cai antes da resposta chegar. Duas coisas podem ter acontecido: o pedido entrou e a resposta se perdeu, ou o pedido nem chegou. Do seu lado, as duas situações são idênticas.
É aí que idempotência decide o desfecho. Com uma chave de deduplicação, você reenvia sem medo: se já tinha entrado, o outro lado reconhece e devolve o mesmo resultado. Sem ela, reenviar é apostar — e metade das apostas cria um pedido duplicado.
O número
Uma operação com 1.200 pedidos por mês e uma taxa de falha de rede de 1% tem 12 reenvios por mês. Com idempotência, doze não-eventos. Sem ela, até doze pedidos duplicados — que viram doze baixas de estoque erradas, doze notas a cancelar e alguns clientes cobrados duas vezes.
O custo não é o pedido duplicado. É a hora de alguém descobrir, estornar, refazer a nota e explicar ao cliente.
Retry sem idempotência é pior do que não ter retry. Você troca "perdi um pedido" — que alguém percebe — por "criei um pedido a mais", que ninguém percebe até o inventário ou a fatura do cliente.
Por que isso importa para a sua operação
Integração de marketplace não é uma chamada, é um processo com estado. Entre o seu sistema e o do canal existem timeout, limite de requisições, manutenção programada e erro temporário. Isso não é falha de quem construiu: é a condição normal de operar contra a API de outra empresa.
A pergunta certa não é "como evitar que caia". É "o que acontece quando cair". Três respostas possíveis:
- Nada — o pedido some e alguém descobre pelo cliente reclamando.
- Tenta de novo, sem controle — duplica.
- Tenta de novo, com chave e log — converge, e dá para provar o que aconteceu.
Só a terceira escala.
O que exigir de uma integração
- Chave de deduplicação por evento. O identificador do pedido no canal, não um número gerado por você. É ele que permite reconhecer o repetido.
- Retry com espera crescente. Tentar de novo no mesmo segundo só empilha requisição em cima de um serviço que já está sofrendo.
- Teto de tentativas e uma fila de fracasso. O que não entrou depois de N tentativas precisa parar num lugar visível, não sumir.
- Log por tentativa e por etapa. "Falhou" sem etapa é uma palavra sem história: não dá para saber se quebrou ao autenticar, ao enviar ou ao confirmar.
- Reprocessamento manual. Alguém precisa conseguir mandar de novo depois de corrigir o cadastro, sem abrir chamado com o fornecedor.
- Ordem preservada por pedido. Atualização de status que chega fora de ordem pode reabrir um pedido já concluído.
O que costuma dar errado
Confiar no identificador que você gerou. Se a chave nasce do seu lado a cada tentativa, cada tentativa tem chave nova — e nenhuma duplicata é reconhecida.
Tratar erro 429 como erro. Limite de requisições não é falha: é o canal pedindo para você ir mais devagar. Tentar de novo na hora piora.
Não separar erro temporário de erro permanente. CNPJ inválido não melhora na décima tentativa. Reprocessar isso mil vezes entope a fila e esconde os erros que teriam solução.
Log que só guarda a última tentativa. Quando o saldo diverge, a pergunta é o que foi enviado e o que o outro lado aceitou, em cada tentativa. Guardar só a última apaga a investigação.
Referência rápida
| Sintoma | Causa provável |
|---|---|
| Pedido em duplicidade | Retry sem chave de deduplicação |
| Pedido some sem aviso | Sem retry, ou sem fila de fracasso |
| Fila entope e nada anda | Erro permanente sendo reprocessado |
| Status volta atrás sozinho | Atualização fora de ordem |
| Saldo diverge e ninguém explica | Log sem etapa e sem tentativa |
Quando o resultado disso aparece no saldo, é o assunto de estoque furado entre marketplaces. Se a dúvida é manter a integração ou trocar o sistema por trás dela, está em integrar ou substituir o Bling, Omie e Bluesoft.
Perguntas frequentes
- O que é idempotência numa integração?
- É a garantia de que processar a mesma mensagem duas vezes produz o mesmo resultado que processar uma vez. Na prática: reenviar um pedido depois de uma falha não cria um segundo pedido.
- Por que uma integração precisa tentar de novo?
- Porque a API do outro lado cai, responde devagar ou devolve erro temporário — e nada disso é exceção, é rotina. Sem retry, cada instabilidade do marketplace vira um pedido perdido na sua operação.
- Retry sem idempotência é pior do que não ter retry?
- É. Sem chave de deduplicação, cada tentativa extra tem chance de criar uma duplicata. Você troca o problema de perder pedido pelo de cobrar duas vezes, que é mais caro.
Davidson Assis
Fundador da Reducess e do Mineer
Constrói software de gestão para PME brasileira há mais de uma década. Hoje toca o Mineer, plataforma que reúne CRM, estoque, WhatsApp, fiscal e IA numa operação só — e escreve aqui sobre o que aparece quando se implanta isso em empresa de verdade.
Continue lendo
A entrada de nota do fornecedor sem digitar nada de novo
· 4 min
Escolher o frete mais barato sem perder a margem
· 3 min
Estoque furado entre marketplaces: por que isso acontece
· 4 min