Integração marketplace Mercado Livre: sincronize estoque e preços sem oversell

O conector pronto resolve — até o dia em que resolve só uma parte, e o que sobra é justamente o que quebra a operação: oversell, divergência de estoque, regra de preço que o plano do SaaS não implementa. Quando isso acontece, o problema não é o conector. É tratar integração de marketplace como assinatura quando ela é, na verdade, um projeto de engenharia.

Este post estrutura a decisão: como a API do Mercado Livre funciona, o problema central de sincronizar estoque entre marketplaces, a arquitetura multicanal que evita vender o que você não tem e quando o conector SaaS perde para a integração sob medida.

Você não precisa decorar endpoints — a documentação oficial faz esse papel. O que muda o desenho da sua integração são quatro características:

• OAuth com token que expira. A credencial é renovada por refresh token; a integração que ignora isso cai sem aviso a cada expiração. Token é um subsistema com monitoramento, não uma variável de ambiente esquecida.
• Notificações por webhook. Pedidos, mudanças de anúncio e atualizações chegam como eventos. O canal certo é o evento; polling é o que queima cota e entrega divergência de horário.
• Rate limits. Cada leitura e cada escrita consome cota. A sincronização ingênua que reescreve o catálogo inteiro a cada ciclo esbarra no limite exatamente no pico — quando você menos pode esperar. Os valores mudam; confira os limites atuais na documentação oficial.
• Autenticidade dos eventos. Todo webhook que entra na sua infraestrutura precisa ter a assinatura validada antes de qualquer processamento. Sem isso, seu endpoint é uma porta aberta.

Somado: integração com o Mercado Livre é um sistema orientado a eventos, com credencial rotativa e cota escassa. Quem faz "chamada HTTP no meio do controller" colhe divergência silenciosa.

Três modos de falha aparecem em toda operação multicanal:

• Divergência. Cada canal mantém a sua verdade de estoque. Sem uma fonte única, a diferença só aparece quando o cliente reclama do cancelamento.
• Oversell. Dois pedidos no mesmo SKU, em canais diferentes, entre duas janelas de sincronização: você vendeu o que não tinha. Em marketplace, oversell é punido com cancelamento e desgaste de reputação — o custo real é maior que a venda perdida.
• Estrangulamento de concorrência. Sincronização ingênua reescreve o estoque inteiro a cada evento. Com rate limit, o backlog cresce, a divergência cresce junto — e alguém propõe "sincronizar com mais frequência", o que piora o gargalo em vez de resolver.

A solução tem três peças que andam sempre juntas:

1. Fila única de eventos. Nenhum sistema escreve direto no canal. Todo pedido e toda mudança entra na mesma fila e é processada em ordem por SKU.
2. Versão de estoque. O estoque carrega a versão da sua fonte (o ERP). A escrita no canal só procede sobre a versão mais recente; versão velha é descartada. Estoque vence como leite.
3. Idempotência por evento. O marketplace reenvia notificações; o mesmo evento entregue duas vezes não pode debitar estoque duas vezes. Deduplicação por ID antes de processar — os detalhes de implementação estão em idempotency for webhooks (EN).

Duas camadas merecem destaque:

• Normalização de catálogo. Cada canal fala um dialeto: SKU, categoria, variante, unidade. O catálogo canônico é a tradução oficial; cada canal vira um adaptador fino. Sem essa camada, você tem três verdades — e nenhuma certa.
• Motor de regras por canal. Preço mínimo, margem-alvo, pausa automática por estoque baixo, regra de frete. Política de canal explicitada em regra, não espalhada em if pelo código.

Esse desenho roda naturalmente sobre a infraestrutura descrita em arquitetura serverless AWS para integrações: carga intermitente de webhook, fila com DLQ e worker assíncrono — o caso de uso ideal de serverless.

Gestão multicanal de marketplace fracassa quando cada canal vira um projeto separado. A arquitetura certa tem um pipeline e N adaptadores:

• Uma mudança de preço no ERP se propaga para todos os canais pelo mesmo caminho.
• Um novo canal entra como adaptador — tradução de dialeto — sem reescrever regras.
• Divergência é investigada em um lugar: a fila, com evento rastreável e DLQ. Não em três painéis de três fornecedores.

Nenhuma resposta serve todo mundo — a tabela é a decisão:

Regra prática: conector resolve catalogar e vender; integração sob medida resolve concorrência de estoque, regra por canal e ERP no meio do caminho. Se o seu problema é "anunciar mais rápido", SaaS. Se é "parar de vender sem estoque e de perder margem por regra", engenharia.

Automatizar anúncios e preços no Mercado Livre funciona em duas camadas:

• Regras determinísticas primeiro. Piso de margem, teto de preço, pausa por estoque baixo, ajuste por posição de concorrência. Sem IA: regra auditável que o time entende e corrige.
• IA onde agrega valor de verdade. Descrição de anúncio, título por canal, variações de copy para teste — geradas com o guia de tom da marca e revisadas por humano. Pricing automático agressivo sem teoria de margem é uma forma elegante de quebrar a operação. A abordagem completa está em marketing com IA para empresas.

1. Polling em vez de webhook — queima cota e entrega informação atrasada.
2. Escrever no canal direto do webhook — sem fila, sem retry, sem DLQ: o primeiro erro do parceiro derruba tudo.
3. Sem idempotência — o reenvio do marketplace vira baixa dupla de estoque.
4. Catálogo duplicado por canal — três verdades, nenhuma certa.
5. Token OAuth sem renovação monitorada — a integração cai e ninguém sabe por quê.
6. Fila sem DLQ — uma mensagem quebrada trava a sincronização inteira. E fila, sozinha, não conserta worker lento — queues are not a silver bullet (EN).

A arquitetura deste post é a que usamos para integrações desse tipo: validação de assinatura na entrada, idempotência por evento, filas com DLQ e normalização de catálogo — os padrões de automação de workflows que sustentam nossos sistemas orientados a eventos, na linha de event-driven systems without folklore (EN).

Um exemplo concreto no mesmo perímetro: implementamos o Mercado Pago Checkout Pro (Pix, cartão e boleto) em fluxos de atendimento por WhatsApp, com webhook de pagamento processado de forma idempotente — a mesma disciplina de eventos que uma integração de marketplace exige. O contexto está em agente de IA para WhatsApp e e-commerce e na página de agentes para WhatsApp.

Se o desenho faz sentido mas você quer validar o formato antes do sistema completo, dá para começar enxuto — um MVP de lançamento que sincroniza um canal, um estoque e as duas regras de preço que mais doem, e cresce a partir daí.