Encomendas duplicadas e cobrança a dobrar no PrestaShop: causas e como evitá-las

O cliente pagou uma vez. No seu back-office há duas encomendas do mesmo carrinho, cada uma com a sua fatura e o seu stock descontado. Ou há uma só encomenda, mas com o estado «Pagamento aceite» duas vezes e duas faturas numeradas. Vistas em separado, as duas encomendas parecem corretas; por isso este problema passa despercebido até conferir o banco ou o cliente reclamar.

De onde vêm os duplicados

1. Duas notificações do gateway ao mesmo tempo

É a causa mais frequente e a menos visível. Muitos gateways avisam do pagamento por dois caminhos: a notificação de servidor para servidor (webhook, IPN, notificação online) e o regresso do cliente à loja. Se as duas chegarem quase ao mesmo tempo, cada uma pergunta «já existe uma encomenda para este carrinho?», as duas recebem «não» porque nenhuma a criou ainda, e cada uma cria a sua. É uma condição de corrida clássica.

2. Novas tentativas do webhook

Se o seu servidor demorar a responder ou devolver um erro, o gateway volta a enviar a notificação. Se o módulo de pagamento não verificar que já a processou, a encomenda ou o estado repetem-se.

3. Duplo clique ou recarregamento

O cliente carrega duas vezes em «Pagar» ou recarrega a página de confirmação. Em métodos sem redirecionamento (transferência, pagamento à cobrança) pode bastar para criar duas encomendas.

4. O back-office

Um funcionário muda o estado de uma encomenda, a página demora e carrega outra vez. O estado é aplicado duas vezes e, se esse estado gerar fatura, saem duas.

5. Módulos que reagem ao mesmo evento

Dois módulos que escutam a mudança de estado e um deles volta a mudá-lo, ou um ERP que reenvia um estado já aplicado.

Como o detetar no seu histórico

1. Carrinhos com mais de uma encomenda. No PrestaShop um carrinho deveria dar uma só encomenda (salvo encomendas divididas por transportadora, que partilham referência). Uma consulta que agrupe encomendas por id_cart e conte as que têm mais de uma é o primeiro filtro.
2. Estados repetidos. Encomendas com o mesmo estado de pagamento duas vezes no histórico.
3. Faturas duplicadas para a mesma encomenda.
4. Cobranças face a encomendas. Compare os pagamentos registados em cada encomenda com o que diz o gateway. Duas encomendas e uma cobrança é um problema de stock e faturação; duas encomendas e duas cobranças é dinheiro a mais que é preciso devolver.

Como limpá-los sem piorar as coisas

• Não elimine encomendas. Perde-se a rastreabilidade e, se havia fatura, estraga a numeração. Cancele a que sobra.
• Uma fatura numerada não se retira: anula-se com uma fatura retificativa, como exige o regulamento de faturação espanhol (Real Decreto 1619/2012, artigo 15).
• Reponha o stock da encomenda que sobra, verificando que ainda não foi reposto.
• Se houve duas cobranças, a devolução é decidida por uma pessoa e faz-se a partir do gateway.
• Não mexa em encomendas já enviadas sem as rever uma a uma.

Como o prevenir

1. Bloqueio por carrinho ao criar a encomenda. A segunda notificação deve esperar que a primeira termine e, ao entrar, ver que a encomenda já existe. É a solução de fundo para a condição de corrida.
2. Idempotência nos webhooks: guardar o identificador de cada notificação processada e não repetir o que já foi feito.
3. Responder depressa ao gateway: se o webhook demorar, o gateway tenta de novo. O que for lento (e-mails, ERP) é melhor depois.
4. Desativar o botão de pagamento ao carregar nele e nos formulários de estado do back-office.
5. Um único caminho que cria a encomenda por gateway, se o módulo o permitir.
6. Vigilância: um aviso no momento em que aparece um duplicado vale mais do que encontrá-lo meses depois.

O que não se deve fazer

• Modificar o núcleo do PrestaShop ou o módulo de pagamento para «o corrigir»: a próxima atualização desfá-lo.
• Desativar a notificação de servidor e confiar tudo ao regresso do cliente: se ele fechar o separador, a encomenda não é criada.
• Limpar em lote sem um ensaio prévio.

Checklist

1. Procure carrinhos com mais de uma encomenda em todo o histórico.
2. Classifique: uma cobrança e duas encomendas, ou duas cobranças.
3. Cancele as que sobram, reponha o stock e emita retificativas onde for preciso.
4. Reveja como cada gateway notifica e se os seus webhooks fazem novas tentativas.
5. Ponha um bloqueio na criação da encomenda e na mudança de estado.
6. Ative avisos para saber no próprio dia.

Como resolvê-lo no PrestaShop

RKR Order Guard obtém um bloqueio do MySQL antes de o controlador do módulo de pagamento carregar o que quer que seja, de modo que a segunda notificação espera e encontra a encomenda já criada; também bloqueia a encomenda enquanto muda de estado, para que não nasçam duas faturas, e evita o duplo envio do formulário de estado no back-office. Sem overrides. Em Encomendas → Encomendas duplicadas revê todo o histórico e classifica cada carrinho: uma cobrança e duas encomendas (cancela a que sobra e repõe o stock), duas cobranças (a devolução é decidida por uma pessoa) ou indeterminado (só o lista). Permite simular antes de executar, nunca elimina encomendas, não emite devoluções nem mexe em encomendas com pacote enviado ou faturas já numeradas, e se o bloqueio esgotar o tempo de espera a venda continua. RKR Sentinel, que acompanha este artigo, avisa por Telegram de pagamentos sem encomenda, valores que não batem certo e encomendas paradas.