← Fase 1 · Cadastro e Acesso às APIs Oficiais

Mercado Livre

Roteiro de acesso à API do Mercado Livre — 7 etapas

0 de 29 tarefas concluídas · 0%

🧭 Como usar esta página: as 7 etapas abaixo seguem a mesma lógica de travas do roteiro Shopee — uma só abre quando a anterior estiver 100% concluída.
Antes de tudo, o porquê

Por que este documento existe antes de qualquer linha de backend

A Shopee só aprova parceiro que já tem um produto ao vivo, integrado de verdade a outro marketplace. Sem essa prova, a solicitação nem entra na fila de análise. Então, antes de desenhar banco, backend ou frontend definitivos, a gente precisa primeiro ter essa integração funcionando — e o Mercado Livre foi escolhido porque o cadastro de desenvolvedor deles não tem esse tipo de barreira de entrada.

Isso significa que, na prática, este roteiro do Mercado Livre é o trabalho técnico que destrava a burocracia da Shopee — os dois roteiros andam juntos, não em sequência.

O que a pesquisa confirmou

O Mercado Livre é de fato mais aberto pra começar — sem análise manual, sem exigir produto prévio. Mas a pesquisa também trouxe à tona pontos que exigem cuidado técnico real: não existe ambiente de teste separado (os testes acontecem em produção, com usuários de teste limitados), o refresh_token só serve uma vez (diferente do padrão mais tolerante da Shopee), e só é permitida 1 aplicação por conta no Brasil.

Fonte oficialCrie uma aplicação no Mercado Livre · Authentication and Authorization
Resumo de tudo que vimos

O panorama da pesquisa do Mercado Livre, em linguagem simples

Titularidade da conta confirmado

Na prática: antes de criar qualquer coisa, a gente precisa decidir de qual conta (idealmente da nossa empresa) vai sair a aplicação — porque só dá pra ter uma por conta no Brasil, e trocar depois é dor de cabeça.

Só é permitida 1 aplicação por conta no Brasil. Ideal ser conta PJ, criada pelo administrador/dono, não colaborador.

Porta de entrada confirmado

Na prática: assim que a conta certa estiver decidida, a gente cria a aplicação no mesmo dia e já sai com as credenciais — sem esperar ninguém aprovar nada, diferente do que acontece do lado da Shopee.

Criação de aplicação é self-service e imediata — sem análise manual, sem exigir produto vivo prévio.

Autorização por vendedor confirmado

Na prática: cada vendedor que a gente conectar vai logar na própria conta do Mercado Livre e autorizar o Carteira Place individualmente — não existe um jeito de conectar vários vendedores de uma vez só.

OAuth: cada vendedor loga e autoriza individualmente. Precisa ser a conta principal do vendedor, não um colaborador.

A armadilha do refresh token confirmado

Na prática: de tempos em tempos o sistema pede uma chave nova pro Mercado Livre — só que essa chave só serve uma vez. Se o nosso código não guardar a próxima na hora certa, aquele vendedor fica sem sincronizar até reconectar manualmente.

access_token dura 6h; o refresh_token é de uso único — cada renovação troca por um novo que precisa ser salvo de forma atômica.

Sem sandbox confirmado

Na prática: antes de conectar o primeiro vendedor de verdade, a gente vai testar tudo com contas de mentirinha criadas pelo próprio Mercado Livre — porque não existe um "modo de teste" separado da produção real.

Não existe ambiente de teste separado. Até 10 usuários de teste por conta, credenciais não recuperáveis depois de criadas.

Limite de uso (rate limit) confirmado

Na prática: se a gente atualizar os dados de um vendedor com muita frequência, só a fila dele trava — não afeta os outros vendedores conectados ao mesmo tempo.

1.500 requisições/minuto por vendedor (documentado oficialmente).

Dados financeiros (Billing) confirmado

Na prática: pra mostrar o lucro em tempo real a gente usa pedidos e pagamentos; a parte de faturamento entra só uma vez por mês, pra bater o resultado oficial.

A Billing API é indicada pra reconciliação fiscal/pós-venda, não como fonte primária de dado em tempo real.

Riscos contínuos confirmado

Na prática: depois que o sistema estiver no ar, precisamos ficar de olho em como ele se comporta — um comportamento fora do padrão pode gerar suspensão do nosso acesso.

Apps podem ser bloqueados por infração de política; há relatos reais de suspensão "para análise de segurança" com pouca transparência sobre o motivo.

Custo confirmado

Na prática: a gente não paga nada pra usar a API em si — o único custo que existe é o mesmo que o vendedor já paga pra vender no Mercado Livre.

API gratuita, sem taxa por chamada. Custos existentes são as comissões normais de venda (10-19% + taxa fixa), pagas pelo vendedor.

Roteiro

7 etapas — e por que organizamos assim

A lógica aqui também é de dependência: cada etapa entrega algo que a próxima precisa. Concluir a última etapa aqui não é só "terminar o Mercado Livre" — é abrir a porta pra seguir com a Shopee.

  1. Etapa 1 — Decidir a titular do app: vem primeiro porque só dá pra ter 1 aplicação por conta no Brasil, e errar essa escolha significa recomeçar do zero.
  2. Etapa 2 — Criar a aplicação: gera as credenciais (APP_ID + Secret_Key) que tudo o resto depende.
  3. Etapa 3 — Fluxo de autorização por vendedor: só faz sentido com credenciais em mãos (Etapa 2).
  4. Etapa 4 — Renovação de tokens: ponto mais frágil do desenho técnico do ML — precisa estar pronto antes de conectar vendedores de verdade.
  5. Etapa 5 — Testes com usuários de teste: vem depois de tudo isso estar de pé, já que não existe sandbox.
  6. Etapa 6 — Coleta de dados de lucro: só então faz sentido construir o produto de verdade.
  7. Etapa 7 — Publicar o app + seção "Integrações": o fechamento — é exatamente o que destrava a Etapa 2 do roteiro da Shopee.
Pendente — pode trabalhar agora Travada — espera a etapa anterior fechar Concluída — 100% das tarefas marcadas
Etapa 1

Conta Mercado Livre: decidir a titular do app

Pendente
Por quêNo Brasil só é permitida 1 aplicação por conta, e transferir titularidade depois é problemático.
Como funcionaIdeal ser conta PJ. Validação de identidade PJ pode levar até 72h. Precisa ser administrador/dono da conta.
Ir fazer issomercadolivre.com.br
Fonte oficialCrie uma aplicação + Validações de dados
  • decisao Qual conta ML vai ser a dona da aplicação? (idealmente PJ, mesmo CNPJ da Shopee)
  • Criar/ativar a conta e completar validação de dados do titular
  • Confirmar acesso como administrador/dono, não colaborador
Etapa 2

Criar a aplicação no DevCenter

Travada
Por quêGera Client_Id (APP_ID) + Secret_Key. Só 1 app por conta — pensar os campos com calma.
Como funcionaRedirect URI precisa bater exatamente. Escopos: read + offline_access (necessário pra refresh_token server-side).
Ir fazer issodevelopers.mercadolivre.com.br/devcenter
Fonte oficialCrie uma aplicação no Mercado Livre
  • decisao Definir domínio/URL de callback definitivo antes de criar o app
  • decisao PKCE: ativar ou não? Se ativar, code_verifier/code_challenge viram obrigatórios
  • Criar aplicação com escopos read + offline_access
  • Guardar APP_ID e Secret_Key em cofre de segredos
  • Configurar tópicos de notificação: orders_v2, payments
Etapa 3

Fluxo OAuth multi-vendedor funcionando

Travada
Por quêCada vendedor autoriza individualmente e vira um par de tokens separado — coração do modelo multi-tenant.
Como funcionaLink auth.mercadolivre.com.br/authorization → vendedor loga/autoriza → callback com code → troca por tokens vinculados ao user_id. Precisa ser a conta principal do vendedor (colaborador dá erro invalid_operator_user_id).
Ir fazer issoauthentication-and-authorization
Fonte oficialAuthentication and Authorization
  • Implementar geração do link + callback que troca code por tokens
  • Armazenar tokens por vendedor (user_id) isoladamente
  • Tratar erro invalid_operator_user_id com mensagem clara
  • Tratar revogação: detectar token morto, sinalizar "reconectar conta"
Etapa 4 · Ponto mais frágil

Renovação de tokens: o refresh de uso único

Travada
Por quêrefresh_token é de uso único — se o sistema falhar em salvar o novo, o vendedor fica sem acesso.
Como funcionaaccess_token expira em 6h. Persistência do novo refresh precisa ser atômica e serializada por vendedor.
Fonte oficialFórum oficial — Refresh Token Expirado ou Usado
  • Job de renovação automática antes das 6h, gravação atômica
  • Lock por vendedor na renovação (nunca duas simultâneas)
  • Alerta interno quando uma renovação falha
Etapa 5

Testes com usuários de teste (não há sandbox)

Travada
Por quêTudo roda em produção — o mecanismo oficial de teste são os usuários de teste.
Como funcionaAté 10 usuários de teste por conta, credenciais não recuperáveis depois. Simulador de notificações pra webhooks.
Ir fazer issorealizacao-de-testes
Fonte oficialRealização de testes
  • Criar 2+ usuários de teste e salvar credenciais imediatamente
  • Simular ciclo: anúncio → compra de teste → pedido no Carteira Place
  • Testar webhooks com o simulador de notificações
  • Validar com 1 conta real antes de conectar cliente de verdade
Etapa 6 · O produto em si

Coleta de dados de lucro: Orders + Payments + Billing

Travada
Por quêÉ aqui que a integração vira produto — o lucro real, a promessa do CarteiraPlace.
Como funcionaBilling API é pra reconciliação fiscal/pós-venda, não tempo real. Desenho certo: Orders+Payments tempo real, Billing conciliação mensal. Rate limit 1.500 req/min por vendedor.
Ir fazer issobilling-reports
Fonte oficialBilling reports + boas práticas
  • Coleta de pedidos (orders_v2) com paginação e backoff pra 429
  • Coleta de payments/repasses vinculados aos pedidos
  • Conciliação mensal via Billing API
  • Cálculo de lucro por pedido: valor - comissão - taxa - frete - custos
  • Dashboard mostrando isso de forma simples
Etapa 7 · Entrega pra Shopee

Publicar o app + seção "Integrações" no ar

Travada
Por quêFecha o ciclo: destrava a submissão do cadastro de parceiro Shopee.
Como funcionaRevisão de publicação exige URL de Política de Privacidade e Termos de Uso.
Ir fazer issodevcenter — revisão de publicação
Fonte oficialRelato real do travamento na publicação (Reclame Aqui)
  • decisao Redigir Política de Privacidade e Termos de Uso (servem pro ML e pra Shopee, LGPD inclusa)
  • Publicar as duas páginas jurídicas no domínio do produto
  • Submeter o app à revisão de publicação
  • Seção "Integrações" visível com dados reais
  • Tudo no ar → marcar Etapa 2 do roteiro Shopee como concluída
Pra não confundir os dois mundos

Shopee × Mercado Livre: as diferenças que importam no código

  • EntradaShopee: análise manual, 10 dias úteis, exige produto vivo. ML: self-service, imediato, sem pré-requisito.
  • access_tokenShopee: 4 horas. ML: 6 horas.
  • refresh_tokenShopee: válido 30 dias, reutilizável no período. ML: uso único — cada refresh gera um novo que substitui o anterior (persistência atômica obrigatória).
  • Expiração da autorizaçãoShopee: vendedor escolhe 7-365 dias, depois reautoriza. ML: sem prazo declarado, mas revogável a qualquer momento pelos dois lados.
  • Ambiente de testeShopee: sandbox com hosts separados (limitado). ML: sem sandbox — usuários de teste em produção.
  • Rate limitShopee: sem tabela oficial confirmada (estimativas ~100 req/min). ML: 1.500 req/min por vendedor, 429 documentado.
  • Apps por contaShopee: múltiplos apps após aprovação. ML Brasil: 1 aplicação por conta.