Shopee

Conector com o marketplace Shopee: conexão da loja, publicação de produtos e importação de pedidos.

A Shopee é um marketplace onde a loja pode anunciar os mesmos produtos do catálogo e receber pedidos. Este conector liga a loja à conta de vendedor na Shopee: o lojista autoriza a loja (OAuth), publica produtos e importa os pedidos feitos na Shopee.

Como funciona

Configurar
Preencha Partner ID, Partner Key e Redirect URL nas configurações do módulo Shopee.
Autorizar
Chame Link de autorização e abra a auth_url no navegador do lojista.
Concluir
A Shopee redireciona para a Redirect URL com code e shop_id; envie os dois para Concluir a conexão.
Operar
Publique produtos e importe pedidos.

Os anúncios têm quatro estados e os pedidos usam o vocabulário de status da Shopee:

Anúncio	Letra	Significado
`active`	`A`	No ar.
`inactive`	`D`	Retirado ou pausado.
`banned`	`B`	Banido pela Shopee.
`reviewing`	`P`	Em análise pela Shopee.

Conceitos principais

Sessão OAuth

Conectar guarda uma sessão com validade. refresh_token_status diz se está valid, expired ou none. Quando expira, refaça a autorização.

Modo de homologação

Com sandbox_mode ligado, sandbox/connect conecta sem OAuth, publicar gera um id local e a importação de pedidos retorna zero. Serve para testar o fluxo sem a Shopee.

Dinheiro

price e total_amount são inteiros em centavos.

Ids como texto

Os ids numéricos de vínculo e de item (id, shopee_item_id) vêm como texto para não perder precisão em linguagens que usam ponto flutuante.

Endpoints

Método	Caminho	Para que serve	Página
GET	`/api/v1/admin/shopee/status`	Estado da conexão (não exige credenciais configuradas)	Conectar a loja
GET	`/api/v1/admin/shopee/auth`	Gera o link de autorização OAuth	Conectar a loja
POST	`/api/v1/admin/shopee/callback`	Troca o código devolvido pela Shopee por uma sessão	Conectar a loja
POST	`/api/v1/admin/shopee/sandbox/connect`	Conexão de teste sem OAuth (só com o modo de homologação ligado)	Conectar a loja
POST	`/api/v1/admin/shopee/disconnect`	Apaga a sessão OAuth guardada	Conectar a loja
GET	`/api/v1/admin/shopee/products`	Lista os anúncios (produtos publicados na Shopee)	Produtos na Shopee
POST	`/api/v1/admin/shopee/products/{id}/publish`	Publica um produto do catálogo na Shopee	Produtos na Shopee
DELETE	`/api/v1/admin/shopee/products/{id}`	Retira um produto da Shopee	Produtos na Shopee
POST	`/api/v1/admin/shopee/sync-orders`	Importa pedidos dos últimos 7 dias da Shopee	Pedidos da Shopee
GET	`/api/v1/admin/shopee/orders`	Lista os pedidos importados	Pedidos da Shopee

Erros comuns

Chamar Link de autorização antes de configurar as credenciais: responde 422 not_configured.
Reusar um code ou deixá-lo expirar: a troca falha com 500.
Ler os dois arrays (items e products/orders) como se fossem listas diferentes.
Esperar que a importação traga mais de 50 pedidos por chamada.
Tratar 422/400 como falha do servidor: são estados esperados (not_configured, not_connected, sandbox_disabled).
Chamar este conector em uma loja que só usa o Hub de Marketplaces: responde 410 crs_markethub_only.

Próximos passos

Conectar a loja

OAuth passo a passo.

Produtos na Shopee

Publicar e retirar anúncios.

Pedidos da Shopee

Importar e consultar pedidos.