Frihet Kitchen
Frihet Kitchen es la app vertical de hostelería sobre Frihet ERP. Combina un KDS (Kitchen Display System) por estación con toma de comandas en modalidad de cobro inmediato (pay_now), emisión fiscal directa en el libro del ERP, recuperación de tickets cerrados (Recall) y analítica operativa de tiempos de preparación.
Cómo funciona
El módulo /kitchen organiza el servicio de cocina y barra en cinco vistas operativas conectadas en tiempo real sobre las colecciones del workspace:
/kitchen(orders.read): resumen operativo con accesos directos a comandas, tablero KDS y métricas del turno./kitchen/pos(orders.write): toma de comandas en modalidad de cobro inmediato (pay_now) con selector de modificadores (ModifierSelectionSheet), modalidad de servicio (dine-in,takeaway,delivery) y método de cobro (cash,card,external)./kitchen/kds(kds.view/kds.bump): pantalla KDS filtrable por estación con flujo de estadosqueued(Pendiente) →preparing(En preparación) →ready(Listo) →served(Servido), consolidación de cantidades en preparación y cajón Recall para recuperar tickets de los últimos 30 días./kitchen/reports(analytics.view): panel de métricas de servicio con tickets activos (activeTickets), tiempo medio de preparación (avgPrepMinutes), tickets servidos (servedTickets), tasa de listos (readyRate%), carga por estación (stationLoad) y mix de estados (statusMix)./kitchen/management(menu.read/menu.write): gestión del catálogo de cocina (fk_kitchenMenuItems) y de las estaciones de preparación (fk_kitchenStations) con sembrado inicial de estaciones base (seedDefaultStations:hot,cold,bar,expo).
La facturación de cada pedido viaja por el motor fiscal del ERP. Las ventas generan tickets simplificados (B2C) o facturas completas (B2B) y aplican IVA o IGIC según la zona. No hay duplicidad de datos: cada comanda cobrada genera su documento fiscal directamente en el libro registro del ERP (fiscalGateway).
El registro VeriFactu de la venta se envía automáticamente a la AEAT si activas Envío automático a AEAT y tienes un certificado digital válido configurado en Finanzas → Fiscal → Cumplimiento. Con Modo pruebas (sandbox) activo, que es el valor por defecto, el envío va al entorno de pruebas de la AEAT. VeriFactu también se aplica a los contribuyentes con domicilio fiscal en Canarias: la AEAT los incluye en el ámbito del RD 1007/2023 y entiende hechas al IGIC las referencias al IVA (preguntas frecuentes de la AEAT). Con la zona fiscal Canarias, el envío de los registros a la AEAT no está disponible en Frihet.
/kitchenLa gestión visual de plano de mesas (/kitchen/tables), las reservas de mesa y las cuentas abiertas (open_table), así como los conectores directos con agregadores de reparto (Glovo, Uber Eats) o los avisos automáticos por WhatsApp, no están habilitados en la superficie estándar actual de /kitchen.
Los pedidos de reparto o para llevar se registran desde /kitchen/pos seleccionando orderType: 'delivery' o 'takeaway', y sus tiempos o prioridades de entrega pueden actualizarse mediante PATCH /v1/kitchen/tickets/:id indicando courierEtaMinutes.
En @frihet/mcp-server 1.17.0, esa misma actualización de estado, prioridad o ETA de repartidor se realiza con la herramienta MCP update_kitchen_ticket (api_dependent).
Configuración
Activa la app desde Ajustes → Frihet Apps (tarjeta Kitchen) en tu cuenta de Frihet ERP. La app está integrada con Frihet POS — si gestionas restauración, normalmente activarás ambas. La activación incluye un periodo de prueba antes de pasar al plan suscrito.
Las estaciones de cocina (fk_kitchenStations) y los platos del menú con su estación asignada (fk_kitchenMenuItems) se configuran directamente desde /kitchen/management tras activar la aplicación.
Recorrido operativo: de configurar estaciones a comandar, marchar en KDS y revisar tiempos
Este recorrido cubre un servicio completo en Frihet Kitchen para el mismo negocio sintético de referencia (Cafetería Puerto Norte S.L., NIF B12345674 — sintácticamente válido según el algoritmo oficial; el formato válido no acredita existencia en el censo de la AEAT — y correo caja@example.com — dominio reservado por IANA según RFC 6761 para documentación; no es un buzón de QA controlado ni una garantía de impedir envíos): sembrar las estaciones de trabajo, dar de alta platos por estación, comandar y cobrar un pedido en /kitchen/pos, marchar los platos en /kitchen/kds, usar Recall ante un cierre accidental y auditar los tiempos en /kitchen/reports.
| Rol en Kitchen | Permisos asignados (KITCHEN_ENTITLEMENTS) | Superficie operativa permitida |
|---|---|---|
admin | orders.read, orders.write, kds.view, kds.bump, menu.read, menu.write, analytics.view | Acceso completo a resumen, Kitchen POS, KDS, reportes y gestión de menú y estaciones. |
manager | orders.read, orders.write, kds.view, kds.bump, menu.read, menu.write, analytics.view | Gestión operativa del turno, catálogo (fk_kitchenMenuItems), estaciones y analítica. |
chef | orders.read, kds.view, kds.bump, menu.read | Operación del tablero /kitchen/kds, avance de estados por estación y recuperación en Recall. |
waiter | orders.read, orders.write, kds.view, menu.read | Toma de comandas y cobro inmediato en /kitchen/pos y consulta visual de /kitchen/kds. |
viewer | orders.read, kds.view, menu.read | Consulta en solo lectura de pedidos, pantalla KDS y carta. |
Paso 1: Sembrar estaciones y dar de alta platos en Gestión
- Entra en
/kitchen/managementcon un usuarioadminomanager(permisomenu.write). - Si el local no tiene estaciones creadas en
fk_kitchenStations, pulsa Crear estaciones por defecto (seedDefaultStations). El sistema registra las 4 estaciones base ordenadas para el pase:hot(Cocina caliente, orden10),cold(Partida fría / postres, orden20),bar(Barra y bebidas, orden30),expo(Pase / expedición, orden40).
- En la sección de carta (
fk_kitchenMenuItems), crea dos platos de ejemplo paraCafetería Puerto Norte S.L.:- Plato 1:
Arroz meloso de setas—SKU: ARR-010, categoríaPrincipales, estaciónhot, precio16,50 €,available: true. - Plato 2:
Tarta fría de queso—SKU: POS-020, categoríaPostres, estacióncold, precio6,00 €,available: true.
- Plato 1:
Paso 2: Tomar comanda en Kitchen POS y enrutar a estaciones
- Abre
/kitchen/poscon rolwaiter,manageroadmin(orders.write). - Selecciona
1 × Arroz meloso de setas(16,50 €) y1 × Tarta fría de queso(6,00 €) por un total de22,50 €. Si el plato incluye variantes o notas de preparación (por ejemplo, punto de cocción o alérgenos), configúralas en el panelModifierSelectionSheet. - Completa los metadatos operativos del pedido antes de confirmar:
- Etiqueta de mesa o referencia (
tableLabel):"Mesa 4". - Modalidad de pedido (
orderType):"dine-in"(sala),"takeaway"(recogida en local) o"delivery"(reparto). - Método de cobro (
paymentMethoden modalidadpay_now):"card"(admitecash|card|external).
- Etiqueta de mesa o referencia (
- Resultado verificable tras confirmar: Kitchen invoca
fiscalGatewaypara emitir el documento fiscal en el ERP (fiscalInvoiceId,fiscalStatus: 'issued') y registra el ticket enfk_kitchenTicketscon estado inicialqueued, desglosando sus líneas enfk_kitchenTicketItemshacia las estacioneshot(Arroz meloso de setas) ycold(Tarta fría de queso).
Paso 3: Operar el KDS por estación, usar Recall y auditar el servicio
- Filtrado y consolidación en
/kitchen/kds(kds.view/kds.bump):- Selecciona el filtro de estación (
all,hot,cold,bar,expo). En la barra superior, el KDS muestra el contador consolidado de unidades activas en preparación para agrupar marchas idénticas.
- Selecciona el filtro de estación (
- Avance de estados (bump):
- Avanza cada línea o el ticket completo de
"Mesa 4"por las columnas del tablero:queued(Pendiente) →preparing(En preparación) →ready(Listo) →served(Servido). - Al marcar el ticket como
served, el servidor sella las marcas de auditoríacompletedAt,bumpedByybumpedAt.
- Avanza cada línea o el ticket completo de
- Recuperación de tickets cerrados (cajón Recall):
- Si un cocinero o encargado marca por error el ticket de
"Mesa 4"comoservedovoided, pulsa Recuperar tickets (Recall) en/kitchen/kds. - El cajón consulta los tickets de los últimos 30 días en
fk_kitchenTicketsordenados porcreatedAt descy permite restituir el ticket seleccionado al estadoready.
- Si un cocinero o encargado marca por error el ticket de
- Cierre y auditoría del servicio en
/kitchen/reports(analytics.view), API REST v1 y MCP:- En
/kitchen/reports, revisa las 4 tarjetas principales (activeTickets,avgPrepMinutes,servedTickets,readyRate%), la tabla de carga por estación (stationLoad) y el desglose por estado (statusMix). - API REST v1: consulta o integra el flujo con
GET /v1/kitchen/tickets,GET /v1/kitchen/stations,GET /v1/kitchen/menu-itemsyPATCH /v1/kitchen/tickets/:id. - Servidor
@frihet/mcp-server1.17.0: las 6 herramientas MCP del dominio Kitchen (list_kitchen_tickets,get_kitchen_ticket,update_kitchen_ticket,list_kitchen_stations,list_menu_items,kitchen_flow_summary, todas conapi_dependent) exponen el estado de comandas, estaciones y métricas de flujo a tus agentes.
- En
Recuperación ante incidencias operativas en Kitchen
| Incidencia durante el servicio | Estado o campo afectado | Acción de recuperación verificada |
|---|---|---|
| Pedido retenido en cocina o con retraso de repartidor | status: 'on_hold', holdReason (máx. 140 caracteres), priority: 'rush' o courierEtaMinutes (0–240) | Envía PATCH /v1/kitchen/tickets/:id (o invoca update_kitchen_ticket) indicando status: 'on_hold' y el motivo en holdReason, o eleva la prioridad a priority: 'rush' actualizando courierEtaMinutes. |
Ticket marcado como served o voided antes de entregar un plato | Ticket fuera de las columnas activas del tablero /kitchen/kds | Abre el cajón Recuperar tickets (Recall) en /kitchen/kds (historial de los últimos 30 días en fk_kitchenTickets ordenado por createdAt desc) y pulsa Recuperar para devolverlo al estado ready. |
Fallo de emisión fiscal al comandar (fiscalStatus: 'failed') | Ticket en fk_kitchenTickets sin fiscalInvoiceId válido | Localiza el ticket con fiscalStatus: 'failed', verifica que el NIF/CIF, la dirección y la serie estén completos en Ajustes → Perfil Fiscal y Finanzas → Fiscal → Cumplimiento, y reintenta. |