# Finanto INSS – Fluxo de Autocontratação (Portabilidade + Refinanciamento)

## Visão geral
- Objetivo: guiar a jornada automática desde a consulta IN100 até o contrato assinado, utilizando os endpoints REST da Finanto.
- Abrangência: operações do tipo **portabilidade (2)** e **portabilidade + refinanciamento (4)**, que dependem de contrato ativo em outro banco.
- Pré-requisitos: integração Finanto configurada (`base_url`, `apikey`), CPF + número de benefício com consentimento do cliente para consulta.

### Execução interna (operador x cron)
- **Operador**: o backoffice dispara cada etapa pela tela do caso (`finanto_inss/cases/show.php`). Sempre registrar `*_by` e `*_at` para saber quem executou.
- **Cron / fila**: os mesmos endpoints podem ser acionados pelos jobs `finanto.inss.in100.refresh`, `finanto.inss.auth_term.sync`, `finanto.inss.pipeline.sync` e pelo comando `php automation.php finanto:loans:sync`. Todos rodam via `php automation.php run`.
- **Modelo híbrido**: consentimentos (consulta IN100 e termo) começam manualmente para garantir compliance e, se ficarem pendentes, o cron assume o polling até `status = signed/success`.

## Etapa 1 – Consulta IN100 (descoberta de contratos)
1. **Disparar finder**
   - `POST {{base_url}}/v3/query-inss-balances/finder`
   - Body JSON: `{"identity":"<CPF>","benefitNumber":"<NB>","lastDays":0,"attempts":3}`
2. **Aguardar processamento (opcional, mas recomendado)**
   - `POST {{base_url}}/v3/query-inss-balances/finder/await`
   - Mesmo payload do passo anterior.
3. **Buscar resultado consolidado**
   - `GET {{base_url}}/v3/query-inss-balances/{id}`
   - Utiliza o `id` retornado no finder/await.

**Resultado esperado**
- `status.key` = `success` → lista de contratos (`contracts[]`) com saldo, parcelas restantes, margem.
- `items[]` → ofertas sugeridas (regra, prazo, parcela, troco) quando há contrato elegível.
- Armazenar `query_id`, contratos e ofertas para reaproveitar na simulação.
- Se `status.key` = `awaiting`, reagendar nova leitura; se `error`, exibir mensagem e abortar.

## Etapa 2 – Seleção da oferta
- Escolher um item dentro de `items[]` (ou montar a partir dos dados retornados).
- Guardar: `ruleId`, `loanValue`, `installmentValue`, `term`, `netValue`, além do contrato de origem (`lenderCode`, `contractNumber`, `dueBalanceValue`, `installmentsRemaining`, `installmentValue`).
- Os campos selecionados abastecem o payload da simulação oficial.

## Etapa 3 – Criar a simulação
- `POST {{base_url}}/v3/loan-inss-simulations`
- Headers: `Accept: application/json`, `Content-Type: application/json`, `apikey: ...`
- Body JSON (resumo):
  - `borrower` → dados do tomador (nome, CPF, benefício, endereço, documento, contato).
  - `items[0]` → usar a oferta escolhida (ruleId, term, rate, installmentValue, loanValue, originContract...).
  - `creditBankAccount` → conta para crédito do troco.
  - `note`, `brokerId`, `validate: true` (opcional).
- **Resposta**: `simulation_id`, `status`, `step`, `items`, `authTerm` (quando já disponível).
- Persistir simulação e payloads em `finanto_inss_cases` / `finanto_inss_simulations`.

## Etapa 4 – Sincronizar / exibir termo de autorização
- `GET {{base_url}}/v3/loan-inss-simulations/{simulation_id}` → confirmar status.
- `GET {{base_url}}/v3/loan-inss-simulations/{simulation_id}/auth-term`
  - Retorno traz `signature.url`, `status` (`awaiting`, `signed`), `expiresAt`.
  - Disponibilizar link para cliente (landing, SMS, e-mail, push).
  - Repetir GET até `status.key = signed`. Registrar timestamps em caso/lead.

## Etapa 5 – Criar contrato (digitação)
- Pré-condição: termo assinado ou `status.key = signed`.
- `POST {{base_url}}/v3/loan-inss-simulations/{simulation_id}/actions`
  - Body: `{"command": "create_loans"}`
- Resposta contém:
  - `loan.id` (identificador do contrato na Finanto).
  - Snapshot da assinatura do contrato (`signature`), quando disponível.
- Se snapshot vier incompleto, chamar: `GET {{base_url}}/v3/loans/{loan_id}`.

## Etapa 6 – Coletar assinatura do contrato
- Monitorar `signature.status` via:
  - `GET {{base_url}}/v3/loans/{loan_id}` (loop até `signed` / `released`).
  - Se necessário, reaproveitar `auth-term` para feedback do cliente.
- Atualizar atributos locais: `signature_status`, `signature_link`, `signature_provider`, `status_history`.

## Etapa 7 – Atualizar status interno
- Ao longo do fluxo, atualizar `FinantoInssCase` com:
  - `query_id`, `simulation_id`, payloads brutos (consulta, simulação, contrato).
  - `stage`: `offers_ready` → `authorization_pending` → `awaiting_signature` → `signed` / `concluded`.
- Sincronizar snapshots no funil/pipeline e registrar notas para suporte.
- Opcional: agendar job para reconsultar `loan` até status final (liberado / pago).

## Observações e boas práticas
- Garantir consentimento do cliente antes de `query-inss-balances` (compliance LGPD).
- Normalizar `ruleId` com o catálogo Finanto (`FinantoRuleCatalog`) quando necessário.
- Em caso de `status.key = error` na etapa 1, guardar payload e mensagem para auditoria e reprocessar manualmente.
- Se `createSimulation` retornar erro, rever se `loanValue`, `installmentValue`, `term` estão coerentes com a oferta retornada pelo IN100.
- Guardar logs (`finanto_debug.log`) para cada transição, facilitando suporte com o parceiro.