Terminales

GET /api/terminales [NUEVO]

Descripción: Lista todas las terminales POS registradas en el sistema. Incluye estado activo/inactivo, última vez que hicieron heartbeat y métricas de uso. El panel de administración usa este endpoint para mostrar qué terminales están online.

Requiere Auth: Sí Permiso requerido: terminales, leer

Respuesta exitosa: 200 — Lista de terminales

Response:

[
  {
    "terminal_id": "T001",
    "nombre": "Caja Principal",
    "activo": true,
    "ultimo_heartbeat": "2025-01-15T10:30:00",
    "ip_address": "192.168.1.100",
    "created_at": "2024-12-01T08:00:00"
  }
]

Errores:

Código	Causa	Solución
401	Token expirado	Re-login
403	Sin permiso terminales, leer	Solicitar permiso a admin

---

GET /api/terminales/{terminal_id} [NUEVO]

Descripción: Obtiene el detalle completo de una terminal específica. Incluye historial de heartbeats y estado actual.

Requiere Auth: Sí Permiso requerido: terminales, leer

Parámetros path:

Parámetro	Tipo	Obligatorio	Descripción
terminal_id	string	✅	ID de la terminal (ej: “T001”)

Respuesta exitosa: 200 — Detalle de la terminal

Errores:

Código	Causa	Solución
404	Terminal no encontrada	Verificar terminal_id

---

POST /api/terminales [NUEVO]

Descripción: Registra una nueva terminal POS en el sistema. Se ejecuta automáticamente cuando una terminal se inicializa por primera vez, o manualmente desde el panel de administración.

Requiere Auth: Sí Permiso requerido: terminales, crear

Body request (ejemplo):

{
  "terminal_id": "T002",
  "nombre": "Caja Sucursal Norte",
  "ip_address": "192.168.2.50"
}

Respuesta exitosa: 201 — Terminal registrada

---

POST /api/terminales/heartbeat [NUEVO]

Descripción: Registra el heartbeat de una terminal. Las terminales envían este request cada N segundos para indicar que están activas. Si una terminal no envía heartbeat en más de 60 segundos, se marca como inactiva automáticamente.

Requiere Auth: Sí Permiso requerido: terminales, actualizar

Body request (ejemplo):

{
  "terminal_id": "T001",
  "ip_address": "192.168.1.100"
}

Respuesta exitosa: 200 — Heartbeat registrado

---

PUT /api/terminales/{terminal_id} [NUEVO]

Descripción: Actualiza la información de una terminal (nombre, IP, estado). Solo los campos enviados se actualizan.

Requiere Auth: Sí Permiso requerido: terminales, actualizar

Parámetros path:

Parámetro	Tipo	Obligatorio	Descripción
terminal_id	string	✅	ID de la terminal a actualizar

Body request (ejemplo):

{
  "nombre": "Caja Principal - Renovada",
  "ip_address": "192.168.1.101"
}

Respuesta exitosa: 200 — Terminal actualizada

---

PATCH /api/terminales/{terminal_id}/toggle [NUEVO]

Descripción: Alterna el estado activo/inactivo de una terminal. Si está activa, la desactiva (y viceversa). Útil cuando un admin quiere habilitar/deshabilitar una caja temporalmente.

Requiere Auth: Sí Permiso requerido: terminales, actualizar

Parámetros path:

Parámetro	Tipo	Obligatorio	Descripción
terminal_id	string	✅	ID de la terminal a toggle

Respuesta exitosa: 200 — Estado de la terminal cambiado

Response:

{
  "terminal_id": "T001",
  "activo": false,
  "mensaje": "Terminal desactivada"
}

---

DELETE /api/terminales/{terminal_id} [NUEVO]

Descripción: Elimina una terminal del sistema. Solo se puede eliminar si no tiene ventas asociadas en las últimas 24 horas. Se recomienda usar toggle en su lugar.

Requiere Auth: Sí Permiso requerido: terminales, eliminar

Parámetros path:

Parámetro	Tipo	Obligatorio	Descripción
terminal_id	string	✅	ID de la terminal a eliminar

Respuesta exitosa: 204 — Terminal eliminada

Errores:

Código	Causa	Solución
404	Terminal no encontrada	Verificar ID
409	Terminal tiene ventas recientes	Usar toggle para desactivar en su lugar