A integração com Shopee é similar ao Mercado Livre, mas com um detalhe técnico: o Shopee usa assinatura HMAC-SHA256 em cada chamada (não OAuth2 padrão). Você só vê isso na configuração do ambiente — do lado do usuário final a experiência é igual: clica em conectar, autoriza no Shopee, volta conectado.

Conectar

Canais → Marketplaces → Shopee → Conectar.

1. Popup abre com a tela de autorização da sua loja Shopee.
2. Autorize o partner (o app do Jefacil) a acessar a loja.
3. Shopee redireciona de volta com code + shop_id. O Jefacil troca por tokens em segundos.
4. O card passa a exibir “Conectado” com o shop_id da sua loja.

Ambiente: exige SHOPEE_PARTNER_ID, SHOPEE_PARTNER_KEY e SHOPEE_REDIRECT_URI no .env do servidor. Registro do partner em open.shopee.com.

Publicar produtos

Clique em “Publicar produtos”. O dialog pede:

• Categoria (category_id) — numérico do Shopee (bem diferente do formato do ML). Descubra no painel Shopee Seller ou via /api/v2/product/get_category.
• IDs de frete (logistic_info) — lista de logistic_id dos canais de entrega que a sua loja tem habilitados. No painel Shopee: Logística → Canais de entrega → copie os IDs. Informe separados por vírgula (ex: 28002,28003).

Os dois campos são obrigatórios — o Shopee não publica um item sem categoria e sem frete declarado.

O Jefacil envia cada produto (estoque > 0, sem anúncio prévio) via POST /api/v2/product/add_item:

Produto sem foto pode ser recusado pelo Shopee — suba fotos antes.

O Jefacil guarda o item_id retornado em MarketplaceProductLink.external_id pra dedup. Re-rodar sync não duplica anúncio.

Limitações no sync de produtos

• Single-variant: cada produto vira um anúncio único. Se você tem variações (tamanho/cor) mapeadas como produtos separados no Jefacil, vira anúncios separados no Shopee.
• Stock em canal default: o estoque vai pro canal normal_stock do Shopee. Multi-warehouse (vários endereços de envio) exige chamada adicional add_model_list que não está implementada ainda.
• Peso fixo em 0.5 kg: o Jefacil não guarda peso do produto ainda. Se sua categoria no Shopee exige peso real, edite manualmente no painel depois do publish.

Receber pedidos

Clique em “Buscar pedidos”. O Jefacil faz uma sequência de 2 chamadas:

1. GET /api/v2/order/get_order_list — só retorna os order_sn (IDs) dos últimos 7 dias.
2. GET /api/v2/order/get_order_detail — em batch, pede detalhes de todos os order_sn.

Cada pedido novo vira IncomingOrder provider=SHOPEE. Deduplication pelo índice único (provider, external_id) onde external_id é o order_sn.

Pedidos aparecem em Canais → WhatsApp → Pedidos recebidos (sim, a tab ainda está com esse nome — lista unificada).

Conversão em venda é igual: clique em “Converter em venda”, PDV abre com carrinho pré-preenchido mapeando item_sku → StoreProduct.

Refresh automático de token

Shopee tokens duram 4 horas. O Jefacil tem cron a cada 30 min renovando tokens prestes a expirar (mesma lógica do ML). Se o refresh_token também expirar (30 dias no Shopee), conta vai pra NEEDS_REAUTH e você vê “Reconectar” no card.

Diferença de assinatura vs. Mercado Livre

O usuário não vê, mas o dev aqui vê: toda call autenticada ao Shopee exige assinatura HMAC-SHA256 na query string:

sign = HMAC-SHA256(partner_key, partnerId + path + timestamp + accessToken + shopId)

Isso significa que partner_id, timestamp e sign vão como query string na URL de cada request (não como header Authorization). O services/shopee_sync.js encapsula essa complexidade.

Não afeta a operação do lojista — é só um detalhe que aparece em casos de debugging.

Limitações conhecidas

• Sem webhook de mudança de status — você descobre um cancel só no próximo sync manual.
• Sem push de preço/estoque pra anúncios já publicados — só CREATE funciona hoje.
• Categoria e logistic_info — você informa em cada sync. Ideal seria guardar por produto.
• Variações — mesmo caveat do ML: crie SKUs separados pra cada variação.