Integração Shopee é ligar a sua loja Magento 2 ou WooCommerce e o ERP à Shopee Open Platform para sincronizar estoque, preço, pedidos, envio e nota fiscal. Eu cuido da conta de desenvolvedor, da assinatura HMAC de cada chamada, do token de 4 horas, do push de pedidos e do envio do XML da nota pela API.
Atualizado em · por Roger Takemiya
Na Shopee, a primeira chamada costuma falhar antes de chegar ao pedido: campo fora de ordem na string base da assinatura, timestamp com mais de 5 minutos, ou app criado na categoria errada, sem acesso à API de que você precisa.
Depois que conecta, vêm os problemas de operação: pedido parado em INVOICE_PENDING porque a nota não subiu, loja que sumiu da integração porque a autorização venceu, estoque atrasado que vira pedido sem envio. Pedido não enviado no prazo é cancelado automaticamente e entra na Taxa de Não Envio, que gera ponto de penalidade acima de 8% na semana.
Eu integro Magento 2, WooCommerce e ERPs à Shopee Open Platform e ajudo na implantação e otimização da conta, seguindo o guia de integração da Central de Educação do Vendedor e a documentação da Open Platform, consultados em 22/11/2026.
No Brasil, a Open Platform aceita dois tipos de conta de desenvolvedor: vendedor empresa registrado (Registered Business Seller) e parceiro terceiro (Third-party Partner, o ISV). Pessoa física está fechada. O vendedor precisa de documentos de empresa válidos no Brasil e de ao menos 1 pedido nos últimos 30 dias.
O tipo de app não muda depois de criado. O ERP System acessa todas as APIs, menos Chat e Ads; o Seller In-house System acessa todas. Não há liberação manual de permissão: escolher errado é criar outro app.
Para ir ao ar, o app precisa de domínio de Redirect URL e de IP na whitelist; sem whitelist, os dados sensíveis do comprador voltam mascarados. A liberação é automática, em cerca de 48 horas.
sign: HMAC-SHA256 da string base com a partner_key, em hexadecimal minúsculo. A loja autoriza o app pelo prazo que escolher, de 7 a 365 dias, e o code da autorização vale 10 minutos, com uso único.access_token vale 4 horas, e o antigo ainda funciona 5 minutos após a renovação. O refresh_token vale 30 dias e é de uso único, então a renovação roda num processo só, com trava. A Partner Key precisa ser trocada a cada 180 dias, sem reautorizar as lojas.set_app_push_config. A callback responde 2xx com corpo vazio, confere o HMAC do cabeçalho Authorization e enfileira. O código 3 avisa mudança de status do pedido; o 12, que a autorização expira em 7 dias. O que se perdeu sai de get_lost_push_message.get_attribute_tree, limite de título e de imagens em get_item_limit, estoque em update_stock e preço em update_price. Desde 01/09/2026, o campo condition é obrigatório no add_item para o Brasil.get_order_list com janela de até 15 dias e filtro INVOICE_PENDING, get_order_detail em lotes de até 50, ship_order e upload_invoice_doc. A tarifa real do pedido vem de get_escrow_detail (net_commission_fee, net_service_fee e pix_discount).partner_id: 2001887
API path: /api/v2/shop/get_shop_info
timestamp: 1655714431
access_token: 59777174636562737266615546704c6d
shop id: 14701711
Base string=2001887/api/v2/shop/get_shop_info165571443159777174636562737266615546704c6d14701711
// em PHP, hash_hmac já devolve hexadecimal minúsculo
$sign = hash_hmac('sha256', $baseString, $partnerKey);Exemplo do guia de assinatura da Open Platform, mais a linha de PHP. Na Public API, a string base leva só partner_id, caminho e timestamp.
Vendedor CNPJ precisa de NF-e para usar os canais de envio, exceto os Correios, e o pedido fica em INVOICE_PENDING até a nota chegar. Vendedor CPF não emite nota: envia com Declaração de Conteúdo, gerada junto da etiqueta.
| Ponto | ERP integrado | Emissão fora e digitação na Central | Emissor de NF-e Shopee |
|---|---|---|---|
| Como a nota chega | Pela API, em upload_invoice_doc | Digitada na Central do Vendedor | Emitida na própria Shopee |
| Quem usa | CNPJ com ERP integrado | Quem emite no site do governo ou em ERP não integrado | Simples Nacional ou MEI com Inscrição Estadual |
| Exigência | XML modelo 55 até 1 MB; CNPJ, UF e IE iguais ao cadastro; CFOP aceito | Alguém preenche pedido a pedido | Certificado A1 (.pfx ou .p12) |
| Atenção | Enviar 5 minutos após emitir (validação no SERPRO) | Escala mal com volume | Como padrão, bloqueia nota por outro meio |
| Bom para | Volume com ERP | Poucos pedidos | Loja pequena sem ERP |
A comissão também mudou duas vezes em 2026: em 01/03 e em 01/10, quando a taxa fixa dos itens até R$ 79,99 foi de R$ 4,00 para R$ 4,50, segundo a Central de Educação do Vendedor. Integração com percentual fixo no código erra a margem; a que lê get_escrow_detail acompanha.
Um cenário comum: loja em WooCommerce que já vende no Mercado Livre por um hub e quer abrir a Shopee, com o mesmo estoque para os dois canais e kits montados a partir de itens avulsos.
O que eu entrego: anúncios revisados contra a regra de anúncio duplicado (produto idêntico com preço diferente vira variação do mesmo anúncio); a venda do kit baixando os itens avulsos no WooCommerce; o estoque dos dois canais saindo do mesmo cálculo; e a nota do ERP subindo pela API. Se o hub já baixa kit, eu só configuro.
Campanha e Shopee Ads têm custo próprio: a Campanha de Destaque cobra 5% a mais sobre todas as vendas da loja no período. Essa conta a Ana Paula, sócia da Agência Buzz, faz na página de especialista Shopee.
O access token dura 4 horas. O refresh token dura 30 dias e é de uso único. A autorização da loja vale no máximo 365 dias, e a Shopee manda um push 7 dias antes de ela expirar.
Os motivos mais comuns são string base fora de ordem e timestamp vencido. Na Shop API a ordem é partner_id, caminho, timestamp, access_token e shop_id, e o timestamp vale 5 minutos.
Não com conta de desenvolvedor própria: no Brasil, a Open Platform só abre conta para vendedor empresa registrado ou parceiro terceiro. E a Shopee exige migrar para CNPJ ao atingir R$ 81 mil de faturamento em 12 meses.
O vendedor CNPJ precisa informar a NF-e antes de usar os canais de envio, exceto os Correios. Pela API, a nota sobe em upload_invoice_doc como XML modelo 55 de até 1 MB, cerca de 5 minutos depois da emissão.
Dá. O Magento 2 tem cron e fila para receber o push, e a Open Platform tem API para produto, estoque, preço, pedido, logística e nota fiscal. O que define o desenho é quem é a fonte do estoque e de onde sai a nota.
A parte técnica e a implantação da conta, sim. A operação do dia a dia, como título, fotos, campanhas e Shopee Ads, eu faço junto com a Ana Paula, sócia da Agência Buzz.
Me conte o que está acontecendo. Respondo pessoalmente, em horário comercial.