O Jefacil conecta com o Mercado Livre via OAuth2 oficial. Depois de conectado, você pode:

• Publicar produtos como anúncios novos (cria item no ML)
• Receber pedidos feitos na sua loja do ML como IncomingOrder pendente
• Ver status da conexão e rotacionar/revogar acesso quando quiser

Conectar

Canais → Marketplaces → Mercado Livre → Conectar.

1. Clique em “Conectar” — o Jefacil abre um popup com a tela de autorização do ML.
2. Faça login na sua conta do ML (se não estiver logado).
3. Autorize o Jefacil a acessar seu catálogo e pedidos.
4. Popup fecha sozinho. O card do ML passa a exibir o badge “Conectado” e o seu external_user_id (nickname do ML).

Se o popup for bloqueado pelo navegador, libere popups pro domínio do Jefacil e tente de novo.

Ambiente: o super admin precisa ter registrado o app do Jefacil no Developers ML e configurado ML_CLIENT_ID, ML_CLIENT_SECRET e ML_REDIRECT_URI no servidor. Sem essas credenciais, o botão “Conectar” devolve marketplace_not_configured.

Publicar produtos

Com a conta conectada, clique em “Publicar produtos”.

O dialog pede dois campos específicos do ML:

• Categoria (category_id) — formato MLB1234. Descubra pela ferramenta de domain discovery do ML passando o nome do produto.
• Tipo de anúncio (listing_type_id) — default sugerido gold_special (clássico). Outros comuns: gold_pro (premium), bronze (grátis com visibilidade limitada).

O Jefacil publica todos os produtos com estoque > 0 que ainda não têm anúncio vinculado. Cada produto vira um item no ML:

• Título — do Jefacil (máx 60 caracteres).
• Descrição — do Jefacil, ou nome se vazia.
• Preço — do StoreProduct da loja ativa.
• Quantidade — estoque atual.
• Fotos — a foto do produto no Jefacil.
• Atributos — brand, gtin, mpn (se preenchidos).

Depois do sync, aparece resumo: 3 criado(s), 1 pulado(s), 0 erro(s). Produtos com erro ficam listados com o motivo do ML (ex: “categoria não aceita esse brand”) — corrige no catálogo e roda de novo.

Pulados são produtos que já têm anúncio publicado — o Jefacil guarda o mapeamento 1:1 via MarketplaceProductLink.external_id. Re-rodar não duplica.

Limitação atual: só CREATE. Update de preço/estoque em anúncios já publicados fica como evolução futura — por enquanto, ajuste manual pelo painel do ML ou despublicação + republish.

Receber pedidos

Clique em “Buscar pedidos” (ícone refresh). O Jefacil chama a API do ML e puxa os pedidos dos últimos 7 dias.

Cada pedido novo vira um IncomingOrder com provider=MERCADO_LIVRE, status PENDING. Aparece na lista unificada em Canais → WhatsApp → Pedidos recebidos (sim, o título é WhatsApp mas a lista abrange todos os providers — vamos renomear pra “Pedidos recebidos” no roadmap).

Se o mesmo pedido for sincronizado duas vezes, o Jefacil ignora o segundo via índice único (provider, external_id). Idempotente.

Converter em venda

Mesma lógica do WhatsApp. Clique em “Converter em venda”:

1. O pedido muda pra CONVERTED.
2. Abre PDV com carrinho pré-preenchido mapeando SKU → StoreProduct.
3. Você confere, ajusta se precisar, finaliza a venda normal.
4. Estoque decrementa, NFC-e rola etc.

SKUs que não batem com o estoque local aparecem num toast de aviso. Costuma acontecer quando o SKU do anúncio no ML está diferente do SKU do produto no Jefacil — padronize seu SKU (recomendamos o do Jefacil) e republicar.

Refresh automático de token

O access token do ML expira em 6 horas. O Jefacil mantém um cron BullMQ que roda a cada 30 min renovando tokens prestes a expirar (margem de 10 min). Você não vê isso acontecer — só sabe que a conta nunca cai em “NEEDS_REAUTH” por expiração silenciosa.

Se o refresh_token também expirar (raro — TTL de 6 meses no ML), o status vira NEEDS_REAUTH e aparece um botão “Reconectar” no card.

Desconectar

Canais → Marketplaces → Mercado Livre → ícone desconectar. O Jefacil zera access_token e refresh_token no banco (remove a autorização do lado dele; no lado do ML permanece até o usuário revogar em Minha conta → Aplicações autorizadas).

Os MarketplaceProductLink são preservados — se você reconectar a mesma conta depois, os produtos continuam mapeados pros anúncios existentes.

Limitações conhecidas

• Sem webhook de mudança de pedido — se o cliente cancela no ML, o Jefacil não sabe até você rodar sync manual ou o status do IncomingOrder continuar desatualizado. Solução pendente: consumir o tópico orders_v2 do ML via webhook.
• Variações não são enviadas — produto com tamanho/cor vai como single-variant. Pra variações, crie SKUs separados.
• Update não é implementado — sync só CRIA items. Mudanças no catálogo precisam ser ajustadas no ML manualmente ou via novo anúncio.
• Categoria e listing_type — você informa em cada sync. Idealmente, um próximo passo do roadmap é guardar esses parâmetros por produto pra evitar redigitar.