Integração Mercado Livre é ligar a sua loja Magento 2 ou WooCommerce e o ERP à API do Mercado Livre para que anúncio, estoque, preço, pedido e nota fiscal sigam sozinhos. Eu faço essa ligação com OAuth 2.0, notificações por tópico processadas em fila e emissão pelo Faturador quando ele é obrigatório, como no Full.
Atualizado em · por Roger Takemiya
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.
urn:mp.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.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.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.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./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.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 perdidasCaminhos 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.
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.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.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.| Ponto | Full | Flex | Coleta e Agências |
|---|---|---|---|
| Quem guarda e despacha | O Mercado Livre, no centro de distribuição | Você, com entrega própria ou contratada | Você embala; a coleta retira ou você leva à agência |
| Nota fiscal | Faturador obrigatório, emissão automática | Obrigatória no Mercado Envios; Faturador recomendado | Obrigató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ço | Sim: R$ 6,25 a R$ 7,75 por unidade, até R$ 78,99 | Não; paga custo de envio por peso e preço |
| Estoque na integração | Vale o do centro de distribuição | Seu, sincronizado com a loja | Seu, sincronizado com a loja |
| Requisito | Reputação ativa, produto apto e espaço no centro | Reputação amarela ou verde; 97% no prazo para manter o mesmo dia | 97% 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.
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.
price_to_win.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.
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 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.
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á, 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.
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.
Me conte o que está acontecendo. Respondo pessoalmente, em horário comercial.