From 02d17a046e34f5880b51b79171de85db22413ef9 Mon Sep 17 00:00:00 2001
From: ronalds <ronalds@rshtech.com.py>
Date: Wed, 19 Nov 2025 02:31:43 -0300
Subject: [PATCH] Mensaje descriptivo de lo que hiciste

---
 API_DOCUMENTATION.md | 860 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 860 insertions(+)
 create mode 100644 API_DOCUMENTATION.md

diff --git a/API_DOCUMENTATION.md b/API_DOCUMENTATION.md
new file mode 100644
index 0000000..3c48a3f
--- /dev/null
+++ b/API_DOCUMENTATION.md
@@ -0,0 +1,860 @@
+# 📚 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:**
+```json
+{
+  "username": "admin",
+  "password": "admin123"
+}
+```
+
+**Response 200:**
+```json
+{
+  "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:**
+```json
+{
+  "username": "nuevo_usuario",
+  "password": "password123",
+  "email": "usuario@email.com",
+  "full_name": "Usuario Nuevo",
+  "role": "mechanic"
+}
+```
+
+**Response 200:**
+```json
+{
+  "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:**
+```json
+{
+  "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: true) - Solo usuarios activos
+
+**Headers:**
+```
+Authorization: Bearer {token}
+```
+
+**Response 200:**
+```json
+[
+  {
+    "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:**
+```json
+{
+  "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:**
+```json
+{
+  "username": "nuevo_mecanico",
+  "password": "password123",
+  "email": "mecanico2@syntria.com",
+  "full_name": "Mecánico 2",
+  "role": "mechanic"
+}
+```
+
+**Response 200:**
+```json
+{
+  "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:**
+```json
+{
+  "email": "nuevo_email@syntria.com",
+  "full_name": "Nombre Actualizado",
+  "role": "admin"
+}
+```
+
+**Response 200:**
+```json
+{
+  "id": 2,
+  "username": "mecanico",
+  "email": "nuevo_email@syntria.com",
+  "full_name": "Nombre Actualizado",
+  "role": "admin",
+  "is_active": true,
+  "created_at": "2025-11-19T00:00:00Z"
+}
+```
+
+**Errores:**
+- `400 Bad Request` - Email 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:**
+```json
+{
+  "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:**
+```json
+{
+  "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:**
+```json
+{
+  "new_password": "nueva_password123"
+}
+```
+
+**Response 200:**
+```json
+{
+  "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:**
+```json
+{
+  "email": "mi_nuevo_email@syntria.com",
+  "full_name": "Mi Nuevo Nombre"
+}
+```
+
+**Response 200:**
+```json
+{
+  "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:**
+```json
+{
+  "current_password": "password_actual",
+  "new_password": "nueva_password123"
+}
+```
+
+**Response 200:**
+```json
+{
+  "message": "Contraseña actualizada correctamente"
+}
+```
+
+**Errores:**
+- `400 Bad Request` - Contraseña actual incorrecta
+
+---
+
+## 📋 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:**
+```json
+[
+  {
+    "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:**
+```json
+{
+  "name": "Inspección de Mantenimiento",
+  "description": "Checklist para mantenimiento preventivo",
+  "ai_mode": "off",
+  "scoring_enabled": true,
+  "logo_url": null
+}
+```
+
+**Response 200:**
+```json
+{
+  "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:**
+```json
+{
+  "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:**
+```json
+{
+  "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:**
+```json
+[
+  {
+    "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:**
+```json
+{
+  "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:**
+```json
+{
+  "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:**
+```json
+{
+  "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:**
+```json
+{
+  "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:**
+```json
+{
+  "inspection_id": 1,
+  "question_id": 1,
+  "answer_value": "pass",
+  "answer_text": null,
+  "is_flagged": false,
+  "comments": null,
+  "photos": []
+}
+```
+
+**Response 200:**
+```json
+{
+  "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:**
+```json
+{
+  "photo_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
+  "question_text": "¿El nivel de aceite es correcto?",
+  "question_type": "pass_fail",
+  "section": "Motor"
+}
+```
+
+**Response 200:**
+```json
+{
+  "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)
+- ✅ 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
+- ❌ No puede gestionar usuarios
+- ❌ No puede gestionar checklists
+
+---
+
+## 💡 Ejemplos de Uso
+
+### Flujo Completo: Crear y Completar Inspección
+
+```bash
+# 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.