Primeira Requisição

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:

Fazer login com sua conta Vendaze
Selecionar um workspace para conectar
Revisar os escopos solicitados
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

Campo	O que significa
`access_token`	JWT assinado que autoriza requisições ao workspace. Inclua como `Authorization: Bearer <token>` em toda chamada à API. Expira em 1 hora.
`refresh_token`	Token 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_type`	Sempre `Bearer`. Indica como enviar o token no header `Authorization`.
`expires_in`	Segundos até o `access_token` expirar. Sempre 3600. Use para agendar renovações proativas.
`workspace_slug`	Slug 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",
    "score": 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.

Visão Geral

Começando

Utilizando a API

Boas Práticas

Pré-requisitos

1. Registrar o aplicativo

2. Construir a URL de autorização

3. Autorizar e obter o code

4. Trocar o code pelos tokens

O que acabou de acontecer

5. Buscar um contato

O que explorar a seguir

Campos Adicionais

Erros

Webhooks

API Reference

​Pré-requisitos

​1. Registrar o aplicativo

​2. Construir a URL de autorização

​3. Autorizar e obter o code

​4. Trocar o code pelos tokens

​O que acabou de acontecer

​5. Buscar um contato

​O que explorar a seguir

Campos Adicionais

Erros

Webhooks

API Reference

Pré-requisitos

1. Registrar o aplicativo

2. Construir a URL de autorização

3. Autorizar e obter o code

4. Trocar o code pelos tokens

O que acabou de acontecer

5. Buscar um contato

O que explorar a seguir