Autenticação — OAuth 2.0

Existem duas credenciais, em níveis diferentes — entender isso é a chave para integrar a sua plataforma à Sellit:

• Sua plataforma → client_id + client_secret. Você registra um App e recebe esse par. Ele identifica a sua plataforma e é o mesmo para todos os seus clientes. A client_secret fica só no seu backend.
• Cada loja do seu cliente → access_token. Quando um lojista autoriza o seu App, você recebe um token por loja. É ele que vai no Authorization: Bearer de cada chamada, agindo em nome daquela loja.

Antes de redirecionar o lojista, gere um par de valores PKCE no seu backend. O code_verifier fica com você; o code_challenge é enviado na URL de autorização.

import { randomBytes, createHash } from "node:crypto"

function generatePkce() {
  const verifier = randomBytes(32).toString("base64url") // 43-128 chars
  const challenge = createHash("sha256")
    .update(verifier)
    .digest("base64url")
  return { verifier, challenge }
}

const { verifier, challenge } = generatePkce()
// Armazene o verifier na sessão — você vai precisar dele na Etapa 2

1. •

   1. Redirecione o lojista para a tela de autorização

   Envie o lojista para o endpoint de autorização com os parâmetros do seu App:

   GET /oauth/authorize

   https://app.sellitbr.com/oauth/authorize
     ?response_type=code
     &client_id=SEU_CLIENT_ID
     &redirect_uri=https://seuapp.com/oauth/callback
     &scope=products:read products:write stock:write
     &state=UM_VALOR_ALEATORIO
     &code_challenge=CHALLENGE_GERADO_ACIMA
     &code_challenge_method=S256

   O lojista verá os escopos solicitados e poderá autorizar ou negar. Em seguida será redirecionado para sua redirect_uri:

   Aprovado

   https://seuapp.com/oauth/callback?code=ac_...&state=SEU_STATE

   Negado

   https://seuapp.com/oauth/callback?error=access_denied&state=SEU_STATE

   Verifique sempre o parâmetro error antes de tentar trocar o code. O code expira em 10 minutos e só pode ser usado uma vez.

2. •

   2. Troque o code por tokens

   No seu backend, troque o code por um access token. Envie a client_secret apenas server-side.

   POST /api/oauth/token

   curl -X POST https://app.sellitbr.com/api/oauth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d grant_type=authorization_code \
     -d client_id=SEU_CLIENT_ID \
     -d client_secret=SUA_CLIENT_SECRET \
     -d code=O_CODE_RECEBIDO \
     -d redirect_uri=https://seuapp.com/oauth/callback \
     -d code_verifier=O_VERIFIER_DO_PKCE

   200 OK

   {
     "access_token": "eyJ...",
     "token_type": "Bearer",
     "expires_in": 7200,
     "refresh_token": "rt_...",
     "scope": "products:read products:write stock:write"
   }

3. •

   3. Chame a API com o Bearer token

   GET /api/v1/products

   curl https://app.sellitbr.com/api/v1/products \
     -H "Authorization: Bearer SEU_ACCESS_TOKEN"

4. •

   4. Renove o token quando expirar

   O access token dura 2 horas. O refresh token dura 30 dias e é rotativo: cada uso emite um novo par (access_token + refresh_token). Sempre salve o novo refresh_token recebido — o anterior é invalidado imediatamente.

   POST /api/oauth/token

   curl -X POST https://app.sellitbr.com/api/oauth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d grant_type=refresh_token \
     -d client_id=SEU_CLIENT_ID \
     -d client_secret=SUA_CLIENT_SECRET \
     -d refresh_token=SEU_REFRESH_TOKEN

   200 OK

   {
     "access_token": "eyJ...",
     "token_type": "Bearer",
     "expires_in": 7200,
     "refresh_token": "rt_NOVO_TOKEN",
     "scope": "products:read products:write stock:write"
   }

   Se o refresh token expirar (30 dias sem uso) ou for usado mais de uma vez, a resposta retorna 400 invalid_grant. Nesse caso, o lojista precisa reautorizar o seu App.

Solicite apenas os escopos que seu App realmente precisa. O lojista consente cada um.

O endpoint POST /api/oauth/token retorna erros no formato RFC 6749: { "error": "...", "error_description": "..." }.