💳 API de Empréstimo Pessoal Lojista

Este guia apresenta o passo a passo para integração com o serviço de empréstimo pessoal em estabelecimentos lojistas, incluindo contratação, gestão de contas, contratos e parcelas.

🎯 Visão Geral

A API de Empréstimo Pessoal Lojista permite que você:

✅ Verifique elegibilidade do cliente para empréstimo
🔍 Simule planos com taxas, IOF e CET
🏦 Gerencie contas bancárias do cliente
📄 Gere pré-contratos para aceite do cliente
💳 Efetive empréstimos e agende transferências
📅 Consulte e cancele agendamentos
📋 Consulte parcelas com status de pagamento
📑 Obtenha contratos em PDF

URLs Base:

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

📚 Recursos Adicionais

🔧 Guia de Troubleshooting — Solução de problemas e erros comuns
📖 Especificação OpenAPI — Referência técnica completa (schemas, tipos, exemplos)

🔐 Autenticação

Esta API utiliza Oracle IDCS com o fluxo Client Credentials (servidor para servidor).

Todos os endpoints requerem autenticação via Bearer Token (JWT) no header:

Authorization: Bearer <seu_token_jwt>

Propriedade	Valor
Sistema	Oracle IDCS
Fluxo OAuth2	Client Credentials
Tipo	Servidor para Servidor (sem usuário)
Token	Access Token (JWT)

Atenção

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

🔑 Como obter o token?

Veja o Passo 2 — Entender os Sistemas e o Passo 3 — Exemplos em 7 linguagens para gerar seu Bearer Token.

📚 Endpoints Disponíveis

1️⃣ Verificar Elegibilidade do Cliente

Verifica se o cliente é elegível para contratar um empréstimo pessoal, retornando valores mínimo/máximo, taxa e datas de vencimento disponíveis.

Endpoint: POST /elegibilidade

Headers:

Header	Tipo	Obrigatório	Descrição
`Authorization`	string	✅	Bearer token JWT
`cpfCliente`	string	✅	CPF do cliente (apenas números)

Corpo da Requisição:

Campo	Tipo	Obrigatório	Descrição
`codigoCliente`	integer	✅	Código identificador do cliente
`numeroBin`	integer	✅	Número do BIN do cartão
`idCanal`	integer	✅	Identificador do canal (ex: 1 = Loja)
`codigoEstabelecimento`	integer	✅	Código do estabelecimento
`origemLojista`	boolean	❌	Origem da contratação (default: false)

Exemplos de requisição:

cURL
JavaScript
Python

curl -X POST "https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1/elegibilidade" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "cpfCliente: 12345678901" \
  -H "Content-Type: application/json" \
  -d '{
    "codigoCliente": 123456,
    "numeroBin": 123456789,
    "idCanal": 1,
    "codigoEstabelecimento": 2,
    "origemLojista": false
  }'

const API_BASE = 'https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1';
const TOKEN = 'SEU_TOKEN_JWT';

async function verificarElegibilidade() {
  const response = await fetch(`${API_BASE}/elegibilidade`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'cpfCliente': '12345678901',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      codigoCliente: 123456,
      numeroBin: 123456789,
      idCanal: 1,
      codigoEstabelecimento: 2,
      origemLojista: false
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`HTTP ${response.status}: ${error.error?.detail}`);
  }

  const data = await response.json();
  console.log('✅ Cliente elegível:', data);
  return data;
}

verificarElegibilidade().catch(err => console.error('❌ Erro:', err.message));

import requests

API_BASE = 'https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1'
TOKEN = 'SEU_TOKEN_JWT'

response = requests.post(
    f'{API_BASE}/elegibilidade',
    headers={
        'Authorization': f'Bearer {TOKEN}',
        'cpfCliente': '12345678901',
        'Content-Type': 'application/json'
    },
    json={
        'codigoCliente': 123456,
        'numeroBin': 123456789,
        'idCanal': 1,
        'codigoEstabelecimento': 2,
        'origemLojista': False
    },
    timeout=15
)

response.raise_for_status()
dados = response.json()
print(f'✅ Valor máximo: R$ {dados["valorMaximoEmprestimo"]}')
print(f'✅ Valor mínimo: R$ {dados["valorMinimoEmprestimo"]}')

Exemplo de resposta (201 Created):

{
  "valorMaximoEmprestimo": 5000.00,
  "valorMinimoEmprestimo": 300.00,
  "taxaMes": 2.49,
  "flagContratosExistentes": true,
  "flagAgendamentosExistentes": false,
  "dataPrimeiroVencimentoMinimo": "2026-05-10",
  "dataPrimeiroVencimentoMaximo": "2026-06-10"
}

Campos da resposta:

Campo	Tipo	Descrição
`valorMaximoEmprestimo`	number	Valor máximo disponível para empréstimo
`valorMinimoEmprestimo`	number	Valor mínimo disponível
`taxaMes`	number	Taxa de juros mensal
`flagContratosExistentes`	boolean	Se o cliente já possui contratos ativos
`flagAgendamentosExistentes`	boolean	Se o cliente possui agendamentos
`dataPrimeiroVencimentoMinimo`	date	Data mínima do primeiro vencimento
`dataPrimeiroVencimentoMaximo`	date	Data máxima do primeiro vencimento

Melhor Prática

Se flagContratosExistentes for true, informe ao operador que o cliente já possui empréstimos ativos antes de prosseguir com nova contratação.

2️⃣ Simular Planos de Empréstimo

Retorna a simulação dos planos disponíveis ao cliente com valores de parcela, taxas, IOF e CET para cada opção de parcelamento.

Endpoint: GET /simulacao-plano

Parâmetros (Header):

Header	Tipo	Obrigatório	Descrição
`Authorization`	string	✅	Bearer token JWT
`cpfCliente`	string	✅	CPF do cliente
`valorTransacao`	number	✅	Valor do empréstimo desejado
`incluirSeguro`	boolean	❌	Incluir seguro na simulação (default: false)

Exemplos de requisição:

cURL
JavaScript
Python

curl -X GET "https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1/simulacao-plano" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "cpfCliente: 12345678901" \
  -H "valorTransacao: 3000" \
  -H "incluirSeguro: false"

const API_BASE = 'https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1';
const TOKEN = 'SEU_TOKEN_JWT';

async function simularPlanos() {
  const response = await fetch(`${API_BASE}/simulacao-plano`, {
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'cpfCliente': '12345678901',
      'valorTransacao': '3000',
      'incluirSeguro': 'false'
    }
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);

  const data = await response.json();
  console.log(`✅ ${data.plano.length} planos disponíveis`);
  data.plano.forEach(p => {
    console.log(`  ${p.numeroDeParcela}x de R$ ${p.valorParcela} (CET: ${p.cetMensal}% a.m.)`);
  });
  return data;
}

import requests

API_BASE = 'https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1'
TOKEN = 'SEU_TOKEN_JWT'

response = requests.get(
    f'{API_BASE}/simulacao-plano',
    headers={
        'Authorization': f'Bearer {TOKEN}',
        'cpfCliente': '12345678901',
        'valorTransacao': '3000',
        'incluirSeguro': 'false'
    },
    timeout=15
)

response.raise_for_status()
dados = response.json()

for plano in dados['plano']:
    print(f"  {plano['numeroDeParcela']}x R$ {plano['valorParcela']} | "
          f"Taxa: {plano['taxaMes']}% a.m. | CET: {plano['cetMensal']}% a.m.")

Exemplo de resposta (200 OK):

{
  "plano": [
    {
      "numeroDeParcela": 3,
      "valorParcela": 1025.42,
      "dataPrimeiroVencimento": "2026-05-27",
      "diasPrimeioVencimento": 30,
      "valorTarifa": 0,
      "valorTotalJuros": 15.39,
      "valorTotalIof": 10.87,
      "valorTotal": 3076.26,
      "taxaMes": 1.00,
      "taxaAno": 12.68,
      "aliqIof": 0.38,
      "iofAdicional": 0.0082,
      "cetMensal": 1.32,
      "cetAnual": 17.04,
      "valorTotalSeguro": 0
    },
    {
      "numeroDeParcela": 12,
      "valorParcela": 272.01,
      "dataPrimeiroVencimento": "2026-05-27",
      "diasPrimeioVencimento": 30,
      "valorTarifa": 0,
      "valorTotalJuros": 202.59,
      "valorTotalIof": 60.87,
      "valorTotal": 3264.12,
      "taxaMes": 1.00,
      "taxaAno": 12.68,
      "aliqIof": 0.38,
      "iofAdicional": 0.0082,
      "cetMensal": 1.32,
      "cetAnual": 17.04,
      "valorTotalSeguro": 0
    }
  ]
}

Melhor Prática

Exiba os planos ordenados por quantidade de parcelas e destaque o CET (Custo Efetivo Total), pois é o indicador mais transparente para o cliente comparar opções.

3️⃣ Listar Bancos Habilitados

Retorna a lista de bancos que podem receber TED/transferência do empréstimo pessoal.

Endpoint: GET /banco

Parâmetros (Header):

Header	Tipo	Obrigatório	Descrição
`Authorization`	string	✅	Bearer token JWT
`ativoSpb`	boolean	❌	Filtrar bancos ativos no SPB (default: false)

Exemplos de requisição:

cURL
JavaScript
Python

curl -X GET "https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1/banco" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "ativoSpb: true"

const response = await fetch(`${API_BASE}/banco`, {
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'ativoSpb': 'true'
  }
});
const bancos = await response.json();
console.log(`✅ ${bancos.length} bancos disponíveis`);

response = requests.get(
    f'{API_BASE}/banco',
    headers={'Authorization': f'Bearer {TOKEN}', 'ativoSpb': 'true'},
    timeout=15
)
bancos = response.json()
print(f'✅ {len(bancos)} bancos disponíveis')

Exemplo de resposta (200 OK):

[
  {
    "codigoCompe": "001",
    "nomeInstituicao": "BANCO DO BRASIL S.A.",
    "listaPrincipal": true
  },
  {
    "codigoCompe": "341",
    "nomeInstituicao": "ITAÚ UNIBANCO S.A.",
    "listaPrincipal": true
  },
  {
    "codigoCompe": "260",
    "nomeInstituicao": "NU PAGAMENTOS S.A.",
    "listaPrincipal": false
  }
]

Boas práticas

Exiba primeiro os bancos com listaPrincipal: true (mais utilizados).
Utilize o codigoCompe retornado ao registrar uma conta ou gerar o pré-contrato.

4️⃣ Gerenciar Contas Bancárias

Consultar Contas do Cliente

Lista contas bancárias ativas vinculadas ao CPF do cliente.

Endpoint: GET /conta

Headers:

Header	Tipo	Obrigatório	Descrição
`Authorization`	string	✅	Bearer token JWT
`cpfCliente`	string	✅	CPF do cliente

cURL
JavaScript
Python

curl -X GET "https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1/conta" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "cpfCliente: 12345678901"

const response = await fetch(`${API_BASE}/conta`, {
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'cpfCliente': '12345678901'
  }
});
const contas = await response.json();

response = requests.get(
    f'{API_BASE}/conta',
    headers={'Authorization': f'Bearer {TOKEN}', 'cpfCliente': '12345678901'},
    timeout=15
)
contas = response.json()

Exemplo de resposta (200 OK):

[
  {
    "codigoCompe": "001",
    "nomeInstituicao": "BANCO DO BRASIL S.A.",
    "numeroAgencia": "0001",
    "numeroConta": "12345",
    "dvConta": "6",
    "tipoConta": "CC",
    "status": "A"
  }
]

Valores de tipoConta: CC (Conta Corrente), PP (Poupança) Valores de status: A (Ativa), I (Inativa), R (Rejeitada)

Registrar Nova Conta

Registra uma nova conta bancária para o cliente receber o crédito do empréstimo.

Endpoint: POST /conta

Headers:

Header	Tipo	Obrigatório	Descrição
`Authorization`	string	✅	Bearer token JWT
`cpfCliente`	string	✅	CPF do cliente

Corpo da Requisição:

Campo	Tipo	Obrigatório	Descrição
`codigoCliente`	integer	✅	Código do cliente
`codigoCompe`	string	✅	Código do banco (COMPE)
`nomeInstituicao`	string	❌	Nome do banco
`numeroAgencia`	string	✅	Número da agência
`numeroConta`	string	✅	Número da conta
`dvConta`	string	✅	Dígito verificador
`ispb`	string	❌	Código ISPB do banco
`tipoConta`	string	✅	`CC` ou `PP`
`status`	string	❌	Status da conta

cURL
JavaScript
Python

curl -X POST "https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1/conta" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "cpfCliente: 12345678901" \
  -H "Content-Type: application/json" \
  -d '{
    "codigoCliente": 123456,
    "codigoCompe": "001",
    "nomeInstituicao": "BANCO DO BRASIL S.A.",
    "numeroAgencia": "1234",
    "numeroConta": "123456",
    "dvConta": "7",
    "ispb": "00000000",
    "tipoConta": "CC",
    "status": "A"
  }'

const response = await fetch(`${API_BASE}/conta`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'cpfCliente': '12345678901',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    codigoCliente: 123456,
    codigoCompe: '001',
    nomeInstituicao: 'BANCO DO BRASIL S.A.',
    numeroAgencia: '1234',
    numeroConta: '123456',
    dvConta: '7',
    ispb: '00000000',
    tipoConta: 'CC',
    status: 'A'
  })
});
const resultado = await response.json();
console.log('✅ Conta registrada, ID:', resultado.idConta);

response = requests.post(
    f'{API_BASE}/conta',
    headers={
        'Authorization': f'Bearer {TOKEN}',
        'cpfCliente': '12345678901',
        'Content-Type': 'application/json'
    },
    json={
        'codigoCliente': 123456,
        'codigoCompe': '001',
        'nomeInstituicao': 'BANCO DO BRASIL S.A.',
        'numeroAgencia': '1234',
        'numeroConta': '123456',
        'dvConta': '7',
        'ispb': '00000000',
        'tipoConta': 'CC',
        'status': 'A'
    },
    timeout=15
)
print(f'✅ Conta registrada: {response.json()["idConta"]}')

Exemplo de resposta (201 Created):

{
  "idConta": 123456
}

5️⃣ Gerar Pré-Contrato

Gera o pré-contrato com todas as condições do empréstimo para o cliente visualizar antes de efetivar. Retorna o documento em PDF codificado em Base64.

Endpoint: GET /precontrato

Parâmetros (Header):

Header	Tipo	Obrigatório	Descrição
`Authorization`	string	✅	Bearer token JWT
`cpfCliente`	string	✅	CPF do cliente
`valorEmprestimo`	number	✅	Valor líquido do empréstimo
`valorTotalIof`	number	✅	Valor total do IOF
`valorTotal`	number	✅	Valor total final
`taxaMes`	number	✅	Taxa de juros mensal
`taxaAno`	number	✅	Taxa de juros anual
`taxaCetMes`	number	✅	CET mensal
`taxaCetAno`	number	✅	CET anual
`codigoCompe`	string	✅	Código do banco
`numeroAgencia`	string	✅	Número da agência
`numeroConta`	string	✅	Número da conta
`tipoConta`	string	✅	`CC` ou `PP`
`numeroParcela`	integer	✅	Quantidade de parcelas
`dataVencimentoParcela`	datetime	✅	Data da 1ª parcela
`valorParcela`	number	✅	Valor de cada parcela
`valorTotalSeguro`	number	✅	Valor do seguro (0 se não contratado)

cURL
JavaScript
Python

curl -X GET "https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1/precontrato" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "cpfCliente: 12345678901" \
  -H "valorEmprestimo: 5000" \
  -H "valorTotalIof: 326" \
  -H "valorTotal: 5826" \
  -H "taxaMes: 2.99" \
  -H "taxaAno: 42.58" \
  -H "taxaCetMes: 3.15" \
  -H "taxaCetAno: 45.20" \
  -H "codigoCompe: 001" \
  -H "numeroAgencia: 1234" \
  -H "numeroConta: 123456-7" \
  -H "tipoConta: CC" \
  -H "numeroParcela: 12" \
  -H "dataVencimentoParcela: 2026-05-28T00:00:00.000Z" \
  -H "valorParcela: 485.50" \
  -H "valorTotalSeguro: 0"

const response = await fetch(`${API_BASE}/precontrato`, {
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'cpfCliente': '12345678901',
    'valorEmprestimo': '5000',
    'valorTotalIof': '326',
    'valorTotal': '5826',
    'taxaMes': '2.99',
    'taxaAno': '42.58',
    'taxaCetMes': '3.15',
    'taxaCetAno': '45.20',
    'codigoCompe': '001',
    'numeroAgencia': '1234',
    'numeroConta': '123456-7',
    'tipoConta': 'CC',
    'numeroParcela': '12',
    'dataVencimentoParcela': '2026-05-28T00:00:00.000Z',
    'valorParcela': '485.50',
    'valorTotalSeguro': '0'
  }
});
const data = await response.json();
// data.pdfBase64 contém o PDF em Base64

response = requests.get(
    f'{API_BASE}/precontrato',
    headers={
        'Authorization': f'Bearer {TOKEN}',
        'cpfCliente': '12345678901',
        'valorEmprestimo': '5000',
        'valorTotalIof': '326',
        'valorTotal': '5826',
        'taxaMes': '2.99',
        'taxaAno': '42.58',
        'taxaCetMes': '3.15',
        'taxaCetAno': '45.20',
        'codigoCompe': '001',
        'numeroAgencia': '1234',
        'numeroConta': '123456-7',
        'tipoConta': 'CC',
        'numeroParcela': '12',
        'dataVencimentoParcela': '2026-05-28T00:00:00.000Z',
        'valorParcela': '485.50',
        'valorTotalSeguro': '0'
    },
    timeout=15
)
dados = response.json()
# dados['pdfBase64'] contém o PDF em Base64

Exemplo de resposta (200 OK):

{
  "numeroContrato": 123,
  "pdfBase64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...",
  "dataEmissao": "2026-04-27T19:54:31.995Z"
}

Importante

O pré-contrato é gerado em PDF Base64 e deve ser apresentado ao cliente para leitura e aceite. O cliente deve concordar com os termos antes da efetivação.

6️⃣ Efetivar Empréstimo

Realiza a efetivação de um empréstimo pessoal para o cliente, gerando o contrato e iniciando a transferência.

Endpoint: POST /efetivacao

Headers:

Header	Tipo	Obrigatório	Descrição
`Authorization`	string	✅	Bearer token JWT
`cpfCliente`	string	✅	CPF do cliente

Corpo da Requisição:

Campo	Tipo	Obrigatório	Descrição
`codigoCliente`	integer	✅	Código do cliente
`idCanal`	integer	✅	Canal de contratação
`codigoEstabelecimento`	integer	✅	Código do estabelecimento
`numeroBin`	integer	✅	BIN do cartão
`idApp`	integer	❌	ID do aplicativo
`valor`	number	✅	Valor do empréstimo
`quantidadeParcela`	integer	✅	Quantidade de parcelas
`dataHoraContratacao`	datetime	❌	Data/hora da contratação
`idEmprestimoPessoal`	integer	❌	ID do empréstimo
`codigoCartao`	string	❌	Código do cartão
`dataHoraAceite`	datetime	❌	Data/hora do aceite do cliente
`Conta`	object	✅	Dados da conta (ver abaixo)
`origemLojista`	boolean	❌	Origem (default: false)
`seguroAceito`	boolean	❌	Seguro contratado (default: false)

Objeto Conta:

Campo	Tipo	Obrigatório	Descrição
`codigoCompe`	string	✅	Código do banco
`numeroAgencia`	string	✅	Agência
`numeroConta`	string	✅	Conta
`dvConta`	string	✅	Dígito verificador
`tipoConta`	string	✅	`CC` ou `PP`

cURL
JavaScript
Python

curl -X POST "https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1/efetivacao" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "cpfCliente: 12345678901" \
  -H "Content-Type: application/json" \
  -d '{
    "codigoCliente": 12345,
    "idCanal": 1,
    "codigoEstabelecimento": 1234567,
    "numeroBin": 12345678,
    "idApp": 1,
    "valor": 3000.00,
    "quantidadeParcela": 12,
    "dataHoraContratacao": "2026-04-13T23:54:45.686Z",
    "idEmprestimoPessoal": 16,
    "codigoCartao": "12345678",
    "dataHoraAceite": "2026-04-13T23:54:45.686Z",
    "Conta": {
      "codigoCompe": "001",
      "numeroAgencia": "1234",
      "numeroConta": "12345",
      "dvConta": "6",
      "tipoConta": "CC"
    },
    "origemLojista": false,
    "seguroAceito": false
  }'

const response = await fetch(`${API_BASE}/efetivacao`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'cpfCliente': '12345678901',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    codigoCliente: 12345,
    idCanal: 1,
    codigoEstabelecimento: 1234567,
    numeroBin: 12345678,
    idApp: 1,
    valor: 3000.00,
    quantidadeParcela: 12,
    dataHoraContratacao: '2026-04-13T23:54:45.686Z',
    idEmprestimoPessoal: 16,
    codigoCartao: '12345678',
    dataHoraAceite: '2026-04-13T23:54:45.686Z',
    Conta: {
      codigoCompe: '001',
      numeroAgencia: '1234',
      numeroConta: '12345',
      dvConta: '6',
      tipoConta: 'CC'
    },
    origemLojista: false,
    seguroAceito: false
  })
});
const resultado = await response.json();
console.log('✅ Contrato:', resultado.numeroContrato);

response = requests.post(
    f'{API_BASE}/efetivacao',
    headers={
        'Authorization': f'Bearer {TOKEN}',
        'cpfCliente': '12345678901',
        'Content-Type': 'application/json'
    },
    json={
        'codigoCliente': 12345,
        'idCanal': 1,
        'codigoEstabelecimento': 1234567,
        'numeroBin': 12345678,
        'idApp': 1,
        'valor': 3000.00,
        'quantidadeParcela': 12,
        'dataHoraContratacao': '2026-04-13T23:54:45.686Z',
        'idEmprestimoPessoal': 16,
        'codigoCartao': '12345678',
        'dataHoraAceite': '2026-04-13T23:54:45.686Z',
        'Conta': {
            'codigoCompe': '001',
            'numeroAgencia': '1234',
            'numeroConta': '12345',
            'dvConta': '6',
            'tipoConta': 'CC'
        },
        'origemLojista': False,
        'seguroAceito': False
    },
    timeout=15
)
dados = response.json()
print(f'✅ Contrato gerado: {dados["numeroContrato"]}')

Exemplo de resposta (201 Created):

{
  "numeroContrato": 987654,
  "valorParcela": 272.01,
  "dataPrimeiroVencimento": "2026-05-10"
}

Empréstimo Efetivado!

O valor será transferido para a conta do cliente. O contrato está criado e as parcelas já estão agendadas.

7️⃣ Consultar Empréstimos do Cliente

Lista todos os empréstimos pessoais efetivados do cliente, incluindo ativos, cancelados, rejeitados e liquidados.

Endpoint: GET /efetivacao

Headers:

Header	Tipo	Obrigatório	Descrição
`Authorization`	string	✅	Bearer token JWT
`cpfCliente`	string	✅	CPF do cliente

cURL
JavaScript
Python

curl -X GET "https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1/efetivacao" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "cpfCliente: 12345678901"

const response = await fetch(`${API_BASE}/efetivacao`, {
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'cpfCliente': '12345678901'
  }
});
const emprestimos = await response.json();

response = requests.get(
    f'{API_BASE}/efetivacao',
    headers={'Authorization': f'Bearer {TOKEN}', 'cpfCliente': '12345678901'},
    timeout=15
)
emprestimos = response.json()

Exemplo de resposta (200 OK):

[
  {
    "idEmprestimoPessoal": 123,
    "codigoCliente": 123456789,
    "numeroBin": 12345678,
    "valorContratacao": 3000.00,
    "valorPrestacao": 272.01,
    "quantidadeParcela": 12,
    "dataHoraContratacao": "2026-04-13T23:54:45.686Z",
    "dataHorasTransferencia": "2026-04-13T23:54:45.686Z",
    "codigoEstabelecimento": 123456,
    "nomeFantasia": "LOJA PARCEIRA",
    "canalContratacao": "Loja",
    "statusEmprestimo": "A",
    "numeroContrato": 5678901,
    "valorTotalJuros": 202.59,
    "valorTotalIof": 60.87,
    "taxaMes": 1.00,
    "cetMensal": 1.32,
    "flagPagamentoEmAtraso": false,
    "flagSeguroAceito": false,
    "diaVencimento": 10,
    "Conta": {
      "codigoCompe": "001",
      "numeroAgencia": "1234",
      "numeroConta": "12345",
      "dvConta": "6",
      "tipoConta": "CC",
      "nomeInstituicao": "BANCO DO BRASIL S.A."
    }
  }
]

Status do Empréstimo (statusEmprestimo):

Código	Descrição
`A`	Ativo
`C`	Cancelado
`R`	Rejeitado
`L`	Liquidado
`T`	Cancelado (Transferência)
`D`	Cancelado (Desistência)

8️⃣ Consultar Agendamentos

Lista os agendamentos de empréstimo pessoal de um cliente.

Endpoint: GET /agendamento

Headers:

Header	Tipo	Obrigatório	Descrição
`Authorization`	string	✅	Bearer token JWT
`cpfCliente`	string	✅	CPF do cliente

cURL
JavaScript
Python

curl -X GET "https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1/agendamento" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "cpfCliente: 12345678901"

const response = await fetch(`${API_BASE}/agendamento`, {
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'cpfCliente': '12345678901'
  }
});
const agendamentos = await response.json();

response = requests.get(
    f'{API_BASE}/agendamento',
    headers={'Authorization': f'Bearer {TOKEN}', 'cpfCliente': '12345678901'},
    timeout=15
)
agendamentos = response.json()

Exemplo de resposta (200 OK):

[
  {
    "idEmprestimoPessoal": 123456,
    "codigoCliente": 1234567,
    "numeroBin": 12345678,
    "valorContratacao": 3000.00,
    "valorPrestacao": 272.01,
    "quantidadeParcela": 12,
    "dataHoraPrevisaoProcessamento": "2026-04-13T23:54:45.686Z",
    "dataHoraContratacao": "2026-04-13T12:45:45.686Z",
    "codigoEstabelecimento": 123,
    "nomeFantasia": "LOJA PARCEIRA",
    "canalContratacao": "LOJA",
    "diaVencimento": 10,
    "Conta": {
      "codigoCompe": "001",
      "numeroAgencia": "1234",
      "numeroConta": "12345",
      "dvConta": "6",
      "tipoConta": "CC",
      "nomeInstituicao": "BANCO DO BRASIL S.A."
    }
  }
]

Cancelar Agendamento

Realiza o cancelamento de um agendamento de empréstimo pessoal. Permitido apenas para agendamentos não efetivados.

Endpoint: POST /agendamento/cancelamento

Corpo da Requisição:

Campo	Tipo	Obrigatório	Descrição
`idAgendamento`	integer	✅	ID do agendamento a cancelar
`idCanal`	integer	✅	Canal do agendamento
`origemLojista`	boolean	❌	Origem (default: false)

cURL
JavaScript
Python

curl -X POST "https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1/agendamento/cancelamento" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "idAgendamento": 123456,
    "idCanal": 123,
    "origemLojista": false
  }'

const response = await fetch(`${API_BASE}/agendamento/cancelamento`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    idAgendamento: 123456,
    idCanal: 123,
    origemLojista: false
  })
});
const resultado = await response.json();
console.log('✅', resultado.mensagem);

response = requests.post(
    f'{API_BASE}/agendamento/cancelamento',
    headers={'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json'},
    json={'idAgendamento': 123456, 'idCanal': 123, 'origemLojista': False},
    timeout=15
)
print(f'✅ {response.json()["mensagem"]}')

Exemplo de resposta (201 Created):

{
  "mensagem": "Cancelamento realizado com sucesso"
}

Atenção

O cancelamento é irreversível. Só é possível cancelar agendamentos que ainda não foram processados.

9️⃣ Consultar Parcelas

Retorna as parcelas de um empréstimo pessoal com status de pagamento e boleto.

Endpoint: GET /parcela

Headers:

Header	Tipo	Obrigatório	Descrição
`Authorization`	string	✅	Bearer token JWT
`numeroContrato`	integer	✅	Número do contrato

cURL
JavaScript
Python

curl -X GET "https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1/parcela" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "numeroContrato: 987654321"

const response = await fetch(`${API_BASE}/parcela`, {
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'numeroContrato': '987654321'
  }
});
const parcelas = await response.json();
parcelas.forEach(p => {
  const status = p.flagPagamentoRealizado ? '✅' : '⏳';
  console.log(`${status} Parcela ${p.numeroParcela}: R$ ${p.valor} - Venc: ${p.dataVencimento}`);
});

response = requests.get(
    f'{API_BASE}/parcela',
    headers={'Authorization': f'Bearer {TOKEN}', 'numeroContrato': '987654321'},
    timeout=15
)
for p in response.json():
    status = '✅' if p['flagPagamentoRealizado'] else '⏳'
    print(f"{status} Parcela {p['numeroParcela']}: R$ {p['valor']} - Venc: {p['dataVencimento']}")

Exemplo de resposta (200 OK):

[
  {
    "numeroParcela": 1,
    "valor": 272.01,
    "dataVencimento": "05/05/2026",
    "dataRegistroBoleto": "05/04/2026",
    "flagRegistroBoleto": true,
    "dataPagamento": "05/05/2026",
    "valorPagamento": 272.01,
    "flagPagamentoRealizado": true
  },
  {
    "numeroParcela": 2,
    "valor": 272.01,
    "dataVencimento": "05/06/2026",
    "dataRegistroBoleto": "05/05/2026",
    "flagRegistroBoleto": true,
    "dataPagamento": null,
    "valorPagamento": null,
    "flagPagamentoRealizado": false
  }
]

🔟 Consultar Contrato (PDF)

Retorna todos os detalhes de um contrato específico de empréstimo, incluindo o documento em PDF codificado em Base64.

Endpoint: GET /contrato

Headers:

Header	Tipo	Obrigatório	Descrição
`Authorization`	string	✅	Bearer token JWT
`numeroContrato`	integer	✅	Número do contrato

cURL
JavaScript
Python

curl -X GET "https://apihml.credsystem.com.br/emprestimo-pessoal-lojista/api/v1/contrato" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "numeroContrato: 987654321"

const response = await fetch(`${API_BASE}/contrato`, {
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'numeroContrato': '987654321'
  }
});
const data = await response.json();
// Converter Base64 em PDF para download
const blob = new Blob(
  [Uint8Array.from(atob(data.pdfBase64), c => c.charCodeAt(0))],
  { type: 'application/pdf' }
);

import base64

response = requests.get(
    f'{API_BASE}/contrato',
    headers={'Authorization': f'Bearer {TOKEN}', 'numeroContrato': '987654321'},
    timeout=15
)
dados = response.json()

# Salvar PDF do contrato
with open(f'contrato_{dados["numeroContrato"]}.pdf', 'wb') as f:
    f.write(base64.b64decode(dados['pdfBase64']))
print(f'✅ Contrato salvo: contrato_{dados["numeroContrato"]}.pdf')

Exemplo de resposta (200 OK):

{
  "numeroContrato": 900016363,
  "pdfBase64": "JVBERi0xLjQKJaqrrK0KMSAwIG9...",
  "dataEmissao": "2026-04-24T15:08:52.165Z"
}

⚠️ Respostas de Erro

Todos os endpoints retornam erros no seguinte formato:

{
  "error": {
    "message": "Bad Request",
    "detail": "Código do cliente é inválido",
    "code": 400,
    "instance": "20260413020409"
  }
}

HTTP Status	Descrição	Ação recomendada
`400`	Requisição inválida	Verifique campos obrigatórios e formatos
`401`	Token inválido/expirado	Renove o token JWT
`503`	Serviço indisponível	Aguarde e tente novamente (retry com backoff)

🔧 Problemas?

Consulte o Guia de Troubleshooting para soluções detalhadas por endpoint.

🎯 Visão Geral​

🔐 Autenticação​

📚 Endpoints Disponíveis​

1️⃣ Verificar Elegibilidade do Cliente​

2️⃣ Simular Planos de Empréstimo​

3️⃣ Listar Bancos Habilitados​

4️⃣ Gerenciar Contas Bancárias​

Consultar Contas do Cliente​

Registrar Nova Conta​

5️⃣ Gerar Pré-Contrato​

6️⃣ Efetivar Empréstimo​

7️⃣ Consultar Empréstimos do Cliente​

8️⃣ Consultar Agendamentos​

Cancelar Agendamento​

9️⃣ Consultar Parcelas​

🔟 Consultar Contrato (PDF)​

⚠️ Respostas de Erro​

🎯 Visão Geral

🔐 Autenticação

📚 Endpoints Disponíveis

1️⃣ Verificar Elegibilidade do Cliente

2️⃣ Simular Planos de Empréstimo

3️⃣ Listar Bancos Habilitados

4️⃣ Gerenciar Contas Bancárias

Consultar Contas do Cliente

Registrar Nova Conta

5️⃣ Gerar Pré-Contrato

6️⃣ Efetivar Empréstimo

7️⃣ Consultar Empréstimos do Cliente

8️⃣ Consultar Agendamentos

Cancelar Agendamento

9️⃣ Consultar Parcelas

🔟 Consultar Contrato (PDF)

⚠️ Respostas de Erro