# 📚 Guía General de Endpoints - API Solicitud de Recursos

**Versión:** 1.0  
**Última Actualización:** Marzo 2024  
**Base URL:** `http://localhost:3000/solicitud-recurso-api`

---

## 📌 Introducción

Este documento sirve como guía de referencia rápida para todos los endpoints disponibles en la API REST de Solicitud de Recursos de UNAULA. Para información más detallada de cada módulo, consulta el archivo `ENDPOINTS.md` en cada carpeta de módulo.

---

## 🗂️ Módulos Disponibles

### 1. **Usuario** 
**Ruta:** `/usuarios`  
**Descripción:** Gestión completa de usuarios del sistema (CRUD)  
📄 [Ver documentación detallada](./src/modulos/usuario/ENDPOINTS.md)

**Endpoints Principales:**
- `POST /registro` - Crear usuario
- `GET /listar` - Listar todos los usuarios
- `GET /listar-usuarios-asignar` - Listar para asignaciones
- `GET /:id` - Obtener usuario por ID
- `PUT /:id` - Actualizar usuario
- `PUT /:id/clave` - Cambiar clave
- `DELETE /:id/desactivar` - Desactivar usuario
- `DELETE /:id` - Eliminar usuario

---

### 2. **Autenticación**
**Ruta:** `/autenticacion`  
**Descripción:** Login y gestión de credenciales  
📄 [Ver documentación detallada](./src/modulos/autenticacion/ENDPOINTS.md)

**Endpoints Principales:**
- `POST /iniciar-sesion` - Login

---

### 3. **Solicitud de Recurso**
**Ruta:** `/solicitud-recurso`  
**Descripción:** Crear, consultar y gestionar solicitudes de recursos  
📄 [Ver documentación detallada](./src/modulos/solicitud-recurso/ENDPOINTS.md)

**Endpoints Principales:**
- `POST /crear-solicitud-recurso` - Crear solicitud
- `GET /rastreo/:id_solicitud/:codigo` - Rastrear solicitud
- `GET /resumen-solicitudes` - Resumen de solicitudes
- `GET /detalle/:id` - Detalle completo
- `PATCH /cambio-estado/:id/estado` - Cambiar estado
- `PATCH /actualizar-campos/:id` - Actualizar campos
- `DELETE /eliminar/:id` - Eliminar solicitud
- `GET /listar-estados-solicitud` - Listar estados

---

### 4. **Trazabilidad**
**Ruta:** `/trazabilidad`  
**Descripción:** Consulta la linea de tiempo de una solicitud agrupada por paso y con historial anidado  
📄 [Ver documentación detallada](./src/modulos/trazabilidad/ENDPOINTS.md)

**Endpoints Principales:**
- `GET /:id_solicitud` - Obtener trazabilidad de una solicitud

---

### 5. **Cargo**
**Ruta:** `/cargo`  
**Descripción:** Catálogo de cargos institucionales  
📄 [Ver documentación detallada](./src/modulos/cargo/ENDPOINTS.md)

**Endpoints Principales:**
- `GET /listar-cargos` - Listar cargos

---

### 5.1 **Dependencia-Cargo**
**Ruta:** `/dependencia-cargo`  
**Descripción:** Gestión de la relación entre dependencias y cargos. Permite asignar dinámicamente cargos a dependencias para filtrado en el frontend.  
📄 [Ver documentación detallada](./src/modulos/dependencia-cargo/ENDPOINTS.md)

**Endpoints Principales:**
- `GET /listar` - Listar todas las relaciones
- `GET /cargos-por-dependencia/:idDependencia` - Obtener cargos de una dependencia (⭐ **Usado en frontend al cambiar dependencia**)
- `GET /dependencias-por-cargo/:idCargo` - Obtener dependencias de un cargo
- `POST /asignar` - Asignar un cargo a una dependencia
- `DELETE /desasignar/:idDependencia/:idCargo` - Desasignar un cargo

---

### 5.1 **Dependencia-Cargo**
**Ruta:** `/dependencia-cargo`  
**Descripción:** Gestión de la relación entre dependencias y cargos. Permite asignar dinámicamente cargos a dependencias.  
📄 [Ver documentación detallada](./src/modulos/dependencia-cargo/ENDPOINTS.md)

**Endpoints Principales:**
- `GET /listar` - Listar todas las relaciones
- `GET /cargos-por-dependencia/:idDependencia` - Obtener cargos de una dependencia (⭐ Frontend)
- `GET /dependencias-por-cargo/:idCargo` - Obtener dependencias de un cargo
- `POST /asignar` - Asignar un cargo a una dependencia
- `DELETE /desasignar/:idDependencia/:idCargo` - Desasignar un cargo

---

### 6. **Dependencia**
**Ruta:** `/dependencia`  
**Descripción:** Catálogo de dependencias de la institución  
📄 [Ver documentación detallada](./src/modulos/dependencia/ENDPOINTS.md)

**Endpoints Principales:**
- `GET /listar-dependencias` - Listar dependencias

---

### 7. **Tipo de Recurso**
**Ruta:** `/tipo-recurso`  
**Descripción:** Gestión de tipos de recursos (CRUD)  
📄 [Ver documentación detallada](./src/modulos/tipo-recurso/ENDPOINTS.md)

**Endpoints Principales:**
- `GET /listar-tipo-recurso` - Listar tipos
- `GET /obtener/:id` - Obtener por ID
- `POST /crear` - Crear tipo
- `PUT /actualizar/:id` - Actualizar tipo
- `DELETE /eliminar/:id` - Eliminar tipo

---

### 7. **Instrumento**
**Ruta:** `/instrumento`  
**Descripción:** Gestión de instrumentos del PDI (CRUD)  
📄 [Ver documentación detallada](./src/modulos/instrumento/ENDPOINTS.md)

**Endpoints Principales:**
- `GET /listar-instrumentos` - Listar instrumentos
- `GET /obtener/:id` - Obtener por ID
- `POST /crear` - Crear instrumento
- `PUT /actualizar/:id` - Actualizar instrumento
- `DELETE /eliminar/:id` - Eliminar instrumento

---

### 8. **Propósito**
**Ruta:** `/proposito`  
**Descripción:** Gestión de propósitos del PDI (CRUD)  
📄 [Ver documentación detallada](./src/modulos/proposito/ENDPOINTS.md)

**Endpoints Principales:**
- `GET /listar-propositos` - Listar propósitos
- `GET /obtener/:id` - Obtener por ID
- `POST /crear` - Crear propósito
- `PUT /actualizar/:id` - Actualizar propósito
- `DELETE /eliminar/:id` - Eliminar propósito

---

### 9. **Acción de Mejora**
**Ruta:** `/accion-mejora`  
**Descripción:** Gestión de acciones de mejora (CRUD)  
📄 [Ver documentación detallada](./src/modulos/accion-mejora/ENDPOINTS.md)

**Endpoints Principales:**
- `GET /listar-accion-mejora` - Listar acciones
- `GET /obtener/:id` - Obtener por ID
- `POST /crear` - Crear acción
- `PUT /actualizar/:id` - Actualizar acción
- `DELETE /eliminar/:id` - Eliminar acción

---

### 10. **Asignación de Solicitud**
**Ruta:** `/asignacion`  
**Descripción:** Asignar responsables a solicitudes  
📄 [Ver documentación detallada](./src/modulos/asignacion-solicitud/ENDPOINTS.md)

**Endpoints Principales:**
- `POST /asignar-responsable` - Asignar responsable

---

### 11. **Configuración del Sistema**
**Ruta:** `/config-sistema`  
**Descripción:** Configuraciones globales del sistema  
📄 [Ver documentación detallada](./src/modulos/config-sistema/ENDPOINTS.md)

**Endpoints Principales:**
- `GET /listar` - Listar configuraciones
- `GET /obtener/:clave` - Obtener por clave
- `GET /crear` - Crear configuración
- `PUT /actualizar/:id` - Actualizar configuración
- `DELETE /eliminar/:id` - Eliminar configuración

---

### 12. **Informes**
**Ruta:** `/informes`  
**Descripción:** Reportes y estadísticas del sistema  
📄 [Ver documentación detallada](./src/modulos/informes/ENDPOINTS.md)

**Endpoints Principales:**
- `GET /informe-inicial` - Informe general del sistema

---

### 13. **Historial de Solicitud**
**Ruta:** `/historial` (Sin endpoints públicos)  
**Descripción:** Auditoría y trazabilidad de cambios  
📄 [Ver documentación detallada](./src/modulos/historial-solicitud/ENDPOINTS.md)

**Funcionalidad:** 
- Registro automático de cambios en solicitudes
- No expone endpoints públicos (uso interno)

---

## 🔐 Autenticación

La mayoría de endpoints requieren autenticación con JWT token. Después de hacer login en `/autenticacion/iniciar-sesion`, incluir el token en el header:

```
Authorization: Bearer <token_jwt>
```

---

## 📊 Estructura de Respuestas

Todas las respuestas siguen este formato:

```json
{
  "cod_estado": 200,
  "mensaje": "Descripción de la respuesta",
  "data": {}
}
```

- `cod_estado`: Código HTTP de estado
- `mensaje`: Descripción amigable del resultado
- `data`: Datos de la respuesta (opcional)

---

## 🔍 Búsqueda Rápida

### Por Método HTTP

#### GET (Lecturas)
- `/usuarios/listar`
- `/usuarios/listar-usuarios-asignar`
- `/usuarios/:id`
- `/cargo/listar-cargos`
- `/dependencia-cargo/listar`
- `/dependencia-cargo/cargos-por-dependencia/:idDependencia`
- `/dependencia-cargo/dependencias-por-cargo/:idCargo`
- `/dependencia/listar-dependencias`
- `/tipo-recurso/listar-tipo-recurso`
- `/tipo-recurso/obtener/:id`
- `/instrumento/listar-instrumentos`
- `/instrumento/obtener/:id`
- `/proposito/listar-propositos`
- `/proposito/obtener/:id`
- `/accion-mejora/listar-accion-mejora`
- `/accion-mejora/obtener/:id`
- `/config-sistema/listar`
- `/config-sistema/obtener/:clave`
- `/informes/informe-inicial`

#### POST (Creaciones)
- `/usuarios/registro`
- `/autenticacion/iniciar-sesion`
- `/solicitud-recurso/crear-solicitud-recurso`
- `/dependencia-cargo/asignar`
- `/tipo-recurso/crear`
- `/instrumento/crear`
- `/proposito/crear`
- `/accion-mejora/crear`
- `/asignacion/asignar-responsable`

#### PUT (Actualizaciones)
- `/usuarios/:id`
- `/tipo-recurso/actualizar/:id`
- `/instrumento/actualizar/:id`
- `/proposito/actualizar/:id`
- `/accion-mejora/actualizar/:id`
- `/config-sistema/actualizar/:id`

#### PATCH (Cambios parciales)
- `/solicitud-recurso/cambio-estado/:id/estado`
- `/solicitud-recurso/actualizar-campos/:id`

#### DELETE (Eliminaciones)
- `/usuarios/:id`
- `/usuarios/:id/desactivar`
- `/solicitud-recurso/eliminar/:id`
- `/dependencia-cargo/desasignar/:idDependencia/:idCargo`
- `/tipo-recurso/eliminar/:id`
- `/instrumento/eliminar/:id`
- `/proposito/eliminar/:id`
- `/accion-mejora/eliminar/:id`
- `/config-sistema/eliminar/:id`

---

## 📚 Flujos Comunes

### 1. Crear una Solicitud de Recurso
```
POST /solicitud-recurso/crear-solicitud-recurso
```

### 2. Ver Estado de una Solicitud
```
GET /solicitud-recurso/rastreo/:id_solicitud/:codigo
```

### 3. Gestionar Usuarios
```
POST /usuarios/registro          # Crear
GET /usuarios/listar             # Listar
GET /usuarios/:id                # Ver uno
PUT /usuarios/:id                # Actualizar
DELETE /usuarios/:id             # Eliminar
```

### 4. Configurar Catálogos
```
POST /tipo-recurso/crear
POST /instrumento/crear
POST /proposito/crear
```

### 5. Cargar Cargos Dinámicamente en el Frontend (⭐ Dependencia-Cargo)
```
1. Usuario selecciona una dependencia en el select
2. Frontend hace petición: GET /dependencia-cargo/cargos-por-dependencia/:idDependencia
3. El select de cargos se llena automáticamente con los resultados
```

---

## 🛠️ Herramientas Recomendadas

- **Postman** - Testear endpoints
- **Thunder Client** - Extensión VS Code
- **cURL** - Línea de comandos
- **REST Client** - Extensión VS Code

---

## ✅ Checklist para Desarrollo

- [ ] Leer la documentación de cada módulo
- [ ] Autenticarse antes de consumir endpoints protegidos
- [ ] Incluir headers apropiados (Content-Type, Authorization)
- [ ] Validar respuestas con el esquema de respuesta estándar
- [ ] Implementar manejo de errores para códigos 4xx y 5xx
- [ ] Cachear datos cuando sea apropiado

---

## 📞 Soporte

Para más información o reportar problemas:
- Consulta los archivos ENDPOINTS.md en cada módulo
- Revisa los comentarios en el código fuente
- Solicita documentación específica a los desarrolladores