> ## Documentation Index
> Fetch the complete documentation index at: https://developers.vendaze.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Primeira Requisição

> Guia completo do registro até a sua primeira chamada real à API da Vendaze.

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](https://app.vendaze.com/register) 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.

```bash theme={null}
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.

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
curl https://api.vendaze.com/v1/people/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

Resposta:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Campos Adicionais" icon="sliders" href="/pt/guides/custom-fields">
    Leia e escreva campos adicionais definidos pelo workspace em pessoas, empresas e negócios.
  </Card>

  <Card title="Erros" icon="triangle-exclamation" href="/pt/guides/errors">
    Entenda os códigos de erro e construa tratamento de erros robusto.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/pt/guides/webhooks">
    Receba notificações em tempo real quando eventos ocorrem nos dados do workspace.
  </Card>

  <Card title="API Reference" icon="code" href="/pt/api-reference">
    Referência completa dos endpoints com schemas de request e response.
  </Card>
</CardGroup>