Pedidos travados no Magento 2: como detectar antes do cliente reclamar

Pedido travado é um problema silencioso. O cliente clica em "Finalizar compra", recebe o e-mail de confirmação, e nada acontece depois. Dois dias depois ele abre Reclame AQUI — você descobre o problema por chargeback ou por reputação, nunca pelo monitoramento.

Este guia mostra como detectar pedidos parados antes do SAC explodir, com foco em Magento 2 (a lógica se aplica a WooCommerce e plataformas próprias).

Por que pedidos ficam travados

Em Magento 2, um pedido passa por uma sequência de estados (state) e status (status). ^[1] Os dois estados onde pedidos costumam morrer:

• pending_payment — aguardando confirmação do gateway. Causa típica: o webhook do gateway não chegou ou foi rejeitado pelo servidor.
• processing — pago, mas sem evolução. Causa típica: integração com ERP, antifraude ou marketplace travando o fluxo.

As 4 causas mais comuns

1. Webhook do gateway falhando. O cliente pagou, o gateway tentou notificar o Magento e a URL respondeu com erro (500, timeout, certificado expirado). O gateway tenta de novo algumas vezes e desiste. Pedido fica empending_payment para sempre.
2. Cron parado ou atrasado. Vários fluxos (atualização de status, atualização de estoque, envio de e-mail) dependem do cron. Cron travado = pedidos travados.
3. Queue consumer parado. Magento 2 usa RabbitMQ/MySQL queue para processar tarefas assíncronas. ^[2] Se o consumer cai, mensagens acumulam e nada é processado. Comum após restart parcial.
4. Integração externa rejeitando. ERP fora do ar, antifraude com quota estourada, marketplace exigindo confirmação manual. O pedido fica suspenso esperando uma resposta que nunca chega.

Alertas mínimos para detectar pedidos travados

Alerta 1 — Pedidos em pending_payment por mais de 2 horas

Em condições normais, um pedido em pending_payment é resolvido em minutos (gateway sincronizando). Se passa de 2 horas, ou o gateway está em incidente, ou o webhook não está chegando. Query base:

SELECT entity_id, increment_id, created_at, grand_total
FROM sales_order
WHERE state = 'pending_payment'
  AND created_at < NOW() - INTERVAL 2 HOUR;

Alerta 2 — Pedidos em processing por mais de 48 horas

Esse é o limiar conservador. Se o seu fluxo padrão entrega em 24h, ajuste para 24h. Pedidos parados por mais que isso costumam ter problema na integração com ERP.

Alerta 3 — Fila de mensagens crescendo

Em Magento 2 com queue em MySQL, monitore a tabela queue_message:

SELECT topic_name, COUNT(*) as pendentes
FROM queue_message qm
JOIN queue_message_status qms ON qm.id = qms.message_id
WHERE qms.status = 4 -- NEW
GROUP BY topic_name
HAVING pendentes > 100;

Aqui está o segredo: se um tópico está com mais de 100 mensagens pendentes e não diminui em 30 minutos, o consumer travou. Reinicie e dispare alerta.

Alerta 4 — Webhook do gateway retornando erro

Configure o endpoint de webhook para logar cada chamada (request + status response). Alerta quando o ratio de respostas não-200 ultrapassa 5% em 15 minutos. A maioria dos gateways tem painel próprio com esse dado.

Alerta 5 — Conferência de receita diária

Soma de pedidos confirmados no Magento vs soma de transações no gateway. Se a diferença passa de 2%, há pedidos pagos que não confirmaram no Magento. Esse cruzamento é manual em muitas lojas — automatize.

Como configurar isso na prática

Opção 1 — Script bash com cron

Funciona para times pequenos. Um script PHP/bash que roda a cada 15 minutos, executa as queries acima e dispara webhook para Slack/Discord quando passa do limite. Custo: 2h para configurar, manutenção zero.

Opção 2 — Monitoramento dedicado

A Especialista Loja Virtual tem um modo específico para isso (pendingOrdersMode). Conectada via REST API do Magento 2, ela faz a verificação a cada poucos minutos e dispara alerta com contagem, lista de increment_id afetados e idade média. Não acessa dados sensíveis — só os agregados.

Opção 3 — APM com dashboard

Datadog/New Relic com SQL custom queries. Custo alto, faz sentido se você já usa para o resto.

O que fazer quando o alerta dispara

Checklist de incidente em pedidos travados:

1. Confirme: o pedido está mesmo travado ou é só lag de processamento? Aguarde 5 minutos antes de agir.
2. Identifique o tópico/integração afetada. Pendentes só no tópico de cancelamento? Provavelmente cron. Pendentes em todos? Cron ou banco.
3. Reinicie o consumer afetado: bin/magento queue:consumers:start <nome> e veja se a fila começa a drenar.
4. Se for webhook não chegando, reenvie manualmente do painel do gateway (PagSeguro, Mercado Pago e Cielo permitem reenviar).
5. Documente: quantos pedidos foram afetados, quanto tempo durou, qual a causa raiz. Não pule esse passo — incidente sem post-mortem volta.

Prevenção a médio prazo

• Healthcheck do webhook. Endpoint que retorna 200 sempre — útil para o gateway "saber" que o servidor está vivo, e para você monitorar com verificador de site online.
• Restart automático do consumer. Supervisor ou systemd com Restart=always. Consumer cai? Volta sozinho em segundos.
• Cron com pid-lock. Cron travado é a causa #1 de pedido travado em Magento 2. Use lock para garantir que só uma instância roda e log para detectar quando demora mais que o esperado.
• Antifraude assíncrono. Pedido entra em fraud_review, antifraude libera depois. Se cair, pedidos continuam entrando.
• Idempotência no webhook. Use o transaction_id do gateway como chave única e ignore duplicatas — assim retries do gateway não criam ordens duplicadas.