Sincronização de stock no WooCommerce sem sobrevendas

A sincronização de stock no WooCommerce não consiste apenas em copiar uma quantidade de um ERP, um WMS ou um catálogo externo. O problema é coordenar decisões tomadas em momentos diferentes: uma venda na loja, uma receção no armazém, um cancelamento, uma reserva temporária ou uma correção manual. Dois sistemas podem apresentar números diferentes e, ainda assim, estar a funcionar de acordo com os seus próprios tempos e regras.

O risco surge quando essa diferença permite vender unidades que já não estão disponíveis ou quando, para o evitar, a loja consulta ou aguarda pelo sistema externo em cada passo da compra. A primeira abordagem causa sobrevendas; a segunda pode degradar o catálogo, o carrinho e o checkout. A arquitetura deve separar a experiência de compra do processamento operacional e tornar cada alteração verificável.

Definir uma fonte de verdade para cada tipo de stock

Antes de escolher APIs, webhooks ou tarefas agendadas, é necessário definir o que representa cada valor. “Stock” costuma agrupar conceitos que não são intercambiáveis:

• Stock físico: unidades efetivamente presentes numa localização.
• Stock comprometido: unidades atribuídas a encomendas que continuam ativas.
• Stock reservado: unidades retidas temporariamente durante uma compra ou uma validação de pagamento.
• Stock disponível para venda: quantidade que pode ser apresentada ao cliente de acordo com regras comerciais, reservas e margens de segurança.
• Stock publicado: valor atualmente apresentado ou aplicado pelo WooCommerce, juntamente com o instante e a origem da respetiva atualização.

O ERP ou WMS costuma ser a autoridade para o stock físico e para os movimentos de armazém. O WooCommerce pode ser a autoridade para o estado do carrinho, da encomenda e de uma reserva associada à sessão de compra. A disponibilidade comercial pode exigir uma regra própria, por exemplo:

disponível_para_venda = físico - comprometido - reservado - margem_de_segurança

Esta regra deve ter um responsável claro. Se o WooCommerce e o sistema externo a calcularem de forma diferente, trocar um valor final não resolverá a inconsistência. Também é conveniente armazenar a data do cálculo, a versão ou sequência do evento e a localização afetada quando o inventário é multi-armazém.

Escolher o fluxo de atualização de acordo com o risco

Nem todas as alterações merecem o mesmo tratamento. Uma importação noturna pode ser suficiente para um catálogo informativo, mas não para referências de elevada rotação ou stock reduzido.

Eventos, consultas, lotes e abordagem híbrida

• Atualização por eventos: o sistema externo emite alterações de inventário e um consumidor atualiza a projeção disponível no WooCommerce. Reduz a latência, mas exige a gestão de tentativas, duplicados e ordem.
• Consulta a pedido: a loja consulta a disponibilidade ao entrar no carrinho ou antes do pagamento. Pode ser útil como validação pontual, mas não deve transformar a disponibilidade do fornecedor numa dependência síncrona de cada página.
• Sincronização periódica: um processo recolhe alterações por lotes. É mais simples para catálogos amplos, embora a janela entre execuções aumente o risco de discrepância.
• Modelo híbrido: eventos para alterações urgentes, processos periódicos para recuperar omissões e uma validação final para produtos sensíveis.

Na prática, o modelo híbrido costuma separar a leitura rápida da compra da operação lenta de inventário. O WooCommerce serve uma projeção local do stock; os eventos atualizam essa projeção em segundo plano; e a reconciliação deteta o que não chegou ou não pôde ser aplicado.

Reservar durante a compra sem descontar duas vezes

Uma reserva não é necessariamente uma venda. Deve ser criada num momento definido, ter expiração e poder ser libertada por cancelamento, falha de pagamento ou abandono. Se o WooCommerce reduzir o seu stock nativo ao criar ou alterar o estado de uma encomenda e, além disso, o ERP descontar a mesma unidade ao receber essa encomenda, pode ocorrer um desconto duplicado.

A solução exige definir um único fluxo contabilístico. Por exemplo, o WooCommerce pode registar a reserva local e enviar ao sistema externo um pedido identificado de reserva. Quando o pagamento é confirmado, essa reserva passa a compromisso ou saída, de acordo com a operação externa. Se expirar, ambas as partes devem receber ou derivar uma libertação verificável.

Uma reserva deve incluir, no mínimo, o identificador da encomenda ou sessão, SKU ou variação, quantidade, estado, hora de expiração e uma chave única de operação. Não basta armazenar uma quantidade agregada: sem identidade, não é possível saber o que libertar nem explicar uma indisponibilidade.

A redução visível do stock, a reserva operacional e o movimento físico são transições distintas. Decidir onde ocorre cada uma evita ajustes manuais posteriores que ocultam a origem do erro.

Processar alterações com filas, idempotência e ordem

As atualizações de inventário não devem ser executadas como trabalho pesado dentro de um pedido web do catálogo ou do checkout. Um endpoint pode validar e persistir a mensagem rapidamente; um consumidor assíncrono processa depois a atualização, regista o resultado e aplica tentativas controladas.

As filas desacoplam picos de eventos da capacidade do WooCommerce e do sistema externo. No entanto, uma fila não corrige, por si só, duplicados nem eventos fora de ordem. Cada mensagem necessita de um identificador idempotente, e o processador deve recordar se já aplicou essa operação.

chave_idempotência = origem + tipo_evento + identificador_operação

Para cada SKU, localização ou combinação que partilhe inventário, é conveniente manter uma sequência ou marca temporal fiável. Se chegar um evento antigo depois de um mais recente, não deve substituí-lo sem uma regra explícita. Quando não existe uma ordem global garantida, é preferível aceitar o evento, marcar a entidade para reconciliação e consultar o estado autorizado antes de corrigir.

Também é necessário limitar a capacidade: tamanho máximo do lote, concorrência do consumidor, tentativas com espera progressiva e uma fila de incidentes para mensagens que ultrapassem o limite. Tentar repetidamente uma credencial inválida ou um SKU inexistente apenas acumula atraso e oculta o problema.

Responder a atrasos e indisponibilidade sem bloquear a loja

A loja necessita de uma política de degradação. Se o ERP não responder, não é razoável que cada página de produto fique à espera de uma ligação externa. A página pode usar a última projeção conhecida, mas a organização deve decidir o que acontece de acordo com a antiguidade do dado e a criticidade do artigo.

• Para stock amplo, a disponibilidade publicada pode ser mantida enquanto é emitido um alerta de atraso.
• Para unidades escassas ou produtos de elevada procura, a compra pode ser ocultada, pode ser aplicada uma margem conservadora ou pode ser exigida uma validação adicional antes da confirmação.
• Para uma encomenda já iniciada, pode ser permitido o avanço até uma verificação final, desde que a mensagem comercial e a política de exceção estejam definidas.

A confirmação da encomenda também não deve depender de uma tarefa longa. Deve registar de forma duradoura a intenção de compra e desencadear o processo posterior. Se uma reserva externa falhar, a encomenda necessita de um estado operacional claro para revisão, pagamento pendente ou cancelamento, e não de uma resposta ambígua ao cliente nem de um processo bloqueado.

Conciliar diferenças sem apagar decisões recentes

A reconciliação compara a projeção do WooCommerce com a fonte autorizada de inventário e com as reservas ativas. Deve ser executada de forma agendada e também após incidentes, acumulação de mensagens ou recuperação de um serviço externo.

Não é conveniente substituir cegamente todas as quantidades. Uma correção pode substituir uma reserva criada há segundos e que ainda não foi propagada. Antes de aplicar o ajuste, é necessário verificar a marca temporal, versão ou sequência de ambas as partes, as operações pendentes e as reservas locais ativas. As diferenças sem explicação devem passar para revisão, especialmente se afetarem encomendas pagas ou produtos com stock negativo.

Uma reconciliação útil classifica a causa: evento não recebido, falha no processamento, alteração manual, SKU mal associado, cálculo diferente de disponível ou atraso normal dentro da janela acordada. Corrigir o valor sem registar a causa faz com que o mesmo erro volte a surgir.

Rastreabilidade e testes antes de ativar a integração

Cada alteração deve deixar uma linha de auditoria: SKU e variação, origem, quantidade anterior e nova, tipo de movimento, identificador de evento, encomenda ou reserva relacionada, data de receção, data efetiva, resultado e motivo de rejeição. Esta informação permite responder por que motivo um cliente viu disponibilidade, por que motivo uma unidade foi libertada ou por que motivo um produto foi ajustado.

Antes de uma ativação gradual, os testes devem simular condições operacionais, e não apenas uma atualização correta:

1. Duas compras concorrentes da última unidade.
2. Eventos repetidos, atrasados e recebidos fora de ordem.
3. Cancelamentos, pagamentos recusados, expiração de reservas e devoluções.
4. Indisponibilidade temporária do ERP, WMS ou API de catálogo.
5. Picos de alterações de stock e recuperação de uma fila acumulada.
6. Edições manuais no WooCommerce e no sistema externo.
7. Variações, kits, produtos partilhados entre canais e alterações de SKU.

Lista de decisão para avaliar o desenho atual

• Está definida a fonte de verdade para stock físico, disponível, reserva e compromisso?
• Sabe-se exatamente quando uma reserva é criada, confirmada e libertada?
• Cada operação é idempotente e pode ser relacionada com uma encomenda, SKU e origem?
• As atualizações pesadas são processadas fora do catálogo, carrinho e checkout?
• Existe uma política explícita para dados antigos ou serviços externos indisponíveis?
• A reconciliação protege operações recentes e classifica as causas da diferença?
• As equipas de ecommerce e operações conseguem explicar uma disponibilidade concreta através de registos?

Se alguma resposta for negativa, a prioridade não deve ser simplesmente aumentar a frequência de sincronização. O redesenho deve centrar-se nos estados, na propriedade dos dados, nas transições de reserva e na recuperação perante falhas. Assim, a sincronização de stock no WooCommerce pode proteger a venda sem transformar o inventário externo num ponto único de bloqueio.