Como usar a API reference

Entenda como navegar pelos endpoints e usar a referência técnica sem se perder

View as Markdown

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:

1GET {{base_url}}/simplificav2/pessoa
2Authorization: Bearer {{bearer_token}}
3Accept: 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.

Convenção de paginação desta V1

  • o padrão operacional documentado é 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:

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

Formato pronto para URL:

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