OAuth 2.0
OAuth 2.0 é um protocolo de autorização que oferece maior controle sobre o escopo de um aplicativo e permite fluxos de autorização em diferentes dispositivos. Ele possibilita a definição de escopos que concedem permissões específicas em nome de um cliente.
Para desenvolver aplicativos para a Yampi, é obrigatório o uso de autenticação com OAuth 2.0. Você pode localizar suas credenciais de acesso para OAuth ao criar seu aplicativo no Painel de Parceiros Yampi.
Atualmente, o uso do OAuth 2.0 é restrito a aplicativos publicados na Loja de Aplicativos da Yampi.
Fluxo de autorização
Para integrar seu aplicativo a uma loja Yampi, é necessário implementar um fluxo de autorização. Esse fluxo redireciona os lojistas Yampi para uma página onde seu aplicativo será integrado à loja.
1. Obtenha as credenciais de autorização no Painel de Parceiros
Acesse o Painel de Parceiros Yampi, crie sua conta, habilite seu Perfil de Desenvolvedor e registre um novo aplicativo.
Para obter o Client ID
da sua integração, é necessário informar a redirect_url
da integração. Essa URL será usada para redirecionar o usuário à sua aplicação, onde o processo de integração será concluído.
Durante o desenvolvimento do seu aplicativo, você pode usar http://localhost/sua-url-de-redirecionamento
como URL de redirecionamento.
2. Redirecionamento para autorização utilizando PKCE
Como essa concessão de autorização não utiliza um Client Secret, é necessário gerar o Code Verifier (verificador de código) e o Code Challenge (desafio de código) para solicitar um token.
Code Verifier
Uma string aleatória de 128 caracteres usada para gerar o Code Challenge
, que será enviado no redirecionamento para autorização e na solicitação do Access Token
.
O Code Challenge deve ser uma sequência aleatória de 43 a 128 caracteres contendo letras, números e os caracteres ”-”, ”.”, ”_”, ”~”. Ele deve ser codificado em Base64 com caracteres seguros para URL e nomes de arquivos. Os caracteres ’=’ finais devem ser removidos, e não devem haver quebras de linha, espaços em branco ou outros caracteres adicionais, conforme definido na especificação RFC 7636.
Exemplo de função para gerar o Code Challenge
usando o Code Verifier
:
Redirecionando para autorização
Seu aplicativo deve fazer uma solicitação de redirecionamento para a rota https://auth.yampi.com.br/oauth/authorize
.
Você usará o Client ID
gerado no passo 1, o Code Verifier e o Code Challenge para solicitar um Authorization Code
ao Authorization Server da Yampi.
O Authorization Server retornará o Authorization Code
, que será usado pelo seu aplicativo para requisitar o Access Token
, o Refresh Token
e o alias da loja integrada.
3. Obtenha um token de acesso do Authorization Server da Yampi
Com o Authorization Code
gerado, seu aplicativo deve obter um Access Token
antes de acessar dados de uma loja pela API Yampi.
O Access Token
pode conceder uma ou mais permissões de acesso, configuradas no painel de parceiros por meio do scope (escopo). O scope define quais rotas da API podem ser acessadas.
Durante a instalação do aplicativo, o usuário será solicitado a conceder as permissões solicitadas. Esse processo é chamado de consentimento do usuário.
Se o usuário conceder permissão, o Authorization Server da Yampi redirecionará o usuário ao seu aplicativo com um Authorization Code
e o alias
da loja integrada.
Formato da requisição para obter o Access Token
:
4. Use o Access Token para acessar a API Yampi
Após obter o Access Token
, ele deve ser incluído no cabeçalho das chamadas HTTP do seu aplicativo.
Formato da requisição com os cabeçalhos obrigatórios: access_token
e X-Partner-Client-ID
:
5. Atualize os tokens
O Access Token
tem um tempo de vida limitado. Tokens gerados pelo fluxo PKCE Authorization Code permanecem válidos por 10 minutos, enquanto o Refresh Token
é válido por 30 dias.
Seu aplicativo deve obter novos tokens antes que o Refresh Token
expire.
Formato da requisição para gerar um novo Access Token
:
Escopos
Os escopos permitem definir acessos granulares ao seu aplicativo, garantindo que ele tenha apenas as permissões necessárias. Consulte os detalhes de cada escopo na Central de Ajuda Yampi.