# Crefaz On API (Parceiros) - Notes

Ultima atualizacao na doc recebida: 15/07/2024 14:30.

## Ambientes / Base URLs
- Staging (doc): https://api-externo-stag.crefazon.com.br/api
- Producao (doc): https://api-externo.crefazon.com.br/api

Observacao: alguns exemplos usam hosts alternativos (Azure):
- https://app-crefaz-api-external-stag.azurewebsites.net/api
- https://app2-crefaz-api-external-stag.azurewebsites.net/api

## Autenticacao
- OAuth2; token Bearer valido por 3 horas.
- Endpoint (exemplo): POST /usuario/login
  - Body: login, senha, apiKey
  - 3 erros seguidos bloqueiam acesso.
- Todas as demais rotas usam Authorization: Bearer <token>.

## Headers padrao
- Accept: application/json
- Content-Type: application/json
(Exceto autenticacao OAuth2.)

## Status HTTP (resumo)
- 200 OK
- 201 Created
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 406 Not Acceptable (Content-Type incorreto)
- 422 Unprocessable Entity (errors no body)
- 429 Too Many Requests (Retry-After)
- 500 Internal Server Error

## Fluxo geral (alto nivel)
1) Verifica produtos por cidade (produtos-regiao).
2) Cadastra proposta (primeira consulta de elegibilidade).
3) Lista ofertas (oferta-produto).
4) Calcula vencimento (calculo-vencimento).
5) Consulta valor limite (consulta-valor-limite).
6) Simula valores (simulacao-valor).
7) Seleciona oferta (PUT oferta-produto).
8) Lista tipos de anexos (tipo-anexos).
9) Upload de anexos (imagem).

## Webhook (API Parceiros)
### Webhook - Visao geral
- Permite que o parceiro receba, de forma automatica e passiva, todas as mudancas de status relacionadas a proposta.
- Elimina a necessidade de consultar constantemente a rota GET /ConsultarProposta, reduzindo trafego, latencia e custo operacional.
- Sempre que houver atualizacao relevante (aprovacao, pendencia, negativa, reanalise ou qualquer transicao de status) o sistema envia notificacao imediata para o endpoint configurado.

### Como configurar o Webhook
- Configurado no cadastro da proposta (doc refere como POST /CadastrarProposta).
- No body da requisicao informar:
  - urlNotificacaoParceiro: string (URL valida e publica para receber Webhook).
- Importante: o endpoint deve aceitar HTTP POST, responder dentro do tempo esperado e retornar status 200 para confirmar recebimento.
- Doc: https://docs.crefaz.dev.br/link/87#bkmrk-importante%3A-certifiq

### Exemplo (body com webhook)
{
  "cpf": "435.901.808-89",
  "nome": "Julio Rossato",
  "ocupacaoId": 1,
  "cidadeId": "1762",
  "logradouro": "Rua Rui Barbosa",
  "bairro": "Limoeiro",
  "cep": "63030000",
  "urlNotificacaoParceiro": "null",
  "nascimento": "1974-07-10",
  "telefone": "44999167734"
}

### Eventualidades enviadas pelo Webhook
- Alteracoes de status
- Pendencias documentais
- Negativa de propostas

### Exemplo de payload enviado pelo Webhook
{
  "propostaId": 123456,
  "situacaoDescricao": "Proposta Pendente",
  "login": "treinamento",
  "observacoes": "Observacao realizada ao pendenciar a proposta",
  "motivos": [
    "Contato Pendente",
    "Valores nao estao certo",
    "Cliente nao atendeu"
  ]
}

## Endpoints detalhados (coletados)

### GET /Proposta/produtos-regiao/:codCidadeIBGE
- Objetivo: listar produtos disponiveis na cidade (codigo IBGE).
- Uso: funis de auto-contratacao, validacao de convenios por cidade.

### POST /Proposta
- Objetivo: cadastra proposta e aciona motor de credito (primeira consulta do lead).
- Campos obrigatorios:
  - nome, cpf, nascimento (YYYY-MM-DD), telefone, ocupacaoId, cidadeId
- Campos opcionais:
  - urlNotificacaoParceiro, cep, bairro, logradouro
- Sucesso:
  - { success: true, data: { propostaId, aprovado }, errors: null }
- Erros: lista de mensagens (CPF invalido, data invalida, proposta em andamento, etc.).

### POST /Proposta/proposta-em-andamento?cpf={{cliente_cpf}}&loginVendedor={{login}}
- Consulta propostas em andamento por CPF + login do vendedor.

### GET /Proposta/oferta-produto/:propostaId
- Lista ofertas por proposta.
- Sucesso: retorna produtos, convenios, convenioDados, tabelaJuros, tabelaJurosValores e dados da proposta.
- Caso nao haja ofertas: success=true e data com mensagem "Nao ha produtos ofertados no momento".

### POST /Proposta/calculo-vencimento
- Calcula vencimento previsto da primeira cobranca.
- Body:
  - propostaId, produtoId, convenioId, tabelaJurosId
  - rota: null (obrigatorio enviar null)
  - leitura: null (obrigatorio enviar null)
  - vencimento: null (obrigatorio enviar null)
- Resposta: data pode ter lista com vencimento ou lista vazia.

### POST /Proposta/consulta-valor-limite/:propostaId
- Retorna limites para a proposta.
- Body:
  - produtoId, tabelaJurosId, vencimento, renda
  - convenioId (apenas para ENERGIA)
  - recalculo: null (sempre)
- Sucesso:
  - valorLimiteSolicitado, valorLimiteParcela, valorLimiteMinimoParcela

### POST /Proposta/simulacao-valor/:propostaId
- Simula valores/parcelas.
- Body:
  - produtoId, convenioId (apenas ENERGIA), tabelaJurosId
  - valor, tipoCalculo (0=valor solicitado, 1=valor por parcela)
  - vencimento, renda, recalculo: null
  - contrato: null (apenas para REFIN)
- Sucesso: prazoValor com opcoes de prazo/valor.

### PUT /Proposta/oferta-produto/:propostaId
- Seleciona a oferta.
- Body (principais):
  - id (propostaId), produtoId, convenioId (ENERGIA), tabelaJurosId
  - plano, prestacao, renda, diaRecebimento, tipoRenda
  - vencimento, valor, tipoCalculo
  - adicionais (obrigatorio para ENERGIA)
  - contratosRefin (apenas REFIN)
- Regra de negocio (ENERGIA):
  - adicionais deve conter convenioDadosId (dados obrigatorios da companhia).
  - Valores vem da fatura (unidade consumidora / numero do cliente).
- Sucesso: propostaId, aprovado, novoLimite.

### POST /Proposta/tipo-anexos
- Lista documentos exigidos/possiveis.
- Body:
  - propostaId (obrigatorio)
  - tipoModalidade (obrigatorio; doc diz sempre enviar 2)
  - tipoRenda (opcional)
- Sucesso: lista de tipos com obrigatorio=true/false.
- Erro: "Proposta inexistente".

### PUT /Proposta/:propostaId/imagem
- Upload de anexos da proposta.
- Introducao: efetua o upload de arquivos em Base64.
- Importante: o campo `conteudo` deve ser Base64 (TI da Crefaz informou que precisa ser assim).
- Importante: usar o prefixo `data:image/png;base64,` antes do Base64 (doc).
- Enviar apenas 1 arquivo por chamada.
- Headers:
  - Accept: application/json
  - Content-Type: application/json
  - Authorization: Bearer <token>
- Body (exemplo):
  - documentoId: id do tipo de anexo
  - conteudo: data:image/jpeg;base64,<base64_do_arquivo>
- Exemplo (curl):
  - PUT https://app-crefaz-api-external-stag.azurewebsites.net/api/Proposta/:propostaId/imagem
  - Body:
    {
      "documentoId": 48,
      "conteudo": "data:image/jpeg;base64,<...>"
    }
- Response (exemplo):
  - { "success": true, "data": "Upload Concluido", "errors": null }
- Headers de response (exemplo):
  - Content-Type: application/json; charset=utf-8
  - Date: Fri, 04 Oct 2024 18:03:20 GMT
  - Server: Kestrel
  - Transfer-Encoding: chunked
  - Request-Context: appId=cid-v1:1d0033e30-cc70-4961-9727-b7389fb39348

### PUT /Proposta/:propostaId
- Cadastra / atualiza proposta (envia para analise).
- Introducao: completa o envio da proposta (cadastro), deixando a mesma no status de aguardando analise.
- Introducao: tambem altera os dados da proposta (atualizacao), quando necessario, com base nos parametros informados.
- Ultima etapa: grava a proposta em questao.
- Recomendacao: importar o maximo de informacoes possiveis do nosso sistema (perfil do lead) e preencher os campos aqui, para reduzir o que o lead precisa digitar no fluxo publico de auto contratacao e facilitar o operador de credito.
- Headers:
  - Accept: application/json
  - Content-Type: application/json
  - Authorization: Bearer <token>
- Exemplo de Request (curl):
```bash
curl --location 'https://app2-crefaz-api-external-stag.azurewebsites.net/api/Proposta/1028688871' \
--request PUT \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJh...' \
--data '{
  "id": 1028688871,
  "cliente": {
    "nome": "Wescley fonseca castro",
    "pep": false,
    "sexo": 1,
    "nomeMae": "Lorena Lourenco Vaz",
    "rgUfId": 16,
    "estadoCivil": 0,
    "nomeConjuge": null,
    "rg": "123456789",
    "rgEmissor": "SSP",
    "nacionalidadeId": 1,
    "naturalidadeUfId": 16,
    "grauInstrucaoId": 5,
    "rgEmissao": "1974-07-10",
    "naturalidadeCidadeId": 1
  },
  "contatos": {
    "contato": {
      "email": "email@email.com.br",
      "telefone": "44998765432",
      "telefoneExtra": []
    },
    "referencia": [
      {
        "nome": "Julio Cesar Correa Rossato",
        "telefone": "44998741256",
        "grau": 1
      },
      {
        "nome": "iego Moraes",
        "telefone": "44998741256",
        "grau": 1
      }
    ]
  },
  "endereco": {
    "cep": "60347470",
    "logradouro": "Rua Rui Barbosa",
    "bairro": "Limoeiro",
    "numero": 100,
    "cidadeId": 1749,
    "complemento": null
  },
  "bancario": {
    "bancoId": "001",
    "digito": "4",
    "agencia": "0123",
    "numero": "012345",
    "conta": 1,
    "tipoConta": 0,
    "tempoConta": 1
  },
  "profissional": {
    "tipoRenda": null,
    "pisPasep": null,
    "empresa": "Crefaz",
    "telefoneRH": null,
    "renda": 1412,
    "profissaoId": 1,
    "outrasRendas": null,
    "tipoOutrasRendas": null,
    "tempoEmpregoAtual": 0
  },
  "unidade": {
    "cpfVendedor": "09630541980",
    "nomeVendedor": "Gabriel Volpe Rodrigues",
    "celularVendedor": "44998662249"
  },
  "operacao": {
    "prazo": 20,
    "renda": 1412,
    "produtoId": 6,
    "prestacao": 182.85,
    "convenioId": 2,
    "diaRecebimento": 5,
    "tabelaJurosId": 2,
    "valorContratado": 1000,
    "tipoModalidade": 2,
    "tipoCalculo": 0,
    "vencimento": "2025-02-28",
    "tipoRenda": 0
  }
}'
```
- Response (exemplo):
  - Sucesso: { "success": true, "data": "Sucesso!", "errors": null }
  - Erro: { "success": false, "data": "Erro", "errors": [ "A proposta nao pertence ao seu usuario!" ] }
- Headers de response (exemplo):
  - Content-Type: application/json; charset=utf-8
  - Date: Fri, 04 Oct 2024 18:03:20 GMT
  - Server: Kestrel
  - Transfer-Encoding: chunked
  - Request-Context: appId=cid-v1:1d0033e30-cc70-4961-9727-b7389fb39348
- Campos obrigatorios:
  - id
  - cliente.nome
  - cliente.rg
  - cliente.rgEmissor
  - cliente.rgUfId
  - cliente.rgEmissao
  - cliente.sexo
  - cliente.estadoCivil
  - cliente.nacionalidadeId
  - cliente.naturalidadeUfId
  - cliente.naturalidadeCidadeId
  - cliente.grauInstrucaoId
  - cliente.nomeMae
  - cliente.pep
  - contatos.contato.telefone
  - endereco.cep
  - endereco.logradouro
  - endereco.numero
  - endereco.bairro
  - endereco.cidadeId
  - operacao.produtoId
  - operacao.vencimento
  - operacao.tabelaJurosId
  - operacao.valor
  - operacao.prazo
  - operacao.prestacao
  - operacao.renda
  - operacao.tipoCalculo
- Obs: lista acima cita `operacao.valor`, mas o exemplo usa `valorContratado`.
- Campos condicionais (doc):
  - cliente.nomeConjuge (obrigatorio apenas quando estado civil = casado)
  - operacao.convenioId (obrigatorio para produto Energia)
  - operacao.dadosAdicionais (obrigatorio para produto Energia)
  - Doc: https://docs.crefaz.dev.br/link/39#bkmrk-cliente.nomeconjuge%C2%A0

### GET /Proposta/:propostaId
- Consulta proposta por ID (detalhes nao fornecidos na coleta).

## Observacoes operacionais
- Integracao pode ser acionada manualmente ou automatizada (crons).
- Ideal: cachear tipos de anexos por produto/tipoModalidade/tipoRenda apos a primeira consulta para evitar chamadas repetidas.