# Daycoval - Fluxo API Refin (Resumo Operacional)

Fonte: `API Daycoval fluxo refin/FluxoCompletoInclusaoPropostaAPIRefinV2..png`.

## Autenticacao

- Metodo: `apiKey` via header.
- Header: `apikey: <token>`.
- Observacao: alem do `apikey`, alguns endpoints exigem header funcional `Login-Usuario` (ver detalhes por endpoint).

## Endpoints detalhados (prints)

### GET /refin/produtos-disponiveis/{cpf}

Metodo responsavel por listar os produtos disponiveis para o CPF.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Path params:
- `cpf` (string): CPF consultado.

Respostas:
- `200` Success.
  - Observacao: o Swagger indica que o `Accept` controla o media type da resposta. O corpo nao foi exibido no print.
- `404` Nenhuma matricula cadastrada para o CPF consultado.
  - Exemplo:
  ```json
  {
    "Mensagem": "Cliente nao localizado."
  }
  ```

### GET /refin/empregadores

Metodo responsavel por listar os empregadores disponiveis para a promotora.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Respostas:
- `200` Success.
  - Media type: `application/json` (controlado por `Accept`).
  - Exemplo:
  ```json
  [
    {
      "Cpf": "string",
      "DataNascimento": "2026-02-12T13:56:46.807Z",
      "Matricula": "string",
      "CodEmpregador": 0
    }
  ]
  ```

### GET /refin/orgaos-consignado/{cpf}/{codEmpregadorExterno}

Metodo para listar orgaos consignados.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Path params:
- `cpf` (string): CPF do cliente.
- `codEmpregadorExterno` (string): codigo do empregador do sistema Funcao.

Respostas:
- `200` Success.
  - Media type: `application/json` (controlado por `Accept`).
  - Exemplo:
  ```json
  [
    {
      "CodOrgao": "string",
      "DscOrgao": "string",
      "CodOrgaoExterno": "string"
    }
  ]
  ```

### GET /refin/prazos-consignado/{codEmpregadorExterno}/refin

Metodo responsavel por listar a quantidade de parcelas disponiveis.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Path params:
- `codEmpregadorExterno` (string): codigo do empregador do sistema Funcao.

Respostas:
- `200` Success.
  - Media type: controlado por `Accept` (nao ha exemplo no print).

### GET /refin/parametros-averbacao/refin/{codEmpregador}

Metodo responsavel por informar se o empregador consultado possui averbacao.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Path params:
- `codEmpregador` (integer/int32): codigo do empregador.

Respostas:
- `200` O Empregador consultado possui Averbacao.
  - Media type: `application/json` (controlado por `Accept`).
  - Exemplo:
  ```json
  [
    {
      "DscParametroAverbacao": "string",
      "TipoParametroAverbacao": "string",
      "ValorParametroAverbacaoDefault": "string",
      "IndExibeTela": true,
      "CodSubProduto": 0,
      "EmpregadoresExterno": "string"
    }
  ]
  ```
- `404` O Empregador consultado nao possui Averbacao.
  - Exemplo:
  ```json
  {
    "Mensagem": "Parametros de Averbacao nao localizados, atraves do Codigo empregador [CodEmpregador] e Codigo sub produto [SubProduto]"
  }
  ```

### GET /refin/saldos-refinanciamentos/{codEmpregadorExterno}/{cpf}/{matricula}

Metodo para calcular saldos de refinanciamento.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Path params:
- `codEmpregadorExterno` (string): codigo do empregador do sistema Funcao.
- `cpf` (string): CPF do cliente.
- `matricula` (string): matricula do cliente.

Respostas:
- `200` Success.
  - Media type: controlado por `Accept` (nao ha exemplo no print).

### POST /refin/simula-proposta-consignado/refin

Metodo para simular uma proposta consignado.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Request body (`application/json`):
```json
{
  "Cpf": "string",
  "Matricula": "string",
  "DataNascimento": "2026-02-12T14:16:41.154Z",
  "Financiamento": {
    "TipoOperacao": 1,
    "CodConvenio": "string",
    "VlrFinanciado": 0,
    "VlrParcela": 0,
    "QtdParcela": 0
  },
  "Origem": {
    "CodEmpregadorExterno": "string",
    "CodOrgaoExterno": "string"
  },
  "ContratoParaRefinanciamento": [
    "string"
  ]
}
```

Respostas:
- `200` Success.
  - Media type: controlado por `Accept` (nao ha exemplo no print).

### POST /refin/inclui-simulacoes/refin

Metodo responsavel por incluir uma nova simulacao.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Request body (`application/json`):
```json
[
  {
    "CodEmpregador": 0,
    "CodDadosBeneficio": 0,
    "Matricula": "string",
    "Cpf": "string",
    "CodLojaPromotora": "string",
    "VlrRendaLiquida": 0,
    "PropostaConsignadoOferta": [
      {
        "CodConvenio": "string",
        "QtdParcela": 0,
        "VlrCliente": 0,
        "VlrParcela": 0,
        "TxCet": 0,
        "TxCetMes": 0,
        "CodOrgao": 0,
        "CodOrgaoExterno": "string",
        "CodEmpregadorExterno": "string",
        "ContratoParaRefinanciamento": [
          {
            "NumeroContrato": "string",
            "QtdeParcelasAbertas": 0,
            "VlrParcela": 0,
            "SaldoNaData": 0
          }
        ],
        "Dta1Vcto": "2026-02-12T14:27:24.395Z",
        "DtaBase": "2026-02-12T14:27:24.395Z",
        "DtaUltVcto": "2026-02-12T14:27:24.395Z",
        "TxAp": 0,
        "TxCliente": 0,
        "TxClienteAno": 0,
        "TxNominal": 0,
        "VlrBruto": 0,
        "VlrFinanciado": 0,
        "VlrIoc": 0,
        "VlrLiquido": 0,
        "VlrPrincipal": 0,
        "VlrTroco": 0,
        "IndSimulacaoPorParcela": true,
        "MatriculaInstituidor": "string",
        "CodVerba": "string",
        "CodServico": "string",
        "SenhaAverbacao": "string",
        "CodPropostaClienteDadosProfissionais": 0
      }
    ]
  }
]
```

Respostas:
- `200` Success.
  - Media type: `application/json` (controlado por `Accept`).
  - Exemplo:
  ```json
  {
    "CodProposta": "string"
  }
  ```

### GET /refin/proposta/{codProposta}

Metodo para detalhar as informacoes da proposta.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Path params:
- `codProposta` (integer/int32): codigo da proposta.

Respostas:
- `200` Success.
  - Media type: controlado por `Accept` (nao ha exemplo no print).

### PUT /refin/cliente/pagamento/{codProposta}

Metodo para alterar os dados cadastrais do cliente.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Path params:
- `codProposta` (integer/int32): codigo da proposta.

Request body (`application/json`):
```json
{
  "PropostaCliente": {
    "CodProposta": 0,
    "CodCliente": 0,
    "NmeCliente": "string",
    "Cpf": "string",
    "DtaNascimento": "2026-02-12T14:27:24.408Z",
    "Email": "string",
    "NmeMae": "string",
    "NmePai": "string",
    "SglSexo": "string",
    "CodEstadoCivil": 0,
    "Documento": "string",
    "DocumentoOrgaoEmissor": "string",
    "DocumentoDataEmissao": "2026-02-12T14:27:24.408Z",
    "DocumentoUfEmissor": "string",
    "CodTipoDocumentoIdentificacao": 0,
    "IndPpe": true,
    "DscPpeMotivo": "string",
    "CodNacionalidade": 0,
    "DscNaturalidade": "string",
    "Enderecos": [
      {
        "CodTipoEndereco": 1,
        "CodTipoLogradouro": 1,
        "DscTipoLogradouro": "string",
        "Cep": "string",
        "DscLogradouro": "string",
        "NroLogradouro": "string",
        "Complemento": "string",
        "Cidade": "string",
        "Bairro": "string",
        "SglUnidadeFederativa": "string",
        "DscUnidadeFederativa": "string"
      }
    ],
    "Telefones": [
      {
        "CodTipoTelefone": 1,
        "NroDddTelefone": "string",
        "NroTelefone": "string"
      }
    ],
    "RedeSociais": [
      {
        "CodRedeSocial": 1,
        "DscLink": "string"
      }
    ]
  }
}
```

Respostas:
- `200` Success.
  - Media type: controlado por `Accept` (nao ha exemplo no print).

### PUT /refin/pagamento/resumo/{codProposta}

Metodo para alterar os dados complementares do cliente.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Path params:
- `codProposta` (integer/int32): codigo da proposta.

Request body (`application/json`):
```json
{
  "DadosProfissionais": [
    {
      "CodPropostaClienteDadosProfissionais": 0,
      "CodProposta": 0,
      "CodEmpregador": 0,
      "DscEmpregador": "string",
      "Matricula": "string",
      "VlrRendaBruta": 0,
      "CodAplicacao": 0,
      "CodTipoBeneficio": 0,
      "IndRecebeCartaoMagnetico": true,
      "CodProduto": 0,
      "DadosBancariosBeneficio": {
        "CodProposta": 0,
        "CodBanco": "string",
        "CodTipoContaBancaria": 0,
        "NroAgencia": "string",
        "DigAgencia": "string",
        "NroConta": "string",
        "DigConta": "string",
        "CodAplicacao": 0,
        "CodPropostaClienteDadosProfissionais": 0
      }
    }
  ],
  "EnderecoEnvioCartaoConsignado": {
    "CodTipoEndereco": 1,
    "CodTipoLogradouro": 1,
    "DscTipoLogradouro": "string",
    "Cep": "string",
    "DscLogradouro": "string",
    "NroLogradouro": "string",
    "Complemento": "string",
    "Cidade": "string",
    "Bairro": "string",
    "SglUnidadeFederativa": "string",
    "DscUnidadeFederativa": "string"
  },
  "Digitador": {
    "CodAgente": "string",
    "CodSupervisor": "string",
    "CodComercial": "string",
    "CodFilial": "string",
    "CodTipoNaturezaRelacionamento": 0
  },
  "DadosBancariosLiberacao": [
    {
      "CodProposta": 0,
      "CodBanco": "string",
      "CodTipoContaBancaria": 0,
      "NroAgencia": "string",
      "DigAgencia": "string",
      "NroConta": "string",
      "DigConta": "string",
      "CodLiberacao": "string",
      "CodProduto": 0,
      "CodPropostaProduto": 0
    }
  ]
}
```

Respostas:
- `200` Success.
  - Media type: controlado por `Accept` (nao ha exemplo no print).

### GET /refin/agentes

Metodo para listar os Agente Bancarios.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Respostas:
- `200` Success.
  - Media type: controlado por `Accept` (nao ha exemplo no print).

### GET /refin/comerciais

Metodo para retornar a lista os Comerciais da Promotora.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Respostas:
- `200` Success.
  - Media type: controlado por `Accept` (nao ha exemplo no print).

### GET /refin/endereco/{cep}

Metodo para retornar os dados do endereco pelo CEP.
Usar apos a simulacao quando for necessario alterar dados de endereco.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Path params:
- `cep` (string): CEP consultado.

Respostas:
- `200` Success.
  - Media type: controlado por `Accept` (nao ha exemplo no print).

### POST /refin/inclui-proposta

Inclui a proposta no sistema de emprestimo consignado.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Request body (`application/json`):
```json
{
  "CodProposta": 0
}
```

Respostas:
- `200` Success.
  - Media type: controlado por `Accept` (nao ha exemplo no print).

### POST /refin/formaliza/proposta

Metodo responsavel por envio de SMS e e-mail para formalizacao da proposta.

Headers obrigatorios:
- `apikey`: token da API (apiKey em header).
- `Login-Usuario`: login do usuario (string).

Request body (`application/json`):
```json
{
  "CodProposta": 0,
  "Telefone": "string"
}
```

Respostas:
- `200` Success.
  - Media type: controlado por `Accept` (nao ha exemplo no print).

## Entendimento do fluxo

O diagrama mostra um fluxo sequencial para refinanciamento consignado. Ha validacoes iniciais por CPF e por empregador (cod interno e externo), consulta de prazos e parametros de averbacao, validacao de saldo para refinanciamento, simulacao, inclusao da simulacao e, por fim, inclusao/ formalizacao da proposta. Alguns passos sao opcionais (amarelos) e dependem de necessidade de ajuste cadastral ou complementar.

Pontos de decisao:
- Se o CPF nao possui produto disponivel, o fluxo termina.
- Se o empregador nao possui averbacao, e solicitada uma senha (cod. servico) antes de seguir para saldo.

## Sequencia recomendada (ordem do diagrama)

1. `GET /refin/produtos-disponiveis/{cpf}`
   - Objetivo: verificar se o CPF possui algum produto disponivel.
   - Se nao houver produto, encerrar.

2. `GET /refin/empregadores-consignados/{codEmpregadorInterno}`
   - Objetivo: validar/obter dados do empregador interno.

3. `GET /refin/orgaos-consignado/{cpf}/{codEmpregadorExterno}`
   - Objetivo: validar/obter o codigo do orgao externo.

4. `GET /refin/prazos-consignado/{codEmpregadorExterno}/refin`
   - Objetivo: verificar prazos permitidos para refin.

5. `GET /refin/parametros-averbacao/refin/{codEmpregador}`
   - Objetivo: verificar parametros de averbacao.

6. Decisao: empregador possui averbacao?
   - Nao: digitar senha solicitada (cod. servico) e seguir.

7. `GET /refin/saldos-refinanciamentos/{codEmpregadorExterno}/{cpf}/{matricula}`
   - Objetivo: verificar saldo disponivel para refin.

8. `POST /refin/simula-proposta-consignado/refin`
   - Objetivo: simular proposta.

9. `POST /refin/inclui-simulacoes/refin`
   - Objetivo: incluir a simulacao.

10. (Opcional) Ajuste de dados cadastrais
   - Se necessario, usar metodos `GET` para consultar/alterar dados cadastrais.
   - Para endereco, usar `GET /refin/endereco/{cep}` antes de atualizar o cadastro.
   - Em seguida:
   - `PUT /refin/cliente/pagamento/{codProposta}`

11. (Opcional) Ajuste de dados complementares
   - Se necessario, usar metodos `GET` para consultar/alterar dados complementares.
   - Em seguida:
   - `PUT /refin/pagamento/resumo/{codProposta}`

12. `GET /refin/agentes`
   - Objetivo: selecionar o agente bancario.

13. `GET /refin/comerciais`
   - Objetivo: selecionar o comercial da promotora.

14. `POST /refin/inclui-proposta`
   - Objetivo: incluir proposta.

15. `POST /refin/formaliza/proposta`
   - Objetivo: iniciar formalizacao (SMSRegistrarFormalizacao).

## Lista consolidada de endpoints

Obrigatorios (azul):
- `GET /refin/produtos-disponiveis/{cpf}`
- `GET /refin/empregadores-consignados/{codEmpregadorInterno}`
- `GET /refin/orgaos-consignado/{cpf}/{codEmpregadorExterno}`
- `GET /refin/prazos-consignado/{codEmpregadorExterno}/refin`
- `GET /refin/parametros-averbacao/refin/{codEmpregador}`
- `GET /refin/saldos-refinanciamentos/{codEmpregadorExterno}/{cpf}/{matricula}`
- `POST /refin/simula-proposta-consignado/refin`
- `POST /refin/inclui-simulacoes/refin`
- `PUT /refin/cliente/pagamento/{codProposta}`
- `PUT /refin/pagamento/resumo/{codProposta}`
- `GET /refin/agentes`
- `GET /refin/comerciais`
- `POST /refin/inclui-proposta`
- `POST /refin/formaliza/proposta`

Nao obrigatorios (amarelo):
- Digitar senha solicitada (cod. servico) quando nao houver averbacao.
- `GET /refin/endereco/{cep}` (quando for necessario alterar dados de endereco).
- Metodos `GET` para ajustar dados cadastrais e dados complementares (nao especificados no diagrama).

## Observacoes e lacunas

- O diagrama nao detalha payloads, respostas, autenticacao ou codigos de erro.
- A origem do `codProposta` nao esta explicita (provavelmente vem da simulacao ou da inclusao da simulacao). Precisamos confirmar no manual da Daycoval.
- Os metodos `GET` para alteracao de dados cadastrais/complementares nao estao nomeados; deve haver endpoints especificos na documentacao tecnica.

## Implicacoes para a integracao

- Fluxo interno (digitacao de refin via API): executar a sequencia acima com coletor de dados para CPF, codEmpregadorInterno/Externo, matricula, senha (quando exigida), dados cadastrais/complementares, selecao de simulacao e selecao de agente/comercial.
- Fluxo de autocontratacao: usar a mesma sequencia, mas com etapas guiadas (produto -> simulacao -> inclusao -> formalizacao via SMS) e captura de dados pelo cliente. O disparo de formalizacao deve acionar `POST /refin/formaliza/proposta`.

## Implementacao no codigo (esqueleto)

Classes criadas para iniciar a integracao:
- `app/Services/Daycoval/DaycovalClient.php`
- `app/Services/Daycoval/DaycovalRefinService.php`
- `app/Services/Daycoval/DaycovalException.php`
- `app/Services/Integration/IntegrationCatalog.php` (novo tipo `daycoval_refin`)

### Configuracao sugerida (api_integrations)

Use uma integracao com tipo `daycoval_refin` e preencha `base_url`.
Por padrao o cliente envia `apikey` no header e usa o campo `username` da integracao como `Login-Usuario`.
Use `extra_config` apenas se precisar sobrescrever esses valores.

Campos aceitos em `extra_config` (JSON), preferencialmente dentro de `daycoval`:
- `auth_mode`: `bearer`, `api_key_header`, `basic`, `none`.
- `auth_header`: nome do header para token (default `Authorization`).
- `auth_prefix`: prefixo do token (default `Bearer`).
- `api_key_header`: header alternativo para api key (default `x-api-key`).
- `auth_token`: token manual (se nao quiser usar `api_key`).
- `timeout`, `connect_timeout`, `retries`, `retry_delay_ms`.
- `headers`: headers extras.
- `accept`, `force_json`.

Exemplo:
```json
{
  "daycoval": {
    "auth_mode": "api_key_header",
    "api_key_header": "x-api-key",
    "timeout": 45,
    "headers": {
      "X-App": "SaqueFacil"
    }
  }
}
```