cambios de api conexion

API_DOCUMENTATION.md

@@ -13,10 +13,11 @@ Este endpoint es consumido por el cliente (tienda) para saber si tiene algún co
 - **Ruta**: `/commands`
 - **Parámetros (Query)**:
     - `store_id`: ID de la tienda (Requerido).
+    - `id_cliente`: ID del cliente (Opcional).
 
 **Ejemplo de Solicitud**:
 ```http
-GET /v1/commands?store_id=44
+GET /v1/commands?store_id=44&id_cliente=1
 ```
 
 **Respuestas**:
@@ -43,6 +44,7 @@ Permite a un administrador o sistema central poner en cola una instrucción SQL
     - `sql` (String): Sentencia SQL a ejecutar (Requerido).
     - `privilegio` (String): Nivel de permiso, por defecto "READ". Opcional.
     - `id_user` (Number): ID del usuario que solicita el comando. Opcional.
+    - `id_cliente` (Number): ID del cliente. Opcional.
 
 **Ejemplo de Solicitud**:
 ```json
@@ -50,7 +52,8 @@ Permite a un administrador o sistema central poner en cola una instrucción SQL
   "store_id": 44,
   "sql": "SELECT count(*) FROM ventas",
   "privilegio": "READ",
-  "id_user": 1
+  "id_user": 1,
+  "id_cliente": 1
 }
 ```
 
@@ -151,7 +154,77 @@ GET /v1/commands/user/1?limit=5
     "fecha_solicitud": "2026-01-13T18:55:00.000Z",
     "fecha_proceso": "2026-01-13T19:00:00.000Z",
     "json_response": [ { "count": 150 } ]
-  },
-  ...
+  }
 ]
 ```
+
+---
+
+## 6. Estado de Tiendas (Heartbeat)
+Devuelve el estado de conectividad de las tiendas basado en su último heartbeat.
+
+- **Método**: `GET`
+- **Ruta**: `/stores/status`
+- **Parámetros (Query)**:
+    - `filter` (String): Filtrar por estado de conectividad. Valores: `online`, `offline`, `all` (Default: `all`).
+    - `id_cliente` (Number): Filtrar por ID de cliente. Opcional.
+
+**Estados de Conectividad**:
+- **ONLINE**: Último ping hace menos de 2 minutos (120 segundos)
+- **DEGRADED**: Último ping entre 2 y 5 minutos (120-300 segundos)
+- **OFFLINE**: Último ping hace más de 5 minutos (>300 segundos)
+
+**Ejemplo de Solicitud**:
+```http
+GET /v1/stores/status?filter=online
+GET /v1/stores/status?filter=all&id_cliente=1
+```
+
+**Respuesta Exitosa (200 OK)**:
+```json
+{
+  "total": 2,
+  "filter_applied": "online",
+  "stores": [
+    {
+      "store_id": 44,
+      "id_cliente": 1,
+      "instance_id": "sql_inyector",
+      "connectivity": "ONLINE",
+      "status": "alive",
+      "last_ping": "2026-02-09T18:15:30.000Z",
+      "seconds_since_ping": 45,
+      "extra_info": {
+        "message": "Consultando comandos",
+        "timestamp": "2026-02-09T18:15:30.000Z"
+      }
+    },
+    {
+      "store_id": 370,
+      "id_cliente": 1,
+      "instance_id": "sql_inyector",
+      "connectivity": "OFFLINE",
+      "status": "alive",
+      "last_ping": "2026-02-09T17:50:00.000Z",
+      "seconds_since_ping": 1530,
+      "extra_info": null
+    }
+  ]
+}
+```
+
+**Notas Importantes**:
+- Si una tienda **nunca ha enviado un heartbeat**, NO aparecerá en la respuesta de este endpoint.
+- Solo se muestran tiendas que tienen al menos un registro en `tb_store_process_heartbeat` con `process_name = 'sql_inyector'`.
+- Para ver tiendas que nunca se han conectado, necesitarías tener una tabla maestra de tiendas y hacer un LEFT JOIN.
+
+---
+
+## Códigos de Estado HTTP
+
+- **200 OK**: Solicitud exitosa
+- **201 Created**: Recurso creado exitosamente
+- **204 No Content**: Solicitud exitosa sin contenido
+- **400 Bad Request**: Parámetros inválidos o faltantes
+- **404 Not Found**: Recurso no encontrado
+- **500 Internal Server Error**: Error del servidor