Vou ser direto: a integração OMS–WMS quebra para quase todos os vendedores que conheço. Os pedidos saem do OMS; o armazém diz que nunca chegaram. O armazém diz que enviou; o comprador diz que nada chegou. Os dois sistemas em verde, e o vendedor paga a conta: a avaliação ruim, o reembolso e o custo do frete.
Eu vendo cross-border há cinco anos. Nos primeiros três, gerenciei meu próprio armazém pequeno; quando o volume estourou, migrei para um 3PL em Los Angeles em September 2024. Mesmo OMS, novo WMS — e a primeira semana me deu lições que paguei com dinheiro de verdade.
A primeira foi o mapeamento de SKU.
Tínhamos 800+ SKUs. Antes do go-live, exportei a lista para o 3PL criar os cadastros de produto no WMS dele. Parece simples. Primeira semana: 100+ pedidos travados em "pending" — o envio passava bem, mas o WMS não encontrava o SKU. Eles haviam criado uns 700; os outros 100+ eram produtos novos dos últimos dois meses, que faltavam na minha exportação. Os pedidos ficaram dois dias parados até eu vê-los no relatório de exceções, bem quando os SKUs de outono/inverno estavam decolando. 100+ pedidos saíram dois dias atrasados; o atendimento apanhou a semana inteira.
Lição dura: a tabela de mapeamento de SKU tem que conciliar a 100%, não 99%. Eu exporto cada SKU do OMS e faço vlookup contra os códigos de item do WMS — uma linha faltando, sem go-live. E uma regra dura: nenhuma página de produto vai ao ar até o mapeamento de SKU dela existir no WMS. Mapeamento primeiro, publicação depois.
A integração OMS WMS começa com a tabela de mapeamento de campos
Um push de pedido do OMS para o WMS é, no fundo, uma tabela de mapeamento de campos — e noventa por cento dos incidentes de integração vivem nela. A maioria dos guias de mapeamento de campos para integração OMS WMS para na tabela. A tabela é a parte fácil; as exceções são onde os vendedores perdem dinheiro. Aqui está nossa versão atual, com a última coluna marcando onde eu me queimei de verdade:
| Campo OMS | Campo WMS | Onde quebra |
|---|---|---|
| Número do pedido no marketplace | Referência externa do pedido | Os dois sistemas usam números de pedido diferentes — envie ambos; o WMS deve deduplicar pela referência externa |
| Número do pedido no OMS | Número do pedido de saída | Não use aqui o número do pedido do marketplace — um comprador fazendo dois pedidos no mesmo dia vai colidir |
| SKU | Código do item | A tabela de mapeamento tem que existir primeiro; "criar mapeamento" é etapa obrigatória em todo lançamento de produto novo |
| Quantidade | Quantidade de picking | Unidades! Vender por caixa vs. por unidade tem que se resolver em uma única unidade no WMS |
| Destinatário / endereço / cidade / estado / CEP / telefone | Info de entrega | A linha 2 do endereço (apt, unit, suite) tem que ser enviada — muitas integrações só mandam a linha 1 |
| Método de envio | Transportadora + código de serviço | Nunca envie nomes de exibição como "Standard" — envie códigos que os dois lados combinaram antes |
| Observação do comprador | Observação de embalagem | Campo próprio — nunca enfie nas linhas de endereço ou a validação de endereço falha |
| Loja / vendedor | Código do vendedor | Obrigatório quando várias lojas compartilham um WMS, senão o estoque é baixado do dono errado |
O mais sorrateiro são as unidades de quantidade. Nosso pack variado vendia por caixa — 12 peças cada. O OMS mandou "caixas", o cadastro do WMS estava em "peças", e os primeiros 20 pedidos pickaram 20 peças em vez de 20 caixas. Os compradores receberam uma peça, acharam que era a caixa inteira e abriram disputas por todo lado. Adicionamos uma coluna de "conversão de unidades" e sinalizamos cada pack variado. Nunca mais aconteceu.
Nunca envie nomes de métodos de envio, só códigos. Começamos com "standard" e "expedited" — o 3PL usa cinco transportadoras, cada uma com seu próprio "standard", e o WMS não sabia de qual estávamos falando. Agora os dois lados compartilham uma tabela de códigos, o OMS envia códigos como GROUND_HOME, e as discussões caíram noventa por cento.
Quatro exceções na integração OMS WMS que você vai ver toda semana
Deixo esta matriz fixada — sintoma, tratamento automático, e quando um humano entra. Quatro tipos cobrem quase tudo:
| Exceção | Sintoma | Tratamento automático | Humano entra quando |
|---|---|---|---|
| SKU sem mapeamento | Pedido travado em pending no WMS | Retido + adicionado ao relatório de exceções | No mesmo dia: adicione o mapeamento, reenvie manualmente |
| Estoque curto | Estoque insuficiente para atender | Reter o pedido inteiro, ou enviar a quantidade disponível conforme a regra | Não resolvido após 4 horas — o CS contata o comprador |
| Endereço ruim | Validação falha / pacote devolvido | Retido | Verifique o endereço manualmente, corrija, reenvie |
| Push duplicado | Mesma referência externa chega duas vezes | O WMS deduplica pela referência externa e descarta | Nenhuma ação necessária — mas a contagem de descartes tem que aparecer no relatório |
O push duplicado merece uma história própria — Black Friday 2024. Nosso push era API em tempo real; a rede falhou, o OMS estourou o timeout e tentou de novo. Sem deduplicação pelo número do pedido externo, o WMS criou dois pedidos de saída e o turno da noite enviou os dois. Um comprador recebeu dois pacotes e devolveu um — frete mais produto me custaram quase $40 naquele pedido. Uma dúzia de duplicados naquela noite. Ainda dói.
Daí saíram duas regras duras. Uma: o WMS tem que deduplicar pelo número do pedido do marketplace — idempotência vai no contrato, não num aperto de mãos. Duas: antes do go-live eu mesmo testo, reenviando o mesmo pedido 10 vezes. Um pedido de saída é aprovado; dois significa que o 3PL volta e corrige.
Endereços ruins também merecem uma nota. A linha 2 do endereço nos EUA — apt, unit, suite — cai direto o tempo todo porque os mapeamentos só mandam a linha 1. Um lote dos nossos pedidos para apartamentos saiu sem número da unidade, a entrega falhou e voltou: sete dias de ida e volta, direto para avaliações de uma estrela. Agora o OMS bloqueia o push a menos que os quatro estejam presentes — destinatário, linhas de endereço (linha 2 incluída), CEP, telefone.
A conclusão contra-intuitiva: menos campos, menos problemas
A maioria acha que mais campos significa integração melhor e tenta enviar tudo até códigos de cupom. Eu também achava, até me morder: cada campo extra é um novo ponto de falha.
Um WMS executa. Ele precisa do destinatário, do conteúdo, da quantidade, do método de envio e de qualquer observação de embalagem. Info de cupom, origem do anúncio — o WMS não usa, e um campo malformado pode derrubar o pedido inteiro. Cortamos nosso payload de 30+ campos para 18; a taxa de exceções caiu pela metade.
Trade-off relacionado: push em tempo real vs. lote agendado. Tempo real é gostoso — os pedidos chegam ao armazém em segundos — mas uma falha de rede significa pedidos perdidos ou duplicados, geralmente às 2h da manhã sem ninguém olhando. Lote (um arquivo a cada 15 minutos) parece bobo, mas é repetível e reconciliável; quando quebra, você reexecuta o arquivo. Minha configuração: push em tempo real mais um job de conciliação a cada 15 minutos comparando números de pedido nos dois sistemas. Pedidos no OMS que faltam no WMS são reenviados automaticamente. Quer os dois benefícios? Faça os dois jobs.
Checklist de go-live: 7 coisas para verificar na véspera
Nossa segunda virada rodou nesta lista — sete checks, ou sem go-live:
- Idempotência: reenvie deliberadamente o mesmo pedido 10 vezes — o WMS tem que criar exatamente 1 pedido de saída.
- Conciliação total de SKU: exporte cada SKU do OMS, vlookup contra os códigos de item do WMS. Uma linha faltando = sem go-live.
- Conversões de unidades: packs variados e packs de caixa, cada conversão detalhada na tabela de mapeamento.
- Completude do endereço: destinatário, linhas de endereço (linha 2 incluída), CEP, telefone — o OMS bloqueia o push se faltar algum.
- Tabela de códigos de transportadora: os dois lados combinam os códigos; sem nomes de exibição, sem palavras vagas como "standard".
- Observações têm campo próprio: observações do comprador nunca vão nas linhas de endereço.
- Rodada sandbox de 50 pedidos: use pedidos históricos reais, incluindo deliberadamente dados sujos — números de apartamento, caixas postais, CEPs remotos, telefones faltando.
Como ler o relatório de exceções: três números
Toda manhã às 8h, o relatório de exceções chega. Três números, só isso:
Primeiro, contagem de pedidos pendentes. Um dígito é normal; mais de 20 e eu ligo para o 3PL.
Segundo, o detalhamento das causas de pendência. Se a mesma causa liderar a lista três dias seguidos, a tabela de mapeamento ou a regra precisa de conserto — isso é sistêmico, não aleatório.
Terceiro, pedidos pendentes há mais de 24 horas — a linha vermelha. Pendente tudo bem; ignorado não. Qualquer coisa presa há tanto tempo é um envio atrasado em gestação; limpe no mesmo dia.
Primeiras duas semanas: a taxa de exceções (pendentes + erros de envio sobre pedidos totais) ficou em torno de 8%. Dois meses nessa rotina: abaixo de 0.5%. Semanas de pico como Black Friday saltam para ~1%, mas tudo é visível no relatório e tudo é acionável.
A integração OMS–WMS não é um problema de tecnologia. É um problema de atenção. Faça direito o mapeamento de campos da integração OMS WMS, dê um dono para cada exceção e leia o relatório diário — faça essas três coisas e a taxa de falha cai noventa por cento. Testei eu mesmo — de 8% a 0.5% com aquela tabela e aquele e-mail.
Por Ah K, Vendedor de e-commerce (5 anos de experiência)
Traduzido do inglês. Em caso de divergência, prevalece a versão em inglês.
