Plano: marketplaces são recurso do Avançado ou superior. No Básico a aba aparece com um cartão explicando o que ela faz, e a conexão fica bloqueada. Ver preços.

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

Primeiro escolha quais produtos vão pro canal, em Produtos → seleciona → Ações → Publicar em canais (ou na aba “Canais” dentro do produto). Depois, com a conta conectada, clique em “Publicar produtos” aqui.

A tela mostra a lista do que vai subir, com o preço que sai em cada anúncio e a categoria já adivinhada pelo nome do produto — quem adivinha é o mesmo classificador que o ML usa no fluxo dele de anunciar. Você confere, troca o que estiver errado (busque por “vestido”, “tênis”…) e publica. A categoria fica guardada no produto, então da segunda vez ela já vem escolhida.

A comissão também é perguntada ao ML — você não precisa digitar. Cada linha mostra a taxa aplicada e de onde ela veio (taxa 14% do ML), e o preço já sai com o acréscimo pra ela não sair do seu bolso. A taxa muda por categoria: no mesmo catálogo de roupa, boné costuma pagar 14% e calça 12%.

Só falta escolher o tipo de anúncio, que vale pro lote:

• Clássico (gold_special) — comissão menor, anúncio não aparece em 12x sem juros.
• Premium (gold_pro) — comissão maior, aparece com 12x sem juros.

Trocar entre os dois recalcula os preços na hora: o Premium cobra mais (no mesmo boné, 19% contra 14%).

Se você tiver digitado uma comissão à mão naquele produto, ela vence a do ML — o sistema nunca sobrescreve número que você escolheu.

Produto com grade sobe com a numeração. Cada tamanho/cor vira uma variação dentro do anúncio, com estoque próprio — o comprador escolhe o 37 e você para de vender o que não tem. A tela mostra quantas numerações vão subir, e o Mercado Livre passa a saber qual numeração foi vendida em cada pedido.

Sobe quem foi designado e tem estoque > 0 e ainda não tem anúncio vinculado. A tela avisa quantos ficaram de fora por falta de estoque. 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 Integrações → 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.
• Grade com mais de 2 eixos — cor + tamanho funciona. Um terceiro eixo (material, por exemplo) faz o produto ser recusado com aviso, em vez de subir sem aquela dimensão.
• Atributos que não temos campo — o Mercado Livre pede coisas como Gênero, Tipo de calça e Material principal em roupa. A tela avisa quais faltam antes de publicar, mas hoje não há onde preenchê-los no Jefácil — o anúncio pode ser recusado.
• Update não é implementado — sync só CRIA items. Mudanças no catálogo precisam ser ajustadas no ML manualmente ou via novo anúncio.
• Tipo de anúncio é do lote — a categoria já é por produto e fica guardada, mas Clássico/Premium você escolhe a cada publicação.
• A categoria sugerida é palpite — acerta na maioria, não em todas. Confira antes de publicar: categoria errada muda os atributos obrigatórios e a comissão da vertical.