Erros de integração com marketplaces: os que mais me pegaram
Uma lista honesta de tropeços de quem já implantou canal, com o sintoma que cada um produz e o caminho mais curto para o diagnóstico.
Já perdi pedido por ambiente trocado, já prometi canal que dependia de homologação e já reprocessei fila até estourar cota. Todos os erros de integração que estão aqui foram meus ou aconteceram com times que eu acompanhei de perto. Nenhum deles é exótico. Todos são evitáveis, e por isso doem tanto.
A lista abaixo está em ordem de frequência, e não de gravidade. Os mais comuns são bobos. Os graves são raros.
Se você está começando, leia junto com o checklist de entrada em um novo canal, que é o texto preventivo desta mesma história.
Erros de integração que aparecem no primeiro mês
Todos os quatro me pegaram na primeira implantação. Nenhum deles gera erro na tela, e é isso que os torna perigosos.
| Erro | Sintoma que aparece | Onde olhar |
|---|---|---|
| Ambiente marcado errado | Anúncio publica, pedido nunca chega | Campo de ambiente da conta |
| Identificador do seller incorreto | Evento chega e não vira pedido | Cadastro da conta e painel do canal |
| Rotina não agendada | Tudo congelado, sem nenhum erro | Horário da última execução do comando |
| Alerta de token ignorado | Integração para de repente numa sexta | Painel de contas e alertas |
Os dois primeiros se resolvem no cadastro de contas e credenciais de canal. O terceiro está em CLI de sincronização e agendamento das rotinas. O quarto é disciplina, e não tem atalho.
Prometer canal que ainda não existe
Este é o erro mais caro em reputação interna. Alguém abre o catálogo, vê o rótulo disponível e monta cronograma. Só que disponível significa apenas que existe família ou conector previsto no código. Credencial ativa, contrato comercial, aderência aos endpoints atuais e homologação ponta a ponta continuam sendo etapas obrigatórias.
Some as condicionais declaradas: importação de anúncios da Amazon depende de relatórios assíncronos, publicação direta em AliExpress, Shein e TikTok depende do schema de categoria e da homologação, e Via, Shein, MadeiraMadeira, Elo7 e Rappi têm paths ou escopos a confirmar no credenciamento.
Culpar a integração quando o problema é o cadastro
Foi o meu erro favorito durante um semestre inteiro. Pedido parado esperando vínculo, anúncio recusado por atributo, produto duplicado gerando saldo fantasma. Tudo isso parece problema de conector e é problema de catálogo.
- SKU divergente entre o anúncio e o cadastro do ERP
- EAN ausente, digitado errado ou repetido entre variações
- Produto cadastrado duas vezes por origens diferentes
- Categoria interna sem correspondência externa mapeada
- Grade criada fora do produto pai, quebrando o saldo por combinação
A cura está em governança de SKU e EAN no multicanal. Cada hora investida ali economiza dez horas de vínculo manual depois.
Brigar com a fila
Reprocessar item que ainda tem tentativa disponível não acelera nada. A fila tenta até cinco vezes, com intervalos de 1, 5, 15, 60 e 240 minutos, e essa cadência cobre a maior parte das falhas passageiras. O único alarme real é a falha final.
Meu recorde de teimosia foi triplicar uma fila durante uma manutenção programada de canal. Quando o canal voltou, engoliu tudo, mas consumiu cota que fez falta no fim do dia. O comportamento correto está em fila de sincronização e política de tentativas.
Achar que o sistema faz o que ele não faz
Três expectativas erradas aparecem sempre. A importação não emite NF-e automaticamente. A camada de delivery recebe e normaliza pedidos, mas o importador comum grava em pedidos e itens de pedido, e não na estrutura dedicada de delivery, com cardápio ainda condicionado à homologação. E o saldo informado pelo canal nunca substitui o estoque central.
Nenhuma dessas é limitação escondida. Todas estão declaradas. O erro é não ler antes de prometer.
Abrir canais demais ao mesmo tempo
Guardei o meu preferido para o fim. Abri três canais no mesmo mês porque a tela permitia. Cada um tinha uma exigência diferente de categoria, um ritmo diferente de homologação e um problema diferente de cadastro. Não consegui aprender com nenhum, porque estava apagando incêndio nos três.
Um canal por vez, com piloto pequeno e duas semanas de observação, entrega mais no trimestre do que três canais simultâneos. Para desenhar isso com calma, veja estratégia multicanal e apoie a decisão em números com dados e relatórios.