ionluzGerar minha chave

API & MCP

Cotação

POST/api/v1/quote

Gera um orçamento a partir do consumo. Campos do corpo (JSON):

CampoTipoDescrição
consumoKwhMesnumberObrigatório. Consumo médio mensal em kWh.
ufstringUF (2 letras). Ajusta a irradiação (HSP). Padrão SP.
fasesstringmono, bi ou tri (aceitamos também monofasico/bifasico/trifasico, com ou sem acento, qualquer caixa). Padrão mono. Qualquer outro valor → 422 fase-invalida.
kwpnumberPotência desejada. Se omitido, dimensionamos pelo consumo.
tarifanumberTarifa em R$/kWh. Se omitida, assumimos um padrão (veja assumptions).
nome, email, telefone, cidadestringDados do lead (opcionais; só usados ao gravar).
telhadostringOpcional: ceramico · metalico · fibrocimento · laje · solo · carport. Na cotação por combinação automática, aplica o preço global de estrutura configurado na aba API (por telhado × nº de módulos). Omisso usa o telhado padrão da conta. A resposta indica em assumptions.telhado quando entrou na conta.
previewbooleantrue = só simula (não grava, não gera PDF). Padrão false.
consentbooleanObrigatório ao gravar (preview: false): true confirma que o titular consentiu (LGPD) com o registro dos dados. Registramos como prova a data, a versão do texto da política e metadados técnicos da requisição (IP, user-agent e origem, quando presentes). Sem ele, 400 consentimento-obrigatorio. Em preview, é ignorado.

Resposta, modo simulação (preview: true)

{
  "ok": true,
  "orcamento": {
    "potenciaKwp": 5.4,
    "valorFinal": 28500,
    "paybackAnos": 6.3,
    "economiaMes1": 336,
    "economia25Anos": 216247,
    "sePaga": true
  },
  "assumptions": {
    "uf": "SP", "fase": "bi", "hspHoraDia": 4.9, "hspFonte": "uf-media",
    "tarifaBrlKwh": 0.99, "tarifaAssumida": true,
    "kwpAlvo": 5.16, "kwpAlvoAssumido": true
  },
  "preview": true,
  "aviso": "Estimativa sujeita a visita técnica.",
  "requestId": "req_9f2c1a7b3d4e5f6a90"
}

O bloco assumptions revela o que o motor assumiu quando você omitiu algo, por exemplo,tarifaAssumida: true significa que caímos na tarifa padrão porque você não enviou tarifa. A tarifa padrão é a residencial B1 homologada pela ANEEL para a UF (São Paulo, 0,99 R$/kWh), a mesma das páginas por cidade do site. E hspFonte diz de onde saíram as horas de sol: mande cidade e, quando o nome casa com uma das 100 cidades do Atlas Brasileiro de Energia Solar, a resposta volta com "hspFonte": "cidade-atlas" e o HSP do município; sem par, vale a média do estado (uf-media). Use isso para deixar claro ao usuário final o que foi estimado.

Deslocamento por km (opcional): se você configurar a sua cidade-sede no perfil, cotações para clientes em outra cidade recebem um acréscimo de R$/km (padrão R$ 5,00, editável) pela distância rodoviária estimada entre as sedes municipais (IBGE, fator rodoviário 1,35). O acréscimo já entra no valorFinal antes do cálculo, payback e economia saem coerentes com o valor cobrado, e a resposta ganha o bloco deslocamento: { "km": 87, "valorBrl": 435 }para o seu controle (ele não aparece no documento do cliente). Mesma cidade não altera o preço. Cidade do cliente não reconhecida: no mesmo estado, sem acréscimo; em outro estado, cobra até o centro do estado.

Resposta, modo gravação (preview: false, exige consent: true)

{
  "ok": true,
  "orcamento": { "potenciaKwp": 5.4, "valorFinal": 28500, "paybackAnos": 6.3,
    "economiaMes1": 336, "economia25Anos": 216247, "sePaga": true },
  "assumptions": { "uf": "SP", "fase": "bi", "hspHoraDia": 4.9, "hspFonte": "uf-media",
    "tarifaBrlKwh": 0.99, "tarifaAssumida": true, "kwpAlvo": 5.16, "kwpAlvoAssumido": true },
  "proposalId": "clx8h2k9a0001abcd",
  "pdfUrl": "https://app.ionluz.com.br/api/pub/clx8h2k9a0001abcd/pdf?t=...",
  "propostaUrl": "https://app.ionluz.com.br/p/clx8h2k9a0001abcd?t=...",
  "aviso": "Estimativa sujeita a visita técnica.",
  "requestId": "req_9f2c1a7b3d4e5f6a90"
}

Ao gravar, você recebe proposalId, o link do pdfUrl (PDF pronto, com a sua marca) e opropostaUrl (página interativa que o cliente abre no celular, antes/depois da conta, gráfico de payback e financiamento). Ambos os links já vêm assinados e são públicos para compartilhar.

Exemplos

// Node.js / navegador (fetch nativo). Use preview:true p/ simular sem gravar.
async function cotar(consumoKwhMes, uf = "SP") {
  const res = await fetch("https://app.ionluz.com.br/api/v1/quote", {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + process.env.IONLUZ_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ consumoKwhMes, uf, preview: true }),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(data.error + ": " + data.message);
  return data.orcamento;
}
import os, requests

def cotar(consumo_kwh_mes, uf="SP", persist=False):
    corpo = {"consumoKwhMes": consumo_kwh_mes, "uf": uf, "preview": not persist}
    if persist:
        corpo["consent"] = True  # obrigatório ao gravar: o titular consentiu (LGPD)
    r = requests.post(
        "https://app.ionluz.com.br/api/v1/quote",
        headers={"Authorization": f"Bearer {os.environ['IONLUZ_API_KEY']}"},
        json=corpo,
        timeout=30,
    )
    data = r.json()
    if not data["ok"]:
        raise RuntimeError(f"{data['error']}: {data['message']}")
    return data["orcamento"]
API v1 · ionluz, orçamentos solares. Dúvidas? Cite o requestId ao escrever para suporte@ionluz.com.br.
Cotação, POST /api/v1/quote · API ionluz