ℹ️ Conteúdo em atualização

Estamos revisando estes procedimentos. Pessoas técnicas podem encontrar ajustes em códigos de erro ou mapeamentos de payload; valide com os logs e o OpenAPI mais recente. Pessoas não técnicas podem continuar usando o passo a passo e acionar o time de suporte caso algo pareça diferente do descrito.

💵 Empréstimo Pessoal

Guia completo para integração com o serviço de Empréstimo Pessoal, incluindo verificação de elegibilidade, simulação, contratação e gerenciamento.

Introdução

Este serviço permite que você ofereça empréstimos pessoais aos seus clientes de forma integrada, com funcionalidades completas de:

✅ Verificação de elegibilidade
💰 Simulação de planos e parcelas
🏦 Gerenciamento de contas bancárias
📝 Contratação (efetivação) e agendamento
📄 Geração de contratos e boletos
❌ Cancelamento e gestão de seguros

URLs Base:

Produção: https://api.credsystem.com.br/emprestimo-pessoal-app/api/v1
Homologação: https://apihml.credsystem.com.br/emprestimo-pessoal-app/api/v1

Autenticação

Todas as chamadas precisam incluir o token de autenticação no header:

Authorization: Bearer <seu_token_jwt>

Atenção

Tokens inválidos ou expirados retornarão erro 401 Unauthorized.

Fluxo de Contratação

Passo 1: Verificar Elegibilidade

Antes de oferecer o empréstimo, verifique se o cliente é elegível.

Endpoint: POST /elegibilidade

Body:

{
  "idCanal": 1
}

Resposta de Sucesso (200):

{
  "valorMaximoEmprestimo": 10000.00,
  "valorMinimoEmprestimo": 500.00,
  "taxaMes": 2.99,
  "flagContratosExistentes": false,
  "flagAgendamentosExistentes": false
}

Campos da Resposta:

valorMaximoEmprestimo: Valor máximo que o cliente pode solicitar
valorMinimoEmprestimo: Valor mínimo permitido
taxaMes: Taxa de juros mensal
flagContratosExistentes: Se o cliente já possui contratos ativos
flagAgendamentosExistentes: Se há agendamentos pendentes

Importante

Se flagContratosExistentes ou flagAgendamentosExistentes for true, o cliente pode ter restrições para nova contratação.

Passo 2: Simular Planos de Pagamento

Simule diferentes opções de parcelamento para o cliente.

Endpoint: GET /simulacao-plano

Parâmetros Query:

valorTransacao: Valor desejado do empréstimo
incluirSeguro: Se deve incluir seguro (true/false)

Exemplo: GET /simulacao-plano?valorTransacao=5000&incluirSeguro=true

Resposta de Sucesso (200):

[
  {
    "plano": [
      {
        "numeroDeParcela": 12,
        "valorParcela": 483.50,
        "dataPrimeiroVencimento": "2024-02-15",
        "diasPrimeioVencimento": 30,
        "valorTarifa": 0.00,
        "valorTotalJuros": 802.00,
        "valorTotalIof": 0.38,
        "valorTotal": 5802.38,
        "taxaMes": 2.99,
        "taxaAno": 42.35,
        "aliqIof": 0.0038,
        "iofAdicional": 0.38,
        "cetMensal": 3.15,
        "cetAnual": 45.20,
        "valorTotalSeguro": 120.00
      },
      {
        "numeroDeParcela": 24,
        "valorParcela": 267.80,
        "dataPrimeiroVencimento": "2024-02-15",
        "diasPrimeioVencimento": 30,
        "valorTarifa": 0.00,
        "valorTotalJuros": 1427.20,
        "valorTotalIof": 0.38,
        "valorTotal": 6427.58,
        "taxaMes": 2.99,
        "taxaAno": 42.35,
        "aliqIof": 0.0038,
        "iofAdicional": 0.38,
        "cetMensal": 3.15,
        "cetAnual": 45.20,
        "valorTotalSeguro": 240.00
      }
    ]
  }
]

Informações do Plano:

numeroDeParcela: Quantidade de parcelas
valorParcela: Valor de cada parcela
valorTotal: Valor total a ser pago (empréstimo + juros + IOF + seguro)
cetMensal/cetAnual: Custo Efetivo Total (importante para transparência)

Passo 3: Gerenciar Conta Bancária

Antes de efetivar, o cliente precisa ter uma conta cadastrada.

3.1 Listar Contas do Cliente

Endpoint: GET /conta

Resposta: Lista de contas bancárias cadastradas

3.2 Cadastrar/Atualizar Conta

Endpoint: POST /conta

Body:

{
  "codigoCompe": "001",
  "nomeInstituicao": "Banco do Brasil",
  "numeroAgencia": "1234",
  "numeroConta": "12345678",
  "dvConta": "9",
  "ispb": "00000000",
  "tipoConta": "CC",
  "status": "A"
}

Tipos de Conta:

CC: Conta Corrente
PP: Poupança

Status:

A: Ativa

Passo 4: Gerar Pré-Contrato

Gere o PDF do pré-contrato para o cliente visualizar antes de aceitar.

Endpoint: GET /precontrato

Headers obrigatórios:

Authorization: Bearer <token>
valorEmprestimo: 5000
valorTotalIof: 0.38
valorTotal: 5802.38
taxaMes: 2.99
taxaAno: 42.35
taxaCetMes: 3.15
taxaCetAno: 45.20
codigoCompe: 001
numeroAgencia: 1234
numeroConta: 12345678
tipoConta: CC
numeroParcela: 12
dataVencimentoParcela: 2024-02-15T00:00:00Z
valorParcela: 483.50
valorTotalSeguro: 120.00

Resposta: String com PDF em Base64

Como usar

Converta o Base64 retornado em arquivo PDF para exibir ao cliente.

Passo 5: Efetivar Contratação

Após o cliente aceitar os termos, efetive a contratação.

Endpoint: POST /efetivacao

Body:

{
  "idCanal": 1,
  "codigoEstabelecimento": 123,
  "valor": 5000.00,
  "quantidadeParcela": 12,
  "seguroAceito": true,
  "codigoCartao": "1234567890",
  "dataHoraAceite": "2024-01-15T14:30:00Z",
  "conta": {
    "codigoCompe": "001",
    "numeroAgencia": "1234",
    "numeroConta": "12345678",
    "dvConta": "9",
    "tipoConta": "CC"
  },
  "assinaturaDigital": {
    "metodoTokenizacao": "BIOMETRIA",
    "nomeLoja": "Loja ABC",
    "nomeRede": "Rede XYZ",
    "device": "Android",
    "modelo": "Samsung Galaxy S21",
    "imei": "123456789012345",
    "latitude": "-23.5505",
    "longitude": "-46.6333",
    "celular": "11987654321"
  }
}

Resposta de Sucesso (200):

{
  "numeroContrato": 123456789,
  "valorParcela": 483.50,
  "dataPrimeiroVencimento": "2024-02-15"
}

Contratado!

Guarde o numeroContrato - você precisará dele para consultas futuras.

Gerenciamento de Contratos

Consultar Dados da Efetivação

Endpoint: GET /efetivacao

Resposta de Sucesso (200):

{
  "idEmprestimoPessoal": 1001,
  "codigoCliente": 12345,
  "numeroBin": 960333,
  "valorContratacao": 5000.00,
  "valorPrestacao": 483.50,
  "quantidadeParcela": 12,
  "dataHoraContratacao": "2024-01-15T14:30:00Z",
  "dataHorasTransferencia": "2024-01-16T10:00:00Z",
  "codigoEstabelecimento": 123,
  "nomeFantasia": "Loja ABC",
  "canalContratacao": "APP_MOBILE",
  "statusEmprestimo": "A",
  "motivoRejeicaoTransferencia": null,
  "Conta": {
    "codigoCompe": "001",
    "numeroAgencia": "1234",
    "numeroConta": "12345678",
    "dvConta": "9",
    "tipoConta": "CC",
    "nomeInstituicao": "Banco do Brasil"
  },
  "Cancelamento": null,
  "numeroContrato": 123456789,
  "valorTotalJuros": 802.00,
  "valorTotalIof": 0.38,
  "taxaMes": 2.99,
  "cetMensal": 3.15,
  "flagPagamentoEmAtraso": false,
  "taxaAno": 42.35,
  "cetAnual": 45.20,
  "flagSeguroAceito": true,
  "flagCancelamentoSeguro": false
}

Status do Empréstimo:

A: Ativo
C: Cancelado
P: Pendente
T: Transferido

Baixar Contrato (PDF)

Endpoint: GET /contrato

Header:

numeroContrato: Número do contrato

Resposta:

{
  "pdfBase64": "JVBERi0xLjQKJeLjz9M..."
}

Gestão de Parcelas

Consultar Parcelas

Endpoint: GET /parcela

Parâmetros Query:

numeroContrato: Número do contrato

Resposta de Sucesso (200):

{
  "numeroParcela": 1,
  "valor": 483.50,
  "dataVencimento": "2024-02-15",
  "dataRegistroBoleto": "2024-01-16",
  "flagRegistroBoleto": true,
  "dataPagamento": null,
  "valorPagamento": 0,
  "flagPagamentoRealizado": false
}

Obter Boleto da Parcela

Endpoint: GET /parcela/boleto

Parâmetros Query:

numeroContrato: Número do contrato
numeroParcela: Número da parcela

Resposta:

{
  "linhaDigitavel": "00190.50095 40144.816060 06809.350314 1 37370000000500",
  "valorBoleto": 483.50,
  "dataVencimento": "2024-02-15",
  "boleto": "JVBERi0xLjQKJeLjz9M..." 
}

Enviar Boleto por SMS

Endpoint: POST /parcela/boleto/envio-sms

Headers:

numeroContrato: Número do contrato
numeroParcela: Número da parcela

Body:

{
  "ddd": "11",
  "celular": "987654321",
  "boleto": "JVBERi0xLjQKJeLjz9M...",
  "linhaDigitavel": "00190.50095 40144.816060 06809.350314 1 37370000000500"
}

Enviar Boleto por E-mail

Endpoint: POST /parcela/boleto/envio-email

Headers:

numeroContrato: Número do contrato
numeroParcela: Número da parcela

Body:

{
  "email": "cliente@email.com",
  "boleto": "JVBERi0xLjQKJeLjz9M...",
  "linhaDigitavel": "00190.50095 40144.816060 06809.350314 1 37370000000500"
}

Cancelamento

Cancelar Efetivação

Endpoint: POST /efetivacao/cancelamento

Body:

{
  "numeroContrato": 123456789,
  "idCanal": 1
}

Resposta:

{
  "linhaDigitavel": "00190.50095 40144.816060 06809.350314 1 37370000000500",
  "valorBoleto": 5000.00,
  "dataVencimento": "2024-02-01",
  "boleto": "JVBERi0xLjQKJeLjz9M..."
}

Importante

Ao cancelar, um boleto será gerado para devolução do valor recebido.

Consultar Boleto de Cancelamento

Endpoint: GET /efetivacao/cancelamento/boleto

Parâmetros Query:

numeroContrato: Número do contrato

Enviar Boleto de Cancelamento

Por SMS:

POST /cancelamento/boleto/envio-sms

Por E-mail:

POST /cancelamento/boleto/envio-email

Gestão de Seguros

Verificar Elegibilidade para Cancelamento

Endpoint: GET /seguro/cancelamento/elegibilidade

Header:

numeroContrato: Número do contrato

Consultar Valores do Cancelamento

Endpoint: GET /seguro/cancelamento/valores

Header:

numeroContrato: Número do contrato

Cancelar Seguro

Endpoint: POST /seguro/cancelamento

Header:

numeroContrato: Número do contrato

Consultar Status de Cancelamento

Endpoint: GET /seguro/consulta-cancelado

Header:

numeroContrato: Número do contrato

Solicitar Transferência (Reembolso)

Endpoint: POST /seguro/cancelamento/pedido-transferencia

Header:

numeroContrato: Número do contrato

Body:

{
  "banco": {
    "codigo": "001",
    "agencia": "1234",
    "conta": "12345678",
    "dvConta": "9",
    "tipoConta": "CC"
  }
}

Agendamentos

Consultar Agendamento

Endpoint: GET /agendamento

Cancelar Agendamento

Endpoint: POST /agendamento/cancelamento

Body:

{
  "idAgendamento": 1001,
  "idCanal": 1
}

Cancelar Elegibilidade

Endpoint: POST /elegibilidade/cancelamento

Body:

{
  "numeroContrato": 123456789
}

Consulta de Bancos

Listar Bancos

Endpoint: GET /banco

Parâmetros Query:

ativoSpb: Filtrar apenas bancos ativos no SPB (true/false)

Verificação de Saúde

Verificar Disponibilidade

Endpoint: GET /isAlive

Resposta: String confirmando que o serviço está disponível

Monitoramento

Use este endpoint para health checks e monitoramento da API.

Códigos de Resposta

Código	Status	Descrição
200	✅ Sucesso	Requisição processada com sucesso
204	∅ Sem conteúdo	Requisição bem-sucedida, mas sem dados para retornar
400	⚠️ Bad Request	Parâmetros inválidos na requisição
401	⛔ Unauthorized	Token inválido ou expirado
500	💥 Internal Error	Erro interno do servidor

Tratamento de Erros

{
  "error": {
    "message": "Descrição do erro",
    "code": 400
  }
}

Boas Práticas

Validação de Elegibilidade: Sempre verifique antes de apresentar ofertas
Simulação Clara: Mostre todas as informações (CET, juros, IOF) de forma transparente
Confirmação: Peça confirmação dupla antes de efetivar
Armazenamento: Guarde o numeroContrato de forma segura
Boletos: Cache boletos já gerados para evitar requisições desnecessárias
PDFs: Converta Base64 corretamente no frontend
Timeout: Configure timeouts de 30-60 segundos para efetivação
Status: Monitore o status do empréstimo regularmente

Fluxo Resumido

1. Verificar Elegibilidade
   ↓
2. Simular Planos
   ↓
3. Cadastrar/Verificar Conta Bancária
   ↓
4. Gerar Pré-Contrato (Cliente visualiza)
   ↓
5. Cliente Aceita
   ↓
6. Efetivar Contratação
   ↓
7. Empréstimo Ativo!

Exemplo de Fluxo Completo

# 1. Verificar elegibilidade
curl -X 'POST' 'https://bff-app-emprestimo-pessoal-hml.credsystem.com.br/emprestimo-pessoal-app/api/v1/elegibilidade' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"idCanal": 1}'

# 2. Simular planos
curl -X 'GET' 'https://bff-app-emprestimo-pessoal-hml.credsystem.com.br/emprestimo-pessoal-app/api/v1/simulacao-plano?valorTransacao=5000&incluirSeguro=true' \
  -H 'Authorization: Bearer TOKEN'

# 3. Cadastrar conta
curl -X 'POST' 'https://bff-app-emprestimo-pessoal-hml.credsystem.com.br/emprestimo-pessoal-app/api/v1/conta' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"codigoCompe":"001","numeroAgencia":"1234","numeroConta":"12345678","dvConta":"9","tipoConta":"CC","status":"A"}'

# 4. Efetivar
curl -X 'POST' 'https://bff-app-emprestimo-pessoal-hml.credsystem.com.br/emprestimo-pessoal-app/api/v1/efetivacao' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{...}'

Suporte

Para dúvidas ou problemas com a integração, entre em contato com a equipe de suporte técnico.

Introdução​

Autenticação​

Fluxo de Contratação​

Passo 1: Verificar Elegibilidade​

Passo 2: Simular Planos de Pagamento​

Passo 3: Gerenciar Conta Bancária​

3.1 Listar Contas do Cliente​

3.2 Cadastrar/Atualizar Conta​

Passo 4: Gerar Pré-Contrato​

Passo 5: Efetivar Contratação​

Gerenciamento de Contratos​

Consultar Dados da Efetivação​

Baixar Contrato (PDF)​

Gestão de Parcelas​

Consultar Parcelas​

Obter Boleto da Parcela​

Enviar Boleto por SMS​

Enviar Boleto por E-mail​

Cancelamento​

Cancelar Efetivação​

Consultar Boleto de Cancelamento​

Enviar Boleto de Cancelamento​

Gestão de Seguros​

Verificar Elegibilidade para Cancelamento​

Consultar Valores do Cancelamento​

Cancelar Seguro​

Consultar Status de Cancelamento​

Solicitar Transferência (Reembolso)​

Agendamentos​

Consultar Agendamento​

Cancelar Agendamento​

Cancelar Elegibilidade​

Consulta de Bancos​

Listar Bancos​

Verificação de Saúde​

Verificar Disponibilidade​

Códigos de Resposta​

Tratamento de Erros​

Boas Práticas​

Fluxo Resumido​

Exemplo de Fluxo Completo​

Suporte​

Introdução

Autenticação

Fluxo de Contratação

Passo 1: Verificar Elegibilidade

Passo 2: Simular Planos de Pagamento

Passo 3: Gerenciar Conta Bancária

3.1 Listar Contas do Cliente

3.2 Cadastrar/Atualizar Conta

Passo 4: Gerar Pré-Contrato

Passo 5: Efetivar Contratação

Gerenciamento de Contratos

Consultar Dados da Efetivação

Baixar Contrato (PDF)

Gestão de Parcelas

Consultar Parcelas

Obter Boleto da Parcela

Enviar Boleto por SMS

Enviar Boleto por E-mail

Cancelamento

Cancelar Efetivação

Consultar Boleto de Cancelamento

Enviar Boleto de Cancelamento

Gestão de Seguros

Verificar Elegibilidade para Cancelamento

Consultar Valores do Cancelamento

Cancelar Seguro

Consultar Status de Cancelamento

Solicitar Transferência (Reembolso)

Agendamentos

Consultar Agendamento

Cancelar Agendamento

Cancelar Elegibilidade

Consulta de Bancos

Listar Bancos

Verificação de Saúde

Verificar Disponibilidade

Códigos de Resposta

Tratamento de Erros

Boas Práticas

Fluxo Resumido

Exemplo de Fluxo Completo

Suporte