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.

​

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.

​

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.

Exemplo de função para gerar o Code Challenge usando o Code Verifier:

<?php
$code_verifier = bin2hex(random_bytes(128 / 2));

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

​

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.

<?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 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 merchant da loja integrada.

Formato da requisição para obter o Access Token:

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'

​

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:

POST 'https://api.dooki.com.br/v2/{alias}/some-route' \
--header 'X-Partner-Client-ID: your-app-client-id' \
--header 'Authorization: Bearer {token}'

​

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:

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 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.