OAuth 2.0

Autenticação OAuth

OAuth 2.0 é um protocolo de autorização que permite maior controle sobre o escopo de um aplicativo e fluxos de autorização em vários dispositivos. O OAuth 2.0 permite que você defina escopos que fornecem permissões específicas em nome de um cliente.

Para o desenvolvimento de Aplicativos para Yampi, é necessário o uso de Autenticação com Oauth 2.0. Você poderá localizar suas credenciais de acesso para uso do OAuth, ao criar seu aplicativo no Painel de Parceiros Yampi.

Tipos de concessão (Grant Types)

Para implementação do OAuth, forneceremos apenas o PKCE Authorization Code e o Refresh Token

Fluxo de Autorização

Para integrar seu aplicativo à uma loja Yampi, será necessário implementar um fluxo de autorização. Esse fluxo permite redirecionar os lojistas Yampi para uma página para que seu aplicativo seja integrado à loja.

1. Obtenha a Credencial de Autorização no Painel de Parceiros Yampi

Visite o painel de parceiros Yampi, crie sua conta, habilite seu Perfil de Desenvolvedor e crie um novo aplicativo.

Para obter o client ID da sua integração, é necessário informar o redirect_url da integração. Esta URL é utilizada para redirecionar o usuário para sua aplicação, onde o processo de integração será realizado.

Durante o desenvolvimento do seu aplicativo, é possível utilizar o http://localhost/sua-url-de-redirecionamento como sua url de redirecionamento.

2. Redirecionamento para Autorização utilizando PKCE

Como esta concessão de autorização não fornece 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.

O Code Verifier

Uma string aleatória de 128 caracteres, utilizada para gerar o Code Challenge que é enviado no redirecionamento para a autorização e para a solicitação do Access Token.

O Code Challenge

O Code Challenge deve ser uma sequência aleatória de 43 a 128 caracteres contendo letras, números e caracteres "-", ".", "_", "~", codificada em Base64 com caracteres seguros para URL e nome de arquivo. Os caracteres '=' finais devem ser removidos, sem quebra de linha, espaço em branco ou outros caracteres adicionais devem estar presentes. conforme definido na especificação RFC 7636.

Exemplo de função para geração do Code Challenge, com o uso do Code Verifier.

$code_verifier = bin2hex(random_bytes(128 / 2));

$encoded = base64_encode(hash('sha256', $code_verifier, true));
$codeChallenge = strtr(rtrim($encoded, '='), '+/', '-_');

Redirecionando para autorização

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 do Authorization Server da Yampi.

O Authorization Server irá retornar o Authorization Code que seu aplicativo irá utilizar para requisitar o Access Token e o Refresh Token, além do alias da loja que está sendo integrado.

<?php

// Função para gerar uma string aleatória
function random_str($length) {
    return bin2hex(random_bytes($length / 2));
}

// Rota para '/redirect'
if ($_SERVER['REQUEST_URI'] === '/redirect') {
    session_start();

    // Gerar o estado e o code_verifier e armazená-los na sessão
    $state = random_str(40);
    $code_verifier = random_str(128);

    $_SESSION['state'] = $state
    $_SESSION['code_verifier'] = $code_verifier

    // Gerar o code_challenge
    $codeChallenge = strtr(rtrim(
        base64_encode(hash('sha256', $code_verifier, true))
    , '='), '+/', '-_');

    // Construir a query
    $query = http_build_query([
        'client_id' => 'client-id',
        'redirect_uri' => '<http://your-app-redirect-url.com/callback>',
        'response_type' => 'code',
        'state' => $state,
        'code_challenge' => $codeChallenge,
        'code_challenge_method' => 'S256',
    ]);

    // Redirecionar para a URL de autorização
    header('Location: <https://auth.yampi.com.br/oauth/authorize?'> . $query);
    exit;
}
?>

const express = require('express');
const crypto = require('crypto');

const app = express();

// Função para gerar uma string aleatória
function randomStr(length) {
  return crypto.randomBytes(length / 2).toString('hex');
}

app.get('/redirect', (req, res) => {
  const state = randomStr(40);
  const codeVerifier = randomStr(128);

  req.session.state = state;
  req.session.code_verifier = codeVerifier;

  const codeChallenge = crypto
    .createHash('sha256')
    .update(codeVerifier)
    .digest('base64')
    .replace(/=/g, '')
    .replace(/\\+/g, '-')
    .replace(/\\//g, '_');

  const query = new URLSearchParams({
    client_id: 'client-id',
    redirect_uri: '<https://your-redirect-url.com/callback>',
    response_type: 'code',
    state: state,
    code_challenge: codeChallenge,
    code_challenge_method: 'S256',
  }).toString();

  res.redirect(`https://auth.yampi.com.br/oauth/authorize?${query}`);
});

3. Obtenha um token de acesso do Servidor de Autorização da Yampi.

Com o Authorization Code gerado, antes que seu aplicativo possa acessar dados de uma loja utilizando a API Yampi, ele deverá obter um Access Token (Token de acesso).

Um único Access Token poderá conceder uma ou mais permissões de acesso, por meio do scope (escopo) configurado no painel de parceiros. O scope controla as permissões de acesso sobre quais rotas da API poderão ser acessadas.

Durante a instalação do seu aplicativo, o usuário é questionado se deseja conceder as permissões que seu aplicativo está solicitando. Este processo é chamado de consentimento do usuário.

Se o usuário conceder a permissão, o Authorization Server da Yampi irá redirecionar o usuário ao seu aplicativo contendo um Authorization Code e o alias da loja que será utilizado para fazer requisições à api yampi que autorizou a integração.

Utilize o Authorization Code para obter um Access Token com a lista de scopes solicitados.

O formato da requisição que você estará criando, é a seguinte:

POST 'https:///auth.yampi.com.br/oauth/token' \\
--header 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'grant_type=authorization_code' \\
--data-urlencode 'client_id=your-app-client-id' \\
--data-urlencode 'redirect_uri=your-redirect-url' \\
--data-urlencode 'code=generated-code-verifier' \\
--data-urlencode 'code_verifier=generated-code-verifier' \\
--data-urlencode 'client_id=your-app-client-id'

4. Access token para acesso à API Yampi

Depois que seu aplicativo obtém um Access Token, ele deve ser utilizado no cabeçalho das chamadas HTTP do seu aplicativo.

O formato da requisição com os cabeçalhos obrigatórios: access_token e X-Partner-Client-ID

POST '<https://api.dooki.com.br/v2/{alias}/some-route>' \\
--header 'Content-Type: application/x-www-form-urlencoded' \\
--header 'X-Partner-Client-ID: your-app-client-id' \\
--data-urlencode 'access_token=bWRWa4gzdnk3WHRGU1o0bmRRcTO5VUxWX1lZTDdJSUtmaWcxbTV9dEFXcW5tOjE2MjIxNDc3NDM5MTQ6MEoxOnJ0OjE' \\

Neste momento, você receberá a resposta da API Yampi e poderá confirmar que todo o processo ocorreu com sucesso!

5. Atualizar tokens

O Access Token possui tempo de vida limitado por padrão. O Access Token gerado por meio do Fluxo PKCE Authorization Code permanecerá válido por 10 minutos e o Refresh Token permanecerá válido por 30 dias.

É necessário que seu aplicativo obtenha um novo Access Token e Refresh Token dentro do período de tempo de vida do Refresh Token.

O formato da requisição que você utilizará para gerar um novo Access Token é a seguinte:

POST 'https:///auth.yampi.com.br/oauth/token' \\
--header 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'refresh_token=your-refresh-token' \\
--data-urlencode 'grant_type=refresh_token' \\
--data-urlencode 'client_id=your-app-client-id'

Escopos

Os escopos permitem que você defina o acesso granular ao seu aplicativo para que ele tenha apenas as permissões necessárias. É possível conferir os detalhes de acesso de cada escopo, na Yampi Central de Ajuda.