158 lines
3.7 KiB
Markdown
158 lines
3.7 KiB
Markdown
# 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 } ]
|
|
},
|
|
...
|
|
]
|
|
```
|