***

title: Primeira chamada
subtitle: Como autenticar e fazer sua primeira consulta sem complicação
slug: getting-started
---------------------

## 1. Entenda o padrão desta API

Esta página mostra como começar a usar as consultas privadas do Simplifica.

Ela é uma API de leitura em JSON, pensada para:

* integrações entre sistemas;
* relatórios e BI;
* automações;
* assistentes e agentes de IA.

## 2. Confirme o tipo de autenticação

No Simplifica existem dois modelos principais:

* token privado com `Authorization: Bearer`, usado nas APIs de consulta;
* token público com `x-api-key`, usado hoje principalmente na API Lead.

Para essas consultas privadas, use o token privado.

No Simplifica, abra o menu do usuário e acesse `Token API` para visualizar as credenciais da empresa.

Você não precisa executar um fluxo externo para obter esse token. Basta copiar o token privado já disponível no Simplifica e enviar `Authorization: Bearer`.

## 3. Autentique com bearer token

Use o cabeçalho:

```http
Authorization: Bearer {{bearer_token}}
```

Importante:

* esta API não usa `x-api-key`;
* nunca publique tokens reais em exemplos ou compartilhamentos.

## 4. Faça a primeira chamada sem filtros

Comece sempre assim:

```http
GET {{base_url}}/simplificav2/oportunidade
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

Essa primeira chamada serve para:

* confirmar que a autenticação está funcionando;
* entender a estrutura da resposta;
* descobrir quais campos o recurso publica;
* só então decidir quais filtros fazem sentido.

## 5. Entenda a paginação

Os endpoints de listagem retornam dados paginados.

Parâmetros principais:

* `limit`: quantos registros trazer por resposta;
* `offset`: quantos registros pular antes de começar a resposta.

Padrão operacional:

* `100` registros por página;
* avance a paginação até `hasMore = false` na carga inicial;
* informe `limit` explicitamente quando quiser previsibilidade.

Exemplo:

```http
GET {{base_url}}/simplificav2/oportunidade?limit={{limit}}&offset=0
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

## 6. Estrutura comum da resposta

Você vai encontrar com frequência:

* `items`
* `count`
* `limit`
* `offset`
* `hasMore`
* `links`

Isso ajuda tanto integrações tradicionais quanto agentes de IA a continuar a paginação quando houver mais resultados.

## 7. Quando usar filtros

Só depois da primeira leitura limpa.

Se você precisar reduzir ou ordenar os dados, use o parâmetro `q`.

Formato legível:

```http
GET {{base_url}}/simplificav2/pessoa?q={"ativo":"S"}
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

Formato pronto para URL:

```http
GET {{base_url}}/simplificav2/pessoa?q=%7B%22ativo%22%3A%22S%22%7D
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

Para aprender esse formato com calma, siga para [Filtros e paginação](/filters-and-pagination).