API de energia solar: o que é, o que calcula e quando integrar
API de energia solar é um endereço na internet que recebe o consumo de um cliente e devolve o orçamento pronto: potência, valor, economia e payback. Quem chama pode ser o seu site, o seu CRM, o seu bot de WhatsApp ou um agente de IA. Este guia explica o que ela calcula, o que ela não substitui e quando vale integrar.
O que entra e o que sai
A entrada mínima é o consumo mensal em kWh. Estado, cidade e tipo de ligação melhoram a precisão, porque mudam a irradiação, a taxa mínima da distribuidora (30, 50 ou 100 kWh) e, com a cidade, o raio de atendimento e o deslocamento. A saída é o orçamento inteiro:
| Campo | O que significa |
|---|---|
| Potência em kWp | Dimensionamento pelo consumo menos a taxa mínima, com a irradiação da cidade ou do estado e as perdas já aplicadas. O sistema sai do kit. |
| Valor final | Preço de venda pela formação de preço da sua conta: valor por obra + valor por kWp, faixa ou custo mais acréscimo. Conta que nunca salvou preço cota pela referência de mercado. |
| Quanto cobre | O percentual do consumo compensável que o sistema cobre (100% é o alvo cheio). |
| Economia do primeiro mês | Diferença entre a conta atual e a conta com o sistema, já com a fração do Fio B do ano corrente. |
| Payback em anos | Ano em que a economia acumulada cruza o investimento. |
| Economia em 25 anos | Acumulado do horizonte, com degradação dos módulos e reajuste de tarifa. |
| Premissas usadas | Tarifa e estado considerados, para você mostrar de onde saiu o número. |
O cálculo é o mesmo do painel: tarifa, irradiação, Fio B e payback saem das mesmas funções, o que evita a situação constrangedora de o site prometer um número e o vendedor apresentar outro. Hoje, a API monta o sistema com o kit e soma o deslocamento quando você cobra por km; no passo a passo, você escolhe o kit e fecha o preço. Nas contas com o menu novo, o passo a passo cota pelo mesmo motor da API, com o mesmo sistema e o mesmo preço.
Calcular e gravar são coisas diferentes
A distinção mais importante da integração é o modo preview. Com ele ligado, a chamada calcula e devolve o orçamento sem criar registro nenhum: serve para calculadora pública, teste e simulação de cenários com o cliente na frente. Com ele desligado, e com o consentimento do titular registrado, a chamada grava a proposta, cria o lead no painel e devolve o link do PDF público.
Na prática, a maioria das integrações usa os dois: preview enquanto o visitante brinca com os números, gravação no momento em que ele deixa o contato. O consentimento fica guardado com data e versão do texto apresentado, que é o que a LGPD exige de quem trata dado pessoal.
Os limites que importam
- Ritmo: 60 cotações por minuto por conta e 120 consultas de cobertura. Para site e atendimento, sobra; para carga de importação, converse antes.
- Repetição segura: a cotação aceita uma chave de idempotência. Se a rede cair depois do envio, repetir a chamada com a mesma chave devolve a mesma resposta em vez de criar uma proposta duplicada.
- Cobertura e área: a cotação recusa o que você marcou como "não atendo" e, se você pediu contato acima do raio, o que fica longe demais (
fora-da-area). A consulta de cobertura mostra em que faixas entra o seu kit. - Teste: a chave de teste (
ilz_test_) existe em qualquer plano, com 50 chamadas por dia, sempre em simulação. - Segurança: a chave é de servidor. Ela nunca deve ir para o navegador, porque qualquer visitante lê o código que roda lá.
Quando integrar, e quando o painel basta
Integrar custa tempo de desenvolvimento e manutenção. Os sinais de que o retorno aparece:
- Você recebe pedido de orçamento fora do horário. Uma calculadora no site responde às duas da manhã e captura o contato enquanto você dorme.
- O mesmo dado é digitado duas vezes. Lead que chega no formulário e é redigitado no orçamento é retrabalho que a integração elimina.
- O atendimento por WhatsApp demora para responder valor. Uma chamada devolve o número ainda dentro da conversa, e ela continua quente.
- Você já usa um agente de IA no atendimento. Conectá-lo ao servidor MCP dá a ele a ferramenta de cotar com o seu preço, sem código.
Se o volume é de poucos orçamentos por semana e todos passam por você, o painel resolve e a integração pode esperar. Nesse caso, a página de captação já entrega captura de lead sem programar nada.
O que a API não resolve
Vale dizer com clareza o que fica fora, porque integração vendida como mágica gera frustração:
- Visita técnica. Nenhuma conta sabe se o telhado aguenta a estrutura, se há sombra da caixa d'água às três da tarde ou se o padrão de entrada precisa de troca. A cotação por API é o começo da conversa.
- Negociação. O valor que sai é o da sua tabela. Desconto, condição de pagamento e brinde continuam sendo decisão sua, no orçamento.
- Homologação. Projeto, ART e protocolo na distribuidora seguem o fluxo normal. A API entrega o número comercial; o processo de conexão continua com você.
- Atendimento. Resposta rápida abre a porta; quem fecha é quem conversa. A automação compra tempo para você falar com quem está pronto para comprar.
Erros comuns de integração
Quatro tropeços aparecem sempre nas primeiras semanas:
- Chave no navegador. Qualquer visitante lê o código da página. A chave mora no servidor, sem exceção.
- Gravar tudo. Chamar sem preview em uma calculadora pública enche o painel de lead sem contato. Preview enquanto for simulação; gravação quando houver consentimento.
- Ignorar o erro. A resposta traz código de erro estável. Tratar cada um com uma mensagem clara na tela evita o visitante achar que o site quebrou.
- Repetir sem chave de idempotência. Retry cego cria proposta duplicada e confunde o comercial.
Os três caminhos
- Calculadora no seu site: um formulário na sua página e uma rota no seu servidor que guarda a chave. O passo a passo, com exemplo pronto, está em calculadora solar para o seu site.
- Agente de IA pelo MCP: o assistente ganha cinco ferramentas, de cotar a conferir a cobertura, e responde dentro da conversa. Veja agente de IA e MCP e o guia sobre cotação por agente de IA.
- WhatsApp: o consumo chega no chat, a API devolve o número e o link da proposta sai na mesma conversa. O fluxo está em cotação por WhatsApp.
Como avaliar antes de assinar
- A conta da API é a mesma do painel, com a sua formação de preço
- Existe modo que calcula sem gravar, para calculadora pública e teste
- A resposta traz as premissas usadas, para você mostrar a origem do número
- Há chave de idempotência, para retry sem duplicar proposta
- A documentação é pública e dá para ler antes de pagar
A referência completa dos endpoints, com todos os campos e os códigos de erro, fica na página de API e MCP e na documentação aberta do app.
Leia também
Calculadora solar no seu site por API: cotação em tempo real sem expor a sua chave
Cotação de energia solar por agente de IA: como o MCP do ionluz funciona
Modelo de proposta de energia solar: o que precisa ter para fechar a venda
Propostas solares honestas, do consumo ao PDF
O ionluz transforma o consumo em kWh do seu cliente em proposta completa: dimensionamento, cálculo pela Lei 14.300, payback e PDF com as cores da sua empresa, e com a sua logo só na Máquina. Criar a conta leva 30 segundos; cada proposta no passo a passo, menos de 1 minuto.