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

Publicado em 05/09/2026 · leitura de 7 min

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 consumo mensal em kWh, UF e 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 com a sua formação de preço, payback e economia estimada.
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 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 a 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 e recebe o link da proposta e do PDF.

Campos que valem a pena pedir

• Consumo mensal (kWh): obrigatório; a média de 12 meses dá o melhor resultado.
• UF: ajusta a irradiação. Sem ela a API assume SP.
• Tipo de ligação: mono, bi ou tri. Define o custo de disponibilidade.
• Tarifa (R$/kWh): opcional; a fatura do cliente traz o valor real.
• Tipo de telhado: opcional; muda a estrutura e o preço quando o seu catálogo tem faixas por telhado.

Antes de mostrar o formulário, GET /api/v1/coverage diz quais faixas de potência a sua conta cobre com kit e preço. Uma calculadora que responde "não atendemos esse porte" é melhor do que uma que inventa.

Limites e comportamento

• Freio por IP de 300 requisições por minuto, antes da autenticação, para conter flood.
• Limite por chave, 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 para nunca duplicar um lead.

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
• Coverage consultado para não cotar o que você não atende
• Resultado rotulado como estimativa
• Idempotência ao gravar leads

A API faz parte do plano Total + API. O manual completo, com exemplos em curl, Node e Python, está em app.ionluz.com.br/docs/api.