Alertas Stock

Alertas Stock

Prefijo: /api/alertas
Requiere Auth: Sí
Permiso requerido: alertas, *

Módulo de alertas de stock. El sistema genera una alerta cuando el stock de un producto baja del umbral mínimo (o llega a cero), permitiendo al equipo de operaciones consultarlas, agruparlas por producto y resolverlas cuando se reabastece.

---

GET /api/alertas/

Descripción: Lista las alertas de stock con paginación y filtro por estado
Requiere Auth: Sí
Permiso requerido: alertas, leer

Parámetros query:

Parámetro	Tipo	Obligatorio	Descripción
skip	int	❌	Número de registros a saltar (default 0)
limit	int	❌	Máximo de registros a retornar (default 100)
resuelta	bool	❌	Filtrar por estado: true (solo resueltas), false (solo pendientes)

Respuesta exitosa: 200 OK

Response:

[
  {
    "id": 1,
    "tenant_id": "uuid-tenant",
    "producto_id": 42,
    "producto_sync_uuid": "uuid-producto",
    "stock_actual": 3,
    "tipo_movimiento": "EGRESO",
    "created_at": "2026-07-30T10:30:00",
    "resuelta": false
  }
]

cURL:

curl "http://localhost/api/alertas/?resuelta=false" -H "Authorization: Bearer <token>"

Python:

import httpx
resp = httpx.get("http://localhost/api/alertas/", params={"resuelta": False}, headers={"Authorization": f"Bearer :token"})
alertas = resp.json()

JavaScript:

const resp = await fetch('http://localhost/api/alertas/?resuelta=false', {
  headers: {'Authorization': `Bearer $:token`}
});
const alertas = await resp.json();

---

GET /api/alertas/count

Descripción: Obtiene el conteo de alertas con desglose por estado
Requiere Auth: Sí
Permiso requerido: alertas, leer

Parámetros query:

Parámetro	Tipo	Obligatorio	Descripción
resuelta	bool	❌	Si se envía, retorna solo el total filtrado

Respuesta exitosa: 200 OK

Response (sin filtros):

{
  "total": 15,
  "pendientes": 9,
  "resueltas": 6
}

cURL:

curl "http://localhost/api/alertas/count" -H "Authorization: Bearer <token>"
curl "http://localhost/api/alertas/count?resuelta=false" -H "Authorization: Bearer <token>"

---

GET /api/alertas/por-producto

Descripción: Retorna las alertas agrupadas por producto (producto_id). Útil para ver qué productos tienen alertas activas.
Requiere Auth: Sí
Permiso requerido: alertas, leer

Respuesta exitosa: 200 OK

Response:

{
  "42": [
    {
      "id": 1,
      "producto_id": 42,
      "stock_actual": 3,
      "resuelta": false
    }
  ]
}

cURL:

curl "http://localhost/api/alertas/por-producto" -H "Authorization: Bearer <token>"

---

GET /api/alertas/:alerta_id

Descripción: Obtiene una alerta por ID
Requiere Auth: Sí
Permiso requerido: alertas, leer

Respuesta exitosa: 200 OK
Errores: 404 (no encontrada)

cURL:

curl http://localhost/api/alertas/1 -H "Authorization: Bearer <token>"

---

PATCH /api/alertas/:alerta_id/resolver

Descripción: Marca una alerta como resuelta (por ejemplo, tras reabastecer el producto)
Requiere Auth: Sí
Permiso requerido: alertas, actualizar

Respuesta exitosa: 200 OK
Errores: 404 (no encontrada)

cURL:

curl -X PATCH http://localhost/api/alertas/1/resolver -H "Authorization: Bearer <token>"

---

PATCH /api/alertas/resolver-todas

Descripción: Resuelve todas las alertas pendientes del tenant de una sola vez
Requiere Auth: Sí
Permiso requerido: alertas, actualizar

Respuesta exitosa: 200 OK

Response:

{
  "resueltas": 9
}

cURL:

curl -X PATCH http://localhost/api/alertas/resolver-todas -H "Authorization: Bearer <token>"