API & MCP

Entrada de leads

POST/api/v1/leads

O lead que chega pela sua integração (o formulário do anúncio pelo Make ou pelo Zapier, ou o seu sistema) vira o mesmo orçamento automático da sua página, com o seu preço e a sua marca. A resposta traz o link da proposta, o do PDF e a mensagem pronta para o WhatsApp do lead. Não programa? O passo a passo sem código está em Formulário do anúncio.

Com a chave viva (plano Máquina) o lead é gravado. Com a chave de teste (ilz_test_...) tudo roda em prévia: a resposta tem o mesmo formato, nada é gravado e nenhum e-mail sai. Dá para montar e testar a integração inteira antes de assinar.

curl -X POST https://app.ionluz.com.br/api/v1/leads \
  -H "Authorization: Bearer ilz_sua_chave" \
  -H "Idempotency-Key: 1259783460127734" \
  -H "Content-Type: application/json" \
  -d '{ "nome": "Maria Exemplo", "telefone": "(15) 99999-0000", "email": "cliente@exemplo.com.br", "cidade": "Sorocaba", "uf": "SP", "fases": "bi", "valorContaBrl": 614, "origem": "meta-formulario", "campanha": { "utm_source": "meta", "utm_medium": "formulario", "utm_campaign": "kit-ionluz", "utm_content": "conta-de-luz" }, "consentimento": { "texto": "Autorizo a Empresa Exemplo Energia Solar a me contatar sobre este orçamento de energia solar.", "data": "2026-09-25T14:01:37+0000", "fonte": "Formulário do anúncio no Instagram" } }'

Campos do corpo

JSON de até 8 KB. Telefone ou e-mail e o consentimento são obrigatórios; o resto é o que o formulário tiver. Campo fora da lista é ignorado.

Campo	Tipo	Descrição
`nome`	string	Nome da pessoa, até 120 caracteres. A mensagem do WhatsApp abre com o primeiro nome.
`telefone`	string	Telefone com DDD em qualquer formato ("(15) 99999-0000", "+5515999990000" ou só os dígitos, também como número). Com 10 ou 11 dígitos depois do 55, a resposta traz o link do WhatsApp. Obrigatório, ou o e-mail.
`email`	string	E-mail da pessoa. Com o envio autorizado na sua conta, o link da proposta vai para ele. Obrigatório, ou o telefone.
`cidade`	string	Cidade do lead; aceita o estado junto ("Sorocaba - SP", "Sorocaba/SP"). Decide as horas de sol, o raio de atendimento e o deslocamento, como na cotação.
`uf`	string	Estado, pela sigla ou pelo nome ("SP" ou "São Paulo"). Sem ele vale o da cidade e, sem os dois, o da sua cidade-sede.
`fases`	string	A ligação: mono, bi ou tri, e o que o formulário responde ("Monofásica", "3 fases"). "Não sei" vale como não informada (monofásica). O que não dá para reconhecer faz o lead virar contato, com semOrcamento.motivo fase-invalida.
`valorContaBrl`	number ou string	O valor de uma conta de luz, em reais: número ou texto ("R$ 350,00", "350 reais"). A faixa do formulário ("R$ 200 a R$ 400") vale o meio; "até R$ 200" vale 200; "acima de R$ 700" vale 700. O consumo sai estimado pela tarifa, com consumoEstimado na resposta. Sem ele (e sem o consumo), o lead vira contato.
`consumoKwhMes`	number	O consumo em kWh por mês, quando o formulário pergunta. Com os dois, vale o consumo.
`tarifa`	number	Tarifa da energia em R$/kWh. Se omitida, vale a tarifa residencial B1 da UF (ANEEL). Valores ficam entre 0,01 e 10.
`telhado`	string	Tipo de telhado (opcional). Escolhe a estrutura das cotações montadas por combinação automática ou pelo catálogo padrão; muda o preço só no modo Custo → venda (nos outros, a estrutura entra como item do documento). Omitido usa o telhado padrão da conta.
`origem`	string	De onde o lead veio: meta-formulario, make, zapier, outro. Para o formulário do anúncio, meta-formulario, pelo Make ou pelo Zapier. Sem o campo, vale outro.
`campanha`	object	As etiquetas da campanha (utm_source, utm_medium, utm_campaign, utm_content, utm_term, fbclid, fbc, gclid, referrer e entrada). Vão para a proposta e para o cliente, sem dado pessoal.
`consentimento`	object	Obrigatório: texto (o que a pessoa aceitou, pelo menos 10 caracteres), data (quando aceitou) e fonte (onde aceitou). Sem ele nada é gravado, nem na prévia passa.
`preview`	boolean	true simula: a resposta tem o mesmo formato, sem gravar e sem e-mail. Com a chave de teste a prévia é sempre aplicada.

A resposta

O lead do exemplo, numa conta que ainda cota pela referência de mercado (o preço sai em faixa) e com o envio de e-mail ao cliente autorizado:

{
  "ok": true,
  "gravado": true,
  "proposalId": "clx8h2k9a0001abcd",
  "propostaUrl": "https://app.ionluz.com.br/p/clx8h2k9a0001abcd?t=...",
  "pdfUrl": "https://app.ionluz.com.br/api/pub/clx8h2k9a0001abcd/pdf?t=...",
  "orcamento": {
    "potenciaKwp": 5.72,
    "valorFinal": 14296.8,
    "paybackAnos": 2.1406530441031313,
    "economiaMes1": 545,
    "economia25Anos": 375409,
    "sePaga": true,
    "cobrePct": 120
  },
  "consumoEstimado": true,
  "consumoKwhMes": 620,
  "valorContaBrl": 614,
  "preco": {
    "publicado": {
      "modo": "faixa",
      "valor": 14296.8,
      "min": 13500,
      "max": 15100,
      "pct": 5,
      "rotulo": "entre R$ 13.500 e R$ 15.100",
      "texto": "Entre R$ 13.500 e R$ 15.100. O valor final é confirmado na visita técnica.",
      "nota": "O valor final é confirmado na visita técnica."
    }
  },
  "whatsapp": {
    "modo": "faixa",
    "mensagem": "Olá, Maria! Aqui é da Empresa Exemplo Energia Solar. O seu orçamento de energia solar está pronto: sistema de 5,72 kWp, entre R$ 13.500 e R$ 15.100.\nO valor final é confirmado na visita técnica. Veja a proposta completa, com a economia estimada: https://app.ionluz.com.br/p/clx8h2k9a0001abcd?t=...\n\nQualquer dúvida, é só responder aqui.",
    "numero": "5515999990000",
    "link": "https://wa.me/5515999990000?text=Ol%C3%A1%2C%20Maria!%20Aqui%20%C3%A9%20da%20Empresa%20Exemplo%20Energia%20Solar.%20O%20seu%20or%C3%A7amento%20de%20energia%20solar%20est%C3%A1%20pronto%3A%20sistema%20de%205%2C72%20kWp%2C%20entre%20R%24%2013.500%20e%20R%24%2015.100.%0AO%20valor%20final%20%C3%A9%20confirmado%20na%20visita%20t%C3%A9cnica.%20Veja%20a%20proposta%20completa%2C%20com%20a%20economia%20estimada%3A%20https%3A%2F%2Fapp.ionluz.com.br%2Fp%2Fclx8h2k9a0001abcd%3Ft%3D...%0A%0AQualquer%20d%C3%BAvida%2C%20%C3%A9%20s%C3%B3%20responder%20aqui."
  },
  "email": { "enviado": true },
  "origem": "meta-formulario",
  "campanha": {
    "utm_source": "meta",
    "utm_medium": "formulario",
    "utm_campaign": "kit-ionluz",
    "utm_content": "conta-de-luz",
    "capturadoEm": "2026-09-25T14:05:00.000Z"
  },
  "aviso": "Estimativa sujeita a visita técnica.",
  "requestId": "req_9f2c1a7b3d4e5f6a90"
}

gravado: o lead está na sua conta. A proposta aparece em Orçamentos automáticos, com a origem API, e você recebe o mesmo aviso de lead dos pedidos da página.
propostaUrl e pdfUrl: os links assinados, prontos para o cliente. pdfUrl vem null enquanto o cliente não vê o preço ("eu aprovo antes" ou só o pedido).
whatsapp: a mensagem pronta (mensagem), o número do lead (numero) e a conversa já com a mensagem escrita (link, wa.me). Abra o link e mande do seu WhatsApp.
email: se o link da proposta foi por e-mail ao lead e, se não foi, o motivo.
campanha: as etiquetas como foram gravadas na proposta e no cliente.

A mensagem do WhatsApp

Sai na voz da sua empresa, pelo modo como a sua conta publica o preço. Os cinco modos, com o lead do exemplo:

modo	Quando	A mensagem
`exato`	A conta mostra o valor.	Olá, Maria! Aqui é da Empresa Exemplo Energia Solar. O seu orçamento de energia solar está pronto: sistema de 5,72 kWp por R$ 14.297. Veja a proposta completa, com a economia estimada: https://app.ionluz.com.br/p/… O valor final a gente confirma na visita técnica. Qualquer dúvida, é só responder aqui.
`faixa`	A conta mostra uma faixa (o automático, enquanto a tabela é a referência de mercado).	Olá, Maria! Aqui é da Empresa Exemplo Energia Solar. O seu orçamento de energia solar está pronto: sistema de 5,72 kWp, entre R$ 13.500 e R$ 15.100. O valor final é confirmado na visita técnica. Veja a proposta completa, com a economia estimada: https://app.ionluz.com.br/p/… Qualquer dúvida, é só responder aqui.
`aprovacao`	"Eu aprovo antes": a proposta nasce pendente e o valor aparece no link depois do seu OK.	Olá, Maria! Aqui é da Empresa Exemplo Energia Solar. Recebemos o seu pedido de orçamento de energia solar. Estamos conferindo o valor e já te mandamos. A proposta fica neste link, e o valor aparece nele assim que a gente confirmar: https://app.ionluz.com.br/p/… Qualquer dúvida, é só responder aqui.
`contato`	Só o pedido: sem preço e sem link, como a página.	Olá, Maria! Aqui é da Empresa Exemplo Energia Solar. Recebemos o seu pedido de orçamento de energia solar, para um sistema de cerca de 5,72 kWp. Vamos te passar o valor por aqui. Qual é o melhor horário para a gente conversar?
`sem-orcamento`	Não deu para orçar sozinho. Quando faltou o valor da conta ou a ligação, a mensagem leva o link da sua página.	Olá, Maria! Aqui é da Empresa Exemplo Energia Solar. Recebemos o seu pedido de orçamento de energia solar e vamos te chamar por aqui. Se quiser ver na hora, mande a foto ou o valor da sua conta de luz por este link: https://app.ionluz.com.br/o/empresa-exemplo-energia-solar Qual é o melhor horário para a gente conversar?

Na prévia não há proposta: o lugar do link aparece como [link da proposta].

O e-mail ao lead

Com e-mail no lead, o link da proposta vai por e-mail em nome da sua empresa, pelo mesmo envio do botão Enviar por e-mail: só com a autorização ligada em Perfil e marca, aba Condições, bloco E-mail ao cliente, e só com o preço visível ao cliente. Até 30 por hora por conta; acima disso o lead é gravado igual e a resposta diz teto. A proposta enviada ganha o selo Enviada e o lembrete antes de vencer.

O lead que vira contato

O lead nunca se perde. Quando não dá para orçar sozinho, ele fica gravado como contato, em Contatos sem orçamento, e a resposta traz semOrcamento com o código que a cotação daria (status 200, porque o lead foi gravado). O lead sem o valor da conta, do exemplo:

{
  "ok": true,
  "gravado": true,
  "proposalId": null,
  "propostaUrl": null,
  "pdfUrl": null,
  "orcamento": null,
  "semOrcamento": {
    "motivo": "consumo",
    "message": "Informe consumoKwhMes (o consumo em kWh por mês, maior que zero) ou valorContaBrl (o valor da conta de luz de um mês, em reais)."
  },
  "whatsapp": {
    "modo": "sem-orcamento",
    "mensagem": "Olá, Maria! Aqui é da Empresa Exemplo Energia Solar. Recebemos o seu pedido de orçamento de energia solar e vamos te chamar por aqui.\nSe quiser ver na hora, mande a foto ou o valor da sua conta de luz por este link: https://app.ionluz.com.br/o/empresa-exemplo-energia-solar\n\nQual é o melhor horário para a gente conversar?",
    "numero": "5515999990000",
    "link": "https://wa.me/5515999990000?text=Ol%C3%A1%2C%20Maria!%20Aqui%20%C3%A9%20da%20Empresa%20Exemplo%20Energia%20Solar.%20Recebemos%20o%20seu%20pedido%20de%20or%C3%A7amento%20de%20energia%20solar%20e%20vamos%20te%20chamar%20por%20aqui.%0ASe%20quiser%20ver%20na%20hora%2C%20mande%20a%20foto%20ou%20o%20valor%20da%20sua%20conta%20de%20luz%20por%20este%20link%3A%20https%3A%2F%2Fapp.ionluz.com.br%2Fo%2Fempresa-exemplo-energia-solar%0A%0AQual%20%C3%A9%20o%20melhor%20hor%C3%A1rio%20para%20a%20gente%20conversar%3F"
  },
  "email": { "enviado": false, "motivo": "sem-orcamento" },
  "origem": "meta-formulario",
  "campanha": {
    "utm_source": "meta",
    "utm_medium": "formulario",
    "utm_campaign": "kit-ionluz",
    "utm_content": "conta-de-luz",
    "capturadoEm": "2026-09-25T14:05:00.000Z"
  },
  "aviso": "O lead foi gravado como contato, sem orçamento automático: ele aparece em Contatos sem orçamento.",
  "requestId": "req_9f2c1a7b3d4e5f6a90"
}

semOrcamento.motivo	O que aconteceu
`consumo`	sem o valor da conta nem o consumo
`consumo-fora-de-faixa`	consumo fora do plausível
`valor-conta`	valor da conta ilegível
`valor-conta-fora-de-faixa`	valor da conta fora do plausível
`valor-conta-na-taxa-minima`	conta na taxa mínima da distribuidora
`fase-invalida`	ligação não reconhecida
`faixa-nao-atendida`	faixa não coberta
`fora-da-area`	fora do raio de atendimento
`sem-preco-configurado`	sem preço para esse sistema

Quando faltou o valor da conta ou a ligação e a sua página está no ar (Sua página), a mensagem do WhatsApp leva o link dela: a pessoa manda a foto ou o valor da conta e vê o orçamento na hora.

O consentimento

Sem ele, nada é gravado (LGPD). Mande o texto que a pessoa aceitou (o aviso com a caixa de consentimento do formulário, de 10 a 2000 caracteres), a data em que ela aceitou e a fonte, onde ela aceitou. A data aceita ISO 8601 (o formulário do anúncio manda com +0000), data e hora sem fuso (vale o horário de Brasília), dd/mm/aaaa hh:mm e o número de segundos desde 1970, entre 2015 e agora, com 10 minutos de folga para o relógio. A proposta guarda os três, e a data dela vira a data do consentimento. Faltou alguma coisa: 400 consentimento-invalido, com campos dizendo o quê.

Idempotência

Mande o id do lead do formulário em Idempotency-Key. A mesma chave com o mesmo lead, em até 30 dias, devolve o mesmo orçamento (com idempotent: true), sem gravar outro e sem mandar outro e-mail: a integração repete o envio horas depois, e a chave fica guardada no banco, não só na memória. Conta como o mesmo lead: nome, telefone, email, cidade, uf, fases, valorContaBrl, consumoKwhMes, tarifa e telhado e a origem. O consentimento e a campanha ficam de fora, porque a integração às vezes recalcula a data ou as etiquetas no reenvio. Outro lead com a mesma chave: 422 idempotencia. A chave crua não vai para o banco, só o hash dela.

Limites

60 chamadas por minuto por conta, e o mesmo freio por endereço de origem da cotação (300 por minuto).
Chave de teste: 50 chamadas por dia na conta, somadas com a cotação e o MCP.
E-mail ao lead: 30 por hora por conta.
Na tela API e cobertura, o uso da API mostra a entrada de leads numa linha própria.

Erros

No envelope de sempre (Erros). Os desta rota: contato-obrigatorio (sem telefone e sem e-mail), consentimento-invalido e origem-invalida (com parametro e aceito), além de json, payload-grande, chave-invalida, plano-sem-api, idempotencia, em-processamento, rate, teto-teste, teto-leads e interno. GET responde 405 metodo-nao-permitido com a dica do formato.

API v1 · ionluz, propostas solares honestas. Dúvidas? Cite o requestId ao escrever para suporte@ionluz.com.br.