Add complete project documentation
Documentation includes: - README.md: Project overview and architecture - API.md: Complete API reference with endpoints - MANUAL_USUARIO.md: User manual in Spanish - INSTALACION.md: Installation and deployment guide - ARQUITECTURA.md: Architecture and database schema - UPLOAD_PANEL.md: CSV upload panel documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Exteban08
563
docs/API.md
Normal file
563
docs/API.md
Normal file
@@ -0,0 +1,563 @@
|
||||
# Documentacion API
|
||||
|
||||
## Informacion General
|
||||
|
||||
- **URL Base**: `https://api.gestionrecursoshidricos.com/api`
|
||||
- **Formato**: JSON
|
||||
- **Autenticacion**: Bearer Token (JWT)
|
||||
|
||||
## Autenticacion
|
||||
|
||||
### Login
|
||||
```http
|
||||
POST /auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "usuario@ejemplo.com",
|
||||
"password": "contraseña"
|
||||
}
|
||||
```
|
||||
|
||||
**Respuesta exitosa:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"user": {
|
||||
"id": "uuid",
|
||||
"email": "usuario@ejemplo.com",
|
||||
"name": "Nombre",
|
||||
"role": "ADMIN"
|
||||
},
|
||||
"accessToken": "jwt_token",
|
||||
"refreshToken": "refresh_token"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Refresh Token
|
||||
```http
|
||||
POST /auth/refresh
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"refreshToken": "refresh_token"
|
||||
}
|
||||
```
|
||||
|
||||
### Logout
|
||||
```http
|
||||
POST /auth/logout
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
### Obtener Perfil
|
||||
```http
|
||||
GET /auth/me
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Proyectos
|
||||
|
||||
### Listar Proyectos
|
||||
```http
|
||||
GET /projects?page=1&pageSize=10
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
**Parametros de consulta:**
|
||||
| Parametro | Tipo | Descripcion |
|
||||
|-----------|------|-------------|
|
||||
| page | number | Numero de pagina (default: 1) |
|
||||
| pageSize | number | Registros por pagina (default: 10) |
|
||||
| status | string | Filtrar por estado (ACTIVE, INACTIVE) |
|
||||
| search | string | Buscar por nombre |
|
||||
|
||||
### Obtener Proyecto
|
||||
```http
|
||||
GET /projects/:id
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
### Estadisticas del Proyecto
|
||||
```http
|
||||
GET /projects/:id/stats
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
### Crear Proyecto
|
||||
```http
|
||||
POST /projects
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "Nombre del Proyecto",
|
||||
"description": "Descripcion",
|
||||
"area_name": "Nombre del Area",
|
||||
"location": "Ubicacion",
|
||||
"meter_type_id": "uuid-tipo-medidor"
|
||||
}
|
||||
```
|
||||
|
||||
### Actualizar Proyecto
|
||||
```http
|
||||
PUT /projects/:id
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "Nuevo Nombre",
|
||||
"status": "ACTIVE"
|
||||
}
|
||||
```
|
||||
|
||||
### Eliminar Proyecto
|
||||
```http
|
||||
DELETE /projects/:id
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
*Requiere rol ADMIN*
|
||||
|
||||
---
|
||||
|
||||
## Concentradores
|
||||
|
||||
### Listar Concentradores
|
||||
```http
|
||||
GET /concentrators?project_id=uuid
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
**Parametros de consulta:**
|
||||
| Parametro | Tipo | Descripcion |
|
||||
|-----------|------|-------------|
|
||||
| project_id | uuid | Filtrar por proyecto |
|
||||
| status | string | Filtrar por estado |
|
||||
| search | string | Buscar por serial o nombre |
|
||||
|
||||
### Obtener Concentrador
|
||||
```http
|
||||
GET /concentrators/:id
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
### Crear Concentrador
|
||||
```http
|
||||
POST /concentrators
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"serial_number": "CONC001",
|
||||
"name": "Concentrador Principal",
|
||||
"project_id": "uuid-proyecto",
|
||||
"location": "Ubicacion",
|
||||
"ip_address": "192.168.1.100"
|
||||
}
|
||||
```
|
||||
|
||||
### Actualizar Concentrador
|
||||
```http
|
||||
PUT /concentrators/:id
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "Nuevo Nombre",
|
||||
"status": "ACTIVE"
|
||||
}
|
||||
```
|
||||
|
||||
### Eliminar Concentrador
|
||||
```http
|
||||
DELETE /concentrators/:id
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Medidores
|
||||
|
||||
### Listar Medidores
|
||||
```http
|
||||
GET /meters?page=1&pageSize=50
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
**Parametros de consulta:**
|
||||
| Parametro | Tipo | Descripcion |
|
||||
|-----------|------|-------------|
|
||||
| page | number | Numero de pagina |
|
||||
| pageSize | number | Registros por pagina |
|
||||
| project_id | uuid | Filtrar por proyecto |
|
||||
| concentrator_id | uuid | Filtrar por concentrador |
|
||||
| status | string | ACTIVE, INACTIVE, OFFLINE, MAINTENANCE, ERROR |
|
||||
| type | string | LORA, LORAWAN, GRANDES CONSUMIDORES |
|
||||
| search | string | Buscar por serial o nombre |
|
||||
|
||||
### Obtener Medidor
|
||||
```http
|
||||
GET /meters/:id
|
||||
```
|
||||
|
||||
### Lecturas del Medidor
|
||||
```http
|
||||
GET /meters/:id/readings?page=1&pageSize=50
|
||||
```
|
||||
|
||||
### Crear Medidor
|
||||
```http
|
||||
POST /meters
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"serial_number": "MED001",
|
||||
"name": "Medidor 001",
|
||||
"concentrator_id": "uuid-concentrador",
|
||||
"project_id": "uuid-proyecto",
|
||||
"area_name": "Zona A",
|
||||
"location": "Depto 101",
|
||||
"type": "LORA",
|
||||
"status": "ACTIVE",
|
||||
"installation_date": "2024-01-15"
|
||||
}
|
||||
```
|
||||
|
||||
### Actualizar Medidor
|
||||
```http
|
||||
PUT /meters/:id
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "Nuevo Nombre",
|
||||
"status": "MAINTENANCE"
|
||||
}
|
||||
```
|
||||
|
||||
### Actualizar Parcial (PATCH)
|
||||
```http
|
||||
PATCH /meters/:id
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"status": "ACTIVE"
|
||||
}
|
||||
```
|
||||
|
||||
### Eliminar Medidor
|
||||
```http
|
||||
DELETE /meters/:id
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
*Requiere rol ADMIN*
|
||||
|
||||
---
|
||||
|
||||
## Lecturas
|
||||
|
||||
### Listar Lecturas
|
||||
```http
|
||||
GET /readings?page=1&pageSize=50
|
||||
```
|
||||
|
||||
**Parametros de consulta:**
|
||||
| Parametro | Tipo | Descripcion |
|
||||
|-----------|------|-------------|
|
||||
| meter_id | uuid | Filtrar por medidor |
|
||||
| project_id | uuid | Filtrar por proyecto |
|
||||
| concentrator_id | uuid | Filtrar por concentrador |
|
||||
| start_date | date | Fecha inicio (YYYY-MM-DD) |
|
||||
| end_date | date | Fecha fin (YYYY-MM-DD) |
|
||||
| reading_type | string | AUTOMATIC, MANUAL, SCHEDULED |
|
||||
|
||||
### Resumen de Consumo
|
||||
```http
|
||||
GET /readings/summary?project_id=uuid
|
||||
```
|
||||
|
||||
**Respuesta:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"totalReadings": 1500,
|
||||
"totalMeters": 50,
|
||||
"avgReading": 125.5,
|
||||
"lastReadingDate": "2024-01-20T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Crear Lectura
|
||||
```http
|
||||
POST /readings
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"meter_id": "uuid-medidor",
|
||||
"reading_value": 1234.56,
|
||||
"reading_type": "MANUAL",
|
||||
"battery_level": 85,
|
||||
"signal_strength": -45,
|
||||
"received_at": "2024-01-20T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Eliminar Lectura
|
||||
```http
|
||||
DELETE /readings/:id
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
*Requiere rol ADMIN*
|
||||
|
||||
---
|
||||
|
||||
## Carga CSV (Sin Autenticacion)
|
||||
|
||||
### Subir Medidores CSV
|
||||
```http
|
||||
POST /csv-upload/meters
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
file: archivo.csv
|
||||
```
|
||||
|
||||
**Formato CSV:**
|
||||
```csv
|
||||
serial_number,name,concentrator_serial,area_name,location,meter_type,status,installation_date
|
||||
MED001,Medidor 1,CONC001,Zona A,Depto 101,LORA,ACTIVE,2024-01-15
|
||||
```
|
||||
|
||||
**Respuesta:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Procesamiento completado: 10 insertados, 5 actualizados, 2 errores",
|
||||
"data": {
|
||||
"total": 17,
|
||||
"inserted": 10,
|
||||
"updated": 5,
|
||||
"errors": [
|
||||
{
|
||||
"row": 15,
|
||||
"field": "concentrator_serial",
|
||||
"message": "Concentrador no encontrado"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Subir Lecturas CSV
|
||||
```http
|
||||
POST /csv-upload/readings
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
file: archivo.csv
|
||||
```
|
||||
|
||||
**Formato CSV:**
|
||||
```csv
|
||||
meter_serial,reading_value,received_at,reading_type,battery_level,signal_strength
|
||||
MED001,1234.56,2024-01-20 10:30:00,MANUAL,85,-45
|
||||
```
|
||||
|
||||
### Descargar Plantilla Medidores
|
||||
```http
|
||||
GET /csv-upload/meters/template
|
||||
```
|
||||
|
||||
### Descargar Plantilla Lecturas
|
||||
```http
|
||||
GET /csv-upload/readings/template
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usuarios
|
||||
|
||||
### Listar Usuarios
|
||||
```http
|
||||
GET /users
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
*Requiere rol ADMIN*
|
||||
|
||||
### Crear Usuario
|
||||
```http
|
||||
POST /users
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "nuevo@ejemplo.com",
|
||||
"password": "contraseña123",
|
||||
"name": "Nombre Usuario",
|
||||
"role_id": "uuid-rol",
|
||||
"project_id": "uuid-proyecto"
|
||||
}
|
||||
```
|
||||
*Requiere rol ADMIN*
|
||||
|
||||
### Actualizar Usuario
|
||||
```http
|
||||
PUT /users/:id
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "Nuevo Nombre",
|
||||
"is_active": true
|
||||
}
|
||||
```
|
||||
|
||||
### Cambiar Contraseña
|
||||
```http
|
||||
PUT /users/:id/password
|
||||
Authorization: Bearer {accessToken}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"currentPassword": "actual",
|
||||
"newPassword": "nueva123"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Roles
|
||||
|
||||
### Listar Roles
|
||||
```http
|
||||
GET /roles
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
**Roles disponibles:**
|
||||
| Rol | Descripcion |
|
||||
|-----|-------------|
|
||||
| ADMIN | Acceso completo al sistema |
|
||||
| OPERATOR | Gestion de medidores y lecturas de su proyecto |
|
||||
| VIEWER | Solo lectura |
|
||||
|
||||
---
|
||||
|
||||
## Notificaciones
|
||||
|
||||
### Listar Notificaciones
|
||||
```http
|
||||
GET /notifications?page=1&pageSize=20
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
### Contador No Leidas
|
||||
```http
|
||||
GET /notifications/unread-count
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
### Marcar como Leida
|
||||
```http
|
||||
PATCH /notifications/:id/read
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
### Marcar Todas como Leidas
|
||||
```http
|
||||
PATCH /notifications/read-all
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Auditoria
|
||||
|
||||
### Listar Logs de Auditoria
|
||||
```http
|
||||
GET /audit-logs?page=1&pageSize=50
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
*Requiere rol ADMIN*
|
||||
|
||||
**Parametros de consulta:**
|
||||
| Parametro | Tipo | Descripcion |
|
||||
|-----------|------|-------------|
|
||||
| user_id | uuid | Filtrar por usuario |
|
||||
| action | string | CREATE, UPDATE, DELETE, LOGIN, etc. |
|
||||
| table_name | string | Filtrar por tabla |
|
||||
| start_date | date | Fecha inicio |
|
||||
| end_date | date | Fecha fin |
|
||||
|
||||
### Mi Actividad
|
||||
```http
|
||||
GET /audit-logs/my-activity
|
||||
Authorization: Bearer {accessToken}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Webhooks TTS (The Things Stack)
|
||||
|
||||
### Health Check
|
||||
```http
|
||||
GET /webhooks/tts/health
|
||||
```
|
||||
|
||||
### Uplink (Datos de Dispositivos)
|
||||
```http
|
||||
POST /webhooks/tts/uplink
|
||||
X-Downlink-Apikey: {webhook_secret}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"end_device_ids": {
|
||||
"device_id": "device-001",
|
||||
"dev_eui": "0004A30B001C1234"
|
||||
},
|
||||
"uplink_message": {
|
||||
"decoded_payload": {
|
||||
"reading": 1234.56,
|
||||
"battery": 85
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Join Accept
|
||||
```http
|
||||
POST /webhooks/tts/join
|
||||
X-Downlink-Apikey: {webhook_secret}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Codigos de Respuesta
|
||||
|
||||
| Codigo | Descripcion |
|
||||
|--------|-------------|
|
||||
| 200 | Exito |
|
||||
| 201 | Creado exitosamente |
|
||||
| 400 | Error en la solicitud |
|
||||
| 401 | No autorizado |
|
||||
| 403 | Prohibido (sin permisos) |
|
||||
| 404 | No encontrado |
|
||||
| 409 | Conflicto (duplicado) |
|
||||
| 500 | Error interno del servidor |
|
||||
|
||||
## Formato de Error
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Descripcion del error",
|
||||
"error": "CODIGO_ERROR"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user