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": 650, "nome": "Ana", "email": "ana@ex.com", "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), garantindo que nunca se crie proposta duplicada. A janela de deduplicação é de 15 minutos.

Honestidade importante: a deduplicação vive em memória no servidor e zera em restart/deploy. Um retry que atravesse um deploy pode criar uma segunda proposta. Para operações críticas, confira pelo proposalId devolvido antes de reenviar. No MCP, o mesmo mecanismo existe via argumento idempotencyKey de quote_solar (chaves independentes das do REST).

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