bench get-app https://github.com/HOLGUINUPC/erpnext-restaurant-pos

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=HOLGUINUPC%2Ferpnext-restaurant-pos)](https://frappegems.com/gems/apps/HOLGUINUPC/erpnext-restaurant-pos)

Restaurant POS — Gestion de Restaurante y Punto de Venta

Aplicacion personalizada para Frappe v15 + ERPNext v15 que gestiona la operacion completa de un restaurante: mesas, carta/menu, comandas (pedidos), pantalla de cocina en tiempo real, cobro y facturacion integrada con ERPNext. Desarrollada con etiquetas en espanol e IGV al 18% (Peru).

Aplicacion de portafolio para demostrar dominio de ERPNext/Frappe: DocTypes personalizados, controladores, reportes, formatos de impresion, integraciones por API (webhook de pedidos online), eventos en tiempo real (frappe.publish_realtime) e integracion con Item / Sales Invoice / Stock.

---

Requisitos

• Frappe Framework v15
• ERPNext v15 (para Item, Customer, Employee, Sales Invoice)
• Python >= 3.10, MariaDB, Redis (provistos por el bench)

---

Features mapeadas a requisitos del puesto

Requisito del puesto	Como lo demuestra esta app
DocTypes personalizados	Restaurant Table, Menu Category, Menu Item, Restaurant Order (submittable), Order Item (child)
Controladores (server-side)	restaurant_order.py: calculo de totales + IGV, transiciones de estado, generacion de factura
Integracion con ERPNext	Menu Item -> Item; al pagar se crea una Sales Invoice (POS); concepto de Stock y POS Profile
Reportes personalizados	Ventas por Producto, Ventas por Mesero (Script Reports con filtros de fecha)
Formatos de impresion	Comanda de Cocina (ticket termico) y Cuenta / Pre-Cuenta (cuenta en espanol con IGV)
Integraciones por API / Webhooks	api.py: create_online_order (webhook delivery), get_kitchen_orders (KDS), update_item_status, get_menu (QR)
Tiempo real	frappe.publish_realtime para la Pantalla de Cocina (KDS)
Roles y permisos	Restaurant Manager, Waiter, Cashier, Kitchen (fixtures) con permisos por DocType
Tareas programadas	tasks.close_stale_orders (scheduler cada 15 min)
Pagina web / portal	www/menu.html — carta digital publica por QR

---

Arquitectura

DocTypes y relaciones

Menu Category 1───* Menu Item ──── (Link) ────> ERPNext Item
                        │
                        * (referenciado en)
                        │
Restaurant Table 1──* Restaurant Order 1──* Order Item
   (estado mesa)        │ (submittable)
                        │
   Employee (waiter) ───┤
   Customer ────────────┤
                        │ al pagar (status = Pagada)
                        ▼
                 ERPNext Sales Invoice (is_pos) ──> Contabilidad / Stock

• Restaurant Table (Mesa): table_number (unico), area (Salon/Terraza/Barra/VIP), seats, status (Libre/Ocupada/Reservada/Cuenta Solicitada).
• Menu Category: category_name, display_order.
• Menu Item: item_name, category, item (Link a ERPNext Item), price (Currency), is_available, preparation_area (Cocina/Barra/Parrilla), description.
• Restaurant Order (Comanda): submittable. table, order_type (Salon/Para Llevar/Delivery), waiter (Employee), customer, status, hijo order_items, totales subtotal / igv / total, sales_invoice.
• Order Item (child): menu_item, qty, rate (fetch), amount, notes, kitchen_status (Pendiente/Preparando/Listo).

Calculo de IGV

Los precios del menu se consideran con IGV incluido (practica de retail en Peru). El controlador desagrega:

total     = suma(qty * rate)
subtotal  = total / 1.18
igv       = total - subtotal

---

Instalacion

# En la carpeta del bench
bench get-app restaurant_pos /ruta/a/restaurant_pos
bench --site mi-sitio install-app restaurant_pos
bench --site mi-sitio migrate
bench build

La instalacion/migracion crea automaticamente: - Los 4 roles (Restaurant Manager, Waiter, Cashier, Kitchen) via fixtures. - El campo personalizado restaurant_order en Sales Invoice (via install.after_install).

---

Flujo de funcionamiento

1. Abrir mesa: el mesero crea una Restaurant Order con la Mesa y sus items. Al enviar (submit) la mesa pasa a Ocupada.
2. Comanda -> Cocina (tiempo real): el submit / cambio a En Preparacion dispara frappe.publish_realtime("new_kitchen_order", ...). La Pantalla de Cocina (KDS) recibe el ticket al instante.
3. Preparar y servir: cada cocinero marca los items (Pendiente -> Preparando -> Listo) desde el KDS (api.update_item_status), que publica kitchen_item_update; el dispositivo del mesero se actualiza solo. Estado del pedido -> Servida.
4. Cobrar: el pedido pasa a Pagada. El controlador genera una Sales Invoice de ERPNext (is_pos) referenciando los items y libera la mesa (Libre).
5. Factura: la venta queda en contabilidad; si el Menu Item esta ligado a un Item de ERPNext, tambien puede mover Stock.

---

API / Integraciones

Todos los endpoints estan en restaurant_pos/restaurant_pos/api.py y son @frappe.whitelist().

1. Webhook de pedidos online / delivery

curl -X POST "https://mi-sitio/api/method/restaurant_pos.restaurant_pos.api.create_online_order" \
  -H "Authorization: token API_KEY:API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "order_type": "Delivery",
    "customer_info": {"customer": "CUST-0001"},
    "items": [
      {"menu_item": "Lomo Saltado", "qty": 2, "notes": "Sin cebolla"},
      {"menu_item": "Chicha Morada", "qty": 2}
    ]
  }'

Respuesta: {"order": "REST-ORD-2026-00012", "status": "created", "total": 96.0}. El pedido entra al mismo flujo de cocina/cobro que uno presencial.

2. Pantalla de Cocina (KDS)

# Obtener pedidos con items pendientes
curl "https://mi-sitio/api/method/restaurant_pos.restaurant_pos.api.get_kitchen_orders" \
  -H "Authorization: token API_KEY:API_SECRET"

# Marcar un item como listo
curl -X POST "https://mi-sitio/api/method/restaurant_pos.restaurant_pos.api.update_item_status" \
  -H "Authorization: token API_KEY:API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"order": "REST-ORD-2026-00012", "row": "abc123", "status": "Listo"}'

3. Carta digital por QR (publica)

curl "https://mi-sitio/api/method/restaurant_pos.restaurant_pos.api.get_menu"

Tambien disponible como pagina web en /menu (www/menu.html).

---

Tiempo real y Pantalla de Cocina (KDS)

La app usa el bus de eventos de Frappe (frappe.publish_realtime, sobre Socket.IO / Redis). Eventos publicados:

Evento	Emisor	Consumidor
new_kitchen_order	RestaurantOrder.notify_kitchen()	Pantalla de Cocina (KDS)
kitchen_item_update	api.update_item_status()	Dispositivo del mesero / KDS
order_paid	al pagar	Caja / dashboard
stale_order_alert	tarea close_stale_orders	Dashboard del gerente

Un KDS (pagina/app) se suscribe con:

frappe.realtime.on("new_kitchen_order", (data) => renderTicket(data));

Asi la cocina ve la comanda sin recargar ni hacer polling.

---

Roles

Rol	Uso tipico	Permisos clave
Restaurant Manager	Gerente	Total sobre todos los DocTypes y reportes
Waiter	Mesero	Crear/editar/enviar comandas; lectura de carta y mesas
Cashier	Cajero	Cobrar (submit/cancel de pedidos), lectura de carta; reportes
Kitchen	Cocina	Lectura de pedidos y carta; actualizar estado de items

---

Estructura del proyecto

restaurant_pos/
  restaurant_pos/
    __init__.py, hooks.py, modules.txt, patches.txt, install.py
    config/
    www/menu.html
    restaurant_pos/
      api.py, tasks.py
      doctype/{restaurant_table,menu_category,menu_item,restaurant_order,order_item}/
      report/{ventas_por_producto,ventas_por_mesero}/
      print_format/{comanda_de_cocina,cuenta_pre_cuenta}/
      workspace/restaurant_pos/
  README.md, license.txt, pyproject.toml, MANIFEST.in, requirements.txt, .gitignore

---

Capturas

(Placeholder — agregar capturas de pantalla de la Comanda, la Pantalla de Cocina, la Cuenta/Pre-Cuenta y los reportes.)

---

Licencia

MIT — ver license.txt.