Sua primeira cotação via API (chave de teste e chave viva)

Leitura de 6 min · verificado em 25/09/2026

Você vai conseguir: fazer uma cotação por código e saber onde está a documentação inteira.

1. 1 Gere a chave de teste

   Em API e cobertura, seção Comece em 10 minutos: chave de teste, clique em Gerar chave de teste. Ela começa com ilz_test_, roda em qualquer plano, calcula com a sua tabela de preço e responde em modo simulação: nada é gravado, e são 50 chamadas por dia. Ela aparece uma vez só: guarde num cofre de segredos.

2. 2 Faça a primeira cotação

   Uma chamada, a cotação completa de volta:

   curl -X POST https://app.ionluz.com.br/api/v1/quote \
     -H "Authorization: Bearer SUA_CHAVE" \
     -H "Content-Type: application/json" \
     -d '{"consumoKwhMes": 550, "uf": "SP", "fases": "bi", "cidade": "Campinas", "preview": true}'

   Copiar

   A resposta traz orcamento (potência, valor, payback, economia e quanto do consumo o sistema cobre) e assumptions. Com a chave de teste vem "sandbox": true e o header X-Ionluz-Sandbox: 1. Sem fases, vale a ligação monofásica.

3. 3 Grave a proposta com a chave viva

   Com o Total + API ativo e as condições comerciais confirmadas, Gerar chave, na seção Chave de API. Ela aparece uma vez; Regenerar chave derruba a anterior na hora e Revogar corta o acesso. Sem preview e com "consent": true do titular, a proposta é gravada e a resposta traz proposalId, propostaUrl e pdfUrl. Ela aparece em Propostas com a origem API.

4. 4 Cobertura e erros

   A cotação funciona desde a primeira chamada: faixa sem kit seu usa o catálogo padrão ionluz (assumptions.kitCatalogoPadrao: true). Faixa marcada "não atendo" responde 422 faixa-nao-atendida; cidade acima do seu raio de atendimento, com "pedir o contato", responde 422 fora-da-area; quando você cobra deslocamento, ele vem em orcamento.deslocamento. GET /api/v1/coverage diz o que você atende, e a cobertura se ajusta em API e cobertura.

5. 5 Boas práticas que a API já cobra

   Idempotência pelo header Idempotency-Key (a mesma chave repetida em 15 minutos não duplica), erros com código e mensagem, e limites com aviso nos headers X-RateLimit-* (60 cotações por minuto por conta). A referência completa, com a calculadora para embutir no seu site, está em docs/api.

   

6. 6 Webhook de saída

   Na mesma tela, seção Webhook de saída, cadastre uma URL https, em qualquer plano, para receber lead.criado, proposta.aberta e proposta.aceita. Cada entrega é assinada com HMAC-SHA256 no header X-Ionluz-Signature; responda 2xx rápido e processe depois. Enviar um ping de teste confere a sua ponta.

Nunca coloque a chave no navegador nem no site público. O seu servidor chama o ionluz; o site do cliente chama o seu servidor.