Modelo de integração e 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

1
{
2
  "id": 162472,
3
  "nome": "Maria da Silva",
4
  "origem_id": 17,
5
  "consultor_id": 598,
6
  "ativo": "S"
7
}

Exemplo simplificado de origem

1
{
2
  "id": 17,
3
  "descricao": "Landing Page",
4
  "ativo": "S"
5
}

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.