Skip to content

Cómo funciona Kamra ​

Esta página es el mapa del sistema: qué piezas hay, cómo pasa una estancia por ellas, dónde se decide el dinero y cómo las personas, los clientes REST y los agentes de IA comparten una única vía de escritura.

Qué lo hace único: Kamra es nativo para agentes. Claude (o cualquier cliente MCP) llama a las mismas herramientas limitadas por rol que la recepción. Los precios nunca salen del modelo. Esa es la ventaja del producto; el resto de esta página muestra cómo el sistema lo hace seguro. Las guías de cada módulo explican las tareas diarias del hotel.

Versión estable actual:v2.6.20 (rama main). Las compilaciones nocturnas siguen develop. Instale desde Frappe Cloud Marketplace o en su propio servidor.

La regla que sigue todo lo demás ​

Hay una sola vía de escritura. La interfaz de recepción, REST, el servidor MCP alojado y el Agente Kamra integrado llaman a las mismas funciones @frappe.whitelist. Los precios, el GST/IVA, la disponibilidad y los cargos por cancelación son código (kamra/pricing.py, libro del folio, auditoría nocturna). Un modelo de lenguaje nunca inventa una tarifa. Si falta un rol o un número está fuera de los límites, la función se niega.

No añada un segundo escritor (SQL directo que se salta la API, un importe en el que se confía porque lo envía el cliente en un endpoint público, una herramienta MCP que calcula su propio precio).

El sistema de un vistazo ​

CapaQué es
Interfaz del personalSPA de React en /kamra (y /hk para limpieza)
Superficies para huéspedes/book, /stay/:slug, registro de entrada en línea
APIMétodos de Frappe en lista permitida: POST /api/method/kamra.<module>.<fn>
AgentesMCP alojado en /mcp (OAuth) o proceso auxiliar stdio mcp/kamra_mcp.py
DineroMotor de precios, libro del folio, cajero, auditoría nocturna
DatosMariaDB mediante DocTypes de Frappe; cargos del folio solo por adición
Opcionalpayments (obligatoria), ERPNext / Frappe HR en el mismo sitio
mermaid
flowchart TB
  subgraph clients [Clients]
    UI["Staff UI /kamra"]
    Guest["Guest /book · check-in · QR"]
    REST["REST token"]
    Claude["Claude / MCP client"]
    Copilot["Kamra Agent copilot"]
  end

  subgraph gate [One write path]
    WL["kamra.*.fn<br/>@whitelist + @require_roles"]
  end

  subgraph core [Deterministic core]
    Price["pricing.py"]
    Folio["folio + ledger"]
    Avail["availability · overlap"]
    Policy["cancel / no-show / deposit"]
  end

  DB[(MariaDB)]
  Log["Agent Action Log"]

  UI --> WL
  Guest --> WL
  REST --> WL
  Claude --> WL
  Copilot --> WL
  WL --> Price
  WL --> Folio
  WL --> Avail
  WL --> Policy
  Price --> DB
  Folio --> DB
  Avail --> DB
  Policy --> DB
  WL --> Log

Superficies del producto ​

URLQuiénPara qué
/kamraPersonalPMS completo (Hoy, calendario, folio, punto de venta, configuración, …)
/kamra/hkLimpiezaPanel de habitaciones y tareas, pensado para el móvil
/kamra/setupAdministraciónAsistente de configuración inicial del alojamiento
/bookHuéspedesReserva directa / catálogo de villas
/stay/:slugHuéspedesSitio de un anuncio o de varios anuncios
/appTIFrappe Desk (vía de escape; no es la interfaz del producto hotelero)
/mcpAgentesMCP por HTTP con streaming (OAuth 2.1)

Los recursos de la SPA de producción vienen precompilados en kamra/public/frontend. Las instalaciones desde Marketplace y Docker no ejecutan npm en el servidor.

Ciclo de la estancia ​

mermaid
sequenceDiagram
  participant G as Guest / Agent / Desk
  participant Q as get_quote
  participant B as create_booking / public book
  participant C as check_in
  participant F as Folio
  participant N as Night audit
  participant X as check_out

  G->>Q: dates, room type, meal, adults
  Q-->>G: nights, tax, total (code)
  G->>B: confirm (or request-to-book)
  Note over B: Instant book holds inventory<br/>RtB waits for host approve
  B-->>G: reservation + optional deposit link
  G->>C: assign room, ID, open folio
  C->>F: Guest folio opened
  loop Each business date
    N->>F: post room night / no-show / holds
  end
  G->>X: settle balance, close folio
  X->>F: invoice number once, status Closed
  1. Cotización: get_quote calcula el precio de cada noche a partir de los planes de tarifas, las temporadas, los regímenes de comidas, los vales, las mascotas, los cargos de limpieza y el paquete fiscal del país.
  2. Reserva: create_booking desde recepción o public_api.book desde la web pública. La reserva inmediata guarda la política de pago; la solicitud de reserva no retiene inventario hasta que se confirma.
  3. Antes de la llegada: depósito opcional, enlace de registro de entrada en línea, plantillas de WhatsApp, captura del documento de identidad.
  4. Registro de entrada: asignación de habitación, ficha de registro, apertura del folio.
  5. Alojados: cargos a la habitación desde el punto de venta, lavandería, solicitudes, cambio de habitación, cargos por llegada anticipada o salida tardía como políticas en el código.
  6. Auditoría nocturna: una sola página a mano, o programada a las 03:00: registra las noches de habitación, las no presentaciones y las retenciones por llegada tardía, avanza la fecha operativa y guarda el paquete de auditoría.
  7. Salida: todas las cuentas liquidadas (o reglas de liquidación parcial), el folio se cierra y el número de factura se asigna una sola vez.

Módulos (lo que gestiona el hotel) ​

Los módulos del alojamiento (enabled_modules, vacío = todos) controlan tanto la interfaz como las herramientas MCP visibles:

MóduloQué cubreGuía para el personal
RecepciónHoy, entrada/salida, calendario, sin reserva previa, ficha de registroRecepción
ReservasReservas, grupos, bloqueos, lista de espera, central de reservasReservas
FacturaciónFolios, pagos, cuentas por cobrar, cajero, facturasFacturación
Auditoría nocturnaAuditoría nocturna, fecha operativa, no presentaciónAuditoría nocturna
LimpiezaPanel de habitaciones, aplicación /hk, lavandería, objetos perdidosLimpieza
OperacionesSolicitudes de huéspedes / solicitudes con SLASolicitudes de huéspedes
Alimentos y bebidasPunto de venta, comandas (KOT), pantalla de cocinaAlimentos y bebidas
EventosBanquetes desde la consulta hasta la orden de evento (BEO)Banquetes
IngresosTarifas, temporadas, tarifas mínimas por demanda, valesIngresos
Motor de reservas/book, catálogo de villas, políticasMotor de reservas
MensajeríaWhatsApp en su número de MetaWhatsApp
CanalesSincronización con OTA / channel managerChannel manager
Finanzas / administraciónInformes, configuración, desarrolladores, estadoInformes, Configuración

Los paquetes fiscales por país, la privacidad (DPDP) y la conexión de IA están en Configuración por país, Funciones y Conecte su IA.

Dinero y libros contables ​

mermaid
flowchart LR
  Quote[Quote snapshot] --> Stay[Reservation]
  Stay --> GF[Guest folio]
  Stay --> DF[Deposit folio]
  POS[POS / laundry / fees] --> GF
  Night[Night audit room night] --> GF
  Pay[Payments / links] --> GF
  GF --> Inv[Tax invoice on close]
  Corp[Company AR] --> AR[AR folio / city ledger]
  GF -.->|route / transfer| Corp

Reglas estrictas aplicadas en el código:

  • Cargos solo por adición. Las anulaciones son líneas de reversión con un motivo, no ediciones sobre la línea original.
  • Para cerrar hace falta saldo cero (o una vía explícita de liquidación parcial).
  • Límites de tarifas: set_room_rate no puede salirse del mínimo / máximo del propietario; las tarifas mínimas por demanda añaden mínimos según la demanda.
  • El alcohol nunca se factura a un folio de empresa al cargar a la habitación desde el punto de venta.
  • Cancelación / no presentación: los cargos salen de los endpoints de vista previa de la política; la condonación queda registrada.
  • Cajero: sesión abierta; PIN opcional para personas; los agentes no usan PIN pero quedan en el registro de actividad.
  • Paquete de localización: elige el desglose de impuestos, los importes en letras y las etiquetas de la factura. Los tramos de GST de la India van por noche según la tarifa.

Autenticación, roles y alcance por alojamiento ​

Roles (ejemplos): Recepción, Responsable de ingresos, Finanzas, Limpieza, Administrador del hotel, Administrador del sistema, Agente Kamra, Auditor nocturno, Gerente de alimentos y bebidas.

Los controles están en el endpoint (@require_roles / _kamra_roles), no solo en los DocPerms. Las instalaciones con varios alojamientos usan Property User Permissions y hooks de Kamra para que un usuario restringido no pueda leer ni sobrescribir las reservas, los folios ni los datos personales de huéspedes de otro alojamiento a través de Desk o REST.

Cómo encaja la IA ​

mermaid
flowchart LR
  Claude[Claude Desktop / Code] -->|OAuth Bearer| MCP["/mcp JSON-RPC"]
  Stdio[mcp/kamra_mcp.py] -->|API key| API[Same whitelist fns]
  Agent[In-app Kamra Agent] -->|BYO OpenAI-compatible key| API
  MCP --> API
  API --> Core[pricing · folio · authz]
  API --> AAL[Activity Log]
  • 116 herramientas controladas en develop (consulte Herramientas MCP); la rama estable main publica el número para esa etiqueta.
  • Las herramientas se filtran por rol ∩ rol MCP ∩ módulos activados ∩ interruptores de IA del alojamiento (consulte Who can use MCP).
  • Las herramientas que modifican datos activan frappe.flags.kamra_agent_call y registran mcp_<name>.
  • Interfaz de conexión: Agente Kamra → Conecte su IA. Conectar Claude requiere HTTPS público.

Resumen de integraciones ​

IntegraciónVía
Pagos / enlacesAplicación payments + paquetes Razorpay / Cashfree para la India
WhatsAppMeta Cloud API en su número: guía
Channel managerEnvío de ARI / webhooks: guía
Webhooks salientesEventos salientes firmados (reservas, auditoría nocturna, …)
ERPNext / RR. HH.Aplicaciones opcionales en el mismo sitio: guía
Exportación contableCSV para Tally / Zoho / ERPNext desde Informes

Programador (tareas integradas) ​

De hooks.py (lo habitual):

  • Envío de ARI / canales cada hora donde esté configurado
  • Auditoría nocturna a las 03:00 (según la configuración del alojamiento)
  • Enlaces previos a la llegada a las 09:00
  • Cada 15 min, escalado de limpieza y caducidad de retenciones
  • Recordatorios de banquetes a las 08:30
  • Restablecimiento de la demo a las 04:15 (solo con kamra_demo_mode)

Mapa del repositorio (para colaboradores) ​

RutaFunción
kamra/api.pyNúcleo de recepción: cotización, reserva, entrada/salida, limpieza, solicitudes
kamra/pricing.pyTarifas e impuestos deterministas
kamra/folio.py / ledger.py / cashier.pyDinero
kamra/pos.py / laundry.py / banquet*.pyAlimentos y bebidas y eventos
kamra/mcp_tools.py / mcp_http.py / mcp_oauth.pyMCP
kamra/public_api.pyEndpoints allow_guest para huéspedes (con límite de peticiones)
kamra/authz.pyRoles y alcance por alojamiento
kamra/localization/Paquetes por país
frontend/src/SPA de React
docs-site/Esta documentación (VitePress)

Siguientes pasos ​

Código abierto (Apache-2.0) · documentación de Kamra v2.8.0 · todas las funciones incluidas, siempre.