Saltar para o conteúdo principal
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

1

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

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

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

Trocar o code pelos tokens

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

Fazer requisições à API

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

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âmetroObrigatórioDescrição
client_idSimO client ID do seu aplicativo.
redirect_uriSimDeve corresponder exatamente a uma URI registrada.
response_typeSimDeve ser code.
stateNãoString 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"
}
CampoDescrição
access_tokenUse em toda requisição à API. Expira em 1 hora.
refresh_tokenUsado para renovar o access token. Válido por 60 dias se utilizado regularmente.
token_typeSempre Bearer.
expires_inSegundos até o access token expirar. Sempre 3600.
workspace_slugSlug 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.