gitea/checklist
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ad59152ccecc69580874e80123ad867495cd1800
checklist/API_DOCUMENTATION.md

18 KiB
Raw Blame History

📚 Documentación API - Syntria

🔐 Autenticación

Todos los endpoints (excepto /api/auth/login y /api/auth/register) requieren autenticación mediante token JWT en el header:

Authorization: Bearer {token}

🔑 AUTH - Autenticación

1. Login

POST /api/auth/login

Inicia sesión y obtiene el token de acceso.

Body:

{
  "username": "admin",
  "password": "admin123"
}

Response 200:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "username": "admin",
    "email": "admin@syntria.com",
    "full_name": "Administrador",
    "role": "admin",
    "is_active": true,
    "created_at": "2025-11-19T00:00:00Z"
  }
}

Errores:

  • 401 Unauthorized - Usuario o contraseña incorrectos

2. Registro

POST /api/auth/register

Crea una nueva cuenta de usuario.

Body:

{
  "username": "nuevo_usuario",
  "password": "password123",
  "email": "usuario@email.com",
  "full_name": "Usuario Nuevo",
  "role": "mechanic"
}

Response 200:

{
  "id": 2,
  "username": "nuevo_usuario",
  "email": "usuario@email.com",
  "full_name": "Usuario Nuevo",
  "role": "mechanic",
  "is_active": true,
  "created_at": "2025-11-19T00:00:00Z"
}

Errores:

  • 400 Bad Request - Usuario ya existe

3. Obtener Mi Perfil

GET /api/auth/me

Obtiene la información del usuario autenticado.

Headers:

Authorization: Bearer {token}

Response 200:

{
  "id": 1,
  "username": "admin",
  "email": "admin@syntria.com",
  "full_name": "Administrador",
  "role": "admin",
  "is_active": true,
  "created_at": "2025-11-19T00:00:00Z"
}

👥 USERS - Gestión de Usuarios

1. Listar Usuarios (Admin)

GET /api/users

Lista todos los usuarios del sistema.

Query Params:

  • skip (int, default: 0) - Paginación
  • limit (int, default: 100) - Límite de resultados
  • active_only (bool, default: false) - Solo usuarios activos

Headers:

Authorization: Bearer {token}

Response 200:

[
  {
    "id": 1,
    "username": "admin",
    "email": "admin@syntria.com",
    "full_name": "Administrador",
    "role": "admin",
    "is_active": true,
    "created_at": "2025-11-19T00:00:00Z"
  },
  {
    "id": 2,
    "username": "mecanico",
    "email": "mecanico@syntria.com",
    "full_name": "Mecánico",
    "role": "mechanic",
    "is_active": true,
    "created_at": "2025-11-19T00:00:00Z"
  }
]

Errores:

  • 403 Forbidden - No tienes permisos (solo admin)

2. Obtener Usuario por ID (Admin)

GET /api/users/{user_id}

Obtiene un usuario específico.

Headers:

Authorization: Bearer {token}

Response 200:

{
  "id": 2,
  "username": "mecanico",
  "email": "mecanico@syntria.com",
  "full_name": "Mecánico",
  "role": "mechanic",
  "is_active": true,
  "created_at": "2025-11-19T00:00:00Z"
}

Errores:

  • 403 Forbidden - No tienes permisos
  • 404 Not Found - Usuario no encontrado

3. Crear Usuario (Admin)

POST /api/users

Crea un nuevo usuario.

Headers:

Authorization: Bearer {token}

Body:

{
  "username": "nuevo_mecanico",
  "password": "password123",
  "email": "mecanico2@syntria.com",
  "full_name": "Mecánico 2",
  "role": "mechanic"
}

Response 200:

{
  "id": 3,
  "username": "nuevo_mecanico",
  "email": "mecanico2@syntria.com",
  "full_name": "Mecánico 2",
  "role": "mechanic",
  "is_active": true,
  "created_at": "2025-11-19T00:00:00Z"
}

Errores:

  • 400 Bad Request - Usuario ya existe o email en uso
  • 403 Forbidden - No tienes permisos

4. Actualizar Usuario (Admin)

PUT /api/users/{user_id}

Actualiza información de un usuario.

Headers:

Authorization: Bearer {token}

Body:

{
  "username": "nuevo_username",
  "email": "nuevo_email@syntria.com",
  "full_name": "Nombre Actualizado",
  "role": "admin"
}

Response 200:

{
  "id": 2,
  "username": "nuevo_username",
  "email": "nuevo_email@syntria.com",
  "full_name": "Nombre Actualizado",
  "role": "admin",
  "is_active": true,
  "created_at": "2025-11-19T00:00:00Z"
}

Notas:

  • El campo is_active NO puede ser modificado por este endpoint
  • Para cambiar el estado usar /deactivate o /activate

Errores:

  • 400 Bad Request - Email o username ya en uso
  • 403 Forbidden - No tienes permisos
  • 404 Not Found - Usuario no encontrado

5. Inactivar Usuario (Admin)

PATCH /api/users/{user_id}/deactivate

Inactiva un usuario (soft delete).

Headers:

Authorization: Bearer {token}

Response 200:

{
  "message": "Usuario inactivado correctamente",
  "user_id": 2
}

Errores:

  • 400 Bad Request - No puedes inactivar tu propio usuario
  • 403 Forbidden - No tienes permisos
  • 404 Not Found - Usuario no encontrado

6. Activar Usuario (Admin)

PATCH /api/users/{user_id}/activate

Reactiva un usuario inactivo.

Headers:

Authorization: Bearer {token}

Response 200:

{
  "message": "Usuario activado correctamente",
  "user_id": 2
}

Errores:

  • 403 Forbidden - No tienes permisos
  • 404 Not Found - Usuario no encontrado

7. Cambiar Contraseña de Usuario (Admin)

PATCH /api/users/{user_id}/password

Cambia la contraseña de cualquier usuario.

Headers:

Authorization: Bearer {token}

Body:

{
  "new_password": "nueva_password123"
}

Response 200:

{
  "message": "Contraseña actualizada correctamente"
}

Errores:

  • 403 Forbidden - No tienes permisos
  • 404 Not Found - Usuario no encontrado

8. Actualizar Mi Perfil

PUT /api/users/me

Actualiza tu propio perfil.

Headers:

Authorization: Bearer {token}

Body:

{
  "email": "mi_nuevo_email@syntria.com",
  "full_name": "Mi Nuevo Nombre"
}

Response 200:

{
  "id": 1,
  "username": "admin",
  "email": "mi_nuevo_email@syntria.com",
  "full_name": "Mi Nuevo Nombre",
  "role": "admin",
  "is_active": true,
  "created_at": "2025-11-19T00:00:00Z"
}

Errores:

  • 400 Bad Request - Email ya en uso

9. Cambiar Mi Contraseña

PATCH /api/users/me/password

Cambia tu propia contraseña.

Headers:

Authorization: Bearer {token}

Body:

{
  "current_password": "password_actual",
  "new_password": "nueva_password123"
}

Response 200:

{
  "message": "Contraseña actualizada correctamente"
}

Errores:

  • 400 Bad Request - Contraseña actual incorrecta

🔑 API TOKENS - Tokens de Acceso API

Autenticación con API Tokens

Además de JWT tokens, puedes usar API tokens persistentes para autenticación. Los API tokens:

  • Tienen el prefijo syntria_
  • No expiran (hasta que sean revocados)
  • Se rastrean por último uso
  • Pueden ser gestionados desde el panel de usuario

Uso:

curl -H "Authorization: Bearer syntria_xxxxxxxxxxxxx" http://api/inspections

1. Listar Mis Tokens

GET /api/users/me/tokens

Lista todos tus API tokens.

Headers:

Authorization: Bearer {token}

Response 200:

[
  {
    "id": 1,
    "description": "Token para integración con sistema externo",
    "is_active": true,
    "last_used_at": "2025-11-19T14:30:00Z",
    "created_at": "2025-11-15T10:00:00Z"
  }
]

Nota: El valor del token no se muestra por seguridad.

2. Generar Nuevo Token

POST /api/users/me/tokens

Genera un nuevo API token.

Headers:

Authorization: Bearer {token}

Body:

{
  "description": "Token para integración con sistema externo"
}

Response 200:

{
  "id": 1,
  "token": "syntria_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "description": "Token para integración con sistema externo",
  "is_active": true,
  "last_used_at": null,
  "created_at": "2025-11-19T15:00:00Z"
}

⚠️ IMPORTANTE: El token completo solo se muestra una vez. Guárdalo de forma segura.

3. Revocar Mi Token

DELETE /api/users/me/tokens/{token_id}

Revoca (desactiva) uno de tus tokens.

Headers:

Authorization: Bearer {token}

Response 200:

{
  "message": "Token revocado correctamente",
  "token_id": 1
}

Errores:

  • 404 Not Found - Token no encontrado

4. Listar Tokens de Usuario (Admin)

GET /api/users/{user_id}/tokens

Lista todos los tokens de un usuario específico.

Headers:

Authorization: Bearer {token}

Response 200:

[
  {
    "id": 1,
    "description": "Token de producción",
    "is_active": true,
    "last_used_at": "2025-11-19T14:30:00Z",
    "created_at": "2025-11-15T10:00:00Z"
  }
]

Errores:

  • 403 Forbidden - No tienes permisos (solo admin)

5. Revocar Token de Usuario (Admin)

DELETE /api/users/{user_id}/tokens/{token_id}

Revoca un token de cualquier usuario.

Headers:

Authorization: Bearer {token}

Response 200:

{
  "message": "Token revocado correctamente",
  "token_id": 1
}

Errores:

  • 403 Forbidden - No tienes permisos (solo admin)
  • 404 Not Found - Token no encontrado

📋 CHECKLISTS - Plantillas de Inspección

1. Listar Checklists

GET /api/checklists

Lista todas las plantillas de inspección.

Query Params:

  • skip (int, default: 0)
  • limit (int, default: 100)
  • active_only (bool, default: false) - Solo activas

Headers:

Authorization: Bearer {token}

Response 200:

[
  {
    "id": 1,
    "name": "Inspección Pre-Entrega",
    "description": "Checklist para vehículos antes de entrega",
    "ai_mode": "off",
    "scoring_enabled": true,
    "logo_url": null,
    "max_score": 100,
    "is_active": true,
    "created_at": "2025-11-19T00:00:00Z",
    "creator_id": 1
  }
]

2. Crear Checklist (Admin)

POST /api/checklists

Crea una nueva plantilla de inspección.

Headers:

Authorization: Bearer {token}

Body:

{
  "name": "Inspección de Mantenimiento",
  "description": "Checklist para mantenimiento preventivo",
  "ai_mode": "off",
  "scoring_enabled": true,
  "logo_url": null
}

Response 200:

{
  "id": 2,
  "name": "Inspección de Mantenimiento",
  "description": "Checklist para mantenimiento preventivo",
  "ai_mode": "off",
  "scoring_enabled": true,
  "logo_url": null,
  "max_score": 0,
  "is_active": true,
  "created_at": "2025-11-19T00:00:00Z",
  "creator_id": 1
}

Errores:

  • 403 Forbidden - No tienes permisos

❓ QUESTIONS - Preguntas del Checklist

1. Crear Pregunta (Admin)

POST /api/questions

Agrega una pregunta a un checklist.

Headers:

Authorization: Bearer {token}

Body:

{
  "checklist_id": 1,
  "section": "Motor",
  "text": "¿El nivel de aceite es correcto?",
  "type": "pass_fail",
  "points": 5,
  "options": null,
  "order": 1,
  "allow_photos": true,
  "max_photos": 3,
  "requires_comment_on_fail": true
}

Response 200:

{
  "id": 1,
  "checklist_id": 1,
  "section": "Motor",
  "text": "¿El nivel de aceite es correcto?",
  "type": "pass_fail",
  "points": 5,
  "options": null,
  "order": 1,
  "allow_photos": true,
  "max_photos": 3,
  "requires_comment_on_fail": true,
  "created_at": "2025-11-19T00:00:00Z"
}

🔍 INSPECTIONS - Inspecciones Realizadas

1. Listar Inspecciones

GET /api/inspections

Lista las inspecciones realizadas.

Query Params:

  • skip (int, default: 0)
  • limit (int, default: 100)
  • vehicle_plate (string) - Filtrar por patente
  • status (string) - Filtrar por estado (draft, completed, inactive)
  • show_inactive (bool, default: false) - Mostrar inactivas

Headers:

Authorization: Bearer {token}

Response 200:

[
  {
    "id": 1,
    "checklist_id": 1,
    "mechanic_id": 2,
    "or_number": "OR-12345",
    "vehicle_plate": "ABC123",
    "vehicle_brand": "Toyota",
    "vehicle_model": "Corolla",
    "vehicle_km": 50000,
    "client_name": "Juan Pérez",
    "score": 85,
    "max_score": 100,
    "percentage": 85.0,
    "flagged_items_count": 2,
    "status": "completed",
    "started_at": "2025-11-19T10:00:00Z",
    "completed_at": "2025-11-19T11:00:00Z",
    "created_at": "2025-11-19T10:00:00Z"
  }
]

2. Crear Inspección

POST /api/inspections

Inicia una nueva inspección.

Headers:

Authorization: Bearer {token}

Body:

{
  "checklist_id": 1,
  "or_number": "OR-12345",
  "vehicle_plate": "ABC123",
  "vehicle_brand": "Toyota",
  "vehicle_model": "Corolla",
  "vehicle_km": 50000,
  "client_name": "Juan Pérez"
}

Response 200:

{
  "id": 1,
  "checklist_id": 1,
  "mechanic_id": 2,
  "or_number": "OR-12345",
  "vehicle_plate": "ABC123",
  "vehicle_brand": "Toyota",
  "vehicle_model": "Corolla",
  "vehicle_km": 50000,
  "client_name": "Juan Pérez",
  "score": 0,
  "max_score": 100,
  "percentage": 0.0,
  "flagged_items_count": 0,
  "status": "draft",
  "started_at": "2025-11-19T10:00:00Z",
  "created_at": "2025-11-19T10:00:00Z"
}

3. Completar Inspección

POST /api/inspections/{inspection_id}/complete

Marca una inspección como completada y calcula el score.

Headers:

Authorization: Bearer {token}

Response 200:

{
  "id": 1,
  "status": "completed",
  "score": 85,
  "percentage": 85.0,
  "flagged_items_count": 2,
  "completed_at": "2025-11-19T11:00:00Z"
}

4. Inactivar Inspección (Admin)

PATCH /api/inspections/{inspection_id}/deactivate

Inactiva una inspección (soft delete).

Headers:

Authorization: Bearer {token}

Response 200:

{
  "message": "Inspección inactivada correctamente",
  "inspection_id": 1
}

Errores:

  • 403 Forbidden - No tienes permisos (solo admin)
  • 404 Not Found - Inspección no encontrada

📝 ANSWERS - Respuestas de Inspección

1. Crear Respuesta

POST /api/answers

Registra una respuesta a una pregunta de inspección.

Headers:

Authorization: Bearer {token}

Body:

{
  "inspection_id": 1,
  "question_id": 1,
  "answer_value": "pass",
  "answer_text": null,
  "is_flagged": false,
  "comments": null,
  "photos": []
}

Response 200:

{
  "id": 1,
  "inspection_id": 1,
  "question_id": 1,
  "answer_value": "pass",
  "answer_text": null,
  "is_flagged": false,
  "points_earned": 5,
  "comments": null,
  "photos": [],
  "created_at": "2025-11-19T10:30:00Z"
}

🤖 AI - Análisis con Inteligencia Artificial

1. Analizar Foto con IA

POST /api/ai/analyze

Analiza una foto usando IA y devuelve sugerencias.

Headers:

Authorization: Bearer {token}
Content-Type: application/json

Body:

{
  "photo_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
  "question_text": "¿El nivel de aceite es correcto?",
  "question_type": "pass_fail",
  "section": "Motor"
}

Response 200:

{
  "analysis": {
    "answer_value": "fail",
    "confidence": 0.85,
    "explanation": "El nivel de aceite está por debajo del mínimo recomendado",
    "is_flagged": true,
    "comments": "Se requiere rellenar aceite urgentemente"
  },
  "model_used": "gpt-4-vision-preview",
  "timestamp": "2025-11-19T10:30:00Z"
}

📊 Códigos de Estado HTTP

  • 200 OK - Solicitud exitosa
  • 201 Created - Recurso creado exitosamente
  • 400 Bad Request - Datos inválidos o faltantes
  • 401 Unauthorized - No autenticado o token inválido
  • 403 Forbidden - No tienes permisos para esta acción
  • 404 Not Found - Recurso no encontrado
  • 500 Internal Server Error - Error del servidor

🔐 Roles y Permisos

Admin

  • ✅ Gestionar usuarios (crear, editar, inactivar, activar)
  • ✅ Cambiar contraseñas de cualquier usuario
  • ✅ Ver y revocar tokens API de cualquier usuario
  • ✅ Gestionar checklists y preguntas
  • ✅ Ver todas las inspecciones
  • ✅ Crear inspecciones
  • ✅ Inactivar inspecciones
  • ✅ Acceso completo a configuración de IA

Mechanic (Mecánico)

  • ✅ Ver sus propias inspecciones
  • ✅ Crear y completar inspecciones
  • ✅ Responder preguntas de inspección
  • ✅ Usar análisis con IA
  • ✅ Actualizar su propio perfil
  • ✅ Cambiar su propia contraseña
  • ✅ Gestionar sus propios tokens API
  • ❌ No puede gestionar usuarios
  • ❌ No puede gestionar checklists
  • ❌ No puede ver tokens de otros usuarios

💡 Ejemplos de Uso

Flujo Completo: Crear y Completar Inspección

# 1. Login
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "mecanico",
    "password": "mec123"
  }'

# Guardar el token de la respuesta
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# 2. Crear inspección
curl -X POST http://localhost:8000/api/inspections \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "checklist_id": 1,
    "or_number": "OR-12345",
    "vehicle_plate": "ABC123",
    "vehicle_brand": "Toyota",
    "vehicle_model": "Corolla",
    "vehicle_km": 50000,
    "client_name": "Juan Pérez"
  }'

# Guardar inspection_id de la respuesta
INSPECTION_ID=1

# 3. Responder preguntas
curl -X POST http://localhost:8000/api/answers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inspection_id": '$INSPECTION_ID',
    "question_id": 1,
    "answer_value": "pass",
    "is_flagged": false,
    "points_earned": 5
  }'

# 4. Completar inspección
curl -X POST http://localhost:8000/api/inspections/$INSPECTION_ID/complete \
  -H "Authorization: Bearer $TOKEN"

🛠️ Testing con Postman

  1. Importa la colección de Postman (disponible en /docs/postman)
  2. Configura la variable de entorno base_url a http://localhost:8000
  3. Ejecuta el request de Login
  4. El token se guardará automáticamente en la variable token
  5. Los demás requests usarán el token automáticamente

📖 Documentación Interactiva

Accede a la documentación interactiva de Swagger:

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc

Puedes probar todos los endpoints directamente desde el navegador.

Reference in New Issue View Git Blame Copy Permalink