Boas práticas e suporte

10. Boas práticas de integração

1. Cadastre o responsável (6.9) uma vez por CNPJ, não por lead. Guarde o id retornado e
   reuse em todos os leads dessa imobiliária — chamar de novo com a mesma pessoa é seguro
   (idempotente), mas não recadastra.
2. Cache do token. Reutilize o access token até perto do vencimento; não solicite um novo
   por requisição.
3. Backoff exponencial em 5xx. Todos os *_INTEGRATION_FAILURE são transitórios e a
   operação pode ser repetida. Comece em ~1s e dobre, com jitter, até um teto de tentativas.
4. Repetir o fechamento do contrato (6.11) com o mesmo contractResponsibleId é seguro.
   Vira um no-op. Repetir com um contractResponsibleId ou contractTerms diferente hoje
   não dá erro (ver gap conhecido em 6.11) — confira a resposta antes de assumir que o
   valor novo foi gravado.
5. Não repita 4xx com o mesmo payload. 400, 403, 409 e 422 são determinísticos.
   Corrija o payload ou o estado antes.
6. Ramifique por code, nunca por message. As mensagens mudam sem aviso; os códigos não.
7. Prefira webhooks a polling. Use os endpoints de status como fallback ou reconciliação,
   não como mecanismo principal. Para assinatura não existe alternativa: só há webhook.
8. Deduplique eventos por id. Entrega é at-least-once.
9. Teste com POST /webhooks/{id}/ping antes de depender do webhook em produção, e
   verifique success no corpo — não o status HTTP.
10. Monitore consecutiveFailures e status dos seus webhooks. Cinco falhas consecutivas
    suspendem a entrega; você para de receber eventos sem nenhum erro aparecer no seu lado.
11. Persista o idApplication. É a chave de todo o fluxo pós-lead e de correlação com o
    suporte Creditas.
12. Nunca logue segredos. auth.value, clientSecret e o access token não devem aparecer
    em log do seu lado — a Creditas já os mascara do dela.
13. Use GET /leads (6.3) para reconciliação, não como fonte primária de estado. É
    paginação por offset — não use como substituto de webhooks para saber quando algo mudou;
    use para conferir periodicamente o que foi produzido, ou para reconstruir estado após uma
    lacuna de eventos.

11. Suporte

• Ao abrir chamado, informe: idApplication (ou preProfileAnalysisId), horário UTC da
  chamada, endpoint, code recebido e o message completo.
• Para problemas de entrega de webhook, informe também o X-Creditas-Delivery-Id ou o id
  da entrega em GET /webhooks/{id}/deliveries.