Integração Mercado Livre

Onde costuma quebrar

Os problemas que mais aparecem numa integração com o Mercado Livre

A integração rodou por meses e um dia parou de baixar pedidos: toda chamada volta com erro de autorização. Alguém trocou a senha da conta, ou dois processos renovaram o token ao mesmo tempo e um deles gravou o refresh token que já não valia.

É o caso mais comum, não o único. Notificação lenta que faz o Mercado Livre desativar o tópico. Variação publicada no modelo antigo para vendedor que já está no User Products. Título cortado porque alguém fixou 60 caracteres no código, quando o limite vem da categoria. Margem errada porque o custo fixo mudou em março de 2026.

Eu ligo Magento 2, WooCommerce e ERPs ao Mercado Livre pela API oficial e também ajudo na implantação e otimização da conta. Os detalhes abaixo seguem a documentação para desenvolvedores do Mercado Livre, consultada em 22/11/2026.

Como funciona

Como eu faço a integração com o Mercado Livre

  1. Diagnóstico. Onde está o estoque, quem emite a nota, qual modalidade de envio cada produto usa e se a conta já está no User Products. Confiro também a aplicação: criar uma nova no DevCenter passa por análise, e desde 30/08/2026 ela precisa estar separada da do Mercado Pago, sem escopos urn:mp.
  2. Autorização OAuth 2.0. Fluxo de código de autorização com PKCE (S256), redirect_uri idêntica à cadastrada e o parâmetro state. Quem autoriza precisa ser administrador da conta; usuário operador recebe invalid_operator_user_id.
  3. Token sob trava. O access_token vale 6 horas. O refresh_token vale 6 meses e é de uso único: cada renovação devolve um novo, e só o último vale. Por isso a renovação roda num processo só, com trava, e grava o par novo antes de liberar as outras chamadas. Troca de senha, troca do Client Secret, revogação ou 4 meses sem chamada invalidam o token.
  4. Notificações em fila. Assino orders_v2, items, questions e shipments, mais catalog_item_competition_status quando há catálogo. O endpoint responde HTTP 200 em menos de 500 ms e só enfileira. O Mercado Livre tenta de novo por 1 hora, e /missed_feeds guarda até 2 dias do que se perdeu.
  5. Anúncio, estoque e preço. Publicação em POST /items e imagens em /pictures/items/upload. Para vendedor no User Products, o título vai em family_name, com preço e estoque por variação.
  6. Pedido, envio e nota. Pedido em /orders e envio em /shipments com o header x-format-new: true. No Full, o Faturador é obrigatório e emite sozinho; nas outras modalidades, a emissão pode ser feita pela API.
  7. Acompanhamento. Log por chamada, alerta para token, 429 e nota pendente, e revisão quando o Mercado Livre muda regra.

Os endpoints que mais aparecem no meu código

POST https://api.mercadolibre.com/oauth/token     troca do code pelo token
GET  /users/$USER_ID/items/search                 anúncios do vendedor
GET  /orders/search?seller=$SELLER_ID&order.status=paid
GET  /shipments/$SHIPMENT_ID                      header x-format-new: true
GET  /sites/MLB/listing_prices                    com logistic_type e shipping_mode
POST /users/$USER_ID/invoices/orders              {"orders":[...]}
GET  /missed_feeds?app_id=$APP_ID                 notificações perdidas

Caminhos conforme a documentação oficial em novembro de 2026. Credencial e token ficam fora do código, como mostro em chave de API fora do Git.

Limites

Limites que entram no desenho da integração

  • Requisições: sem número geral publicado. O limite é por aplicação e por endpoint, e o excesso devolve 429 com local_rate_limited. A recomendação oficial é backoff exponencial com jitter. A exceção documentada são as APIs do Flex, com 1.000 requisições por minuto.
  • Título: o limite vem do campo max_title_length de cada categoria. Numa consulta à API pública em 22/11/2026, a maioria tinha 60 caracteres, mas Celulares e Smartphones tinha 150.
  • Variações: até 100 por anúncio, e até 250 em algumas categorias. Anúncio de catálogo não tem variação.
  • Pedidos: a API guarda pedidos por até 12 meses. Histórico mais antigo precisa estar no seu banco.
  • Tarifa: segundo a Central de Ajuda do Mercado Livre, o Clássico (gold_special) cobra de 10% a 14% e o Premium (gold_pro) de 15% a 19%, conforme a categoria. Para margem certa, consulte listing_prices com logistic_type e shipping_mode, porque desde 02/03/2026 o custo fixo depende da logística.
Comparação

Full, Flex, Coleta e Agências do ponto de vista da integração

Modalidades do Mercado Envios, segundo a Central de Ajuda e a documentação do Mercado Livre (consulta em 22/11/2026)
PontoFullFlexColeta e Agências
Quem guarda e despachaO Mercado Livre, no centro de distribuiçãoVocê, com entrega própria ou contratadaVocê embala; a coleta retira ou você leva à agência
Nota fiscalFaturador obrigatório, emissão automáticaObrigatória no Mercado Envios; Faturador recomendadoObrigatória; sem ela não sai etiqueta e o anúncio é pausado
Custo fixo abaixo do limite de preço (desde 02/03/2026)Não; paga custo de envio por peso e preçoSim: R$ 6,25 a R$ 7,75 por unidade, até R$ 78,99Não; paga custo de envio por peso e preço
Estoque na integraçãoVale o do centro de distribuiçãoSeu, sincronizado com a lojaSeu, sincronizado com a loja
RequisitoReputação ativa, produto apto e espaço no centroReputação amarela ou verde; 97% no prazo para manter o mesmo dia97% no prazo para manter o Chegará amanhã

Full não compensa para todo produto: armazenagem é cobrada por dia e por unidade, e estoque parado há mais de 4 meses paga custo extra. Essa conta a Ana Paula, sócia da Agência Buzz, faz na página de especialista Mercado Livre.

Exemplo

Um cenário comum, do pedido à nota

Um cenário comum: loja em Magento 2, ERP emitindo nota, anúncios no Mercado Livre criados à mão e estoque atualizado por planilha. Chega até mim como venda cancelada por falta de estoque e reputação saindo do verde, que na janela de 60 dias aceita até 1,5% de canceladas pelo vendedor, segundo a Central de Ajuda.

O que eu entrego: anúncio e variação ligados ao SKU do Magento; estoque calculado a partir da quantidade disponível para venda, menos uma margem para o canal; notificação em fila, processada pelo cron; pedido criado no Magento com o número do Mercado Livre; nota pelo Faturador via API ou pelo fluxo que o seu contador definiu; e relatório do que falhou nas últimas 24 horas.

Quando você não precisa de mim

  • Se você vende pouco, só no Mercado Livre, o painel do vendedor e o simulador de custos resolvem.
  • Se o seu ERP já integra com o Mercado Livre e cobre a sua regra, o trabalho é configurar, não programar.
  • Regra fiscal não é comigo: CFOP, regime e os campos de IBS e CBS que o emissor pede para o Regime Normal são do contador.
  • Não prometo posição na busca nem vitória no catálogo, que considera preço, parcelamento, frete e reputação. Eu entrego o dado atualizado, via price_to_win.
  • Não sou parceiro certificado do Mercado Livre e não vendo integração pronta por assinatura.

Perguntas frequentes

Quanto tempo dura o token da API do Mercado Livre?

O access token dura 6 horas. O refresh token dura 6 meses e é de uso único: cada renovação devolve um novo, e só o último vale. Troca de senha, troca do Client Secret, revogação ou 4 meses sem chamadas à API invalidam o token.

Por que o Mercado Livre desativou as minhas notificações?

A documentação pede resposta HTTP 200 em até 500 milissegundos, e tópico que não responde a tempo pode ser desativado. O certo é responder na hora, guardar a notificação numa fila e processar depois.

O que muda na integração com o User Products?

É o modelo do Mercado Livre que permite preço, estoque e entrega diferentes por variação. Para vendedor já ativado, o título vai no campo family_name, e integração que não se adaptou não consegue mais publicar no modelo antigo.

Sou obrigado a usar o Faturador do Mercado Livre?

No Full, sim: ele é obrigatório e emite as notas sozinho. Nas outras modalidades é recomendado e gratuito, e exige CNPJ habilitado na Sefaz e certificado A1. Na Coleta e nas Agências, sem nota não sai etiqueta.

Dá para integrar WooCommerce com o Mercado Livre sem plugin pago?

Dá, com código próprio falando com a API e uma fila no Action Scheduler. Para loja pequena, plugin ou ERP com conector costuma sair mais barato; código próprio vale quando a regra da loja não cabe no plugin.

Você também cuida da conta e dos anúncios?

Faço a implantação técnica e ajusto a conta junto com a Ana Paula, sócia da Agência Buzz, que cuida da operação: título, ficha técnica, fotos, reputação, logística e Mercado Ads.