Conectar a loja

Mostra o estado da conexão, gera o link de autorização, conclui a conexão com o código devolvido pela Shopee e desconecta.

A Shopee usa o fluxo OAuth: o lojista autoriza a loja dentro da Shopee e recebe de volta um código. Antes de conectar, preencha Partner ID, Partner Key e Redirect URL nas configurações do módulo Shopee (PUT /api/v1/admin/modules/shopee/settings). Todas as rotas exigem o módulo shopee ativo e o privilégio manage_shopee ou manage_settings.

Estado da conexão

GET/api/v1/admin/shopee/statusAdmin

Estado da conexão com a Shopee

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shopee/status" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Estado

json

{
  "connected": true,
  "partner_id": "1234567",
  "shop_id": "7654321",
  "refresh_token_status": "valid",
  "token_expires_at": "2027-10-11T21:00:00Z",
  "sandbox_mode": false,
  "configured": true
}

Campos da resposta

connectedboolean

true se há uma sessão OAuth guardada.

partner_idstring

Partner ID configurado. Vazio se não configurado.

shop_idstring

Id da loja na Shopee: o da conexão quando conectado; senão o configurado. Vazio se nenhum.

refresh_token_statusstring

validexpirednone

Validade da sessão.

token_expires_atstring

Validade da sessão (RFC 3339). null se não conectado.

sandbox_modeboolean

true quando o modo de homologação está ligado nas configurações.

configuredboolean

true quando Partner ID e Partner Key estão preenchidos.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_shopee","manage_settings"]}`
403	O módulo `shopee` não está ativo nesta loja.	`{"error":"module_disabled","module":"shopee"}`
410	A loja usa exclusivamente o Hub de Marketplaces (`markethub`) e este conector antigo está bloqueado.	`{"error":"crs_markethub_only","moved_to":"markethub"}`
500	Falha ao ler o estado.	`{"error":"Failed to load connection status"}`

Link de autorização

GET/api/v1/admin/shopee/authAdmin

Gera o link para o lojista autorizar a loja na Shopee

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shopee/auth" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Link gerado

json

{
  "auth_url": "https://partner.shopeemobile.com/api/v2/shop/auth_partner?partner_id=1234567&timestamp=1791752539&sign=...&redirect=https://minhaloja.example.com/admin/shopee"
}

Campos da resposta

auth_urlstring

URL para abrir no navegador do lojista. Contém assinatura com timestamp; gere de novo se demorar para usar.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_shopee","manage_settings"]}`
403	O módulo `shopee` não está ativo nesta loja.	`{"error":"module_disabled","module":"shopee"}`
410	A loja usa exclusivamente o Hub de Marketplaces (`markethub`) e este conector antigo está bloqueado.	`{"error":"crs_markethub_only","moved_to":"markethub"}`
422	Partner ID, Partner Key ou Redirect URL não configurados.	`{"error":"not_configured","detail":"Configure Partner ID, Partner Key e Redirect URL em Ajustes → Outras antes de conectar."}`
500	Falha ao gerar o link.	`{"error":"Failed to generate auth URL: ..."}`

Concluir a conexão

POST/api/v1/admin/shopee/callbackAdmin

Troca o código de autorização por uma sessão

Corpo da requisição

codestringobrigatório

O código que a Shopee anexa ao endereço de retorno (code na query).

shop_idintegerobrigatório

Id da loja na Shopee (shop_id na query de retorno). Número inteiro, diferente de zero.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shopee/callback" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "abc123", "shop_id": 7654321}'

Resposta

200Conectado

json

{
  "success": true,
  "shop_id": 7654321,
  "expires_at": "2027-10-11T21:00:00Z"
}

Campos da resposta

successboolean

Sempre true.

shop_idinteger

Id da loja conectada.

expires_atstring

Quando a sessão expira (RFC 3339).

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_shopee","manage_settings"]}`
403	O módulo `shopee` não está ativo nesta loja.	`{"error":"module_disabled","module":"shopee"}`
410	A loja usa exclusivamente o Hub de Marketplaces (`markethub`) e este conector antigo está bloqueado.	`{"error":"crs_markethub_only","moved_to":"markethub"}`
400	Corpo inválido, `code` vazio ou `shop_id` zero/ausente.	`{"error":"code is required"}`
500	A Shopee recusou o código (expirado, já usado) ou falhou a comunicação.	`{"error":"Failed to exchange token: ..."}`

Conectar em homologação

POST/api/v1/admin/shopee/sandbox/connectAdmin

Conexão local de teste, sem OAuth

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shopee/sandbox/connect" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conectado em homologação

json

{
  "success": true,
  "sandbox": true,
  "shop_id": 7654321,
  "expires_at": "2027-10-11T21:00:00Z"
}

Campos da resposta

success / sandboxboolean

Sempre true.

shop_idinteger

Id da loja configurado (ou um valor fixo de teste).

expires_atstring

Validade de 1 ano.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_shopee","manage_settings"]}`
403	O módulo `shopee` não está ativo nesta loja.	`{"error":"module_disabled","module":"shopee"}`
410	A loja usa exclusivamente o Hub de Marketplaces (`markethub`) e este conector antigo está bloqueado.	`{"error":"crs_markethub_only","moved_to":"markethub"}`
422	O modo de homologação não está ligado nas configurações do módulo.	`{"error":"sandbox_disabled","detail":"Ative o Modo homologação nas Configurações do Shopee para conectar sem OAuth."}`
500	Falha ao gravar a sessão.	`{"error":"Failed to connect: ..."}`

Desconectar

POST/api/v1/admin/shopee/disconnectAdmin

Apaga a sessão guardada

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shopee/disconnect" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Desconectado

json

{
  "success": true
}

Campos da resposta

successboolean

Sempre true. A rota é idempotente: funciona mesmo sem conexão ativa.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_shopee","manage_settings"]}`
403	O módulo `shopee` não está ativo nesta loja.	`{"error":"module_disabled","module":"shopee"}`
410	A loja usa exclusivamente o Hub de Marketplaces (`markethub`) e este conector antigo está bloqueado.	`{"error":"crs_markethub_only","moved_to":"markethub"}`
500	Falha ao apagar.	`{"error":"Failed to disconnect"}`

Veja também

API atual/Referência completa/Shopee

Conectar a loja

Mostra o estado da conexão, gera o link de autorização, conclui a conexão com o código devolvido pela Shopee e desconecta.

Estado da conexão

GET/api/v1/admin/shopee/statusAdmin

Estado da conexão com a Shopee

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shopee/status" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Estado

json

{
  "connected": true,
  "partner_id": "1234567",
  "shop_id": "7654321",
  "refresh_token_status": "valid",
  "token_expires_at": "2027-10-11T21:00:00Z",
  "sandbox_mode": false,
  "configured": true
}

Campos da resposta

connectedboolean

true se há uma sessão OAuth guardada.

partner_idstring

Partner ID configurado. Vazio se não configurado.

shop_idstring

Id da loja na Shopee: o da conexão quando conectado; senão o configurado. Vazio se nenhum.

refresh_token_statusstring

validexpirednone

Validade da sessão.

token_expires_atstring

Validade da sessão (RFC 3339). null se não conectado.

sandbox_modeboolean

true quando o modo de homologação está ligado nas configurações.

configuredboolean

true quando Partner ID e Partner Key estão preenchidos.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_shopee","manage_settings"]}`
403	O módulo `shopee` não está ativo nesta loja.	`{"error":"module_disabled","module":"shopee"}`
410	A loja usa exclusivamente o Hub de Marketplaces (`markethub`) e este conector antigo está bloqueado.	`{"error":"crs_markethub_only","moved_to":"markethub"}`
500	Falha ao ler o estado.	`{"error":"Failed to load connection status"}`

Link de autorização

GET/api/v1/admin/shopee/authAdmin

Gera o link para o lojista autorizar a loja na Shopee

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shopee/auth" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Link gerado

json

{
  "auth_url": "https://partner.shopeemobile.com/api/v2/shop/auth_partner?partner_id=1234567&timestamp=1791752539&sign=...&redirect=https://minhaloja.example.com/admin/shopee"
}

Campos da resposta

auth_urlstring

URL para abrir no navegador do lojista. Contém assinatura com timestamp; gere de novo se demorar para usar.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_shopee","manage_settings"]}`
403	O módulo `shopee` não está ativo nesta loja.	`{"error":"module_disabled","module":"shopee"}`
410	A loja usa exclusivamente o Hub de Marketplaces (`markethub`) e este conector antigo está bloqueado.	`{"error":"crs_markethub_only","moved_to":"markethub"}`
422	Partner ID, Partner Key ou Redirect URL não configurados.	`{"error":"not_configured","detail":"Configure Partner ID, Partner Key e Redirect URL em Ajustes → Outras antes de conectar."}`
500	Falha ao gerar o link.	`{"error":"Failed to generate auth URL: ..."}`

Concluir a conexão

POST/api/v1/admin/shopee/callbackAdmin

Troca o código de autorização por uma sessão

Corpo da requisição

codestringobrigatório

O código que a Shopee anexa ao endereço de retorno (code na query).

shop_idintegerobrigatório

Id da loja na Shopee (shop_id na query de retorno). Número inteiro, diferente de zero.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shopee/callback" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "abc123", "shop_id": 7654321}'

Resposta

200Conectado

json

{
  "success": true,
  "shop_id": 7654321,
  "expires_at": "2027-10-11T21:00:00Z"
}

Campos da resposta

successboolean

Sempre true.

shop_idinteger

Id da loja conectada.

expires_atstring

Quando a sessão expira (RFC 3339).

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_shopee","manage_settings"]}`
403	O módulo `shopee` não está ativo nesta loja.	`{"error":"module_disabled","module":"shopee"}`
410	A loja usa exclusivamente o Hub de Marketplaces (`markethub`) e este conector antigo está bloqueado.	`{"error":"crs_markethub_only","moved_to":"markethub"}`
400	Corpo inválido, `code` vazio ou `shop_id` zero/ausente.	`{"error":"code is required"}`
500	A Shopee recusou o código (expirado, já usado) ou falhou a comunicação.	`{"error":"Failed to exchange token: ..."}`

Conectar em homologação

POST/api/v1/admin/shopee/sandbox/connectAdmin

Conexão local de teste, sem OAuth

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shopee/sandbox/connect" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conectado em homologação

json

{
  "success": true,
  "sandbox": true,
  "shop_id": 7654321,
  "expires_at": "2027-10-11T21:00:00Z"
}

Campos da resposta

success / sandboxboolean

Sempre true.

shop_idinteger

Id da loja configurado (ou um valor fixo de teste).

expires_atstring

Validade de 1 ano.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_shopee","manage_settings"]}`
403	O módulo `shopee` não está ativo nesta loja.	`{"error":"module_disabled","module":"shopee"}`
410	A loja usa exclusivamente o Hub de Marketplaces (`markethub`) e este conector antigo está bloqueado.	`{"error":"crs_markethub_only","moved_to":"markethub"}`
422	O modo de homologação não está ligado nas configurações do módulo.	`{"error":"sandbox_disabled","detail":"Ative o Modo homologação nas Configurações do Shopee para conectar sem OAuth."}`
500	Falha ao gravar a sessão.	`{"error":"Failed to connect: ..."}`

Desconectar

POST/api/v1/admin/shopee/disconnectAdmin

Apaga a sessão guardada

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shopee/disconnect" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Desconectado

json

{
  "success": true
}

Campos da resposta

successboolean

Sempre true. A rota é idempotente: funciona mesmo sem conexão ativa.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_shopee","manage_settings"]}`
403	O módulo `shopee` não está ativo nesta loja.	`{"error":"module_disabled","module":"shopee"}`
410	A loja usa exclusivamente o Hub de Marketplaces (`markethub`) e este conector antigo está bloqueado.	`{"error":"crs_markethub_only","moved_to":"markethub"}`
500	Falha ao apagar.	`{"error":"Failed to disconnect"}`