Mercado Livre — Integração com Marketplace¶

Aplicativo externo IntegraML.exe | Sincronização automática em intervalo configurável (padrão: 1 hora)

O que é¶

A Integração Mercado Livre é um aplicativo standalone (separado do Master Key) que sincroniza dados entre o Master Key e anúncios publicados na plataforma Mercado Livre. A sincronização ocorre em ciclos automáticos.

O fluxo é bidirecional: - Mercado Livre → Master Key: anúncios e pedidos - Master Key → Mercado Livre: preços, estoque e notas fiscais

A integração não publica novos anúncios no Mercado Livre — os anúncios são criados diretamente na plataforma. O aplicativo importa os anúncios existentes para a tabela ANUNCIOS no Master Key e, a partir daí, mantém preços e estoque sincronizados.

Pré-requisitos¶

Conta de vendedor no Mercado Livre com acesso à API (Client ID e Client Secret gerados no painel de desenvolvedores)
Acesso ao banco de dados do Master Key pelo computador onde o aplicativo roda
Cliente cadastrado no Master Key com o nome MERCADO LIVRE (usado para registrar os pedidos importados)

Importante: cada anúncio importado precisa ser vinculado manualmente a um produto do Master Key na tabela ANUNCIOS (campo AN_PRODUTO). Sem esse vínculo, o estoque e o preço do anúncio não são atualizados.

Configuração¶

As configurações são armazenadas diretamente no banco de dados do Master Key (tabela PARAMESP), não em arquivo INI. Acesse o menu Opções → Configurações no aplicativo para configurar.

Autenticação OAuth¶

Parâmetro (banco)	O que é
`ML.Token`	Access token OAuth 2.0 gerado após autorização
`ML.RefreshToken`	Refresh token para renovação automática do access token
`ML.GeneratedAuthToken`	Código de autorização usado na primeira autenticação
`ML.UserId`	ID do usuário vendedor no Mercado Livre

Primeira execução: o aplicativo abre o navegador na URL de autorização do Mercado Livre. Após o vendedor autorizar o acesso, o sistema exibe um campo para colar o código de autorização recebido. O token é gerado e salvo automaticamente. Nas execuções seguintes, o token é renovado automaticamente via refresh token.

Operação¶

Parâmetro (banco)	O que é
`ML.VendedorPadrao`	Vendedor padrão atribuído aos pedidos importados
`ML.PracaPadrao`	Praça padrão atribuída aos clientes/pedidos importados

Fluxo de Sincronização¶

A cada ciclo, o aplicativo executa as etapas na seguinte ordem de dependências:

Token ──► Pedidos ──────────────────────────────┐
      ──► Envio de Notas                         ▼
      ──► Importar Anúncios ──► Preço ──► Estoque

Token é gerado/renovado primeiro. Em seguida, Pedidos, Envio de Notas e Importar Anúncios iniciam em paralelo. Preço aguarda Importar Anúncios. Estoque aguarda Pedidos e Preço.

1. Token¶

Verifica se o access token está válido. Se expirado, renova automaticamente usando o refresh token via POST /oauth/token. Se não houver token, exige autenticação manual (fluxo OAuth completo via navegador).

2. Importar Anúncios (Mercado Livre → Master Key)¶

Importa e atualiza os anúncios do vendedor na tabela ANUNCIOS do Master Key.

Busca os anúncios modificados ordenados por last_updated_desc via GET users/{userId}/items/search
Para cada anúncio, busca os detalhes via GET items/{id} e a descrição via GET items/{id}/description
Para quando last_updated do anúncio for anterior à última sincronização
Se o anúncio não existir na tabela ANUNCIOS, cria o registro (sem vínculo com produto — vínculo é manual)
Verifica e cadastra a categoria do anúncio via VerificaCadastraCategoria

Mapeamento de status:

Status Mercado Livre	`AN_STATUS`
`active`	1
`paused`	2
`closed`	3
`inactive`	2
`under_review`, `payment_required`	0

Campos importados na tabela ANUNCIOS:

Campo ML	Campo `ANUNCIOS`	Descrição
`id`	`AN_IDANUNCIO`	ID do anúncio no Mercado Livre
`title` (até 60 chars)	`AN_TITULO`	Título do anúncio
`price`	`AN_VALOR`	Preço do anúncio
`status`	`AN_STATUSML` / `AN_STATUS`	Status do anúncio
`category_id`	`AN_CATEGORIA`	Categoria ML
`listing_type_id`	`AN_TIPO_LISTAGEM`	Tipo de listagem
`permalink`	`AN_LINK`	URL pública do anúncio
Descrição em texto	`AN_DESCRICAO`	Descrição plain text

3. Pedidos (Mercado Livre → Master Key)¶

Importa pedidos gerados nos anúncios do vendedor desde a última sincronização.

Requer o cliente MERCADO LIVRE cadastrado no Master Key
Carrega Vendedor Padrão, Praça Padrão e Atividade Padrão das configurações (usa primeiro registro ativo como fallback se não configurado)
Autenticação: Authorization: Bearer {token}

4. Preço (Master Key → Mercado Livre)¶

Envia o preço atualizado para cada anúncio cujo produto foi modificado desde a última sincronização.

Para anúncios sem variação: envia PUT items/{id} com {"price": valor}
Para anúncios com variação (grade): envia {"variations": [{"id": idVariacao, "price": valor}]} para cada variação ativa (AV_ATIVO <> 'N')
Anúncios com variação onde alguma variação não tem produto ou grade vinculada são ignorados

O preço enviado é AN_VALOR do cadastro do anúncio na tabela ANUNCIOS.

5. Estoque (Master Key → Mercado Livre)¶

Atualiza o estoque disponível de cada anúncio cujo produto foi modificado desde a última sincronização. Executa após Pedidos e Preço.

Para anúncios sem variação: envia PUT items/{id} com {"available_quantity": estoque}
Estoque = (AN_PERC_ESTQ / 100) × saldo_do_produto — a percentagem permite alocar apenas parte do estoque para o ML
Valor máximo aceito pela API: 99.999; valores negativos são enviados como 0
Para anúncios com variação: envia {"variations": [{"id": idVariacao, "available_quantity": estoque_grade}]} para cada variação ativa
Cada variação usa AV_PERC_ESTQ para a percentagem e o saldo da grade correspondente

6. Envio de Notas (Master Key → Mercado Livre)¶

Envia XML das notas fiscais emitidas no Master Key para o Mercado Livre, vinculando ao pedido correspondente.

Se o banco de NF-e for separado, conecta ao banco auxiliar para buscar o XML
Se não houver banco auxiliar configurado e a conexão falhar, a etapa é silenciosamente ignorada

Tabelas e campos relevantes¶

Tabela	Campo	Função
`ANUNCIOS`	`AN_IDANUNCIO`	ID do anúncio no Mercado Livre
`ANUNCIOS`	`AN_PRODUTO`	Produto do Master Key vinculado ao anúncio (vínculo manual)
`ANUNCIOS`	`AN_VALOR`	Preço enviado ao Mercado Livre
`ANUNCIOS`	`AN_PERC_ESTQ`	Percentual do estoque do produto alocado para este anúncio (padrão: 100%)
`ANUNCIOS`	`AN_STATUS`	Status interno (0=pendente, 1=ativo, 2=pausado, 3=fechado)
`ANC_VARIACOES`	`AV_IDVARIACAO`	ID da variação no Mercado Livre
`ANC_VARIACOES`	`AV_PRODUTO` / `AV_SEQGRADE`	Produto/grade vinculado à variação
`ANC_VARIACOES`	`AV_PERC_ESTQ`	Percentual do estoque da grade alocado para esta variação
`ANC_VARIACOES`	`AV_ATIVO`	Variação ativa (`N` = ignorada na sincronização)
`PARAMESP`	`ML.*`	Configurações e tokens OAuth armazenados no banco

Perguntas frequentes do suporte¶

"O aplicativo abre o navegador e pede um código" → É o fluxo de autorização OAuth na primeira configuração (ou após expiração do refresh token). Autorize o acesso na página do Mercado Livre e cole o código de autorização exibido no campo do aplicativo.

"Preço/Estoque não está sendo atualizado no anúncio" → Verifique se o anúncio na tabela ANUNCIOS está vinculado a um produto (AN_PRODUTO preenchido). Sem esse vínculo, a etapa ignora o anúncio. Para anúncios com variação, cada variação na tabela ANC_VARIACOES também precisa ter AV_PRODUTO ou AV_SEQGRADE vinculado.

"Estoque enviado está diferente do saldo real" → Verifique o campo AN_PERC_ESTQ no cadastro do anúncio — ele define qual percentual do estoque do produto é alocado para o Mercado Livre. Se for 50, apenas metade do saldo é enviada.

"Pedido não entrou no Master Key" → Confirme que existe um cliente com nome MERCADO LIVRE cadastrado no banco. Verifique também se Vendedor Padrão e Praça Padrão estão configurados.

"Nota fiscal não foi enviada ao Mercado Livre" → Verifique se o pedido correspondente foi importado (o vínculo é pelo número do pedido externo). Se usa banco de NF-e separado, confirme a configuração de Database NF-e.

"Token expirado / erro de autenticação" → O token é renovado automaticamente via refresh token. Se o refresh token também expirar (inatividade prolongada), será necessário reautorizar manualmente: o aplicativo abrirá o navegador novamente para o fluxo OAuth completo.