gitea/checklist
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Mensaje descriptivo de lo que hiciste

Browse Source
This commit is contained in:
ronalds
2025-11-19 02:31:43 -03:00
parent ffe298a544
commit 02d17a046e
1 changed files with 860 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

860
API_DOCUMENTATION.md Normal file
View File

@@ -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.