# Documentación API - Servicio SQL Injector

**Base URL**: `http://localhost:3120/v1`

Este servicio permite la ejecución remota de consultas SQL en tiendas distribuidas mediante un mecanismo de polling, almacenamiento de resultados y consulta de historial.

---

## 1. Consultar Comandos Pendientes (Polling)
Este endpoint es consumido por el cliente (tienda) para saber si tiene algún comando SQL pendiente de ejecutar.

- **Método**: `GET`
- **Ruta**: `/commands`
- **Parámetros (Query)**:
    - `store_id`: ID de la tienda (Requerido).

**Ejemplo de Solicitud**:
```http
GET /v1/commands?store_id=44
```

**Respuestas**:
- **200 OK**: Se encontró un comando pendiente.
  ```json
  {
      "command_id": 123,
      "sql": "SELECT * FROM users LIMIT 1",
      "privilegio": "READ"
  }
  ```
- **204 No Content**: No hay comandos pendientes.
- **500 Internal Server Error**: Error del servidor.

---

## 2. Crear Nuevo Comando
Permite a un administrador o sistema central poner en cola una instrucción SQL para ser ejecutada por una tienda específica.

- **Método**: `POST`
- **Ruta**: `/commands`
- **Cuerpo (JSON)**:
    - `store_id` (Number): ID de la tienda objetivo (Requerido).
    - `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.

**Ejemplo de Solicitud**:
```json
{
  "store_id": 44,
  "sql": "SELECT count(*) FROM ventas",
  "privilegio": "READ",
  "id_user": 1
}
```

**Respuesta Exitosa (201 Created)**:
```json
{
    "success": true,
    "message": "Comando creado exitosamente",
    "command_id": 124
}
```

---

## 3. Guardar Resultado de Comando
Este endpoint es utilizado por el cliente (tienda) para reportar el resultado de la ejecución del SQL.

- **Método**: `POST`
- **Ruta**: `/commands/result`
- **Cuerpo (JSON)**:
    - `command_id` (Number): ID del comando ejecutado (Requerido).
    - `result` (Object/Array): El resultado de la consulta SQL. 
    *Nota: Si se envía el cuerpo sin la propiedad `result`, el sistema intentará tomar todo el cuerpo como el resultado.*

**Ejemplo de Solicitud**:
```json
{
  "command_id": 124,
  "result": [
    { "count": 150 }
  ]
}
```

**Respuesta Exitosa (200 OK)**:
```json
{
    "success": true,
    "message": "Resultado guardado correctamente"
}
```

---

## 4. Consultar Estado/Resultado de Comando
Permite consultar si un comando específico ya fue ejecutado y obtener su resultado.

- **Método**: `GET`
- **Ruta**: `/commands/:command_id`
- **Parámetros (Path)**:
    - `command_id`: ID del comando a consultar.

**Ejemplo de Solicitud**:
```http
GET /v1/commands/124
```

**Respuestas**:
- **200 OK**: Comando completado.
  ```json
  {
      "command_id": 124,
      "status": "completed",
      "result": [
          { "count": 150 }
      ],
      "processed_at": "2026-01-13T19:00:00.000Z"
  }
  ```
- **404 Not Found**: El comando no existe o aún no ha sido procesado (estado pendiente).

---

## 5. Historial de Comandos por Usuario
Devuelve una lista de los últimos comandos solicitados por un usuario específico.

- **Método**: `GET`
- **Ruta**: `/commands/user/:id_user`
- **Parámetros (Path)**:
    - `id_user`: ID del usuario.
- **Parámetros (Query)**:
    - `limit`: Cantidad de registros a traer (Default: 50).

**Ejemplo de Solicitud**:
```http
GET /v1/commands/user/1?limit=5
```

**Respuesta Exitosa (200 OK)**:
```json
[
  {
    "command_id": 124,
    "store_id": 44,
    "sql": "SELECT count(*) FROM ventas",
    "privilegio": "READ",
    "estado": "1",
    "fecha_solicitud": "2026-01-13T18:55:00.000Z",
    "fecha_proceso": "2026-01-13T19:00:00.000Z",
    "json_response": [ { "count": 150 } ]
  },
  ...
]
```