[BR] Welcome! Guia para Novos Desenvolvedores: Principais fluxos e dúvidas.

Olá, desenvolvedor(a).

Após a aprovação do perfil (Third-Party Partner ou Registered Business Seller), é responsabilidade do desenvolvedor acompanhar integralmente a documentação oficial da Shopee Open Platform.

Documentações principais

Developer Guide – Fluxos de integração, onboarding e explicações técnicas. (https://open.shopee.com/developer-guide/4)

API Reference – Lista de APIs, endpoints, parâmetros e exemplos. (https://open.shopee.com/documents/v2/v2.ams.get_open_campaign_added_product?module=127&type=1)

Announcements – Atualizações, mudanças de comportamento, políticas e novas funcionalidades. (https://open.shopee.com/announcements?page=1&category=55)

NOVIDADE: Central de Notificações no Console do Desenvolvedor & Assistente IA! ⭐ (https://open.shopee.com/announcements/1448?category=3&is_top=false)

Relembraremos abaixo as documentações dos seguintes tópicos e uma breve lista Perguntas & Respostas:

1. Apps: Criação, Permissões

2. App de Chat

3. IP Whitelist/Sensitive Data/Mascaramento de Dados

4. Sandbox

5. Autorização e Autenticação

6. Partner Key e Reset

7. PERMISSÕES, APIS E CATEGORIA DO APLICATIVO

A categoria selecionada durante a criação do aplicativo é o fator que determina todas as capacidades e limitações da integração.

Anúncio: [BR] Criação de App: permissões e APIs são definidas pela categoria selecionada

https://open.shopee.com/announcements/1400?category=3&is_top=false

#️⃣Perguntas frequentes

👤"Minha aplicação não consegue chamar determinada API. Podem liberar?"

Não. As permissões são definidas exclusivamente pela categoria escolhida na criação do App.

👤"É possível habilitar uma API manualmente?"

Não. A equipe Open Platform não realiza liberações individuais de APIs ou escopos.

👤"Posso adicionar permissões em um App já existente?"

Não. Caso precise de capacidades diferentes, pode ser necessário criar um novo App com outra categoria.

👤"Recebo 'permission denied' ou não encontro determinado endpoint."

Verifique:

- se a API pertence à categoria do seu aplicativo;

- se o endpoint ainda existe na API Reference;

- se não houve alteração publicada nos Announcements.

2. CUSTOMER SERVICE (CHAT API)

Conforme política global da Shopee Open Platform, novas solicitações para aplicativos da categoria Customer Service de desenvolvedores independentes e plataformas Third-party Partner foram encerradas em 18 de novembro de 2024. (Applications for Customer Service Apps from Individual Third Parties and Third-party Partner Platforms have been closed since November 18, 2024.)

Anúncio: [BR] Lembrete: Política de Acesso à Chat API (Chat API)

https://open.shopee.com/announcements/1430

#️⃣Perguntas frequentes

👤"Como solicito acesso à Chat API?"

Para Third-party Partners e desenvolvedores independentes, novas solicitações foram encerradas em novembro de 2024.

👤"Sou seller. Como solicito Chat API?"

A solicitação deve ser feita pelo RM (Account Manager).

👤"A Open Platform consegue liberar Chat API para minha aplicação?"

Não.

👤"A Open Platform consegue verificar meu processo de aprovação?"

Não. Esse fluxo é tratado internamente entre Seller e RM.

3. IP WHITELIST / SENSITIVE DATA / MASCARAMENTO

O acesso a dados sensíveis está diretamente relacionado às configurações de segurança da aplicação, incluindo IP Whitelist.

Documentação: Requesting Access to Sensitive Data - How to Enable IP Address Whitelisting https://open.shopee.com/developer-guide/718

Anúncio: [BR] Lembrete: Acesso a Dados Sensíveis (Sensitive Data Access)

https://open.shopee.com/announcements/1364

Além disso, existem cenários e status específicos em que os dados do comprador não serão disponibilizados pela API, conforme documentado em: Passo a passo para subir a NF-e através da OpenAPI - https://open.shopee.com/developer-guide/382.

#️⃣Perguntas frequentes

👤"Os dados do comprador estão mascarados. Podem liberar?"

Não há liberação manual.

Primeiro verifique:

- IP Whitelist configurado e ativado;

- cenário em que o pedido se encontra (existem status em que determinados dados não são disponibilizados).

👤"Vocês conseguem configurar minha IP Whitelist?"

Não. Toda configuração é realizada pelo próprio desenvolvedor dentro do Console.

👤"Como habilito acesso aos dados sensíveis?"

Siga integralmente o guia de IP Whitelist e Sensitive Data disponível na documentação.

4. SANDBOX

O ambiente Sandbox (test-stable) é destinado exclusivamente para testes e validações de integração. Embora seja funcional, ele não replica integralmente o ambiente de produção e, portanto, comportamentos divergentes, limitações e instabilidades podem ocorrer.

Documentação: Sandbox Testing V2 https://open.shopee.com/developer-guide/644

#️⃣Perguntas frequentes

👤"O Sandbox está igual Produção?"

Não. O Sandbox é um ambiente apenas para testes e não replica integralmente Produção.

👤"Estou recebendo erro ao criar pedido de teste."

Tente:

- criar novos produtos;

- utilizar outra categoria;

- repetir o fluxo.

Erros conhecidos incluem:

error_sandbox_order_checkout_cart_item

invalid product

Failed to get info

👤"Esse erro acontece apenas no Sandbox."

Isso pode ser esperado.

Comportamentos inconsistentes podem ocorrer exclusivamente no ambiente test-stable.

👤"Quando devo abrir ticket?"

Após realizar testes de isolamento. Enviar obrigatoriamente:

- vídeo completo;

- arquivo HAR;

- request/response completo.

5. AUTORIZAÇÃO E AUTENTICAÇÃO

6. Para todos os tipos de App, é necessário criar um link de autorização. O link de autorização é composto por uma URL fixa de autorização e outros parâmetros obrigatórios.

7. O timestamp utilizado para calcular o sign é válido apenas por 5 minutos. Após a expiração do timestamp e do sign, o link de autorização deixará de ser válido e será necessário gerar um novo link.

8. Os sellers podem escolher durações predefinidas (7 dias, 30 dias, 90 dias, 180 dias ou 365 dias) ou selecionar “Customize Expiration Time” para definir qualquer data de expiração dentro de 365 dias. (Trata-se da expiração da autorização de integração dada pela loja na Shopee, o processo inicia-se na integradora e o seller é apenas redirecionado para URL da Shopee para logar com dados da loja.)

9. Após a conclusão da autorização, a página frontend será redirecionada para o redirect_uri especificado no link de autorização, juntamente com o code (código de autorização), que é válido por 10 minutos e o ID da loja (shop_id).

10. O acess_token obtido pelo code é válido por 4 horas e o refresh_token é válido por 30 dias. Chame API Refresh Access Token (RefreshAccessToken) para obter um novo access_token quando necessário.

Documentação: Authorization and Authentication https://open.shopee.com/developer-guide/20

#️⃣Perguntas frequentes

👤"Meu link de autorização expirou."

O timestamp utilizado no sign possui validade de apenas 5 minutos.

Será necessário gerar um novo link.

👤"Recebo 'invalid sign'."

Verifique:

- timestamp;

- cálculo do sign;

- Partner Key utilizada;

- URL correta.

👤"O code expirou."

O authorization code:

- vale apenas uma utilização;

- expira após 10 minutos.

"Meu access_token expirou."

- O access_token possui validade de 4 horas.

- Utilize o refresh_token para gerar um novo.

👤"Preciso pedir nova autorização ao seller sempre que renovar token?"

Não. A renovação do access_token utiliza apenas o refresh_token.

👤"O seller precisa autorizar novamente após refresh?"

Não. A autorização da loja permanece válida conforme o período escolhido pelo seller (até 365 dias).

6. PARTNER KEY

- Sem reset automático da chave após expiração

- Uma vez expirada, a plataforma não irá gerar uma nova chave automaticamente. Ao invés disso, a chave será marcada como inválida e as chamadas de API que a utilizarem serão bloqueadas

- Quando o reset da Partner Key for efetuado, a nova chave será ativa imediatamente, sem a necessidade de definir um período para ativação

- Será possível definir um período para expiração da chave antiga, com um máximo de 72 horas após o reset, de modo a permitir uma transição mais suave e minimizar interrupções durante atualizações de sistema.

- A Partner Key continua válida por 180 dias a partir da data de geração

- Não é necessário realizar a re-autorização do vendedor (a mesma tem a validade que o seller determinar, com máximo de até 365 dias)

- A partner key é configurada e reseta dentro do APP, em APP LIST no Console: https://open.shopee.com/console/app

Anúncio: [Importante] Melhorias no reset da Open API Partner Key https://open.shopee.com/announcements/1192

#️⃣Perguntas frequentes

👤"Minha Partner Key expirou. Vocês conseguem gerar outra?"

Não. O reset deve ser realizado pelo próprio desenvolvedor no Console.

👤"Após reset preciso reautorizar todas as lojas?"

Não. O reset da Partner Key não invalida as autorizações concedidas pelos sellers.

👤"Posso manter a chave antiga funcionando durante a migração?"

Sim. É possível definir um período de transição de até 72 horas.

👤"Quanto tempo a Partner Key é válida?"

180 dias.

Antes de abrir um ticket

Verifique primeiro:

- A documentação oficial.

- A API Reference.

- Os Announcements.

- Se o endpoint ainda existe.

- Se o fluxo seguido está correto.

- Se sua aplicação possui a permissão necessária (pela categoria do app).

- Se o comportamento já não está documentado.

- Utilize a Assistente IA.

Atenciosamente,

Shopee Open Platform