API CRM

1. O que é uma API?

API é a sigla para Application Programming Interface (Interface de Programação de Aplicações).
Na prática, é um “meio de comunicação” que permite que o SolarZ CRM converse com outros sistemas (como ERP, plataforma de atendimento, BI, chatbot, etc.), trocando dados de forma segura e automatizada.

Com a API do SolarZ CRM você pode:

• Exportar dados do CRM para outras ferramentas (BI, Excel, sistemas internos…);

• Integrar processos de forma automática (ex.: criar/atualizar negócios conforme ações em outro sistema).

Atualmente você tem acesso a dois conjuntos de rotas:

1. Open API – focada em exportação e leitura simples de dados (uso típico: BI, relatórios, Excel);

2. API Externa (External API) – focada em operar o CRM de fora para dentro, permitindo criar e atualizar negócios, além de consultar informações detalhadas.

2. Geração do Token de Acesso

Para utilizar a API, é necessário um token de autenticação. Esse token garante que somente usuários autorizados acessem os dados da sua conta.

Como gerar:

1. Acesse o SolarZ CRM com seu login.

2. Vá até o menu do seu perfil de usuário.

3. Clique em "Gerar novo Token" e copie o código apresentado.

4. Guarde esse token. Ele será utilizado para autenticar suas requisições na API.

3. Onde encontrar a documentação (Swagger)

Toda a documentação da API está disponível em painéis interativos (Swagger). Lá é possível visualizar, testar e entender cada rota.

Você encontrará dois painéis principais:

1. Open API – Exportação de dados

   • Documentação: /api/v3/api-docs/open

   • Objetivo: listar e consultar dados de forma simples e paginada.

2. API Externa – Operações externas no CRM

   • Documentação: /api/v3/api-docs/external

   • Objetivo: criar, atualizar e consultar negócios e seus vínculos.

No Swagger você pode:

• Ver todos os endpoints disponíveis;

• Ler a descrição dos campos de entrada e saída (schemas);

• Testar chamadas usando seu token diretamente pela interface.

4. Open API – Exportação e leitura simples de dados

A Open API é ideal para quem quer extrair informações do CRM e usar em outros lugares, como:

• Power BI, Data Studio ou outras ferramentas de BI;

• Planilhas em Excel/Google Sheets;

• Sistemas internos de relatórios.

4.1. Principais recursos da Open API

Abaixo, um resumo dos endpoints mais usados (todos começam com /open-api/...):

👤 Usuários

• GET /open-api/users
  Lista usuários de forma paginada (nome, e-mail, telefone, empresa e perfil).

• GET /open-api/users/{id}
  Retorna os dados de um usuário específico.

📥 Canais de origem (Referral Sources)

• GET /open-api/referral-sources
  Lista os canais de origem dos leads (ex.: Indicação, Anúncios, Site, etc.), útil para cruzar dados de marketing.

🎯 Motivos de perda

• GET /open-api/reason-for-loss
  Lista os motivos de perda cadastrados (texto e posição), ideal para relatórios de performance comercial.

📑 Propostas

• GET /open-api/proposals
  Lista propostas criadas no CRM, com opção de filtrar por período (startDate, endDate) e paginação.
  Inclui informações como:

  • customId, datas de criação/atualização;

  • cliente (pessoa/organização), potência, valor para o cliente;

  • status (WON/LOST/OPEN), tipo de projeto;

  • campos personalizados da proposta (initialData, plantData, etc.).

💰 Tipos de precificação

• GET /open-api/pricing-types
  Lista os tipos de precificação configurados na conta (nome, tipo de projeto, se é default).

📊 Funis de vendas (pipelines)

• GET /open-api/pipeline
  Retorna todos os funis de vendas com suas etapas e totais.

• GET /open-api/pipeline/{id}
  Retorna um funil específico por ID.

• GET /open-api/pipeline/stage/{id}
  Retorna uma etapa específica do funil, com posição e totais.

💼 Negócios (deals)

• GET /open-api/deal
  Lista negócios de forma paginada, com possibilidade de filtrar por período (startDate, endDate).
  Retorna, por exemplo:

  • id, customId, name, value;

  • idade do negócio, dias inativo;

  • motivo de perda (com comentário), pipeline/etapa, IDs de pessoa e organização;

  • datas de criação, atualização, ganho e perda;

  • campos personalizados do negócio (dealCustomFieldValues);

  • fonte de origem (referralSource), unidade de negócio (businessUnitDTO).

👤 Pessoas (contatos)

• GET /open-api/client/persons
  Lista pessoas de forma paginada, com opção de filtrar por período.
  Inclui:

  • id, customId, nome, documento, e-mail, telefone;

  • cargo, dono (owner), organização associada;

  • endereço simplificado (cidade, estado);

  • campos personalizados e canal de origem.

🏢 Organizações (empresas)

• GET /open-api/client/organizations
  Lista organizações de forma paginada, também com opção de filtrar por período.
  Inclui:

  • id, customId, nome, documento (CNPJ ou identificador), e-mail, telefone;

  • endereço (cidade, estado);

  • owner, campos personalizados e canal de origem.

📍 Endereços

• GET /open-api/addresses/{id}
  Retorna os dados completos de um endereço específico (rua, CEP, bairro, número, cidade, estado, coordenadas).

📅 Atividades

• GET /open-api/activities
  Lista atividades (ligações, reuniões, tarefas, etc.) de forma paginada, com opção de filtrar por período.
  Inclui:

  • título, tipo de atividade, datas de início/fim, prioridade;

  • notas, se é dia inteiro;

  • vínculo com organização, pessoa e negócio;

  • status (PENDING, DONE…), dono e data de criação.

5. API Externa – Operações de escrita (criar/atualizar negócios)

A API Externa foi criada para cenários onde você precisa operar o CRM a partir de outros sistemas, como:

• Criar negócios automaticamente a partir de um ERP, e-commerce, chatbot, formulário do site, etc.;

• Atualizar negócio quando o cliente faz uma ação (ex.: pagar boleto, assinar contrato, responder NPS…);

• Manter vínculo entre negócio e usina monitorada.

5.1. Principais recursos da API Externa

Todas as rotas começam com /external/....

💼 Negócios – leitura detalhada

• GET /external/deal/{id}
  Retorna todos os detalhes de um negócio, incluindo:

  • dados básicos (nome, valor, status, datas, ativo/inativo);

  • pipeline e etapa;

  • pessoa e organização completas (com endereço);

  • owner (usuário dono do negócio);

  • serviço solar (informações de dimensionamento e cidade);

  • campos personalizados do negócio;

  • informação se está ou não vinculado a usina no monitoramento;

  • metadados, como pipedriveDealId ou IDs externos.

💼 Negócios – atualização completa

• PUT /external/deal/{id}
  Permite atualizar um negócio já existente, incluindo:

  • nome, valor, pipeline, etapa;

  • pessoa, organização, owner;

  • status do negócio (WON, LOST, OPEN…);

  • data prevista de fechamento;

  • campos personalizados (dealCustomFieldValues).

Use essa rota quando quiser sincronizar o estado do negócio com outro sistema (por exemplo, mudar o status para WON quando um contrato é assinado em outro lugar).

💼 Negócios – atualização de vínculo com usina

• PATCH /external/deal/{id}
  Permite atualizar somente se o negócio está ou não vinculado a uma usina no monitoramento, usando um payload simples com linkedToSolarPlant.

Exemplo de uso: após uma usina ser criada no módulo de monitoramento, seu sistema marca o negócio como “vinculado”.

💼 Negócios – lista com filtro por alterações recentes

• GET /external/deal
  Retorna negócios relacionados ao usuário, com mudanças nos últimos lastNumberDaysInterval dias (por padrão, 7).
  É útil para:

  • sincronizar somente o que mudou recentemente;

  • economizar chamadas e evitar percorrer toda a base.

Parâmetros típicos:

• page, size – paginação;

• lastNumberDaysInterval – número de dias para trás a considerar;

• active – se busca apenas negócios ativos.

💼 Negócios – criação (POST)

• POST /external/deal
  Cria um novo negócio no CRM a partir de um sistema externo.

Você pode informar, por exemplo:

• nome do negócio, pipeline, etapa, valor;

• IDs de pessoa e organização já existentes no CRM;

• expectedCloseDate, ownerId;

• campos personalizados.

Em muitos cenários avançados, também há rotas para criar negócio junto com pessoa, organização e atividades em uma única chamada (como /external/deal/with-person-org-activities), pensadas para integrar funil completo de uma vez só. Verifique no Swagger da API Externa quais dessas rotas estão habilitadas para sua conta.

6. Quando usar cada tipo de API?

Para facilitar, pense assim:

Use Open API quando:

• Quer exportar dados para BI (Power BI, Data Studio, etc.);

• Precisa gerar relatórios personalizados em Excel ou Google Sheets;

• Vai apenas consultar e analisar dados (negócios, propostas, pessoas, organizações, atividades, funis…).

Exemplos práticos:

• Criar um painel de taxa de conversão por etapa do funil;

• Analisar motivos de perda por período;

• Cruzar origens de leads com negócios ganhos.

Use API Externa quando:

• Quer criar negócios automaticamente a partir de outro sistema (ex.: ERP, e-commerce, plataforma de leads);

• Precisa atualizar o status de negócios (WON/LOST) conforme eventos externos;

• Precisa marcar se um negócio está vinculado a uma usina no monitoramento;

• Deseja manter tudo sincronizado em tempo real entre o SolarZ CRM e outras plataformas.

Exemplos práticos:

• Gerar um negócio no CRM assim que um lead preencher um formulário no seu site;

• Atualizar um negócio para “WON” assim que o cliente assina a proposta em outro sistema;

• Marcar no negócio que ele está vinculado à usina criada no SolarZ Monitoramento.

7. Exemplos práticos (sem código)

Exemplo A – Conectar ao Power BI (Open API)

1. Gere seu token de acesso no CRM;

2. No Power BI, use a opção de conectar via Web;

3. Informe a URL de um endpoint da Open API (por exemplo, /open-api/deal com filtros de data);

4. Adicione o cabeçalho Authorization: Bearer SEU_TOKEN;

5. Carregue os dados e monte seus dashboards comerciais (taxa de conversão, valor de funil, tempo médio de fechamento, etc.).

Exemplo B – Exportar para Excel (Open API)

1. Faça uma requisição GET para um endpoint como /open-api/client/persons ou /open-api/proposals;

2. Baixe o retorno em JSON;

3. Converta para CSV (ou use o Power Query no Excel para transformar o JSON diretamente);

4. Crie suas tabelas dinâmicas e relatórios internos.

Exemplo C – Integração com ERP ou sistema financeiro (API Externa)

1. Seu ERP registra uma nova venda;

2. A partir do ERP, você chama o POST /external/deal para criar um negócio no CRM com os dados da venda;

3. Quando o pagamento é confirmado no ERP, ele chama PUT /external/deal/{id} para atualizar o status do negócio para WON;

4. Assim, tanto o ERP quanto o CRM ficam alinhados automaticamente, sem lançar tudo duas vezes.

8. Boas práticas e segurança

• Proteja seu token:
  Não compartilhe em grupos, prints ou código público (GitHub, por exemplo).

• Use HTTPS:
  Sempre faça chamadas para a API usando HTTPS, garantindo criptografia no tráfego.

• Controle de acesso interno:
  Gere tokens apenas para usuários que realmente precisam de acesso via API.

• Paginação e filtros:
  Aproveite os parâmetros de paginação (page, size) e período (startDate, endDate, lastNumberDaysInterval) para otimizar consultas e evitar resposta muito grandes.

• Homologação primeiro:
  Sempre que possível, teste integrações em ambiente de homologação ou com conta de testes antes de aplicar em produção.

Resumo geral

• A API do SolarZ CRM agora está dividida em Open API (leitura/exportação) e API Externa (leitura + escrita);

• Você gera um token dentro do próprio CRM e o usa com Authorization: Bearer;

• Use Open API para consultar e exportar dados (BI, relatórios, Excel);

• Use API Externa para criar e atualizar negócios e integrar processos de negócio com outros sistemas;

• Toda a documentação técnica e testes podem ser feitos via Swagger, disponível nos endpoints /api/v3/api-docs/open e /api/v3/api-docs/external.