Sistema de gestión de colas y turnos para comercios, clínicas, administraciones públicas y cualquier organización que necesite organizar la atención presencial al cliente.
Web oficial y documentación: https://www.keues.dev
Keues está pensado para cualquier negocio o institución con atención presencial y varios mostradores o puestos:
- Comercios de alimentación — carnicerías, pescaderías, fruterías: el cliente saca un número y espera a ser llamado.
- Banca, clínicas y administración pública — gestión de turnos con distintas prioridades y tipos de servicio.
- Grandes superficies — puestos sin tickets donde el monitor simplemente avisa de qué caja ha quedado libre.
- Mercados tradicionales — el cliente coge un número de papel y el monitor digital muestra a quién están atendiendo.
Todo corre en un único contenedor Docker en tu propia infraestructura. Sin cuotas, sin datos en la nube de terceros, con API abierta.
- El ciclo de atención
- Ecosistema de aplicaciones
- Tipos de flujo
- Características
- Instalación
- Documentación de la API
- Pruebas
- Arquitectura
- Licencia
1. El cliente saca su turno
Se acerca al terminal de autoservicio (TicketMachine), elige el servicio que necesita navegando por el menú configurado por el administrador y recibe su código de turno (p. ej. C-004).
2. El operador llama al siguiente Cuando termina con un cliente, pulsa "Llamar siguiente" en su puesto (Counter). El sistema selecciona automáticamente el ticket más adecuado según la prioridad de las colas, el tiempo de espera acumulado y el ratio de atención configurado.
3. Los monitores se actualizan al instante Las pantallas visibles para los clientes (Monitors) muestran el turno llamado y el puesto al que debe dirigirse el cliente, sin recargar la página y sin delay apreciable.
4. El operador cierra el turno Al terminar la atención, marca el ticket como atendido. El mostrador queda libre para el siguiente ciclo.
Keues se compone de cuatro aplicaciones que trabajan juntas:
| Aplicación | Quién la usa | Qué hace |
|---|---|---|
| Keues (este repo) | Administrador | API central + dashboard web de configuración y seguimiento en tiempo real |
| Keues-Counter | Operador del mostrador | Llama el siguiente turno, marca tickets como atendidos o libera el puesto |
| Keues-Monitors | Pantallas visibles al cliente | Muestra el turno actual y el mostrador al que debe ir el cliente |
| Keues-TicketMachine | Cliente (kiosco táctil) | Muestra el menú de servicios y entrega el número de turno |
Cada establecimiento puede tener varios flujos simultáneos según el tipo de atención que ofrezca:
| Tipo | Cuándo usarlo | Cómo funciona |
|---|---|---|
TicketMachine |
Carnicería, clínica, banco, farmacia… | El cliente saca un ticket en el terminal y el operador lo llama desde el mostrador |
SetFree |
Cajas de supermercado, taquillas, puntos de información | Sin tickets: el operador avisa en pantalla cuando su puesto queda libre |
ManualCall |
Mercados con dispensador de papel, pescaderías | El operador sube o baja el número manualmente y el monitor lo muestra en tiempo real |
Gestiona varios locales desde un único sistema. Cada establecimiento tiene sus propias colas, mostradores, flujos y dispositivos, completamente independientes.
El algoritmo de selección del siguiente turno combina tres mecanismos:
- Prioridad — las colas con mayor prioridad se atienden antes. Útil para separar urgencias de citas programadas, o clientes VIP de cola general.
- Peso — cuando varias colas tienen la misma prioridad, el peso define el ratio de atención entre ellas. Un peso de 3:1 entre la cola A y la B significa que se atienden 3 tickets de A por cada 1 de B.
- Envejecimiento (aging) — cada X minutos que un ticket lleva esperando, sube automáticamente un punto de prioridad, evitando que nadie espere indefinidamente aunque su cola tenga menor prioridad base.
Panel web con seguimiento en tiempo real de cada establecimiento:
- KPIs del día: tickets en espera, en atención, atendidos y cancelados.
- Tiempo medio de espera y tiempo medio de servicio.
- Vista en tiempo real de qué mostrador está atendiendo qué turno y desde cuándo.
- Tickets esperando por cola ordenados por antigüedad.
- Historial completo con filtros por estado, cola, rango de fechas y búsqueda libre.
- Menú de la TicketMachine configurable como árbol de categorías y servicios, con icono y color por nodo.
- Numeración por cola con prefijo personalizable (ej:
C,P,M) y valor máximo configurable. - Mostradores especializados — cada mostrador puede estar autorizado a atender solo determinadas colas.
- Colores para colas y mostradores, visibles en el dashboard y en los monitores.
Los monitores y mostradores reciben los cambios al instante. Sin recargar. Sin polling. El administrador también ve el dashboard actualizado en tiempo real.
Interfaz disponible en español e inglés. Toggle de tema claro/oscuro en la barra superior.
- Primer arranque guiado: el sistema detecta que no hay administrador y lo crea paso a paso.
- Autenticación con JWT en cookie HttpOnly.
- Recuperación de contraseña por email (SMTP configurable).
Un solo contenedor Docker. Los datos persisten en un volumen local. Sin base de datos externa, sin servicios adicionales.
docker run -d \
--name keues \
-p 8080:8080 \
-v "$(pwd)/data:/app/data" \
gorerecord/keues:latestAbre http://localhost:8080: en el primer arranque el dashboard te guiará para crear el primer administrador.
O con Docker Compose:
services:
keues:
image: gorerecord/keues:latest
container_name: keues
ports:
- "8080:8080"
volumes:
- ./data:/app/data
environment:
KEUES_DASHBOARD_URL: "http://localhost:8080"
restart: unless-stoppedRequisitos: .NET 10 SDK y Node.js + pnpm.
# API
dotnet run --project Keues.API
# → http://localhost:5125
# Dashboard
cd Keues.Dashboard
pnpm install
pnpm devEl proxy de Vite apunta a
http://localhost:8080. Si lanzas la API en otro puerto, ajustaKeues.Dashboard/vite.config.mjs.
OpenAPI disponible en http://localhost:5125/openapi/v1.json durante el desarrollo. Para regenerar docs/openapi.json:
./scripts/export-openapi.shdotnet test Keues.TestsLa suite cubre los casos de uso (numeración, prioridad, aging, peso, autenticación) y la API completa con integración HTTP real.
Arquitectura interna
┌──────────────────────────────────────────────────────────┐
│ Keues.Dashboard SPA React (administración web) │
├──────────────────────────────────────────────────────────┤
│ Keues.API Endpoints HTTP + hub tiempo real │
├──────────────────────────────────────────────────────────┤
│ Keues.Application Casos de uso │
├──────────────────────────────────────────────────────────┤
│ Keues.Domain Entidades y reglas de negocio │
├──────────────────────────────────────────────────────────┤
│ Keues.Infrastructure EF Core · SQLite · JWT · SMTP │
└──────────────────────────────────────────────────────────┘
Tecnologías: ASP.NET Core (.NET 10), Entity Framework Core + SQLite, SignalR, JWT, React 19 + TypeScript + Vite 8 + Mantine 9, xUnit, Docker.
Este proyecto se distribuye bajo la licencia MIT. Consulta el archivo LICENSE.
Hecho con 💙 por HastaCs.