API & MCP

Boas práticas

A lista curta do que separa uma integração que aguenta produção de uma que quebra na primeira semana.

• Comece pela chave de teste: integre e valide com a ilz_test_, e troque pela viva só quando o fluxo estiver de pé.
• Segurança: chave só no servidor. Rotacione ao suspeitar de vazamento (revogar + gerar nova é instantâneo).
• Simule antes de gravar: preview: true em calculadoras e testes; grave só quando virar lead de verdade.
• Trate os assumptions: mostre ao usuário quando a tarifa/potência foi estimada, para transparência.
• Consentimento primeiro: ao gravar, colete o aceite do titular e envie consent: true, é obrigatório e fica registrado como prova (LGPD).
• Retries com idempotência: em POSTs que gravam, sempre envie Idempotency-Key (no MCP, o argumento idempotencyKey).
• Respeite o rate-limit: use os headers X-RateLimit-* e recue no 429.
• Cobertura primeiro: consulte /v1/coverage (ou check_coverage) para não cotar faixas que você não atende.
• Webhook em vez de varredura: receba lead.criado e proposta.aberta, e guarde GET /v1/proposals para reconciliar de tempos em tempos.
• Valide a assinatura do webhook sobre o corpo bruto e recuse timestamp velho, antes de confiar no que chegou.
• Estimativas: todo valor é sujeito a visita técnica, deixe isso visível ao cliente final.