API & MCP

Idempotência

Para requisições que gravam (não-preview), envie um cabeçalho Idempotency-Key único por operação (ex.: o id do pedido no seu sistema). Se a mesma chave chegar de novo com o mesmo corpo, típico de retry por timeout de rede, devolvemos a mesma proposta (com "idempotent": true), sem duplicar o lead.

curl -X POST https://app.ionluz.com.br/api/v1/quote \
  -H "Authorization: Bearer ilz_sua_chave" \
  -H "Idempotency-Key: pedido-8421" \
  -H "Content-Type: application/json" \
  -d '{ "consumoKwhMes": 620, "uf": "SP", "cidade": "Sorocaba", "fases": "bi", "nome": "Cliente Exemplo", "email": "cliente@exemplo.com.br", "telefone": "(15) 99999-0000", "consent": true }'
# Reenviar com a MESMA Idempotency-Key e o MESMO corpo devolve a MESMA proposta
# (campo "idempotent": true), sem criar um lead duplicado.

Se a mesma Idempotency-Key for reusada com um corpo diferente, respondemos 422 idempotencia. Se duas requisições com a mesma chave chegarem ao mesmo tempo, a segunda recebe 409 em-processamento (retentável), e nunca se cria proposta duplicada. A janela de deduplicação é de 15 minutos.

O que conta como "o mesmo corpo". Os campos que mudam a cotação ou o lead: consumoKwhMes, valorContaBrl, uf, fases, kwp, tarifa, nome, email, telefone, cidade e telhado. preview e consent ficam de fora: repetir só para reafirmar o consentimento casa com o original. Nas contas com o motor novo, opcao também conta: a mesma chave com outra opção responde 422 idempotencia. Com a chave de teste nada é gravado, então não há deduplicação.