Erros Comuns - ecosif-auth

Este documento lista os erros mais comuns ao integrar com a API ecosif-auth e como resolvê-los.

Erros de Autenticação

401 Unauthorized - "Token expirado"

Problema: Token JWT expirou (padrão: 30 minutos)

Solução:

// Fazer login novamente
const loginResponse = await fetch('http://localhost:8080/api/auth/signin', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'usuario@exemplo.com',
    password: 'senha123',
    azure: false
  })
});

const { accessToken } = await loginResponse.json();
// Usar novo token

401 Unauthorized - "Token inválido"

Problema: Token malformado ou assinatura inválida

Soluções: 1. Verifique se está incluindo "Bearer " antes do token: ```javascript // Correto headers: { 'Authorization': 'Bearer ' + token }

// Incorreto headers: { 'Authorization': token } ```

Verifique se o token não foi corrompido durante armazenamento
Verifique se está usando a mesma chave secreta (AUTH_TOKEN_SECRET) em todos os serviços

401 Unauthorized - "Credenciais inválidas"

Problema: Username ou senha incorretos (autenticação local)

Soluções: 1. Verifique se o username está correto 2. Verifique se a senha está correta 3. Verifique se o usuário existe no sistema 4. Verifique se está usando autenticação local (azure: false)

400 Bad Request - "Usuário não encontrado" (Azure AD)

Problema: Tentando fazer login externo com usuário que não existe e ECOSIF_AUTH_AUTO_PROVISION=false

Solução: Cadastre o usuário no eCosif ou habilite auto-provision (ECOSIF_AUTH_AUTO_PROVISION=true) e use POST /api/auth/external-login com id_token válido:

curl -X POST http://localhost:8080/api/auth/external-login \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "AZURE",
    "token": "<id_token>",
    "tokenType": "ID_TOKEN"
  }'

Erros de Validação

400 Bad Request - "Username é obrigatório"

Problema: Campo username não foi enviado ou está vazio

Solução:

{
  "username": "usuario@exemplo.com",  // ← Incluir este campo
  "password": "senha123",
  "azure": false
}

400 Bad Request - "Tenant é obrigatório para criação de usuário"

Problema: Tentando criar usuário via Azure AD sem fornecer tenant

Solução:

{
  "username": "usuario@empresa.com",
  "userCreate": {
    "name": "Nome",
    "username": "usuario@empresa.com",
    "tenant": "empresa-exemplo",  // ← Incluir este campo
    "active": true,
    "role": "STAFF"
  }
}

400 Bad Request - "Dados do usuário são obrigatórios para criação"

Problema: Tentando criar usuário sem fornecer userCreate

Solução: Incluir objeto userCreate quando usuário não existir:

{
  "username": "usuario@empresa.com",
  "userCreate": {  // ← Incluir este objeto
    "name": "Nome",
    "username": "usuario@empresa.com",
    "tenant": "empresa-exemplo",
    "active": true
  }
}

Erros de Usuário

401 Unauthorized - "Usuário inativo"

Problema: Usuário existe mas está inativo (active = false)

Solução: - Entre em contato com o administrador para ativar o usuário - Ou ative manualmente no banco de dados (se tiver acesso)

401 Unauthorized - "O usuário expirou"

Problema: Usuário possui data de expiração (expiryDate) no passado

Solução: - Entre em contato com o administrador para renovar a validade do usuário - Ou atualize expiryDate no banco de dados (se tiver acesso)

Erros de Requisição

404 Not Found

Problema: Endpoint não encontrado

Soluções: 1. Verifique a URL do endpoint 2. Verifique se está usando o método HTTP correto (GET, POST, etc.) 3. Verifique o context-path (padrão: /)

415 Unsupported Media Type

Problema: Header Content-Type incorreto ou ausente

Solução: Inclua o header correto:

headers: {
  'Content-Type': 'application/json'  // ← Sempre incluir para POST/PUT
}

500 Internal Server Error

Problema: Erro interno do servidor

Soluções: 1. Verifique os logs do servidor 2. Verifique se o banco de dados está acessível 3. Entre em contato com a equipe de desenvolvimento 4. Verifique se todas as variáveis de ambiente estão configuradas

Erros de Endpoint Administrativo

400 Bad Request - "Serviço não encontrado"

Problema: Serviço solicitado não está na lista de serviços permitidos

Solução: Use um dos serviços válidos: - ecosif-auth - ecosif-masterdata - ecosif-moviments - ecosif-querys - ecosif-reports - ecosif-compliance - ecosif-angular - nginx - postgres

Para listar serviços disponíveis:

curl -X GET "http://localhost:8080/api/admin/docker-logs/services" \
  -H "Authorization: Bearer $TOKEN"

401 Unauthorized - Endpoints Administrativos

Problema: Tentando acessar endpoint administrativo sem autenticação

Solução: Inclua token JWT válido:

headers: {
  'Authorization': 'Bearer ' + token  // ← Sempre incluir
}

Erros de Rede

Erro de Conexão

Problema: Não é possível conectar ao servidor

Soluções: 1. Verifique se o servidor está rodando 2. Verifique se a URL está correta 3. Verifique firewall/proxy 4. Verifique se está usando HTTPS em produção

Timeout

Problema: Requisição demora muito para responder

Soluções: 1. Aumente o timeout da requisição 2. Verifique a performance do servidor 3. Verifique conexão com banco de dados

Erros de CORS

CORS Error no Navegador

Problema: Navegador bloqueia requisição por CORS

Solução: 1. Verifique se a origem está configurada em ECOSIF_CORS 2. Em desenvolvimento, use a mesma origem ou configure CORS corretamente 3. Em produção, configure CORS para o domínio da aplicação

Checklist de Troubleshooting

Antes de reportar um problema, verifique:

[ ] URL do endpoint está correta
[ ] Método HTTP está correto (GET, POST, etc.)
[ ] Headers necessários estão incluídos (Content-Type, Authorization)
[ ] Body JSON está formatado corretamente
[ ] Token JWT está válido e não expirado
[ ] Servidor está rodando e acessível
[ ] Variáveis de ambiente estão configuradas corretamente
[ ] Logs do servidor foram verificados

Como Reportar Problemas

Ao reportar um problema, inclua:

Endpoint: URL completa do endpoint
Método HTTP: GET, POST, etc.
Request: Body e headers da requisição (sem informações sensíveis)
Response: Código de status e body da resposta
Erro esperado vs. atual: O que esperava vs. o que recebeu
Ambiente: Versão da API, ambiente (dev/prod), etc.
Logs: Logs relevantes do servidor (se disponível)

Recursos Adicionais

Autenticação: Como autenticar corretamente
Uso da API: Como usar a API
Exemplos: Exemplos de requisições

Suporte

Se o problema persistir:

Consulte a documentação completa em /docs
Teste no Swagger UI: http://localhost:8080/swagger-ui.html
Entre em contato com a equipe de desenvolvimento