Integração de WMS para Pequeno E-Commerce
A questão de quando um sistema de gerenciamento de armazém vale a pena integrar surge mais cedo do que a maioria das pequenas operações de e-commerce espera. As planilhas funcionam bem até que não funcionam mais — e o ponto de inflexão geralmente não é o volume de pedidos, mas a complexidade dos pedidos: múltiplos SKUs com rastreamento de variantes, kits, pedidos em atraso em múltiplos locais de atendimento ou a necessidade de figuras precisas de disponível para promessa no checkout. Esta publicação cobre nossa experiência integrando o GreaterWMS com uma pequena operação de e-commerce, o que funcionou, o que exigiu mais design do que antecipamos, e onde as planilhas ainda são a resposta certa.
Por que GreaterWMS
GreaterWMS é um sistema de gerenciamento de armazém de código aberto com uma API REST, um backend Django e um frontend Vue. Ele suporta inventário em múltiplos armazéns, rastreamento de lotes e partidas, gerenciamento de pedidos de entrada e saída e relatórios básicos. O código-fonte é ativamente mantido e a documentação da API, embora não seja exaustiva, cobre as operações principais.
Escolhemos o GreaterWMS em detrimento de alternativas hospedadas por dois motivos. Primeiro, já executávamos uma infraestrutura self-hosted e não queríamos adicionar outra dependência SaaS com precificação por pedido em escala. Segundo, a natureza de código aberto significava que poderíamos estender o modelo de dados sem esperar por um ciclo de solicitação de funcionalidades do fornecedor. Para uma pequena operação com necessidades específicas em torno do rastreamento de validade de lotes, essa flexibilidade importava.
A implantação é uma stack Docker Compose com a aplicação Django, PostgreSQL e Redis. Em um VPS modesto, ela roda confortavelmente ao lado de outros serviços. A configuração inicial leva algumas horas; o trabalho de integração leva consideravelmente mais tempo.
Padrões de Integração de API
O GreaterWMS usa autenticação baseada em token. Você gera um token por usuário através da interface administrativa e o passa como um Bearer token no cabeçalho de Autorização. Não há fluxo OAuth ou mecanismo de rotação de chaves de API integrado, o que significa que você deve criar um usuário de serviço dedicado com permissões mínimas em vez de usar uma conta de administrador.
A API é amplamente RESTful com payloads JSON. Os principais recursos com os quais você interage para uma integração de e-commerce são: goods (seu catálogo de produtos em termos de WMS), inventory (níveis de estoque atuais por armazém e produto), inbound orders (ordens de compra e devoluções) e outbound orders (pedidos de clientes para atendimento).
Um padrão que estabelecemos cedo: nunca chamar a API do WMS de forma síncrona a partir do caminho de checkout. O WMS não está no seu caminho de transação crítica, e se ele estiver lento ou temporariamente indisponível, não deve afetar a capacidade do seu cliente de concluir uma compra. Todas as interações com o WMS passam por uma fila assíncrona. O checkout registra o pedido no seu banco de dados principal e publica um evento. Um worker em segundo plano recebe o evento e cria o pedido de saída no GreaterWMS. Falhas no worker são repetidas com backoff exponencial e geram alertas em caso de falha persistente. Esse desacoplamento é inegociável.
Sincronização de Pedidos
A chamada de criação de pedido de saída recebe um ID de produto, uma quantidade e informações de endereço de destino. O mapeamento entre os itens de linha do seu pedido de e-commerce e os IDs de produtos do WMS precisa ser mantido explicitamente. Armazenamos o ID de produto do WMS como um campo adicional em cada variante de produto no nosso banco de dados de catálogo. Esse mapeamento é definido manualmente quando um novo produto é criado e verificado no worker de sincronização antes de despachar a solicitação de criação do pedido de saída.
A sincronização de status funciona na direção oposta: o GreaterWMS atualiza o status do pedido de saída conforme o armazém o processa, e seu sistema de e-commerce precisa refletir isso. O GreaterWMS não envia atualizações de status; você faz polling. Executamos um job de polling a cada poucos minutos que consulta pedidos de saída com status “em andamento” e verifica se o status mudou para “despachado” ou “cancelado”. Quando isso acontece, atualizamos o pedido correspondente no nosso banco de dados de e-commerce e acionamos quaisquer ações subsequentes — e-mails de notificação ao cliente, atualizações de número de rastreamento.
A idempotência na criação do pedido de saída é importante. Se o worker em segundo plano tentar novamente após uma falha transitória, ele não deve criar pedidos de saída duplicados no GreaterWMS. Armazenamos o ID do pedido de saída do WMS no nosso registro de pedido interno imediatamente após uma chamada de criação bem-sucedida. Em uma nova tentativa, o worker verifica se um ID do WMS já existe antes de fazer a chamada de criação. Se existir, o worker pula a criação e prossegue com qualquer ação subsequente que estava tentando executar.
Atualizações de Inventário
Manter as contagens de inventário do seu e-commerce sincronizadas com o WMS é a parte que requer mais atenção contínua. Há duas direções: sua plataforma de e-commerce precisa de níveis de estoque precisos para evitar vendas em excesso, e o WMS precisa refletir compras e devoluções que se originam fora dele.
Para leituras de nível de estoque, puxamos snapshots de inventário da API de inventário do GreaterWMS de forma programada e gravamos os valores em um cache Redis que a loja de e-commerce lê. O intervalo de polling depende da sua velocidade de vendas. Para produtos de giro lento, de hora em hora é suficiente. Para produtos que vendem em picos, você precisa de um intervalo menor ou de um modelo de reserva no checkout — onde um cliente colocando um item no carrinho reserva temporariamente o estoque independentemente do ciclo de sincronização do WMS.
As devoluções são o caso mais complexo. Um item devolvido pode retornar ao estoque, ir para um local de quarentena para inspeção ou ser baixado. O GreaterWMS tem um fluxo de pedido de entrada para devoluções, mas mapear os estados de devolução do seu e-commerce para os estados de pedido de entrada do WMS requer um design explícito. Criamos uma máquina de estados que traduz os códigos de motivo de devolução do sistema de e-commerce em códigos de disposição do WMS, e revisamos o mapeamento com a equipe do armazém sempre que um novo motivo de devolução é adicionado. Sem esse mapeamento, o estoque devolvido silenciosamente falha em reaparecer no inventário disponível.
Condições de Corrida e Estoque Reserva
Mesmo com a sincronização de inventário baseada em polling, condições de corrida são possíveis. Se dois pedidos chegarem simultaneamente e ambos lerem o mesmo nível de estoque em cache antes que qualquer um deles seja refletido no WMS, você pode vender a mais pela quantidade de unidades equivalente ao intervalo de polling. Para produtos onde a venda em excesso é inaceitável — itens de edição limitada, perecíveis com restrições rígidas de lote — a abordagem correta é uma camada de reserva que decrementa uma contagem disponível local no checkout e reconcilia com o WMS de forma assíncrona.
Uma mitigação mais simples é o estoque reserva: manter uma contagem disponível no seu banco de dados de e-commerce que é o nível de estoque do WMS menos uma pequena reserva. Os pedidos depletam esse buffer. Quando o buffer chega a zero, o produto aparece como fora de estoque, mesmo que o WMS ainda mostre unidades. Isso cria um pequeno risco de manter estoque que os clientes não podem pedir, mas elimina o risco de venda em excesso e não requer nenhuma lógica de reserva. Para a maioria das pequenas operações, a abordagem de buffer é a troca certa.
Quando o WMS Faz Sentido vs Planilhas
Um sistema de gerenciamento de armazém adiciona complexidade de integração, sobrecarga operacional e um novo sistema para manter. Antes de se comprometer com uma integração, vale a pena ser honesto sobre se os problemas que você está tentando resolver realmente exigem um WMS.
As planilhas são adequadas quando: sua contagem de SKUs é pequena e estável, você tem um único armazém ou local de atendimento, os pedidos são processados manualmente e o volume é baixo, e você não precisa de disponível para promessa em tempo real no checkout. Nesse caso, uma integração de WMS custa mais para construir e manter do que os problemas que ela resolve.
Um WMS começa a valer a pena quando: você tem múltiplos armazéns ou locais de separação, você precisa de rastreamento de lote ou partida por razões de conformidade ou qualidade, sua taxa de devolução é alta o suficiente para que a disposição de devoluções precise de tratamento sistemático, ou seu processamento de pedidos é automatizado e requer reserva precisa de estoque para evitar vendas em excesso. Esses são problemas operacionais que as planilhas genuinamente não conseguem resolver em nenhum nível razoável de rigor.
O trabalho de integração que descrevemos nesta publicação levou várias semanas de tempo de engenharia, incluindo testes. Esse tempo poderia ter financiado uma quantidade significativa de trabalho manual de coordenação de armazém. Seja preciso sobre quais problemas você está resolvendo e se o software é a ferramenta certa para eles antes de começar.