Saltar para o conteúdo principal
Este guia percorre o fluxo completo de ponta a ponta: registrar o aplicativo, autorizar um usuário e buscar os contatos do workspace. Ao final você terá um access_token funcionando e uma resposta real da API no terminal.

​
Pré-requisitos

  • Conta na Vendaze com pelo menos um workspace ativo (crie gratuitamente se ainda não tiver)
  • curl disponível no terminal

​
1. Registrar o aplicativo

Envie uma requisição de registro com o nome do app, e-mail de contato, redirect URIs e os escopos necessários. 
curl -X POST https://api.vendaze.com/v1/auth/register-app \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "Minha Integração de Teste",
    "email": "dev@meuapp.com",
    "redirect_uris": ["https://meuapp.com/oauth/callback"],
    "scopes": ["people:read", "companies:read", "deals:read"]
  }'
Verifique sua caixa de entrada. Você receberá um e-mail com um link seguro para visualizar seu client_id e client_secret. Abra o link em até 15 minutos. O link expira e não pode ser reaberto. Copie os dois valores para um lugar seguro antes de continuar.

​
2. Construir a URL de autorização

Construa a URL de autorização e abra no browser. Substitua SEU_CLIENT_ID pelo valor recebido. 
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-123
O parâmetro state deve ser uma string aleatória gerada por você. Em produção, armazene-o na sessão e verifique no callback para prevenir ataques de CSRF.

​
3. Autorizar e obter o code

Após abrir a URL no browser, você vai:
  1. Fazer login com sua conta Vendaze
  2. Selecionar um workspace para conectar
  3. Revisar os escopos solicitados
  4. Clicar em “Autorizar”
Após autorizar, o browser redireciona para: 
https://meuapp.com/oauth/callback?code=AUTH_CODE_AQUI&state=token-csrf-aleatorio-123
Copie o valor de code da URL. Ele expira em 10 minutos e só pode ser usado uma vez.

​
4. Trocar o code pelos tokens

Envie o code pelo seu servidor. Esta requisição nunca deve ser feita 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_AQUI&client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET"
Resposta: 
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "workspace_slug": "acme-corp"
}

​
O que acabou de acontecer

CampoO que significa
access_tokenJWT assinado que autoriza requisições ao workspace. Inclua como Authorization: Bearer <token> em toda chamada à API. Expira em 1 hora.
refresh_tokenToken de longa duração usado para obter um novo access_token sem interação do usuário. Válido por 60 dias a partir do último uso. Armazene criptografado no banco.
token_typeSempre Bearer. Indica como enviar o token no header Authorization.
expires_inSegundos até o access_token expirar. Sempre 3600. Use para agendar renovações proativas.
workspace_slugSlug do workspace autorizado pelo usuário. Use para identificar a qual workspace este token pertence no seu modelo de dados.
Armazene os dois tokens com segurança no servidor. Nunca os exponha em código client-side ou em URLs.

​
5. Buscar um contato

Use o access_token para fazer sua primeira chamada real à API. Busque uma pessoa específica pelo UUID: 
curl https://api.vendaze.com/v1/people/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
Resposta: 
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "Ana Costa",
    "emails": [{ "email": "ana@empresa.com", "type": "work" }],
    "phones": [{ "phone": "+5511999990001", "type": "mobile" }],
    "company_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "company": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "full_name": "Acme Corp" },
    "position": "Head of Sales",
    "ranking": 0,
    "tags": [],
    "lists": [],
    "custom_fields": [],
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-05-20T14:22:00Z"
  }
}
A resposta inclui os dados da pessoa com company, tags, lists e custom_fields embutidos.

​
O que explorar a seguir

Campos Adicionais

Leia e escreva campos adicionais definidos pelo workspace em pessoas, empresas e negócios.

Erros

Entenda os códigos de erro e construa tratamento de erros robusto.

Webhooks

Receba notificações em tempo real quando eventos ocorrem nos dados do workspace.

API Reference

Referência completa dos endpoints com schemas de request e response.