Shopee · Open Platform

Integração Shopee com Magento 2, WooCommerce e ERP pela Open Platform

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

Onde costuma quebrar

A Shopee pede mais cuidado técnico do que parece

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.

Antes do código

Conta de desenvolvedor e tipo de app

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.

Como funciona

Como eu faço a integração com a Shopee

  1. Diagnóstico. Fonte do estoque, forma de enviar a nota, canais de envio da loja e se o app certo já existe.
  2. Assinatura e autorização. Toda chamada leva 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.
  3. Token sob trava. O 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.
  4. Push em fila. Configurado em 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.
  5. Produto, estoque e preço. Atributos obrigatórios por categoria em 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.
  6. Pedido, envio e nota. 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).
  7. Acompanhamento. As Regras de Saúde da Integração pedem mais de 80% de sucesso por API num grupo de endpoints; abaixo disso, o ERP pode ser bloqueado para novas conexões. Monitoro a taxa de erro de cada chamada e do push.

A string base, no exemplo da própria documentação

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.

Nota fiscal

Três jeitos de informar a nota na Shopee

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.

Formas de informar a NF-e na Shopee, segundo a Central de Educação do Vendedor (consulta em 22/11/2026)
PontoERP integradoEmissão fora e digitação na CentralEmissor de NF-e Shopee
Como a nota chegaPela API, em upload_invoice_docDigitada na Central do VendedorEmitida na própria Shopee
Quem usaCNPJ com ERP integradoQuem emite no site do governo ou em ERP não integradoSimples Nacional ou MEI com Inscrição Estadual
ExigênciaXML modelo 55 até 1 MB; CNPJ, UF e IE iguais ao cadastro; CFOP aceitoAlguém preenche pedido a pedidoCertificado A1 (.pfx ou .p12)
AtençãoEnviar 5 minutos após emitir (validação no SERPRO)Escala mal com volumeComo padrão, bloqueia nota por outro meio
Bom paraVolume com ERPPoucos pedidosLoja 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.

Exemplo

Um cenário comum

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 que eu não faço na Shopee

  • Não prometo limite de requisições: a documentação não publica o rate limit por endpoint, então o desenho tem fila e nova tentativa.
  • Não ofereço integração de chat como terceiro: a Shopee fechou novos pedidos de app de Customer Service para ISV e terceiros em 18/11/2024.
  • Não decido regra fiscal: CFOP, regime e Inscrição Estadual são com o seu contador.
  • Não sou parceiro oficial da Shopee nem vendo conector por assinatura.
  • Loja pequena e sem ERP costuma se virar com o painel e o Emissor de NF-e Shopee. Integração vem depois.

Perguntas frequentes

Quanto tempo dura o token da 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.

Por que a minha chamada à API da Shopee volta com erro de assinatura?

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.

Vendedor CPF consegue integrar pela Open Platform?

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.

Por que o pedido fica em INVOICE_PENDING?

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á para integrar a Shopee com Magento 2?

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.

Você também cuida dos anúncios e do Shopee Ads?

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.

Quer que eu olhe o seu caso?

Me conte o que está acontecendo. Respondo pessoalmente, em horário comercial.