Autenticação

A Vendaze API usa OAuth 2.1 Authorization Code flow com client_secret. Esta é uma integração server-side: todas as trocas de token precisam acontecer no seu back-end. O client_secret nunca pode ser exposto em código no browser, binários de app mobile ou qualquer ambiente que o usuário final possa inspecionar. Antes de continuar, você precisa de um client_id e client_secret. Veja Registre seu aplicativo.

Como funciona

Redirecionar o usuário para o endpoint de autorização

Seu servidor constrói a URL de autorização e redireciona o browser do usuário para ela.

Usuário faz login e aprova

O usuário seleciona um workspace e visualiza os escopos solicitados na tela de consentimento da Vendaze. Ele pode apenas aprovar ou negar o acesso completo, sem opção de selecionar escopos individualmente.

Receber o código de autorização

A Vendaze redireciona o browser de volta para sua redirect_uri com um code de curta duração.

Trocar o code pelos tokens

Seu servidor troca o code por um access_token e refresh_token via requisição back-end.

Fazer requisições à API

Inclua o access_token como Bearer token em toda requisição.

Renovar ao expirar

Access tokens expiram em 1 hora. Use o refresh_token para obter um novo sem interação do usuário.

Passo 1 - Redirecionar o usuário

Construa a URL de autorização e redirecione o browser do usuário para ela. Isso deve ser uma navegação de browser, não uma requisição HTTP server-side. Não use fetch, axios, curl ou qualquer cliente HTTP para chamar este endpoint. O usuário precisa ser redirecionado para que possa fazer login e aprovar o acesso na tela de consentimento da Vendaze.

GET https://api.vendaze.com/oauth/authorize
  ?client_id=SEU_CLIENT_ID
  &redirect_uri=https://meuapp.com/oauth/callback
  &response_type=code
  &state=TOKEN_CSRF_ALEATORIO

Exemplo de redirecionamento em uma aplicação web:

const params = new URLSearchParams({
  client_id: 'SEU_CLIENT_ID',
  redirect_uri: 'https://meuapp.com/oauth/callback',
  response_type: 'code',
  state: crypto.randomUUID(),
});

// Armazene o state para verificação CSRF no callback
sessionStorage.setItem('oauth_state', params.get('state'));

// Navegue o browser. Nunca use fetch/axios aqui.
window.location.href = `https://api.vendaze.com/oauth/authorize?${params}`;

Parâmetro	Obrigatório	Descrição
`client_id`	Sim	O client ID do seu aplicativo.
`redirect_uri`	Sim	Deve corresponder exatamente a uma URI registrada.
`response_type`	Sim	Deve ser `code`.
`state`	Não	String aleatória que você gera. Retornada sem alteração. Fortemente recomendada para proteção contra CSRF.

Sempre inclua o state e verifique-o no callback. Rejeite qualquer callback onde o state recebido não bate com o que você enviou. Isso protege contra ataques de CSRF.

Passo 2 - Usuário autoriza

O usuário seleciona o workspace e visualiza os escopos solicitados na tela de consentimento da Vendaze. Ele pode apenas aprovar ou negar o acesso completo, sem opção de selecionar escopos individualmente. Nenhuma ação necessária do seu lado durante este passo.

Passo 3 - Receber o callback

Após aprovar, o usuário é redirecionado para sua redirect_uri:

https://meuapp.com/oauth/callback?code=AUTH_CODE&state=SEU_STATE

Verifique que o state bate com o que você armazenou e troque o code pelos tokens. Se o usuário recusar a autorização:

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

Trate o parâmetro error e exiba uma mensagem adequada ao usuário.

Passo 4 - Trocar o code pelos tokens

Códigos de autorização expiram em 10 minutos e só podem ser usados uma vez. Troque imediatamente após receber o callback.

Esta requisição deve ser feita pelo seu servidor, nunca pelo browser.

curl -X POST https://api.vendaze.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE_DO_CALLBACK&client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET"

Resposta (200):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "workspace_slug": "acme-corp"
}

Campo	Descrição
`access_token`	Use em toda requisição à API. Expira em 1 hora.
`refresh_token`	Usado para renovar o access token. Válido por 60 dias se utilizado regularmente.
`token_type`	Sempre `Bearer`.
`expires_in`	Segundos até o access token expirar. Sempre 3600.
`workspace_slug`	Slug do workspace autorizado pelo usuário. Use para identificar qual conta está conectada no seu app.

Armazenamento de tokens

Armazene os dois tokens com segurança no servidor. As seguintes práticas se aplicam:

access_token: curta duração (1 hora). Armazene em memória ou cache rápido. Nunca em localStorage ou cookies acessíveis ao JavaScript.
refresh_token: longa duração (60 dias). Armazene criptografado no banco de dados, associado ao usuário e workspace. É a credencial que permite manter o acesso sem interação do usuário.
Nunca logue nenhum dos tokens. Nunca os inclua em URLs ou query strings.
Nunca os exponha em respostas da API para o seu próprio front-end. O front-end deve chamar seu back-end, que chama a Vendaze.

Passo 5 - Fazer requisições à API

Inclua o access_token em toda requisição como Bearer token:

curl https://api.vendaze.com/v1/people \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

O contexto do workspace é resolvido automaticamente a partir do token. Você nunca envia um identificador de workspace nas requisições.

Passo 6 - Renovar o access token

Access tokens expiram em 1 hora. Renove usando o refresh token antes da expiração, ou reativamente quando receber o erro token_expired.

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

A resposta é idêntica ao Passo 4. Substitua os dois tokens no seu lado. Um novo refresh_token é emitido a cada renovação e o anterior é imediatamente invalidado.

Refresh tokens expiram se ficarem sem uso por 60 dias. A cada renovação, a janela de 60 dias é reiniciada. Se expirar, o usuário precisa passar pelo fluxo completo de autorização novamente.

Revogar acesso

Para desconectar um workspace do seu aplicativo, revogue o access token:

curl -X POST https://api.vendaze.com/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "token": "ACCESS_TOKEN",
    "client_id": "SEU_CLIENT_ID",
    "client_secret": "SEU_CLIENT_SECRET"
  }'

Sempre envie o access_token, não o refresh_token. O endpoint de revogação precisa de um JWT para identificar o usuário e remover o grant de autorização.

Após revogar, delete os dois tokens do seu armazenamento. O usuário precisará re-autorizar se quiser reconectar.

Próximo: Faça sua primeira requisição para usar seu access token em uma chamada real à API.

Visão Geral

Começando

Utilizando a API

Boas Práticas

Como funciona

Passo 1 - Redirecionar o usuário

Passo 2 - Usuário autoriza

Passo 3 - Receber o callback

Passo 4 - Trocar o code pelos tokens

Armazenamento de tokens

Passo 5 - Fazer requisições à API

Passo 6 - Renovar o access token

Revogar acesso

​Como funciona

​Passo 1 - Redirecionar o usuário

​Passo 2 - Usuário autoriza

​Passo 3 - Receber o callback

​Passo 4 - Trocar o code pelos tokens

​Armazenamento de tokens

​Passo 5 - Fazer requisições à API

​Passo 6 - Renovar o access token

​Revogar acesso

Como funciona

Passo 1 - Redirecionar o usuário

Passo 2 - Usuário autoriza

Passo 3 - Receber o callback

Passo 4 - Trocar o code pelos tokens

Armazenamento de tokens

Passo 5 - Fazer requisições à API

Passo 6 - Renovar o access token

Revogar acesso