🔧 Troubleshooting — Empréstimo Pessoal Lojista

Este guia ajuda você a identificar e resolver problemas comuns ao integrar com a API de Empréstimo Pessoal Lojista.

---

🎯 Início Rápido: Checklist de Debug

Antes de abrir um chamado de suporte, verifique:

• Token válido: Seu JWT está dentro da validade?
• Headers corretos: Header Authorization: Bearer <token> está presente?
• CPF no header: O header cpfCliente foi enviado nos endpoints que o exigem?
• URL correta: Está usando HML ou PRD apropriadamente?
• Formato JSON: Body está em JSON válido com Content-Type: application/json?
• Campos obrigatórios: Todos os campos required foram enviados?
• Tipo de dados: Números são numbers (não strings) no body?

---

📚 Erros Comuns por Endpoint

1️⃣ Elegibilidade (POST /elegibilidade)

⚠️ 400 Bad Request

Possíveis Causas:

Detalhe	Solução
Código do cliente é inválido	Verifique se codigoCliente é um inteiro válido e existe na base
Campo(s) obrigatório(s)	Envie todos os campos obrigatórios: codigoCliente, numeroBin, idCanal, codigoEstabelecimento
cpfCliente é obrigatório	Adicione o header cpfCliente com 11 dígitos numéricos
codigoEstabelecimento inválido	Verifique se o código é numérico e pertence à sua rede

Exemplo de requisição correta:

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

⚠️ 401 Unauthorized

Possíveis Causas:

Detalhe	Solução
Autenticação inválida	Token JWT inválido ou mal formatado. Gere um novo token
Token expirado	Tokens têm validade limitada. Implemente renovação automática
Authorization ausente	Adicione header: Authorization: Bearer <seu_token>

Como renovar o token:

1. Faça nova requisição ao endpoint de autenticação (Client Credentials)
2. Guarde o novo access_token
3. Use o campo expires_in para renovar antes de expirar

⚠️ 503 Service Unavailable

Possíveis Causas:

Detalhe	Solução
Serviço indisponível	Sistema de elegibilidade temporariamente fora. Tente novamente após 30 segundos

Implementação de retry com backoff exponencial:

async function comRetry(fn, tentativas = 3) {
  for (let i = 0; i < tentativas; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status !== 503 || i === tentativas - 1) throw error;
      await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
    }
  }
}

---

2️⃣ Simulação de Plano (GET /simulacao-plano)

⚠️ 400 Bad Request

Possíveis Causas:

Detalhe	Solução
valorTransacao é obrigatório	Adicione header valorTransacao com valor numérico
cpfCliente é obrigatório	Adicione header cpfCliente
Valor fora do limite permitido	O valor deve estar entre o valorMinimoEmprestimo e valorMaximoEmprestimo retornados pela elegibilidade

Dica: Sempre use os valores retornados pelo endpoint de elegibilidade como referência para o valorTransacao.

⚠️ 401 Unauthorized

Detalhe	Solução
Autenticação inválida	Renove o token JWT

---

3️⃣ Bancos (GET /banco)

⚠️ 400 Bad Request

Possíveis Causas:

Detalhe	Solução
ativoSpb formato inválido	O valor deve ser true ou false (boolean como string no header)

⚠️ 503 Service Unavailable

Detalhe	Solução
Serviço indisponível	Serviço de bancos temporariamente indisponível. Tente novamente

Dica: A lista de bancos muda com pouca frequência. Considere cachear por 1-4 horas.

---

4️⃣ Contas (GET/POST /conta)

⚠️ 400 Bad Request — GET /conta

Detalhe	Solução
cpfCliente é obrigatório	Adicione o header cpfCliente
CPF inválido	Verifique se o CPF tem 11 dígitos numéricos

⚠️ 400 Bad Request — POST /conta

Detalhe	Solução
codigoCliente é obrigatório	Informe o código do cliente no body
codigoCompe é obrigatório	Informe o código do banco (use os valores de GET /banco)
tipoConta inválido	Use apenas CC (Conta Corrente) ou PP (Poupança)
dvConta é obrigatório	Informe o dígito verificador da conta
Conta já cadastrada	O cliente já possui essa conta registrada

Validações importantes:

• codigoCompe: use os códigos retornados pelo endpoint /banco
• tipoConta: apenas CC ou PP
• status: apenas A (Ativa), I (Inativa) ou R (Rejeitada)

---

5️⃣ Pré-Contrato (GET /precontrato)

⚠️ 400 Bad Request

Detalhe	Solução
Campo(s) obrigatório(s)	Todos os 16 headers são obrigatórios. Verifique se enviou todos
tipoConta inválido	Use apenas CC ou PP
dataVencimentoParcela formato inválido	Use formato ISO 8601: 2026-05-28T00:00:00.000Z
valorEmprestimo deve ser numérico	Envie valores numéricos sem aspas no header

Checklist de headers obrigatórios:

cpfCliente, valorEmprestimo, valorTotalIof, valorTotal,
taxaMes, taxaAno, taxaCetMes, taxaCetAno,
codigoCompe, numeroAgencia, numeroConta, tipoConta,
numeroParcela, dataVencimentoParcela, valorParcela, valorTotalSeguro

⚠️ 503 Service Unavailable

Detalhe	Solução
Serviço indisponível	Geração de PDF temporariamente indisponível. Aguarde e tente novamente

---

6️⃣ Efetivação (GET/POST /efetivacao)

⚠️ 400 Bad Request — POST /efetivacao

Detalhe	Solução
codigoCliente é obrigatório	Informe no body
valor é obrigatório	Informe o valor do empréstimo
quantidadeParcela é obrigatório	Informe a quantidade de parcelas escolhida
Conta é obrigatório	Informe o objeto Conta com todos os campos obrigatórios
Conta.codigoCompe é obrigatório	Preencha todos os campos do objeto Conta
Conta.tipoConta inválido	Use apenas CC ou PP
Cliente não elegível	Verifique elegibilidade novamente antes de efetivar
Valor fora do limite	O valor deve estar entre mínimo e máximo da elegibilidade

⚠️ 400 Bad Request — GET /efetivacao

Detalhe	Solução
cpfCliente é obrigatório	Adicione o header cpfCliente

⚠️ 503 Service Unavailable

Detalhe	Solução
Serviço indisponível	Sistema de efetivação indisponível. NÃO tente novamente automaticamente — pode gerar duplicidade

Cuidado com retry na efetivação!

Diferente dos outros endpoints, o POST /efetivacao não deve ter retry automático em caso de 503. Aguarde e consulte os empréstimos do cliente (GET /efetivacao) para verificar se a operação foi processada antes de tentar novamente.

---

7️⃣ Agendamentos (GET /agendamento · POST /agendamento/cancelamento)

⚠️ 400 Bad Request — GET /agendamento

Detalhe	Solução
cpfCliente é obrigatório	Adicione o header cpfCliente

⚠️ 400 Bad Request — POST /agendamento/cancelamento

Detalhe	Solução
idAgendamento é obrigatório	Informe o ID do agendamento no body
idCanal é obrigatório	Informe o canal
Agendamento não encontrado	Verifique se o ID está correto via GET /agendamento
Agendamento já processado	Não é possível cancelar agendamentos já efetivados

---

8️⃣ Parcelas (GET /parcela)

⚠️ 400 Bad Request

Detalhe	Solução
numeroContrato é obrigatório	Adicione o header numeroContrato
numeroContrato deve ser inteiro	Envie apenas números inteiros
Contrato não encontrado	Verifique o número do contrato via GET /efetivacao

---

9️⃣ Contrato (GET /contrato)

⚠️ 400 Bad Request

Detalhe	Solução
numeroContrato é obrigatório	Adicione o header numeroContrato
Contrato não encontrado	Verifique o número via GET /efetivacao

⚠️ 503 Service Unavailable

Detalhe	Solução
Serviço indisponível	Geração de PDF temporariamente indisponível

---

🔄 Erros Globais (Todos os Endpoints)

401 Unauthorized

Retornado quando o token JWT é inválido, expirado ou ausente.

Soluções:

1. Verifique se o header Authorization: Bearer <token> está presente
2. Confirme que o token não expirou (use expires_in para controlar)
3. Gere um novo token via endpoint de autenticação
4. Implemente renovação automática (30 segundos antes de expirar)

503 Service Unavailable

Serviço dependente temporariamente indisponível.

Estratégia de retry recomendada:

Endpoint	Pode retry?	Backoff
POST /elegibilidade	✅	2s, 4s, 8s
GET /simulacao-plano	✅	2s, 4s, 8s
GET /banco	✅	2s, 4s
GET/POST /conta	✅	2s, 4s, 8s
GET /precontrato	✅	2s, 4s
POST /efetivacao	⚠️ NÃO	Consultar antes de retentar
GET /efetivacao	✅	2s, 4s
GET /agendamento	✅	2s, 4s
POST /agendamento/cancelamento	⚠️ Verificar	Consultar status antes
GET /parcela	✅	2s, 4s
GET /contrato	✅	2s, 4s

---

💡 Dicas Gerais

Formato de dados

Campo	Formato esperado	Exemplo
CPF	11 dígitos numéricos (sem pontos/traço)	12345678901
Data	ISO 8601	2026-05-28T00:00:00.000Z
Valores monetários	Número decimal	3000.00
Código do banco	String de 3 dígitos	"001"
Tipo de conta	CC ou PP	"CC"

Ordem recomendada de integração

1. POST /elegibilidade     → Verificar se o cliente pode contratar
2. GET /simulacao-plano    → Apresentar opções ao cliente
3. GET /banco              → Listar bancos para seleção
4. GET /conta              → Verificar contas existentes
5. POST /conta             → Registrar nova conta (se necessário)
6. GET /precontrato        → Gerar documento para aceite
7. POST /efetivacao        → Efetivar após aceite do cliente
8. GET /parcela            → Acompanhar parcelas
9. GET /contrato           → Obter PDF quando necessário

---

📞 Suporte

Se o problema persistir após verificar este guia:

1. Colete informações: HTTP status, campo instance do erro, timestamp da requisição
2. Verifique o ambiente: Confirme se está usando HML ou PRD
3. Entre em contato: suporte.tecnico@credsystem.com.br
4. Horário: Segunda a Sexta, 8h às 18h (BRT)