***

title: Como usar a API reference
subtitle: Entenda como navegar pelos endpoints e usar a referência técnica sem se perder
slug: api-reference
-------------------

Esta aba mostra a referência técnica da API gerada a partir da specification OpenAPI.

Ela é útil para:

* ver todos os endpoints publicados;
* entender quais campos existem em cada recurso;
* saber o tipo de cada campo;
* consultar parâmetros, autenticação e formatos de resposta.

## Regra mais importante

Ao abrir um endpoint, pense nesta ordem:

1. confirme se ele usa token privado ou token público;
2. veja a rota base;
3. entenda o que aquele recurso retorna;
4. teste primeiro sem filtro;
5. só depois adicione `limit`, `offset` e `q`.

Exemplo de começo correto:

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

Na prática:

* `Authorization: Bearer` indica token privado;
* `x-api-key` indica token público daquele canal;
* hoje a API Lead usa token público;
* as APIs de consulta usam token privado.

## Paginação

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

## O que você encontra em cada endpoint

* descrição funcional do recurso;
* parâmetros disponíveis;
* schema da resposta;
* exemplos de uso;
* agrupamento por domínio, como CRM, Comercial, Reuniões e Financeiro.

## Sobre referências por ID

Vários recursos desta API retornam relacionamentos por identificador.

Exemplo:

* uma pessoa pode trazer `origem_id`;
* o significado desse valor é resolvido consultando o endpoint de origem correspondente.

Isso foi feito para priorizar performance e facilitar sincronização estruturada do lado consumidor.

O modelo recomendado é:

1. sincronizar primeiro os cadastros auxiliares;
2. sincronizar depois os dados principais;
3. resolver os relacionamentos no seu sistema, warehouse ou BI.

## Sobre os filtros

Nesta API, o uso principal de filtro é pelo parâmetro `q`.

Isso significa que:

* a maior parte dos endpoints não usa dezenas de parâmetros fixos;
* você consulta primeiro a estrutura;
* depois monta o filtro usando os campos publicados naquele recurso.

Exemplo:

Formato legível:

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

Formato pronto para URL:

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

## Quando usar esta aba e quando usar os guias

* use a aba `Documentação` quando quiser explicação passo a passo;
* use a aba `API Reference` quando quiser detalhe técnico do endpoint e dos campos.

As duas partes se complementam: a documentação explica o contexto; a referência mostra o contrato.