Calculadora solar no seu site por API: cotação em tempo real sem expor a sua chave

Publicado em 05/09/2026 · atualizado em 25/09/2026 · leitura de 4 min · API e agentes de IA

Uma calculadora no seu site transforma visitante em lead com número na mão: ele digita o consumo e vê potência, valor e economia com o seu preço. Com a API do ionluz isso é uma chamada HTTP. Este guia mostra a arquitetura mínima, com a chave protegida e sem gravar nada que o visitante não autorizou.

Como funciona

1. O visitante informa o consumo mensal em kWh, a cidade, a UF e o tipo de ligação no seu formulário.
2. O seu servidor chama POST /api/v1/quote com a sua chave e preview: true.
3. A resposta traz potência em kWp, valor de venda pela sua formação de preço, payback, economia estimada e quanto do consumo o sistema cobre.
4. Você mostra o resultado e oferece o próximo passo: deixar contato ou receber a proposta completa.

A chave nunca vai para o navegador

A chave viva começa com ilz_, é ligada à sua conta e ao seu preço, e aparece uma única vez na criação. Se ela for para o JavaScript da página, qualquer pessoa copia. A solução é uma rota intermediária no seu servidor (por exemplo /minha-cotacao) que recebe os dados do formulário, adiciona a chave e repassa para o ionluz. O manual em /docs/api traz o exemplo pronto dessa rota.

Preview: simular sem gravar

Com preview: true, a API calcula e responde sem criar registro no seu histórico e sem contar como lead. É o modo certo para calculadora: o visitante pode testar dez consumos diferentes sem virar dez propostas. Quando ele deixa o contato e aceita o tratamento dos dados, você chama de novo sem preview, com a chave viva, e recebe o link da proposta e do PDF. A chave de teste (ilz_test_) só simula.

Campos que valem a pena pedir

• Consumo mensal (kWh): obrigatório; a média de 12 meses dá o melhor resultado.
• Cidade: opcional e recomendada. Nas cidades do Atlas, troca a irradiação da UF pela do município, e é ela que decide o raio de atendimento e o deslocamento.
• UF: ajusta a irradiação e a tarifa de referência. Sem ela a API assume SP.
• Tipo de ligação: mono, bi ou tri. Define a taxa mínima da distribuidora. Sem ela, mono.
• Tarifa (R$/kWh): opcional; a fatura do cliente traz o valor real.
• Tipo de telhado: opcional. No sistema montado pelo catálogo, escolhe a estrutura; no modo custo mais acréscimo, também entra no preço.

Não precisa consultar nada antes. A cotação funciona desde a primeira chamada, com o seu kit onde você cobriu a faixa e com o catálogo padrão do ionluz no resto. Ela recusa em dois casos, e a calculadora precisa tratar os dois: faixa marcada como "não atendo" (422 faixa-nao-atendida) e cidade acima do seu raio quando você pede contato (422 fora-da-area, com a distância e o raio). Nos dois, mostre um formulário de contato no lugar do erro. Como a cotação monta o sistema.

Limites e comportamento

• Freio por IP de 300 requisições por minuto, antes da autenticação, para conter flood.
• Até 60 cotações por minuto por conta, informado nos cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.
• Respostas de erro estruturadas, com requestId para citar no suporte.
• Idempotência: ao gravar uma proposta, repita a mesma chave de operação (Idempotency-Key, válida por 15 minutos) para nunca duplicar um lead.
• Para testar, gere a chave de teste (ilz_test_) em qualquer plano: 50 chamadas por dia, sempre em simulação.

O que mostrar ao visitante

Potência sugerida, valor, economia mensal estimada e payback. Rotule como estimativa, diga que o preço final depende da visita técnica e peça o contato só depois de mostrar o número. Visitante que já viu o resultado deixa o telefone com muito mais frequência do que o que precisa preencher formulário para ver qualquer coisa.

Checklist

• Chave de API só no servidor, atrás de uma rota sua
• Preview para simular; gravação só com consentimento
• Recusas tratadas: faixa-nao-atendida e fora-da-area viram formulário de contato
• Resultado rotulado como estimativa
• Idempotência ao gravar leads

A chave viva, que grava propostas, faz parte do plano Total + API; a chave de teste, de qualquer plano. O manual completo, com exemplos em curl, Node e Python, está em app.ionluz.com.br/docs/api.