Importação de pedidos: o dia em que o mesmo pedido entrou duas vezes
O caminho completo de um pedido de canal até virar pedido nativo, com as regras que evitam duplicidade e os pontos em que o processo ainda pede gente.
Antes de existir importação de pedidos aqui, a gente copiava do painel do canal para o ERP na unha. Numa segunda de dezembro, duas pessoas digitaram o mesmo pedido com dez minutos de diferença. Saíram duas notas, duas baixas de estoque e dois volumes para o mesmo cliente. Ele devolveu um. O frete de devolução foi por nossa conta, claro.
Essa história é a razão pela qual a palavra idempotente aparece tanto neste texto. O hub trata pedido duplicado como não evento, e isso vale mais do que qualquer tela bonita.
Vou descrever o caminho inteiro: como o pedido é detectado, o que é gravado, o que acontece com estoque e financeiro, e onde ainda é preciso um humano decidir. Se o saldo por trás disso ainda não está claro, leia antes estoque centralizado para múltiplos marketplaces.
A importação de pedidos começa por dois caminhos
O hub trabalha com polling e com recepção de eventos. O polling consulta o canal periodicamente e é o caminho que sempre funciona. O evento chega mais rápido, mas depende do canal e nunca é tratado como verdade sozinho. Os dois convivem, e é justamente por isso que a idempotência precisa existir.
Nenhum efeito é aplicado com base apenas no que chegou pelo webhook. O hub registra o evento, resolve a empresa pelo identificador do seller, enfileira e só então consulta o canal de forma autenticada, servidor a servidor. Esse detalhe está aprofundado em webhooks de marketplace e segurança.
O espelho: guardar o pedido como ele veio
Antes de virar pedido nativo, o pedido do canal é gravado num espelho normalizado, com comprador, itens, envio, pagamento, comissão e o payload bruto original. Guardar o bruto parece exagero até o dia em que o canal muda um campo e você precisa provar o que recebeu.
O cliente é localizado ou criado antes da gravação do pedido, o que evita duplicar cadastro a cada compra. Depois disso, tudo entra numa transação única.
Resolver o item é onde o cadastro cobra a fatura
Cada item do pedido precisa virar um produto do ERP. A resolução acontece por vínculo de anúncio, por SKU ou por EAN, com vínculo manual quando nada bate. Com cadastro limpo, isso é invisível. Com cadastro sujo, vira uma fila de pedidos esperando alguém decidir de qual produto se trata.
| Etapa | O que acontece | Onde costuma travar |
|---|---|---|
| Detecção | Polling ou evento identifica o pedido novo | Conta com token vencido |
| Espelho | Grava comprador, itens, envio, pagamento e comissão | Payload com campo inesperado |
| Cliente | Localiza ou cria o cadastro | Documento ausente ou mascarado pelo canal |
| Itens | Resolve por vínculo, SKU ou EAN | SKU divergente entre ERP e anúncio |
| Gravação | Pedido, estoque e conta a receber em transação | Saldo insuficiente por divergência física |
Meu erro clássico foi tratar isso como problema de integração. Não era. Era cadastro. A leitura de governança de SKU e EAN no multicanal resolveu mais chamados do que qualquer ajuste técnico que eu fiz naquele semestre.
Estoque e financeiro andam junto com o pedido
A baixa é atômica, de produto e de combinação, e o cancelamento estorna o estoque e rebalanceia os demais canais. Produtos marcados como afiliado ou dropshipping não movimentam saldo local.
No financeiro, a importação cria de forma idempotente uma conta a receber para o repasse líquido do canal, com vencimento inicial fixado em D+30 no código. Se o seu contrato prevê outro prazo, esse ajuste precisa acompanhar o contrato do canal. Não presuma que D+30 é o prazo do seu marketplace.
- Baixa atômica de produto e de combinação na gravação do pedido
- Estorno de estoque e rebalanceio quando o pedido é cancelado
- Conta a receber idempotente para o repasse líquido do canal
- Vencimento inicial em D+30 fixado no código, a ajustar conforme contrato
- Acesso ao pedido nativo para seguir os fluxos fiscal e de expedição do ERP
A nota fiscal continua sendo decisão sua
A importação não emite NF-e automaticamente. Alguns conectores aceitam chave da nota, mas o fluxo atual do hub enfileira rastreio, transportadora e URL, sem comprovar o repasse automático da chave fiscal ao canal. Trate emissão como etapa do seu processo, dentro do que você já faz em documentos fiscais.
Já vi equipe assumir que o hub emitiria nota porque o campo existia. Ficaram três dias sem faturar pedido de canal, esperando algo que nunca ia acontecer sozinho.
O que olhar todo dia
- Pedidos aguardando importaçãoNúmero subindo é sinal de conta com problema ou rotina parada, não de movimento forte.
- Erros de importaçãoCostumam ser item sem vínculo. Resolva o vínculo e reprocesse em vez de lançar manualmente.
- Falhas finais da filaJá esgotaram as tentativas e exigem decisão humana. Nunca deixe passar do dia.
- Pedidos importados sem rastreioÉ o vazamento que mais gera reclamação, e o assunto de rastreio e status de pedidos.