SQL-INYECTOR/API_DOCUMENTATION.md

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:

GET /v1/commands?store_id=44

Respuestas:

• 200 OK: Se encontró un comando pendiente.

  {
      "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:

{
  "store_id": 44,
  "sql": "SELECT count(*) FROM ventas",
  "privilegio": "READ",
  "id_user": 1
}

Respuesta Exitosa (201 Created):

{
    "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:

{
  "command_id": 124,
  "result": [
    { "count": 150 }
  ]
}

Respuesta Exitosa (200 OK):

{
    "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:

GET /v1/commands/124

Respuestas:

• 200 OK: Comando completado.

  {
      "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:

GET /v1/commands/user/1?limit=5

Respuesta Exitosa (200 OK):

[
  {
    "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 } ]
  },
  ...
]