***

title: Modelo de integração e performance
subtitle: >-
Entenda por que a API usa referências por ID e como consumir isso do jeito
certo
slug: integration-model-and-performance
---------------------------------------

## Como esta API foi pensada

Os endpoints de consulta do `simplificav2` foram desenhados para leitura performática.

O objetivo principal é permitir que o cliente:

* sincronize dados com um sistema externo;
* monte uma cópia local para BI ou warehouse;
* mantenha cadastros auxiliares atualizados;
* faça consultas de alto volume sem depender de joins pesados em cada chamada.

## Por que muitos campos vêm por ID

Nesta API, vários recursos retornam referências por identificador em vez de expandir tudo em cada resposta.

Exemplo comum:

* a pessoa pode retornar `origem_id`;
* para descobrir os dados dessa origem, a integração consulta `pessoa_origem`.

Isso é intencional.

## Vantagem desse modelo

Esse padrão ajuda a:

* reduzir payload por resposta;
* evitar repetição de dados em massa;
* melhorar performance das consultas principais;
* permitir sincronização incremental de cadastros auxiliares;
* facilitar consumo em BI, warehouse e integrações que mantêm tabelas de referência locais.

## Estratégia recomendada de integração

### 1. Sincronize os cadastros auxiliares

Antes de consumir em volume os dados principais, sincronize recursos como:

* `pessoa_origem`
* `categoria`
* `segmento`
* `consultor`
* `atividade_motivo`
* `reuniao_motivo`
* `etapa_negociacao`
* `origem_comercial`
* `categoria_produto`
* `categoria_financeira`
* `tipo_pagamento`

### 2. Depois sincronize os dados principais

Exemplos:

* `pessoa`
* `atividade`
* `reuniao`
* `oportunidade`
* `venda`
* `receita`
* `despesa`

### 3. Resolva as referências no seu lado

Assim, quando a API retornar um `origem_id`, `consultor_id`, `categoria_id` ou outro identificador, o seu sistema já terá as tabelas auxiliares necessárias para montar a visão completa.

### 4. Faça a carga inicial com paginação

* defina um `limit` compatível com a sua integração;
* avance o `offset` até `hasMore = false`;
* registre a última página processada para retomar a integração com segurança.

### 5. Faça a sincronização incremental por tempo quando existir campo temporal

* use o campo temporal publicado naquele endpoint;
* combine o filtro temporal com paginação;
* prefira datas e horários em UTC no formato ISO 8601.

## Exemplo prático

### Exemplo simplificado de pessoa

```json
{
  "id": 162472,
  "nome": "Maria da Silva",
  "origem_id": 17,
  "consultor_id": 598,
  "ativo": "S"
}
```

### Exemplo simplificado de origem

```json
{
  "id": 17,
  "descricao": "Landing Page",
  "ativo": "S"
}
```

Leitura correta:

* o endpoint `pessoa` entrega o cadastro principal;
* o endpoint `pessoa_origem` entrega a tabela de referência da origem;
* o lado consumidor junta os dois conforme a sua necessidade.

## Regra prática para clientes e agentes de IA

Quando receber um campo terminado em `_id`, assuma primeiro que:

1. aquele valor é uma referência;
2. existe outro endpoint responsável pelo cadastro auxiliar correspondente;
3. o ideal é manter esse cadastro sincronizado no sistema consumidor.

### Boas práticas para automações e agentes de IA

* use sempre os nomes de campo exatamente como publicados no schema;
* não presuma campos que não estejam documentados;
* comece pelas chamadas sem filtro;
* pagine até `hasMore = false`;
* resolva entidades relacionadas por endpoints auxiliares;
* trate `400`, `401` e `500` com fluxos diferentes e preserve logs de requisição e resposta.

## Importante sobre exemplos JSON

Os exemplos desta documentação são ilustrativos para explicar o modelo.

O contrato exato de campos, tipos e nomes publicados em cada recurso continua sendo a API Reference.