Como usar a 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;
• ver as ações privadas já liberadas para CRM, atividades, reuniões e consultório;
• 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 se é leitura ou operação;
4. teste primeiro sem filtro;
5. só depois adicione limit, offset e q.

Exemplo de começo correto:

1
GET {{base_url}}/simplificav2/pessoa
2
Authorization: Bearer {{bearer_token}}
3
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 privadas de consulta e as ações privadas 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, Consultório 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

Nas rotas de leitura, 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:

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

Formato pronto para URL:

1
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
2
Authorization: Bearer {{bearer_token}}
3
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.