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 quando o fluxo estiver de pé.
• Chave só no servidor. A de teste também: ela gasta a cota diária da conta. Rotacione ao suspeitar de vazamento (gerar outra derruba a anterior na hora).
• Simule antes de gravar: preview: true em calculadoras e testes; grave quando virar lead de verdade.
• Mande a cidade desde a simulação: ela muda as horas de sol, o raio de atendimento e o deslocamento.
• Mostre o que foi estimado: os assumptions, quanto do consumo o sistema cobre (cobrePct) e, quando o pedido foi pelo valor da conta, que o consumo é estimado (consumoEstimado).
• Mostre o preço como a conta publica: se a resposta trouxer preco.publicado, use o rotulo ou o texto; valorFinal pode ser o centro de uma faixa ou vir null.
• Avisos: mostre ao cliente só os de para: "cliente".
• 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 POST que grava, envie Idempotency-Key (no MCP, o argumento idempotencyKey).
• Respeite o limite: use os cabeçalhos X-RateLimit-* e recue no 429.
• Pedido de contato: faixa-nao-atendida e fora-da-area são escolhas da conta ("não atendo" e raio de atendimento). Responda com o pedido de contato do cliente.
• Webhook em vez de varredura: receba lead.criado, proposta.aberta e proposta.aceita, e use GET /v1/proposals para reconciliar de tempos em tempos.
• Valide a assinatura do webhook sobre o corpo bruto, recuse timestamp velho e confira o tamanho antes da comparação.
• Estimativas: todo valor é sujeito a visita técnica; deixe isso visível ao cliente final.