Autenticación y Seguridad

🔐 Autenticación API TitanicSoft - SYNERGY

Descripción General

La API de TitanicSoft utiliza autenticación basada en JWT (JSON Web Tokens) para proteger todos los endpoints. El proceso de autenticación sigue el estándar Bearer Token Authentication.

---

📍 Endpoint de Autenticación

POST /auth/login

Base URL: {URL_BASE}/auth/login

Método HTTP: POST

Content-Type: application/json

---

📥 Petición (Request)

Headers Requeridos

Content-Type: application/json

Body (JSON)

{
  "usuario": "string",
  "password": "string"
}

Parámetros

Campo	Tipo	Requerido	Descripción
usuario	string	✅ Sí	Nombre de usuario del sistema
password	string	✅ Sí	Contraseña del usuario

Ejemplo de Petición

{
  "usuario": "synergy_api",
  "password": "Mi_Contraseña_Segura_123"
}

---

📤 Respuestas (Responses)

✅ Autenticación Exitosa (200 OK)

Cuando las credenciales son válidas y el usuario está activo.

Código HTTP: 200

Body:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200abc123..."
}

Descripción de campos:

Campo	Tipo	Descripción
token	string	Token JWT para usar en las siguientes peticiones
token_type	string	Tipo de token (siempre “Bearer”)
expires_in	number	Tiempo de expiración del token en segundos (1 hora)
refresh_token	string	Token para renovar la sesión (futuro uso)

---

❌ Errores de Autenticación

1. Método HTTP Incorrecto (405 Method Not Allowed)

Cuando se usa un método diferente a POST (ej: GET, PUT, DELETE).

Código HTTP: 405

{
  "codigo_http": 405,
  "estado": "method_not_allowed",
  "mensaje": "Método no permitido"
}

---

2. Error de Validación (400 Bad Request)

Cuando faltan campos requeridos o están vacíos.

Código HTTP: 400

{
  "codigo_http": 400,
  "estado": "validation_error",
  "mensaje": "Error en la validación",
  "detalles": {
    "usuario": "El campo usuario es requerido",
    "password": "El campo password es requerido"
  }
}

Casos comunes:

• Campo usuario vacío o no enviado
• Campo password vacío o no enviado

---

3. Credenciales Incorrectas (401 Unauthorized)

Cuando el usuario no existe o la contraseña es incorrecta.

Código HTTP: 401

{
  "codigo_http": 401,
  "estado": "unauthorized",
  "mensaje": "Credenciales incorrectas"
}

Motivos:

• Usuario no existe en la base de datos
• Contraseña incorrecta

Nota de Seguridad: Por razones de seguridad, no se especifica si el error es por usuario inexistente o contraseña incorrecta.

---

4. Usuario Suspendido (403 Forbidden)

Cuando el usuario existe pero ha sido suspendido.

Código HTTP: 403

{
  "codigo_http": 403,
  "estado": "forbidden",
  "mensaje": "Usuario suspendido"
}

Motivo:

• La cuenta del usuario tiene el flag fl_suspendido = 1

---

5. Error del Servidor (500 Internal Server Error)

Cuando ocurre un error inesperado en el servidor.

Código HTTP: 500

{
  "codigo_http": 500,
  "estado": "server_error",
  "mensaje": "Error interno del servidor"
}

---

🔑 Uso del Token en Peticiones Posteriores

Una vez autenticado exitosamente, todas las peticiones a los endpoints protegidos deben incluir el token en el header Authorization.

Header de Autorización

Authorization: Bearer {token}

Ejemplo Completo

GET /api/persona HTTP/1.1
Host: api.titanicsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

---

⏱️ Expiración del Token

• Tiempo de vida: 1 hora (3600 segundos)
• Después de este tiempo, se deberá solicitar un nuevo token mediante el endpoint /auth/login

Respuestas por Token Expirado o Inválido

Cuando intentas usar un endpoint protegido con un token inválido o expirado:

Token Expirado

Código HTTP: 401

{
  "codigo_http": 401,
  "estado": "token_expired",
  "mensaje": "Token ha expirado"
}

Token Inválido o Malformado

Código HTTP: 401

{
  "codigo_http": 401,
  "estado": "unauthorized",
  "mensaje": "Token inválido"
}

Token No Proporcionado

Código HTTP: 401

{
  "codigo_http": 401,
  "estado": "unauthorized",
  "mensaje": "Token de autorización requerido"
}

Sesión Expirada en Base de Datos

Código HTTP: 401

{
  "codigo_http": 401,
  "estado": "session_expired",
  "mensaje": "Sesión expirada. Debe iniciar sesión nuevamente."
}

Token Usado Desde Otro Dispositivo

Código HTTP: 401

{
  "codigo_http": 401,
  "estado": "token_mismatch",
  "mensaje": "Token no válido. Sesión iniciada desde otro dispositivo."
}

---

🛡️ Rate Limiting (Control de Frecuencia)

La API implementa un control de frecuencia de peticiones para prevenir abuso.

Límite: 10 peticiones por minuto por usuario

Respuesta cuando se excede el límite

Código HTTP: 429

{
  "codigo_http": 429,
  "estado": "rate_limit_exceeded",
  "mensaje": "Límite de peticiones excedido. Máximo 10 peticiones por minuto.",
  "retry_after": 60
}

---

📋 Flujo de Autenticación Completo

┌─────────────┐
│   Cliente   │
│  (Synergy)  │
└──────┬──────┘
       │
       │ 1. POST /auth/login
       │    { usuario, password }
       │
       ▼
┌─────────────────┐
│  API TitanicSoft │
│                  │
│  ✓ Valida método │
│  ✓ Valida campos │
│  ✓ Busca usuario │
│  ✓ Valida estado │
│  ✓ Verifica pwd  │
│  ✓ Genera JWT    │
└──────┬──────────┘
       │
       │ 2. Respuesta con Token
       │    { token, expires_in, ... }
       │
       ▼
┌─────────────┐
│   Cliente   │
│  (Synergy)  │
│             │
│ Almacena    │
│ token       │
└──────┬──────┘
       │
       │ 3. Peticiones subsecuentes
       │    Authorization: Bearer {token}
       │
       ▼
┌─────────────────┐
│  API TitanicSoft │
│                  │
│  ✓ Valida token  │
│  ✓ Verifica DB   │
│  ✓ Procesa       │
└─────────────────┘

---

📝 Notas Importantes

1. Seguridad del Token:

   • El token debe mantenerse seguro y no compartirse
   • Debe transmitirse siempre por HTTPS
   • No debe almacenarse en lugares inseguros

2. Renovación de Sesión:

   • Cuando el token expire, se debe solicitar uno nuevo mediante /auth/login
   • El campo refresh_token está presente pero aún no implementado

3. Múltiples Dispositivos:

   • Si un usuario inicia sesión desde otro dispositivo, el token anterior quedará invalidado
   • Esto es por seguridad: solo puede haber una sesión activa por usuario

4. Algoritmo de Hash:

   • Las contraseñas se hashean usando SHA-512 con un salt único por usuario
   • Formato: hash('sha512', password . salt)

---

🧪 Ejemplo de Prueba con cURL

# Autenticación
curl -X POST https://api.titanicsoft.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "usuario": "synergy_api",
    "password": "Mi_Contraseña_Segura_123"
  }'

# Respuesta:
# {
#   "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
#   "token_type": "Bearer",
#   "expires_in": 3600,
#   "refresh_token": "def50200..."
# }

# Uso del token en petición posterior
curl -X GET https://api.titanicsoft.com/api/persona \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json"

---

🧪 Ejemplo con Postman

1. Autenticación

Request:

• Method: POST
• URL: {{BASE_URL}}/auth/login
• Headers:
  • Content-Type: application/json
• Body (raw JSON):

{
  "usuario": "synergy_api",
  "password": "Mi_Contraseña_Segura_123"
}

Scripts - Tests:

// Guardar el token automáticamente
if (pm.response.code === 200) {
    var jsonData = pm.response.json();
    pm.environment.set("auth_token", jsonData.token);
}

2. Uso en Endpoints Protegidos

Request:

• Method: POST / PUT / GET / DELETE
• URL: {{BASE_URL}}/api/{endpoint}
• Headers:
  • Authorization: Bearer {{auth_token}}
  • Content-Type: application/json

---

🔗 Endpoints Relacionados

• Siguiente: 02_PERSONAS.md - Gestión de Personas (Clientes, Proveedores, Personal)
• Ver también: Todos los endpoints requieren autenticación excepto /auth/login

---

Versión: 1.0
Última actualización: Enero 2026
Contacto: Equipo TitanicSoft