⚡ Troubleshooting e FAQ

Encontrou algum problema na integração? Use este guia para diagnosticar e resolver rapidamente.

🗺️ Diagnóstico Rápido

Minha requisição falhou
    │
    ├── Código 400? ──→ Parâmetros inválidos (veja seção 400)
    ├── Código 401? ──→ Token expirado ou ausente (veja seção 401)
    ├── Código 403? ──→ Sem permissão para esta API (veja seção 403)
    ├── Código 429? ──→ Rate limiting atingido (veja seção 429)
    ├── Código 500? ──→ Erro interno — tente novamente com retry
    └── Timeout?    ──→ Verifique conectividade e timeouts

🔧 Erros por Código HTTP

Referência Rápida

Código	Significado	Causa mais comum	Ação imediata
400	Bad Request	Parâmetros incorretos	Verificar body e Content-Type
401	Unauthorized	Token expirado/ausente	Gerar novo token
403	Forbidden	Sem permissão	Verificar APIs aprovadas
429	Too Many Requests	Rate limit	Aguardar + implementar backoff
500	Internal Error	Erro do servidor	Retry com backoff exponencial

🔴 Erro 401 — Unauthorized

O que significa?

Token inválido, expirado, ausente ou mal formatado. Este é o erro mais comum na integração.

Checklist de diagnóstico:

#	Verificação	Comando/Ação
1	Token está sendo enviado?	Verifique o header `Authorization`
2	Formato correto?	Deve ser `Bearer eyJhbGci...` (com "Bearer ")
3	Token expirou?	Verifique `expires_in` da última geração
4	Credenciais estão corretas?	Gere um novo token para testar

⚠️ Erros comuns no formato do header

✅ Correto:
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR...

❌ Sem prefixo "Bearer":
Authorization: eyJhbGciOiJSUzI1NiIsInR...

❌ Com aspas no token:
Authorization: Bearer "eyJhbGciOiJSUzI1NiIsInR..."

❌ Espaço extra:
Authorization:  Bearer eyJhbGciOiJSUzI1NiIsInR...

❌ Header errado:
Authentication: Bearer eyJhbGciOiJSUzI1NiIsInR...

🟡 Erro 400 — Bad Request

Pode ocorrer em dois momentos diferentes:

🔹 400 na Autenticação OAuth2 — Erro ao gerar o token

Causa: Parâmetros incorretos ou ausentes na chamada de autenticação.

Checklist:

Verificação	Esperado
Content-Type	`application/x-www-form-urlencoded`
grant_type	`client_credentials`
client_id	Sem espaços extras, exatamente como recebido
client_secret	Sem espaços extras, exatamente como recebido

# Requisição correta (todos os parâmetros obrigatórios)
curl -X POST \
  "https://ssoprd.credsystem.com.br/auth/realms/credsystem/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET"

Armadilhas comuns

JSON no body → OAuth2 espera x-www-form-urlencoded, NÃO JSON
Espaço ou quebra de linha no client_secret ao copiar do e-mail
Encoding de caracteres especiais — se o secret tiver +, = ou &, faça URL encode

🔹 400 na API de Negócio — Erro nos dados enviados

Causa: Dados inválidos no corpo da requisição.

Checklist:

Consulte a documentação OpenAPI da API específica
Valide o formato JSON (Content-Type: application/json)
Verifique tipos dos campos (string vs number, formatos de data)
Campos obrigatórios estão todos presentes?
CPF/CNPJ estão no formato esperado? (com ou sem máscara)

🟠 Erro 403 — Forbidden

O que significa?

Seu token é válido, mas você não tem permissão para acessar esta API específica.

Possíveis causas e soluções:

Causa	Solução
API não aprovada para suas credenciais	Verifique o e-mail de aprovação
Ambiente errado (HML vs PRD)	Confirme a URL base da requisição
Recurso específico não autorizado	Confirme se o escopo inclui o recurso
Credenciais de outro projeto	Verifique se está usando o par correto

Precisa de acesso a mais APIs?

Entre em contato com suporte.tecnico@credsystem.com.br informando seu client_id e quais APIs adicionais precisa.

🔵 Erro 429 — Too Many Requests

Limite de requisições atingido

Suas requisições excederam o rate limiting da infraestrutura.

O que fazer imediatamente:

Pare de enviar requisições — aguarde o tempo indicado no header Retry-After (se disponível)
Implemente backoff exponencial com jitter para os retries
Revise seu fluxo — você pode estar gerando tokens desnecessariamente

Prevenção a longo prazo:

Prática	Impacto
Cache de token	Reduz chamadas de autenticação drasticamente
Cache de respostas (quando aplicável)	Reduz chamadas repetidas à API
Retry com backoff exponencial + jitter	Evita "thundering herd"
Webhooks em vez de polling	Elimina requisições desnecessárias

👉 Ver implementações completas em Boas Práticas

⚪ Erro 500+ — Erros do Servidor

Erro temporário

Erros 5xx geralmente são temporários. Implemente retry automático com backoff exponencial.

Estratégia de Retry Recomendada:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tentativa 1 → aguarde  1s  + jitter
Tentativa 2 → aguarde  2s  + jitter
Tentativa 3 → aguarde  4s  + jitter
Tentativa 4 → aguarde  8s  + jitter
Tentativa 5 → aguarde 16s  + jitter (máximo)

⚠️ Se persistir após 5 tentativas → registre o erro e acione o suporte

👉 Ver implementação de retry em 6 linguagens

❓ Perguntas Frequentes

🔐 Credenciais e Acesso

Quanto tempo demora para receber as credenciais?

Após a solicitação pelo Portal do Desenvolvedor, sua solicitação será analisada em até 72 horas úteis.

Fluxo de aprovação:

📋 Solicitação ──→ 🔍 Análise (até 72h) ──→ ✅ Aprovação
                                                  │
                                          ┌───────┴───────┐
                                          ▼               ▼
                                     📂 SharePoint    📧 E-mail
                                     (documentação)   (credenciais)

Não recebeu após 72h úteis?

Verifique a pasta spam/lixo eletrônico
Procure e-mails do domínio @credsystem.com.br
Entre em contato com seu representante comercial

Esqueci minhas credenciais. O que fazer?

Procure no e-mail de aprovação que você recebeu originalmente
Entre em contato com suporte.tecnico@credsystem.com.br
Solicite novas credenciais se necessário (rotação)

Nunca faça isso

❌ Pedir credenciais por canais não seguros (chat, WhatsApp)
❌ Compartilhar credenciais por e-mail sem criptografia
❌ Commitar credenciais no Git

Posso ter múltiplas credenciais?

Sim! Você pode (e é recomendado) solicitar credenciais separadas para:

Cenário	Recomendação
Ambientes diferentes	Credenciais separadas para HML e PRD
Projetos distintos	Um par de credenciais por projeto
Times diferentes	Isolar acesso por equipe

Entre em contato com suporte.tecnico@credsystem.com.br para solicitar.

Como rotacionar minhas credenciais?

Passo a passo:

1. 📧 Solicite → suporte.tecnico@credsystem.com.br
   (informe seu client_id atual)
       │
2. 🔑 Receba novas credenciais
       │
3. 🧪 Teste em HOMOLOGAÇÃO primeiro
       │
4. ✅ Funcionou? → Atualize PRODUÇÃO
       │
5. 🔒 Invalide as credenciais antigas

Importante

Sempre teste as novas credenciais em homologação antes de atualizar produção para evitar downtime.

🔑 Tokens e Autenticação

O token expira em poucos minutos. É normal?

Sim, é normal e intencional!

Tokens de curta duração são uma medida de segurança. Se um token for comprometido, ele expira rapidamente.

O que você DEVE fazer:

Prática	Por quê
Cache de token no backend	Evita gerar novo token a cada request
Renovação automática antes de expirar	Zero downtime na integração
Usar `expires_in` dinâmico	O tempo pode mudar sem aviso
Tratar erro 401 com retry	Fallback para quando o token já expirou

O que NUNCA fazer:

❌ Gerar novo token a cada requisição (desperdiça recursos e pode causar rate limit)
❌ Assumir validade fixa (ex: "sempre 5 min") — use o campo expires_in

👉 Ver implementação de cache de token

Posso usar as APIs direto do navegador (frontend)?

NÃO — Risco de Segurança Crítico

Fazer autenticação no frontend expõe suas credenciais (client_secret). Qualquer pessoa pode abrir o DevTools e ver/copiar suas credenciais.

Arquitetura correta:

✅ CORRETO                           ❌ ERRADO
━━━━━━━━━━━━━━━━━━━━                ━━━━━━━━━━━━━━━━━━━━
Frontend                             Frontend
  │ "Quero listar vendas"              │ client_secret ← EXPOSTO!
  ▼                                    ▼
Backend (SEU)                        API Credsystem
  │ OAuth2 + Token em cache              ← SEM proteção
  ▼
API Credsystem
  ← Token protegido

👉 Ver guia completo de segurança

Posso usar as mesmas credenciais em HML e PRD?

NÃO — Credenciais são separadas por ambiente

Você receberá pares diferentes de client_id + client_secret para cada ambiente.

Ambiente	Uso	URL base
Homologação (HML)	Testes e desenvolvimento	`hml-api.credsystem.com.br`
Produção (PRD)	Dados reais, operação live	`api.credsystem.com.br`

Boas práticas

Use variáveis de ambiente separadas (CRED_HML_SECRET vs CRED_PRD_SECRET)
Nunca use credenciais de produção para testes
Configure seu CI/CD para injetar credenciais corretas por ambiente

📋 APIs e Limites

Como sei quais APIs foram aprovadas para mim?

As APIs aprovadas correspondem exatamente ao que foi solicitado no momento do cadastro. Verifique o e-mail de aprovação para confirmar a lista completa.

Precisa de APIs adicionais?

Entre em contato com suporte.tecnico@credsystem.com.br informando seu client_id e quais APIs adicionais você precisa.

Quantas requisições posso fazer por minuto?

Existem limites de rate limiting para proteger a infraestrutura. Os limites variam por API e plano.

Estratégias para evitar o erro 429:

Estratégia	Impacto
Cache de tokens	⬇️ Reduz chamadas de auth
Cache de respostas	⬇️ Elimina chamadas repetidas
Retry com backoff exponencial	⚡ Recuperação automática
Webhooks em vez de polling	⬇️ Elimina requisições de verificação

👉 Ver implementações completas em Boas Práticas

💬 Precisa de Mais Ajuda?

📧 Suporte Técnico — suporte.tecnico@credsystem.com.br

Ao entrar em contato, inclua as informações abaixo para agilizar o atendimento:

Informação	Exemplo
Empresa/Organização	Loja XYZ Ltda
Client ID	`abc123...` (NUNCA envie o Secret!)
Ambiente	Homologação ou Produção
Código de erro	HTTP 401, 403, etc.
Descrição do problema	"Token expira antes do esperado"
Exemplo de requisição	cURL sem credenciais

📚 Navegação

Documento	Descrição
Índice de Autenticação	Visão geral do fluxo
Passo 1: Solicitar Credenciais	Como obter acesso
Passo 2: Entender Sistemas	Red Hat SSO e Oracle IDCS
Passo 3: Exemplos Práticos	Código em 7 linguagens
Passo 4: Usar Token	Cache, renovação e uso
Segurança	Proteção e auditoria
Boas Práticas	Performance, retry e monitoramento

🗺️ Diagnóstico Rápido​

🔧 Erros por Código HTTP​

🔴 Erro 401 — Unauthorized​

🟡 Erro 400 — Bad Request​

🟠 Erro 403 — Forbidden​

🔵 Erro 429 — Too Many Requests​

⚪ Erro 500+ — Erros do Servidor​

❓ Perguntas Frequentes​

🔐 Credenciais e Acesso​

🔑 Tokens e Autenticação​

📋 APIs e Limites​

💬 Precisa de Mais Ajuda?​

📚 Navegação​