Como implementar entrega eventual entre ERP e loja virtual usando filas e idempotência (sem pedidos duplicados)

Por · Publicado em · Atualizado em · 7 min de leitura

Galeria comercial coberta com lojas e pessoas no corredor
Representa o contexto de loja física para integrar ERP e comércio eletrônico Foto: Warre Van de Wouwer / Pexels

Precisa saber como implementar entrega eventual entre ERP e loja virtual usando filas e idempotência para evitar pedidos duplicados? O caminho combina mensageria, um desenho de eventos consistente e deduplicação na aplicação. A seguir, você entende as causas dos duplicados, a arquitetura recomendada e um passo a passo prático para ativar com segurança.

O problema real: pedidos duplicados e estoque errado

Pedidos duplicados surgem quando integrações fazem retentativas sem controle. Timeouts, instabilidades e concorrência geram reprocessamentos. Sem idempotência, a mesma mensagem cria dois pedidos, estoura estoque e bagunça o financeiro. Veja sintomas comuns e o que costuma causar cada um.

Sintoma Possível causa Impacto
Dois pedidos com mesmo pagamento Retentativa do gateway/API sem idempotência Chargebacks e conciliação demorada
Estoque negativo após virada de hora Processamento concorrente de eventos de baixa Pedidos cancelados por indisponibilidade
Notas fiscais em duplicidade Execução repetida de workflow Retrabalho fiscal e contábil
Pedidos presos em “Processando” Fila sem DLQ e mensagem envenenada Backlog crescente e perda de vendas
Webhook reentregue múltiplas vezes At-least-once sem deduplicação Efeito cascata de duplicidade

Conceitos essenciais: entrega eventual, filas e idempotência

Entrega eventual aceita pequeno atraso para ganhar resiliência. Fila de mensagens desacopla sistemas e permite retentativas. A maioria das filas opera com “pelo menos uma vez” (at-least-once): a mesma mensagem pode chegar repetida. Por isso, a aplicação precisa ser idempotente: processar N vezes com o mesmo resultado final.

Filas FIFO com deduplicação ajudam a reduzir reentregas, mas não eliminam a necessidade de idempotência na borda da aplicação. Idempotência vive perto do banco de dados e das regras de negócio.

Arquitetura recomendada para ERP ↔ e‑commerce

Uma topologia robusta combina padrões de integração orientada a eventos com deduplicação no consumidor.

Componentes práticos:

- Outbox pattern no ERP ou na loja: o sistema grava o evento e o estado de negócio na mesma transação do banco. Um publicador assíncrono lê e coloca na fila.

- Fila (FIFO ou padrão) com DLQ: retentativas com backoff e isolamento de mensagens problemáticas.

- Consumidor idempotente: antes de criar/atualizar pedido, checa uma chave única e registra o processamento.

Se o seu ERP não expõe facilmente mudanças, considere CDC (Change Data Capture) e um outbox. Há um guia de migração com CDC em Estratégia de migração de banco de dados com zero-downtime usando CDC.

Passo a passo de implementação

Um caminho incremental reduz risco e dá visibilidade.

  • Mapeie fluxos críticos: criação de pedido, baixa de estoque, faturamento e cancelamento.
  • Defina o contrato de eventos: identificadores imutáveis, versão do evento e origem.
  • Implemente outbox ou CDC para publicar eventos de forma confiável.
  • Provisione a fila e a DLQ; ajuste política de retentativas e visibilidade.
  • No consumidor, crie um repositório de idempotência (tabela) com índice único.
  • Use upsert transacional para criar/atualizar pedido de forma idempotente.
  • Implemente backoff exponencial, idempotência por TTL quando fizer sentido.
  • Teste sob falhas: simule timeouts e quedas de rede. Dicas de performance em Como reduzir latência de APIs REST: cache e SQL.

Idempotência na prática: chaves, upsert e deduplicação

A chave idempotente deve identificar de forma única a intenção de negócio. Exemplos: orderId da loja, paymentIntentId do provedor, ou hash estável de campos do pedido.

Boas práticas para o consumidor:

- Persistir a chave idempotente antes da ação: INSERT com unique key; se já existir, trate como repetição.

- Usar upsert (INSERT ... ON CONFLICT/ON DUPLICATE KEY) para mudanças idempotentes.

- Registrar status do processamento (em andamento, concluído, falhou) e timestamps.

- Evitar efeitos colaterais fora da transação (e-mails, webhooks) sem checagem de idempotência própria.

Documentações úteis: filas FIFO e deduplicação em AWS SQS (aws.amazon.com/sqs/), chaves idempotentes em APIs como a da Stripe (stripe.com/docs/idempotency).

Retentativas, DLQ e garantia de pelo menos uma vez

Falhas acontecem. Retentativas com backoff exponencial reduzem picos. Use DLQ para isolar mensagens que sempre falham e evitar travar o fluxo.

Não confunda idempotência com rate limiting ou autenticação. Eles se complementam. Para fortalecer a borda da API, veja o Guia de APIs seguras com OAuth2 e rate limiting.

  • Defina limites de retentativas por tipo de erro (transiente vs permanente).
  • Aplique backoff exponencial com jitter para evitar thundering herd.
  • Monitore taxa de DLQ, latência end-to-end e backlog da fila.
  • Implemente reprocessamento assistido da DLQ com observabilidade detalhada.

Testes e observabilidade antes de ligar a chave

Sem telemetria, a idempotência vira caixa-preta. Instrumente contadores de duplicatas evitadas, latência por etapa e tamanho do backlog.

Teste de carga deve incluir mensagens duplicadas e entrega fora de ordem. Prove que o mesmo evento N vezes não muda o estado final.

Registre correlações: traceId, idempotencyKey e orderId. Dashboards e alertas reduzem MTTR em incidentes.

Sinais de que é hora de mudar e próximos passos

Alguns sinais indicam necessidade de entrega eventual com idempotência. Se muitos se aplicam, vale priorizar a implementação.

Para planejar o protocolo de integração, escolha REST ou GraphQL pelo caso de uso. Comparação útil em Comparativo: GraphQL vs REST para integração entre e‑commerce e ERP (sincronização de catálogo e estoque).

  • Pedidos, faturas ou webhooks duplicados em picos.
  • Timeouts e retentativas frequentes no ERP ou na loja.
  • Estoque divergente após cancelamentos ou estornos.
  • Backlog crescente de integrações e janelas manuais de correção.
Decisão Quando usar Risco se ignorar
Entrega eventual + fila Fluxos assíncronos toleram pequeno atraso Acoplamento rígido e quedas derrubam vendas
Chave idempotente única Eventos podem reentregar Pedidos duplicados e conciliação cara
DLQ + reprocessamento Existem mensagens envenenadas Fila trava e causa backlog
Observabilidade Ambiente heterogêneo e distribuído Diagnóstico lento e correções às cegas

Perguntas frequentes

Qual a melhor chave idempotente para pedidos de e‑commerce?

Use um identificador imutável que represente a intenção de negócio, como o orderId da loja ou o identificador do pagamento. Evite chaves geradas a cada tentativa. Garanta unicidade com índice único e registre o status de processamento.

Filas FIFO eliminam duplicação de mensagens?

Filas FIFO reduzem reordenação e oferecem deduplicação por janela de tempo. Ainda assim, duplicatas podem surgir. Mantenha idempotência no consumidor para garantir que reentregas não criem pedidos em dobro.

Como evitar e‑mails ou webhooks duplicados ao reprocessar?

Aplique idempotência também nesses efeitos colaterais. Guarde uma chave por evento enviado, com TTL quando couber, e cheque antes de reenviar. Para webhooks, exija idempotency-key do cliente ou deduza a partir do payload.

O que colocar na DLQ e como reprocessar com segurança?

Envie para a DLQ mensagens que excedem o limite de tentativas ou falham por erro de dados. Reprocesse após correção, mantendo rastreabilidade. Monitore taxa de DLQ e configure alertas para picos anormais.

Preciso de consistência forte no estoque?

Em operações de alto volume, a baixa de estoque geralmente tolera alguns segundos de atraso. Se for crítico, adote reservas temporárias ou checagem síncrona pontual, mantendo o restante assíncrono e idempotente.

Pronto para eliminar pedidos duplicados?

Vamos mapear seus fluxos, definir chaves idempotentes e ativar filas com segurança. Uma conversa curta ajuda a estimar esforço e riscos no seu cenário.

Falar sobre minha integração

Veja também