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.

URLs de instalação

A instalação do seu aplicativo usa duas URLs, configuradas no bloco URLs de instalação em Configurar o aplicativo, no Painel de Parceiros:

URL	Para que serve	O que a Yampi envia
URL de entrada	Para onde a Yampi envia o lojista quando ele inicia a instalação pela Loja de Aplicativos. A partir dela, seu aplicativo redireciona o lojista para `/oauth/authorize`.	Nenhum parâmetro
URL de callback	Para onde a Yampi devolve o lojista depois da tela de consentimento, com o código de autorização ou com o erro de recusa.	Autorização: `code`, `state` e `merchant` Recusa: `error=access_denied` e `state`

Exemplo de configuração:

Campo	Valor
URL de entrada	`https://www.seuapp.com.br/instalar`
URL de callback	`https://www.seuapp.com.br/oauth/callback`

O redirect_uri enviado para /oauth/authorize e para /oauth/token deve ser idêntico à URL de callback configurada. Se for diferente, a Yampi exibe uma página de erro e não devolve o lojista ao seu aplicativo.

Regras das URLs

As duas URLs são obrigatórias.
As duas precisam usar HTTPS ao enviar para análise. Para versões em desenvolvimento, endereços localhost também são aceitos, por exemplo http://localhost:3000/oauth/callback.
As duas URLs podem ser iguais. Nesse caso, o mesmo endpoint recebe o lojista sem parâmetros, no início da instalação, e com code ou error, no retorno da autorização, e precisa tratar os dois casos.
Em um aplicativo publicado, alterar qualquer uma das URLs cria uma nova versão major. Essa versão passa por análise e exige um novo teste de instalação em loja teste. Veja Atualizando aplicativos publicados.
As URLs valem apenas para novas autorizações. Instalações existentes e tokens já emitidos não são afetados.

Aplicativos criados antes da separação tinham um único campo, URL de redirecionamento. O valor desse campo foi copiado para a URL de entrada e para a URL de callback, e o seu aplicativo continua funcionando sem nenhuma alteração. Se o seu painel ainda exibe o campo único, ele vale como URL de entrada e como URL de callback.

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 Parceiro Tech e registre um novo aplicativo. Em Configurar o aplicativo, preencha a URL de entrada e a URL de callback, descritas em URLs de instalação. O Client ID da sua integração é gerado depois que você salva essas configurações.

2. Redirecionamento para autorização utilizando PKCE

Quando o lojista clica em Instalar na Loja de Aplicativos, a Yampi abre a sua URL de entrada, sem parâmetros. A partir dela, seu aplicativo inicia a autorização. 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:

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

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

Redirecionando para autorização

Ao receber o lojista na URL de entrada, seu aplicativo deve redirecioná-lo 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. No parâmetro redirect_uri, envie a URL de callback configurada no Painel de Parceiros. 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 da URL de entrada: '/instalar'
if ($_SERVER['REQUEST_URI'] === '/instalar') {
    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' => 'https://www.seuapp.com.br/oauth/callback', // URL de 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');
}

// Rota da URL de entrada
app.get('/instalar', (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://www.seuapp.com.br/oauth/callback', // URL de callback
    response_type: 'code',
    state: state,
    code_challenge: codeChallenge,
    code_challenge_method: 'S256',
  }).toString();

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

Recebendo o retorno na URL de callback

Depois que o lojista responde à tela de consentimento, a Yampi o redireciona para a sua URL de callback:

Situação	Parâmetros na query string
O lojista autorizou	`code` (código de autorização), `state` e `merchant` (alias da loja)
O lojista recusou	`error=access_denied` e `state`

Exemplo de retorno com autorização:

https://www.seuapp.com.br/oauth/callback?code=def50200a1b2c3...&state=9f2c4e7a1b...&merchant=minha-loja

Antes de usar o code, confira se o state recebido é o mesmo que seu aplicativo salvou na sessão ao redirecionar para /oauth/authorize. Se for diferente, descarte o retorno.

<?php

// Rota da URL de callback: '/oauth/callback'
if (parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH) === '/oauth/callback') {
    session_start();

    // Descartar retornos com state diferente do gerado na URL de entrada
    if (!isset($_GET['state']) || !hash_equals($_SESSION['state'] ?? '', $_GET['state'])) {
        http_response_code(400);
        exit('State inválido.');
    }

    // O lojista recusou a autorização
    if (isset($_GET['error'])) {
        header('Location: /instalacao-cancelada');
        exit;
    }

    $code = $_GET['code'];
    $merchant = $_GET['merchant']; // alias da loja que instalou o aplicativo

    // Trocar o code pelo Access Token (passo 3)
    $ch = curl_init('https://auth.yampi.com.br/oauth/token');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POSTFIELDS => http_build_query([
            'grant_type' => 'authorization_code',
            'client_id' => 'client-id',
            'redirect_uri' => 'https://www.seuapp.com.br/oauth/callback',
            'code' => $code,
            'code_verifier' => $_SESSION['code_verifier'],
        ]),
    ]);
    $tokens = json_decode(curl_exec($ch), true);
    curl_close($ch);

    // Salvar $tokens['access_token'] e $tokens['refresh_token'] associados à loja $merchant
}

// Rota da URL de callback
app.get('/oauth/callback', async (req, res) => {
  const { code, state, merchant, error } = req.query;

  // Descartar retornos com state diferente do gerado na URL de entrada
  if (!state || state !== req.session.state) {
    return res.status(400).send('State inválido.');
  }

  // O lojista recusou a autorização
  if (error) {
    return res.redirect('/instalacao-cancelada');
  }

  // Trocar o code pelo Access Token (passo 3)
  const response = await fetch('https://auth.yampi.com.br/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: 'client-id',
      redirect_uri: 'https://www.seuapp.com.br/oauth/callback',
      code,
      code_verifier: req.session.code_verifier,
    }),
  });
  const tokens = await response.json();

  // Salvar tokens.access_token e tokens.refresh_token associados à loja `merchant`
  res.redirect('/instalacao-concluida');
});

Erros comuns

Erro	O que significa
Página de erro sem redirecionamento	`client_id` inválido ou `redirect_uri` diferente da URL de callback cadastrada no Painel de Parceiros — o servidor não redireciona de volta por segurança
`?error=access_denied` na URL de callback	O lojista recusou a autorização na tela de consentimento
`?error=invalid_request` na URL de callback	Parâmetro obrigatório ausente ou malformado (`code_challenge`, `code_challenge_method`, `response_type`)

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 à sua URL de callback com um Authorization Code e o merchant da loja integrada. Formato da requisição para obter o Access Token. O redirect_uri deve ser a URL de callback, idêntica à enviada em /oauth/authorize:

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=https://www.seuapp.com.br/oauth/callback' \
--data-urlencode 'code=authorization-code-recebido' \
--data-urlencode 'code_verifier=generated-code-verifier'

Erros comuns

`error`	`hint`	O que significa
`invalid_client`	—	`client_id` inválido ou não corresponde ao app registrado
`invalid_request`	`Cannot decrypt the authorization code`	Code malformado ou `code_verifier` ausente
`invalid_grant`	`Authorization code has expired`	O `authorization_code` expirou — reinicie o fluxo a partir da etapa 2
`invalid_grant`	`Authorization code has been revoked`	O código já foi utilizado — cada código é de uso único
`invalid_grant`	`Failed to verify 'code_verifier'`	O `code_verifier` enviado não corresponde ao `code_challenge` da etapa 2
`invalid_grant`	`The redirect uri is incorrect.`	A `redirect_uri` desta requisição difere da URL de callback usada em `/oauth/authorize`

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}'

Erros comuns

Erro retornado	O que significa
`401 {"message":"Unauthenticated."}`	`Access Token` expirado (válido por 10 minutos) ou ausente no header `Authorization`
`401` em rotas de parceiro	Header `X-Partner-Client-ID` ausente — o servidor não consegue identificar o aplicativo
`403 Forbidden`	A rota acessada está fora do escopo (`scope`) concedido pelo usuário na etapa de consentimento

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'

Erros comuns

`error`	`hint`	O que significa
`invalid_client`	—	`client_id` não corresponde ao que gerou o `Refresh Token`
`invalid_request`	`Cannot decrypt the refresh token`	Token malformado — valor truncado ou corrompido
`invalid_request`	`Check the \`refresh_token` parameter`	Parâmetro `refresh_token` ausente na requisição
`invalid_grant`	`Token has been revoked`	`Refresh Token` expirado (30 dias) ou revogado — reinicie o fluxo a partir da etapa 2

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.

Autenticação

Webhooks

URLs de instalação

Regras das URLs

Fluxo de autorização

1. Obtenha as credenciais de autorização no Painel de Parceiros

2. Redirecionamento para autorização utilizando PKCE

Code Verifier

Redirecionando para autorização

Recebendo o retorno na URL de callback

Erros comuns

3. Obtenha um token de acesso do Authorization Server da Yampi

Erros comuns

4. Use o Access Token para acessar a API Yampi

Erros comuns

5. Atualize os tokens

Erros comuns

Escopos