Logo Portal do Desenvolvedor
Logo Credsystem

Menu

Pular para o conteúdo principal

🔧 Troubleshooting - Acesso e Onboarding

Este guia ajuda você a identificar e resolver problemas comuns nos fluxos de login, primeiro acesso, recuperação de senha e troca de dispositivo.

🎯 Início Rápido: Checklist de Debug​

Antes de abrir um chamado de suporte, verifique:

  • Credenciais válidas: client_id e client_secret estão corretos?
  • Realm correto: O {realm} na URL está correto para o seu ambiente?
  • Content-Type: Está usando application/x-www-form-urlencoded para o login?
  • Token de sessão: O token retornado na validação de dados está sendo usado nos passos seguintes?
  • URL correta: Está usando HML ou PRD apropriadamente?
  • Formato JSON: Body está em JSON válido (para endpoints de identificação)?
  • CPF válido: O CPF informado é válido e está cadastrado?

📑 Índice por Fluxo​

📚 Erros Comuns por Endpoint​

🔑 Login / Autenticação​

Obter Token de Acesso (Login) (POST /token)​

⚠️ 400 Bad Request
MensagemDetalheSolução
Parâmetros ausentesgrant_type, client_id ou client_secret não enviadosVerifique se todos os campos obrigatórios estão no body como x-www-form-urlencoded
grant_type inválidoValor de grant_type não reconhecidoUse password para login ou refresh_token para renovação
⛔ 401 Unauthorized
MensagemDetalheSolução
Credenciais inválidasclient_id ou client_secret incorretosConfirme as credenciais com a equipe de suporte. Credenciais de HML ≠ PRD
Usuário/senha incorretosusername ou password não correspondemVerifique se o usuário existe e a senha está correta
Realm incorretoO realm na URL não existeConfirme o realm correto para seu APP com a equipe técnica

👤 Primeiro Acesso / 🔑 Recuperação de Senha / 📲 Troca de Dispositivo​

nota

Os endpoints abaixo são compartilhados entre os fluxos de Primeiro Acesso, Recuperação de Senha e Troca de Dispositivo.

Validar Dados do Cliente (POST /identificacao/dados)​

⚠️ 400 Bad Request
MensagemDetalheSolução
Dados inválidosCPF, data de nascimento ou nome da mãe não conferemVerifique se os dados informados estão corretos e correspondem ao cadastro
CPF inválidoCPF com formato inválido ou dígitos incorretosEnvie apenas números (11 dígitos). Valide os dígitos verificadores
Campos obrigatórioscpf, dataNascimento ou nomeMae ausentesTodos os 3 campos são obrigatórios no body JSON
🔍 404 Not Found
MensagemDetalheSolução
Cliente não encontradoCPF não localizado na base de clientesConfirme o CPF com o cliente. Ele precisa ter um cartão Credsystem ativo

Solicitar Biometria (POST /identificacao/biometria)​

⚠️ 400 Bad Request
MensagemDetalheSolução
Consumidor obrigatórioCampo consumidor não enviado no bodyEnvie o campo consumidor com o código do cliente no body JSON
⛔ 401 Unauthorized
MensagemDetalheSolução
Token inválidoO token de sessão é inválido ou expiradoUse o token retornado no passo 1 (validação de dados). Tokens de sessão expiram em 15 minutos

Enviar Código SMS (POST /identificacao/token-sms/envio)​

⛔ 401 Unauthorized
MensagemDetalheSolução
Token inválidoToken de sessão expirado ou não reconhecidoReinicie o fluxo desde o passo 1 se o token expirou (15 min)
💥 500 Internal Server Error
MensagemDetalheSolução
Erro no envioFalha no serviço de SMSTente novamente em alguns segundos. Se persistir, contate o suporte

Validar Código SMS (POST /identificacao/token-sms)​

⚠️ 400 Bad Request
MensagemDetalheSolução
Código inválidoO código SMS digitado não confereVerifique se o código foi digitado corretamente. Códigos expiram após alguns minutos
Código expiradoO tempo de validade do código SMS passouSolicite um novo código via POST /identificacao/token-sms/envio
Tentativas excedidasNúmero máximo de tentativas atingidoReinicie o fluxo desde o passo 1

Validar Perguntas de Segurança (POST /identificacao/perguntas)​

⚠️ 400 Bad Request
MensagemDetalheSolução
Respostas incorretasUma ou mais respostas não conferemPeça ao cliente para verificar as respostas. As perguntas são sobre dados cadastrais
Campos obrigatóriosAs respostas não foram enviadasEnvie todas as respostas no body JSON conforme as perguntas retornadas

Obter Termo de Aceite (GET /contratos/termo-aceite)​

⛔ 401 Unauthorized
MensagemDetalheSolução
Token inválidoToken de sessão expiradoReinicie o fluxo se o token de sessão expirou

Aceitar Termo de Aceite (PUT /contratos/termo-aceite)​

⛔ 401 Unauthorized
MensagemDetalheSolução
Token inválidoToken de sessão expiradoReinicie o fluxo se o token de sessão expirou

Criar/Atualizar Senha (POST /usuario/acesso)​

⚠️ 400 Bad Request
MensagemDetalheSolução
Senha não atende requisitosA senha informada não cumpre as regras de complexidadeA senha deve ter no mínimo 6 caracteres, incluindo letras e números
Senhas não conferemO campo de confirmação não bate com a senhaCertifique-se de que os campos senha e confirmação são idênticos
⛔ 401 Unauthorized
MensagemDetalheSolução
Token inválidoToken de sessão expiradoReinicie o fluxo completo desde o passo 1

🔄 Erros Gerais (Todos os Fluxos)​

⛔ 401 — Token de Sessão Expirado

Sintoma: Após o passo 1 funcionar, os passos seguintes retornam 401.

Causa: O token de sessão retornado na validação de dados expira em 15 minutos.

Solução:

  1. Reinicie o fluxo desde o passo 1 (Validar Dados)
  2. Implemente controle de tempo para alertar o usuário antes de expirar
  3. Não armazene tokens de sessão por mais de 15 minutos
💥 500 — Erro no Envio de SMS

Sintoma: O passo de envio de SMS retorna 500 intermitentemente.

Solução:

  1. Aguarde 10 segundos e tente novamente
  2. Implemente retry com backoff (10s, 20s, 30s)
  3. Se persistir após 3 tentativas, abra chamado com suporte
🌐 CORS / Content-Type Incorreto

Sintoma: Erro de CORS ou 415 Unsupported Media Type no login.

Solução:

  1. O endpoint de login (/token) usa Content-Type: application/x-www-form-urlencoded, não JSON
  2. Os endpoints de identificação (/identificacao/*) usam Content-Type: application/json
  3. Chamadas à API devem ser feitas pelo backend, não pelo frontend
🔒 Realm Incorreto

Sintoma: 404 ou 401 ao tentar login mesmo com credenciais corretas.

Solução:

  1. O {realm} na URL do Keycloak é específico para cada APP/parceiro
  2. Confirme o realm com a equipe técnica da Credsystem
  3. Realms de HML ≠ PRD

📞 Contato com Suporte​

Se o problema persistir após seguir este guia:

Informações para incluir no chamado:​

  1. Fluxo que estava sendo executado (Login, Primeiro Acesso, Recuperação, Troca)
  2. Passo em que o erro ocorreu (1, 2, 3...)
  3. Timestamp de quando ocorreu o erro
  4. Dados enviados (remova informações sensíveis como senhas e tokens)
  5. Resposta recebida (completa, incluindo status code e body)
  6. Ambiente (HML ou PRD)
  7. Realm utilizado na URL

Canais de Contato:​

Tempo de Resposta:​

  • 🔴 Crítico (produção parada): 2 horas
  • 🟡 Alto (funcionalidade impactada): 8 horas
  • 🟢 Normal (dúvidas, melhorias): 24 horas

🔄 Ambientes​

ServiçoURL HMLURL PRD
Keycloak (Login)https://ssohml.credsystem.com.br/auth/realms/{realm}/protocol/openid-connecthttps://ssoprd.credsystem.com.br/auth/realms/{realm}/protocol/openid-connect
Sessão/Identificaçãohttps://apihml.credsystem.com.br/api/v1https://api.credsystem.com.br/api/v1

🎓 Recursos Adicionais​