Logo Portal do Desenvolvedor
Logo Credsystem

Menu

Pular para o conteúdo principal

🔧 Troubleshooting - Clientes Lojista

Este guia ajuda você a identificar e resolver problemas comuns ao integrar com a API de Clientes Lojista.

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

Antes de abrir um chamado de suporte, verifique:

  • Token válido: Seu Bearer token está dentro da validade?
  • Headers corretos: Header Authorization: Bearer <token> está presente?
  • URL correta: Está usando HML ou PRD apropriadamente?
  • Pelo menos um identificador: Enviou CPF OU cartão OU ambos?
  • TraceId salvo: Guardou o traceId da requisição com erro?

🔍 Erros comuns por Endpoint​

1️⃣ Consultar Cliente (GET /clientes)​

⚠️ 400 Bad Request

Possíveis Causas e Soluções:​

TítuloDetalheSolução
Authorization é obrigatórioInformar o token de autorização válido.Adicione header:
Authorization: Bearer <seu_token>
Informação obrigatória.Informe o CPF e/ou cartão.Informe cpf OU cartao OU ambos nos headers
Campo(s) obrigatório(s)CPF é obrigatórioCaso tenha enviado o CPF, verifique se é válido.

Exemplo de requisição correta:

# Com CPF e Cartão
curl -X GET "https://apihml.credsystem.com.br/servicos-lojista/api/v1/clientes" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "cpf: 25296540000" \
  -H "cartao: 9604201327474511"

# Apenas com CPF
curl -X GET "https://apihml.credsystem.com.br/servicos-lojista/api/v1/clientes" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "cpf: 25296540000"

# Apenas com Cartão
curl -X GET "https://apihml.credsystem.com.br/servicos-lojista/api/v1/clientes" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "cartao: 9604201327474511"
⚠️ 401 Unauthorized

Possíveis Causas e Soluções:​

TítuloDetalheSolução
Authorization inválidoInforme o token de authorização válido.Obtenha um novo token válido via endpoint de autenticação
Não AutorizadoAuthorization expirado.Tokens têm validade limitada. Renove seu token

Como renovar o token:

  1. Faça nova requisição ao endpoint de autenticação
  2. Guarde o novo token de forma segura
  3. Implemente lógica de renovação automática antes da expiração
  4. Não compartilhe tokens entre ambientes (HML/PRD)

Exemplo de erro:

{
  "tipo": "",
  "titulo": "Não Autorizado",
  "status": 401,
  "detalhe": "Authorization expirado.",
  "instancia": "/api/v1/clientes",
  "traceId": "abc123def456"
}
⚠️ 403 Forbidden

Possíveis Causas e Soluções:​

TítuloDetalheSolução
Acesso negadoVocê não tem permissão para acessar esse recurso.Verifique suas credenciais e permissões de acesso

Possíveis motivos:

  • Token pertence a outro estabelecimento/rede
  • Permissões insuficientes no sistema
  • Cliente bloqueado para consulta

Ação recomendada:

  1. Verifique se o token usado é do estabelecimento correto
  2. Confirme se tem permissão para consultar esse cliente
  3. Entre em contato com o suporte se o problema persistir
⚠️ 404 Not Found

Possíveis Causas e Soluções:​

TítuloDetalheSolução
Dados não encontradosEstabelecimento não encontrado ou não pertence a sua rede.Verifique os dados informados.
Dados não encontradosCliente não encontrado ou não pertence a sua rede.Verifique os dados informados.
Dados não encontradosNenhum cartão foi localizado vinculado à Loja/Rede.Verifique se o cliente pertence a sua rede.

Cenários comuns:

  1. Cliente não cadastrado

    • O CPF não existe na base de dados

  2. Cartão não vinculado ao CPF

    • O cartão existe, mas pertence a outro CPF
    • CPF e cartão enviados não correspondem ao mesmo cliente

  3. Dados incorretos

    • CPF ou cartão digitado errado
    • Dígitos verificadores inválidos

Como resolver:

# Tente com apenas o CPF
curl -X GET "https://apihml.credsystem.com.br/servicos-lojista/api/v1/clientes" \
  -H "Authorization: Bearer <token>" \
  -H "cpf: 25296540000"

# Se não funcionar, tente apenas com o cartão
curl -X GET "https://apihml.credsystem.com.br/servicos-lojista/api/v1/clientes" \
  -H "Authorization: Bearer <token>" \
  -H "cartao: 9604201327474511"
⚠️ 422 Unprocessable Content

Possíveis Causas e Soluções:​

TítuloDetalheSolução
Validação de camposCPF não é válido.Verifique o CPF informado
💥 500 Internal Server Error

Possíveis Causas e Soluções:​

TítuloDetalheSolução
Erro internoOcorreu um erro interno no processamento da consulta.Aguarde alguns minutos e tente novamente
Falha no sistemaErro inesperado ao processar a solicitação.Entre em contato com o suporte informando o traceId

O que fazer:

  1. Primeiro: Salve o traceId retornado no erro
  2. Segundo: Aguarde 1-2 minutos e tente novamente
  3. Terceiro: Se persistir, entre em contato com o suporte

Informações para o suporte:

  • TraceId do erro
  • Horário exato da requisição
  • Headers enviados (sem o token)
  • Ambiente (HML ou PRD)

Exemplo de erro:

{
  "tipo": "",
  "titulo": "Erro interno",
  "status": 500,
  "detalhe": "Ocorreu um erro interno no processamento da consulta.",
  "instancia": "/api/v1/clientes",
  "traceId": "7a89b3c2-d4e5-6f7g-8h9i-j0k1l2m3n4o5"
}
Importante

Erros 500 geralmente são temporários. Se ocorrerem frequentemente, pode indicar um problema mais sério que precisa ser investigado pelo suporte.

💥 503 Service Unavailable

Possíveis Causas e Soluções:​

TítuloDetalheSolução
Serviço indisponívelO serviço está temporariamente indisponível.Implemente retry com backoff exponencial
Falha no processamentoFalha na comunicação com o serviço de consulta.Aguarde e tente novamente
TimeoutO serviço não respondeu dentro do tempo esperado.Aumente o timeout da requisição

📞 Contato com Suporte​

Se o problema persistir após seguir este guia:

Informações para incluir no chamado:​

  1. TraceId da requisição com erro
  2. Timestamp de quando ocorreu
  3. Endpoint que estava sendo acessado
  4. Dados enviados (remova informações sensíveis)
  5. Resposta recebida (completa)
  6. Ambiente (HML ou PRD)
  7. Passos para reproduzir o problema

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​

Homologação (HML)​

  • URL Base: https://apihml.credsystem.com.br/servicos-lojista/api/v1
  • Propósito: Testes e desenvolvimento
  • Dados: Fictícios, podem ser deletados
  • SLA: Sem garantia de disponibilidade 24/7

Produção (PRD)​

  • URL Base: https://api.credsystem.com.br/servicos-lojista/api/v1
  • Propósito: Operação real
  • Dados: Reais, não podem ser deletados
  • SLA: 99.9% de disponibilidade

📊 Status da API​

Para verificar o status em tempo real da API:

🔗 Status Page (se disponível)

📚 Recursos Adicionais​