jcae/pagasis

Fork 0

forked from val-lop20/Pagina-de-Asistencia-MAC

Files

T

Valeria López a683957af6 Primer commit - Sistema de asistencia MAC

2025-10-15 23:45:32 -06:00

12 KiB

Raw Blame History

Sistema de Asistencia MAC - Documentación de API

Información General

Version: 1.0.0
Base URL: http://localhost/api/
Autenticación: JWT Bearer Token
Formato: JSON

Inicio Rápido

Acceder a la Documentación

API Root (JSON): http://localhost/api/ 🔒 Requiere Autenticación
Documentación HTML: http://localhost/api/docs/ 🔒 Requiere Autenticación
Panel Admin: http://localhost/admin/

Nota: Los endpoints /api/ y /api/docs/ ahora requieren autenticación JWT. Primero debes hacer login en /api/auth/login/ para obtener un token de acceso.

Flujo Básico

Login: Obtener tokens de acceso
Usar Token: Incluir en header Authorization
Refrescar Token: Cuando expire el access token

Autenticación

La API utiliza JWT (JSON Web Tokens) para autenticación.

Obtener Token

POST /api/auth/login/
Content-Type: application/json

{
  "account_number": "3123123"
}

Respuesta:

{
  "message": "Login exitoso",
  "user": {
    "id": 3,
    "username": "3123123",
    "profile": {
      "account_number": "3123123",
      "user_type": "assistant",
      "full_name": "pancho"
    }
  },
  "tokens": {
    "access": "eyJhbGci....",
    "refresh": "eyJhbGci...."
  }
}

Usar Token

Para endpoints que requieren autenticación, incluye el header:

Authorization: Bearer <your_access_token>

Refrescar Token

POST /api/auth/token/refresh/
Content-Type: application/json

{
  "refresh": "<your_refresh_token>"
}

Endpoints

Authentication Endpoints

POST /api/auth/login/

Descripción: Iniciar sesión con número de cuenta

Auth Required: ❌ No

Body:

{
  "account_number": "1234567"
}

Response 200:

{
  "message": "Login exitoso",
  "user": { ... },
  "tokens": {
    "access": "...",
    "refresh": "..."
  }
}

Response 400:

{
  "account_number": ["El número de cuenta debe tener exactamente 7 dígitos."]
}

2. Logout

POST /api/auth/logout/

Descripción: Cerrar sesión

Auth Required: ✅ Sí

Response 200:

{
  "message": "Logout exitoso"
}

3. Get Profile

GET /api/auth/profile/

Descripción: Obtener perfil del usuario autenticado

Auth Required: ✅ Sí

Response 200:

{
  "id": 3,
  "username": "3123123",
  "email": "",
  "profile": {
    "account_number": "3123123",
    "user_type": "assistant",
    "full_name": "pancho"
  },
  "is_staff": false
}

4. Check Auth Status

GET /api/auth/check-auth/

Descripción: Verificar si el usuario está autenticado

Auth Required: ❌ No

Response 200:

{
  "is_authenticated": true,
  "user": { ... }
}

5. Refresh Token

POST /api/auth/token/refresh/

Descripción: Refrescar access token usando refresh token

Auth Required: ❌ No

Body:

{
  "refresh": "<refresh_token>"
}

Response 200:

{
  "access": "<new_access_token>"
}

6. System Configuration

GET /api/auth/system-config/

Descripción: Obtener configuración del sistema

Auth Required: ✅ Sí

Response 200:

{
  "minimum_attendance_percentage": 80.0,
  "minutes_before_event": 10,
  "minutes_after_start": 25
}

Events Endpoints

1. List Events

GET /api/events/

Descripción: Listar todos los eventos activos

Auth Required: ❌ No

Response 200:

[
  {
    "id": 1,
    "title": "Inteligencia Artificial",
    "description": "Conferencia sobre IA",
    "event_type": "conference",
    "modality": "presencial",
    "speaker": "Dr. García",
    "date": "2025-10-12",
    "start_time": "10:00:00",
    "end_time": "12:00:00",
    "location": "Auditorio A",
    "max_capacity": 100,
    "is_active": true
  }
]

2. Register External User

POST /api/events/external/register/

Descripción: Registrar un usuario externo para eventos

Auth Required: ✅ Sí (Solo asistentes)

Body:

{
  "full_name": "Juan Pérez",
  "account_number": "9999999"
}

Response 201:

{
  "id": 10,
  "full_name": "Juan Pérez",
  "account_number": "9999999",
  "status": "approved"
}

3. Search External Users

GET /api/events/external/search/?account_number=9999999

Descripción: Buscar usuarios externos

Auth Required: ✅ Sí

Query Parameters:

account_number (string): Número de cuenta a buscar

Response 200:

[
  {
    "id": 10,
    "full_name": "Juan Pérez",
    "account_number": "9999999",
    "status": "approved"
  }
]

4. Approve External User

POST /api/events/external/<user_id>/approve/

Descripción: Aprobar un usuario externo

Auth Required: ✅ Sí (Solo asistentes)

Body:

{
  "approved": true
}

Response 200:

{
  "message": "Usuario aprobado exitosamente"
}

Attendance Endpoints

1. Register Attendance

POST /api/attendance/

Descripción: Registrar asistencia a un evento

Auth Required: ✅ Sí (Solo asistentes)

Body:

{
  "event_id": 1,
  "account_number": "3123123",
  "registration_method": "manual"
}

Response 201:

{
  "id": 42,
  "event": 1,
  "timestamp": "2025-10-12T10:30:00Z",
  "is_valid": true
}

2. Get Student Stats

GET /api/attendance/stats/?account_number=0000111

Descripción: Obtener estadísticas de asistencia de un estudiante

Auth Required: ✅ Sí

Query Parameters:

account_number (string): Número de cuenta del estudiante

Response 200:

{
  "total_events": 10,
  "attended_events": 8,
  "attendance_percentage": 80.0,
  "meets_minimum": true
}

3. Get Recent Attendances

GET /api/attendance/recent/

Descripción: Obtener asistencias recientes (últimas 50)

Auth Required: ✅ Sí

Response 200:

[
  {
    "id": 42,
    "student": {
      "account_number": "0000111",
      "full_name": "María García"
    },
    "event": {
      "id": 1,
      "title": "Inteligencia Artificial"
    },
    "timestamp": "2025-10-12T10:30:00Z",
    "is_valid": true
  }
]

4. Get My Attendances

GET /api/attendance/my/

Descripción: Obtener mis asistencias registradas

Auth Required: ✅ Sí

Response 200:

[
  {
    "id": 42,
    "event": {
      "id": 1,
      "title": "Inteligencia Artificial",
      "date": "2025-10-12",
      "start_time": "10:00:00"
    },
    "timestamp": "2025-10-12T10:30:00Z",
    "is_valid": true
  }
]

Códigos de Estado

Código	Descripción
200	OK - Solicitud exitosa
201	Created - Recurso creado exitosamente
400	Bad Request - Datos inválidos
401	Unauthorized - No autenticado o token inválido
403	Forbidden - Sin permisos
404	Not Found - Recurso no encontrado
429	Too Many Requests - Rate limit excedido
500	Internal Server Error - Error del servidor

Ejemplos con cURL

curl -X POST http://localhost/api/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"account_number":"3123123"}'

2. Obtener perfil (con token)

TOKEN="your_access_token_here"

curl -X GET http://localhost/api/auth/profile/ \
  -H "Authorization: Bearer $TOKEN"

3. Listar eventos

curl -X GET http://localhost/api/events/

4. Registrar asistencia

TOKEN="your_access_token_here"

curl -X POST http://localhost/api/attendance/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": 1,
    "account_number": "0000111",
    "registration_method": "manual"
  }'

5. Obtener estadísticas

TOKEN="your_access_token_here"

curl -X GET "http://localhost/api/attendance/stats/?account_number=0000111" \
  -H "Authorization: Bearer $TOKEN"

6. Refrescar token

REFRESH_TOKEN="your_refresh_token_here"

curl -X POST http://localhost/api/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d "{\"refresh\":\"$REFRESH_TOKEN\"}"

Testing con Postman

Importar Collection

Descarga la colección: postman_collection.json
En Postman: File → Import
Selecciona el archivo JSON

Variables de Entorno

Crea un entorno con estas variables:

{
  "base_url": "http://localhost",
  "access_token": "",
  "refresh_token": "",
  "account_number": "3123123"
}

Workflow de Testing

Login: Ejecuta el request de login
Set Token: Copia el access_token a la variable de entorno
Test Endpoints: Ejecuta otros requests usando {{access_token}}

Rate Limiting

La API implementa rate limiting para prevenir abuso:

Login: 5 intentos por minuto por IP
Check Auth: 30 consultas por minuto por IP
Token Refresh: 10 intentos por minuto por IP

Errores Comunes

401 Unauthorized

Causa: Token inválido o expirado

Solución: Refrescar el token o hacer login nuevamente

# Refrescar token
curl -X POST http://localhost/api/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh":"<refresh_token>"}'

400 Bad Request

Causa: Datos inválidos en el request

Solución: Verificar el formato y campos requeridos

{
  "account_number": ["El número de cuenta debe tener exactamente 7 dígitos."]
}

429 Too Many Requests

Causa: Rate limit excedido

Solución: Esperar un minuto antes de reintentar

Best Practices

1. Manejo de Tokens

// Guardar tokens
localStorage.setItem('access_token', response.tokens.access);
localStorage.setItem('refresh_token', response.tokens.refresh);

// Incluir en requests
headers: {
  'Authorization': `Bearer ${localStorage.getItem('access_token')}`
}

// Refrescar cuando expire
if (error.status === 401) {
  // Intentar refrescar
  const newToken = await refreshToken();
  // Reintentar request original
}

2. Manejo de Errores

try {
  const response = await fetch('/api/endpoint/', options);
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Request failed');
  }
  return await response.json();
} catch (error) {
  console.error('API Error:', error);
  // Mostrar mensaje al usuario
}

3. Rate Limiting

// Implementar backoff exponencial
const retryWithBackoff = async (fn, retries = 3) => {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < retries - 1) {
        await new Promise(r => setTimeout(r, 2 ** i * 1000));
        continue;
      }
      throw error;
    }
  }
};

Seguridad

Headers de Seguridad

La API implementa los siguientes headers de seguridad:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

CORS

CORS está configurado para permitir requests desde:

http://localhost
http://127.0.0.1

HTTPS

En producción, siempre usar HTTPS para proteger los tokens.

Soporte

Documentación: http://localhost/api/docs/
Admin Panel: http://localhost/admin/
Issues: https://github.com/yourusername/mac_attendance/issues

Changelog

v1.0.0 (2025-10-12)

✅ Autenticación JWT
✅ Gestión de eventos
✅ Registro de asistencias
✅ Estadísticas de asistencia
✅ Usuarios externos
✅ Rate limiting
✅ Documentación completa

12 KiB Raw Blame History

Sistema de Asistencia MAC - Documentación de API

Información General

Índice

Inicio Rápido

Acceder a la Documentación

Flujo Básico

Autenticación

Obtener Token

Usar Token

Refrescar Token

Endpoints

Authentication Endpoints

1. Login

2. Logout

3. Get Profile

4. Check Auth Status

5. Refresh Token

6. System Configuration

Events Endpoints

1. List Events

2. Register External User

3. Search External Users

4. Approve External User

Attendance Endpoints

1. Register Attendance

2. Get Student Stats

3. Get Recent Attendances

4. Get My Attendances

Códigos de Estado

Ejemplos con cURL

1. Login y obtener token

2. Obtener perfil (con token)

3. Listar eventos

4. Registrar asistencia

5. Obtener estadísticas

6. Refrescar token

Testing con Postman

Importar Collection

Variables de Entorno

Workflow de Testing

Rate Limiting

Errores Comunes

401 Unauthorized

400 Bad Request

429 Too Many Requests

Best Practices

1. Manejo de Tokens

2. Manejo de Errores

3. Rate Limiting

Seguridad

Headers de Seguridad

CORS

HTTPS

Soporte

Changelog

v1.0.0 (2025-10-12)

12 KiB

Raw Blame History