# Crédito Pessoal – Integração Crefaz

> Objetivo: habilitar o produto **Crédito Pessoal › Crédito Crefaz** com fluxo 100% integrado à API do parceiro, mantendo fallback manual sempre disponível.

## 1. Visão Geral

- **Modos**  
  - *Integrado*: usa API Crefaz para consulta, cálculo, seleção de oferta, formalização e acompanhamento (webhook).  
  - *Manual*: mesmo formulário e estágios, porém sem chamadas externas; operador lança dados internamente e conclui offline.  
  - Operador escolhe o modo ao selecionar o subproduto; pode alternar (ex.: iniciar manual, depois sincronizar quando API retornar).

- **Ambientes & Configurações**  
  - Chaves `crefaz.api_key`, `crefaz.login`, `crefaz.senha`, `crefaz.base_url`, `crefaz.webhook_url`.  
  - Painel *Configurações › Integrações* com toggle “Ativar Integração Crefaz” e campos para credenciais, ambiente (stag/prod) e URL de notificação.  
  - Ao ativar: libera item de menu “Crefaz”, funil dedicado e botões de consulta/atualização dentro dos leads elegíveis.

## 2. Fluxo Operacional

| Etapa | Ação principal | Endpoint/API | Observações |
|-------|----------------|--------------|-------------|
|1. Cadastro inicial|Salvar lead com dados básicos (nome, CPF, telefone, ocupação, cidade IBGE, consentimento, modo manual/integrado) | `POST /Proposta` quando modo integrado | Campos não obrigatórios ainda; `urlNotificacaoParceiro` apontando para nosso webhook. |
|2. Consultar disponibilidade|Verificar produtos na região | `GET /Proposta/produtos-regiao/:codCidadeIBGE` | Retorno com flags `energia`, `boleto`, etc. Guarda no lead. |
|3. Consultar propostas existentes|Botão “Consultar Crefaz” roda: login → `POST /Proposta/proposta-em-andamento` → `GET /Proposta/:id` | | Atualiza lead/status com dados trazidos da Crefaz. |
|4. Listar ofertas|Mostrar produtos, convênios, tabelas, renda presumida | `GET /Proposta/oferta-produto/:id` | Necessário para cálculos seguintes. |
|5. Calcular vencimento|Com dados do produto selecionado | `POST /Proposta/calculo-vencimento` | Para Energia, exige `convenioId`, rota/leitura. |
|6. Consultar limite|Trazer `valorLimiteSolicitado`, `valorLimiteParcela` | `POST /Proposta/consulta-valor-limite/:id` | Enviar `recalculo = null`. |
|7. Simular oferta|Obter combinações prazo/valor | `POST /Proposta/simulacao-valor/:id` | `tipoCalculo` define se valor é total ou parcela. |
|8. Selecionar oferta|Persistir plano, prestação, renda, adicionais | `PUT /Proposta/oferta-produto/:id` | Energia exige `adicionais` com `convenioDadosId`. |
|9. Formalizar proposta|Enviar dados completos do cliente/contatos/endereço/banco/profissional/unidade/operacao | `PUT /Proposta/:id` | Campos obrigatórios condicionais (ex.: `nomeConjuge` só para casados). |
|10. Anexos|Listar tipos necessários e subir arquivos | `POST /Proposta/tipo-anexos` + `PUT /Proposta/:id/imagem` | Upload único por requisição (base64). |
|11. Consulta & status|Revisar dados e acompanhar status | `GET /Proposta/:id` | UI mostra timeline + botão “Atualizar status”. |
|12. Webhook|Receber atualizações proativas | payload `{ propostaId, situacaoDescricao, observacoes, motivos[] }` | Handler move o lead no funil e grava histórico. |

## 3. Interface do Operador

### 3.1 Formulário em Etapas
- **Etapa 1 – Dados básicos:** CPF, nome, telefone, ocupação, cidade, consentimento LGPD, toggle “Utilizar integração Crefaz” e botão “Consultar disponibilidade”. Somente esses campos são obrigatórios inicialmente.
- **Etapa 2 – Pré-oferta:** renda (manual ou importada), tipo renda, produto, convênio, dados específicos (instalação/UC). Após preenchidos, habilita botões para *Calcular vencimento*, *Consultar limite* e *Simular oferta*.
- **Etapa 3 – Seleção de oferta:** operador escolhe prazo/valor retornados; campo `tipoCalculo`; pode reenviar simulações. Ao confirmar, dispara `PUT /Proposta/oferta-produto`.
- **Etapa 4 – Formalização:** blocos de identificação (RG completo), endereço, contatos, bancário, profissional, referências, anexos. Cada bloco libera suas obrigatoriedades apenas quando a proposta estiver em fase de envio.

### 3.2 Controles Acessórios
- Botão **“Consultar Crefaz”** no lead: roda sequência de sincronização e popula campos automaticamente. Disponível sempre que o lead tiver subproduto Crefaz.
- Botão **“Atualizar status”**: reexecuta `GET /Proposta/:id` e sincroniza timeline + funil.
- **Menu “Crefaz”**: abre painel com filtros, estatísticas e link rápido para “Abrir portal Crefaz” (URL externa configurável).
- **Funil dinâmico**: colunas baseadas em `situacaoDescricao` (Pré-cadastro, Seleção de Oferta, Documentação, Aguardando Análise, Aprovado, Pendente, Negado). Cada card mostra lead, propostaId, status local/externo, últimas pendências; clique leva à tela do lead com ações relevantes.

## 4. Modelagem & Persistência

- **leads**: adicionar flags/colunas `crefaz_enabled`, `crefaz_proposta_id`, `crefaz_status`, `crefaz_renda_presumida`, `crefaz_webhook_url`, `crefaz_mode` (manual/integrado), timestamps de sincronização.
- **crefaz_proposals** (nova tabela): histórico por lead/proposta (status, payloads, limite, oferta selecionada, dados adicionais). Útil para auditoria.
- **crefaz_sync_logs**: registro de todas as chamadas para troubleshooting (endpoint, request, response, código HTTP e operador).
- **crefaz_documents**: metadados dos uploads (documentoId, tipo, hash, enviado_em).
- **webhooks**: reuso de tabela existente (se houver) ou criar `crefaz_webhook_events` para armazenar payloads recebidos.

## 5. Serviços & Componentes

- `CrefazAuthService`: faz login e gerencia cache do token (expira em 3h).  
- `CrefazClient`: wrapper HTTP genérico (`get`, `post`, `put`) aplicando headers `Accept/Content-Type`, Bearer token e tratamento de erros (401, 403, 422, 429).  
- `CrefazProposalService`: orquestra endpoints específicos (disponibilidade, ofertas, limites, simulações, seleção, cadastro, consulta).  
- `CrefazSyncService`: usado pelos botões de UI; controla fallback (marca fluxo como manual caso API falhe repetidamente).  
- `CrefazWebhookHandler`: endpoint que recebe payloads, valida assinatura (futuro), atualiza lead/proposta e dispara notificações internas.

## 6. UX – Botões & Ações

- **Consultar disponibilidade**: chama `/Proposta/produtos-regiao`.  
- **Listar ofertas**: chama `/Proposta/oferta-produto`; exibe convênios e tabelas; permite escolher.  
- **Calcular vencimento**, **Consultar limite**, **Simular oferta**, **Selecionar oferta**: botões agrupados no passo “Oferta” disparando os serviços correspondentes.  
- **Cadastrar/Atualizar proposta**: salva blocos; quando modo integrado, dispara `PUT /Proposta/:id`.  
- **Upload de arquivos**: componente que escolhe `documentoId` com base nos `tipo-anexos` e envia base64 com preview.  
- **Atualizar status**: sempre visível; executa `GET /Proposta/:id` e mostra timeline atualizada.  
- **Abrir portal Crefaz**: atalho no menu e nos cards do funil.

## 7. Falhas & Fallback

- Circuit breaker para chamadas Crefaz: ao ultrapassar X falhas consecutivas, modo integrado entra em “degradação” e os botões exibem aviso. Operador pode continuar manualmente; quando sistema detectar sucesso novamente, retoma o modo integrado.  
- Logs com detalhes do erro (`errors` do payload, status HTTP, timestamp).  
- Notificações internas quando webhook retorna status crítico (ex.: negativa).

## 8. Próximos Passos Técnicos

1. Criar migrations/tabelas (`crefaz_proposals`, `crefaz_documents`, `crefaz_sync_logs`, colunas extras em `leads`).  
2. Implementar serviços (`CrefazAuthService`, `CrefazClient`, `CrefazProposalService`, `CrefazWebhookHandler`).  
3. Ajustar formulários de lead e proposta para o modo Crefaz (etapas, botões, validações progressivas).  
4. Construir painel/funil + item de menu e link externo.  
5. Adicionar testes de integração/mocks e documentação operacional para a equipe.  
6. Liberar configuração no painel para inserir API key/login e ativar integração.

Com este documento como guia, conseguimos iniciar a implementação sem depender de novas informações da Crefaz. A ativação efetiva ocorre assim que o credenciamento entregar `apiKey`, login e senha.

### Webhook no CRM

- Endpoint exposto: `POST /webhooks/crefaz/status`.
- Header obrigatório `X-Crefaz-Signature` contendo `HMAC-SHA256(body, CREFAZ_WEBHOOK_SECRET)`. Sem o segredo configurado o CRM rejeita o payload.
- Payload esperado segue o contrato oficial (campos como `propostaId`, `situacaoDescricao`, `observacoes`, `motivos`).
- Tratativa atual: salva o evento em `crefaz_webhook_events`, atualiza `crefaz_status`, `crefaz_status_description`, `crefaz_proposta_id` e `crefaz_last_status_at` do lead e garante auditoria do JSON bruto.
- Futuras evoluções: validar timestamps/nonce enviados pela Crefaz e disparar notificações internas ou automações específicas conforme o status recebido.