GRH/docs/API.md

# 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"
}
```