Skip to main content
O Mercado Livre é o maior marketplace da América Latina. A integração usa OAuth 2.0 e importa vendas pagas como shipments.

​
Conectando

​
1. Autorizar OAuth 2.0

  1. Acesse Integrações > Mercado Livre
  2. Clique em Conectar Mercado Livre
  3. Você será redirecionado para o ML (https://auth.mercadolivre.com.br/authorization) — faça login e autorize
  4. O ML retorna para o BulkRoute no endpoint /integrations/mercadolivre/callback com o código
  5. O BulkRoute troca o código por access_token e refresh_token e armazena na integração
O refresh_token é usado automaticamente quando o access_token expira. Você não precisa reconectar manualmente enquanto o refresh token for válido.

​
2. Mapear carriers

O Mercado Livre identifica a opção de envio por shipping.option_id. Mapeie em Integrações > Mercado Livre > Mapeamentos: Se não houver mapeamento, o BulkRoute faz fallback por nome: se shipping_option.name contiver “CORREIOS”, “JADLOG” ou “BRASPRESS”, usa o carrier correspondente; caso contrário, usa MERCADOLIVRE.

​
3. Disparar sincronização

A sincronização é manual — não há cron automático. Para importar vendas:
  1. Em Integrações > Mercado Livre, clique em Sincronizar Agora
  2. Escolha o tipo de sync:
    • orders — importa vendas pagas do ML
    • tracking — envia tracking codes de volta ao ML
    • full — executa ambos
  3. O job entra na fila BullMQ e processa em background (concurrency 2)
  4. Acompanhe o progresso em Sync History
O Mercado Livre envia webhooks para POST /integrations/mercadolivre/webhook, mas o BulkRoute atualmente apenas registra o evento (log) — não dispara sincronização automaticamente. Use o botão Sincronizar Agora manualmente.

​
O que é importado

​
Cubagem

O Mercado Livre não envia dimensões por item. O BulkRoute resolve cubagem de duas formas:
  1. Mapeamento manual de categoria — em Integrações > Mercado Livre > Mapeamentos, crie um mapeamento do tipo category com external_id = category_id do ML e bulkroute_value = objeto JSON com weight, height, width, length
  2. Variação do item — se não houver mapeamento, o BulkRoute usa variation.weight/height/width/length do item ML (quando disponível)
A documentação anterior mencionava uma “tabela de cubagem padrão por categoria” automática. Isso não existe no código — a cubagem depende de mapeamento manual ou dos dados de variação do item.

​
Sincronização de tracking

O BulkRoute envia o tracking code para o ML via POST https://api.mercadolibre.com/shipments/{shipmentId}/tracking com corpo:
O sync tracking busca shipments com tracking_code e metadata.mlShipmentId (limite 200 por execução).

​
Mercado Envios vs frete próprio

O BulkRoute detecta se o pedido é Mercado Envios (frete gerenciado pelo ML) verificando shipping.id. Quando detectado, armazena metadata.mlIsMercadoEnvios: true.
Atualmente não há diferença operacional entre Mercado Envios e frete próprio no BulkRoute — ambos seguem o mesmo caminho de criação de shipment. O flag mlIsMercadoEnvios é apenas informativo no metadata.

​
Endpoints da API BulkRoute

​
Rate limit e retry

  • A API do ML tem rate limit. Em 429, o BulkRoute respeita Retry-After (default 2s) e tenta novamente (até 3 vezes)
  • Fila BullMQ: 3 tentativas, backoff exponencial de 10s
  • Concorrência do worker: 2

​
Troubleshooting