Integración de Sihot con Ágora: cargos a habitación y Z-cierre

La integración de Sihot (SIHOT) con Ágora carga en la cuenta del huésped lo que consume en el restaurante o el bar del hotel y envía a Sihot el Z-cierre con las ventas del día a clientes no alojados. También imprime la firma del huésped en el albarán y anula en Sihot el cargo de un albarán anulado en Ágora. Todo pasa por Connect Manager, que guarda el registro de cada operación.

Este manual es para el técnico de FOS o del distribuidor que la configura: qué datos pedir, dónde meterlos, cómo funciona, cómo comprobarla y qué hacer cuando falla.

Qué hace la integración#

• Abre desde Ágora, con una acción personalizada, la pantalla de cargo de Connect Manager dentro de un diálogo del TPV.
• Busca la habitación en Sihot por número y enseña los Datos de la reserva: Nº de hab., un desplegable Cliente con los huéspedes de la habitación, Checkin, Checkout, Regimen y Lím. Créd. Si el límite de crédito es menor que el ticket, el botón Cargar se desactiva.
• Avisa al abrir si el ticket lleva descuentos que no admite: por importe, o por línea y a pie de ticket a la vez.
• Si activas Solicitar firma, recoge la firma del huésped y la imprime en el albarán de Ágora.
• Crea el albarán en Ágora desde el propio TPV, a nombre del huésped elegido con su habitación (Nombre Apellido (Nº hab.: 101)) sobre el cliente configurado, y después envía el cargo a la cuenta de ese huésped: línea a línea (centro de venta, familia, producto, formato, cantidad, precio, IVA, albarán, caja y usuario) o, con Concepto único bien configurado, en una sola línea. Puede añadir el número de comensales.
• Anula el cargo: al anular en Ágora un albarán de la integración, envía a Sihot el abono a la misma cuenta.
• Envía el Z-cierre: las facturas de Ágora del día (ventas a no alojados), agrupadas, con sus formas de pago, a la cuenta de una habitación de Sihot.
• Guarda en Connect Manager cada cargo y cada cierre, con lo enviado y la respuesta de Sihot.

Qué no hace#

• No envía las facturas de Ágora a Sihot. Si Ágora las manda a la URL de documentos, Connect Manager las acepta sin enviarlas. Las ventas a no alojados solo llegan agrupadas en el Z-cierre.
• No busca por nombre del huésped ni por tarjeta: solo por número de habitación.
• No envía propinas ni manda la firma a Sihot: la firma queda en Connect Manager y se imprime en el albarán.
• El envío automático del Z-cierre a la Hora de generación fich. contable y la cancelación de albaranes abiertos tras Nº de días para cerrar albaranes dependen de tareas programadas del motor que hoy no están activas. El Z-cierre se lanza a mano desde el panel.
• No sincroniza reservas, disponibilidad ni tarifas.

Requisitos#

• Connect Manager: el local dado de alta en app.connectmanager.es. La URL de API y la API key de Ágora van en los datos del local, no en la integración. El alta del local y de la integración la hace FOS (el botón Añadir solo lo ven los administradores); el distribuidor revisa y completa el resto.
• Ágora: acceso para crear acciones personalizadas y botones, un cliente genérico para los albaranes y acceso a la configuración del servicio para activar la integración de documentos (firma y anulaciones).
• Conectividad: el cargo lo hace el TPV a través del diálogo, con su API local. Connect Manager sí necesita llegar a la API de Ágora (puerto 8984, publicada o con Zero Connect) para las listas del panel y para el Z-cierre, que lee las facturas desde fuera. Los «buscadores» vacíos casi siempre son falta de conexión con esa API.
• Sihot: la URL de su interfaz, un usuario y contraseña de integración y el identificador del hotel; para el Z-cierre, una habitación ocupada que haga de cuenta de las ventas externas y las formas de pago de Sihot.

Reparto de tareas: FOS da de alta el local y la integración; el distribuidor rellena los campos, hace las asociaciones y configura Ágora; el hotel o Sihot facilita credenciales, identificadores y la habitación del Z-cierre.

Datos que necesitamos#

Configuración paso a paso#

En Sihot#

1. Pide al hotel o a Sihot la URL de la interfaz, el usuario, la contraseña y el identificador del hotel.
2. Decide con el hotel cómo se identifican las cajas en Sihot (por local, por TPV o por centro de venta de Ágora) y pide sus números.
3. Si se usa el Z-cierre: la habitación que hará de cuenta de las ventas a no alojados, que tiene que estar ocupada, y las formas de pago de Sihot.
4. Si se quiere Concepto único: los identificadores y descripciones de Middlecat, Articlecat y Articleno que usará Sihot.

En Connect Manager: datos del local#

1. Entra en https://app.connectmanager.es y ve a Administración → Locales. Abre el local.
2. Revisa URL de API y API key de Ágora y pulsa el botón de prueba junto a la URL: debe salir Conexión con éxito.
3. Pulsa Guardar.

En Connect Manager: la integración de hoteles#

1. En la columna de la derecha, entra en Integraciones → Integraciones de hoteles. Abre la de Sihot o, si eres administrador, pulsa Añadir y elige el Proveedor Sihot.
2. En Conf. general rellena URL Api:, Usuario, Password, Id. del hotel y, si quieres avisos, Email de receptor de notificaciones. Ahí llegan los errores del Z-cierre; los fallos de un cargo no se avisan por correo.
3. Para el Z-cierre, en Conf. de Z-cierre marca Z-cierre y rellena Núm. de habitación de Z-cierre y Hora de generación fich. contable. Cada vez que guardas, Connect Manager pide a Sihot la cuenta de esa habitación y la usa en los cierres: si no está ocupada, no la obtiene y, si nunca se obtuvo, el cierre fallará.
4. En Conf. de cargos ajusta las opciones de la tabla y elige el Cliente.
5. Pulsa Guardar: sale Se ha guardado la integración de hoteles y se activan las pestañas de asociaciones.
6. En Familias, por cada familia con identificador propio en Sihot: Familia (de Ágora) e Id. del servicio.
7. La segunda pestaña se llama Local, TPV o Centro de venta según Agrupar cargos por.... Por cada entidad: la de Ágora, Tipo de facturación (Interna para los cargos a habitación, Externa para el Z-cierre; si necesitas las dos, crea dos filas), External id. (el número de caja de Sihot) y Nombre externo.
8. En Métodos de pago, por cada forma de pago de Ágora: Método de pago de Agora y Método de pago Sihot (la lista viene de Sihot). Con Z-cierre, asócialas todas.
9. En Enlaces, copia la URL botón acción personalizada y, si aparece, la URL para enviar facturas desde Ágora: solo se muestra con Dejar abierto el albarán o Solicitar firma marcadas.

Pausar el envío de cargos al PMS y Pausar el envío de cargos al PMS después de solo los ven los administradores de FOS; con el envío pausado, el TPV muestra Integración pausada.

En Ágora#

1. Si no existe, crea el cliente genérico para los albaranes y comprueba que es el elegido en Cliente.
2. Ve a Herramientas → Acciones personalizadas y pulsa + Nuevo: Texto «Cargo habitación», Tipo Url/Aplicación y, en Acción, la URL botón acción personalizada tal cual, con sus marcadores {user_id}, {pos_id}, {ticket_global_id}…
3. Marca Mostrar Urls en un diálogo de Ágora: la pantalla lee el ticket y crea el albarán a través de ese diálogo.
4. En Herramientas → Configuración de Botones, coloca la acción en un botón del perfil del local y da el permiso de la acción a los perfiles que vayan a cargar.
5. Para la firma y las anulaciones: en la configuración del servicio de Ágora, entra en Activar módulos adicionales → Servicios de integración, pega la URL para enviar facturas desde Ágora y marca Habilitar integración de documentos y Enviar albaranes.

Las URL tienen esta forma, precedidas del dominio que muestre el panel: /venues/123/hotels/sihot/query-chargeable-room/?user={user_id}&pos_id={pos_id}&ticket_id={ticket_id}&ticket_global_id={ticket_global_id}&ticket_line_index={ticket_line_index}&introduced_value={introduced_value} para la acción y /api/venues/123/hotels/sihot/generate-invoice para los documentos.

Cómo funciona#

Al pulsar la acción, el diálogo carga la pantalla de Connect Manager, que pide al TPV el ticket abierto. El camarero escribe la habitación; Connect Manager se identifica en Sihot (guarda el token hasta que caduca) y trae los huéspedes de esa habitación. Elige el huésped en Cliente, el huésped firma si se pide y pulsa Cargar. El orden es: primero se sube la firma, después el TPV crea el albarán y, por último, Connect Manager envía el cargo a la cuenta del huésped en Sihot. Si Sihot lo acepta, sale «Se generó el siguiente cargo:» con el número interno del registro y el diálogo se cierra a los dos segundos.

sequenceDiagram
    participant C as Camarero
    participant AG as TPV Ágora
    participant CM as Connect Manager
    participant SH as Sihot
    C->>AG: Pulsa la acción Cargo habitación
    AG->>CM: Abre la pantalla de cargo en un diálogo
    CM->>AG: Pide el ticket por la API local
    C->>CM: Escribe el nº de habitación
    CM->>SH: Consulta la habitación
    SH-->>CM: Huéspedes, fechas, régimen y crédito
    C->>CM: Elige huésped, firma y pulsa Cargar
    CM->>AG: Crea el albarán por la API local
    opt Con la integración de documentos activa
        AG->>CM: Envía el albarán a la URL de documentos
        CM-->>AG: Acepta y devuelve la firma para imprimir
    end
    CM->>SH: Cargo a la cuenta del huésped
    SH-->>CM: Cargo aceptado
    CM-->>C: Se generó el siguiente cargo

Cada línea del cargo lleva el centro de venta, la familia (con el Id. del servicio asociado o el de Ágora), el producto, el formato, la cantidad, el precio unitario y total con los descuentos repartidos, el IVA, el número de albarán (SERIE/000123), la caja (según Agrupar cargos por..., con su asociación Interna) y el usuario de Ágora. Los platos de menú a 0 € no se envían. Como el albarán se crea antes, si Sihot rechaza el cargo el albarán ya existe en Ágora y la pantalla dice «No se ha podido generar el albarán…»; el motivo de Sihot queda en Operaciones hoteleras → Cargos.

Anulación de un cargo#

Con la integración de documentos activa en Ágora, al anular un albarán que salió de la integración Ágora envía el documento de anulación a la URL de documentos. Connect Manager localiza el cargo por la serie y el número del albarán y envía a Sihot el abono a la misma cuenta. Si Sihot lo rechaza, Connect Manager responde a Ágora con el rechazo y el motivo. Los albaranes que no salieron de la integración se aceptan sin tocar Sihot.

El Z-cierre#

Se lanza desde Inicio, en el recuadro Generar cierre Z del hotel (Sihot) (Local, Fecha y Click para generar), o desde Operaciones hoteleras → Cierres de caja, seleccionando un cierre y pulsando Exportar. Connect Manager pide a Ágora las facturas de ese día de negocio, las agrupa por local, TPV o centro de venta (con su asociación Externa), suma las líneas por formato (o en un concepto único) y envía a la cuenta de la habitación del Z-cierre las líneas, el rango de facturas, los pagos por forma de pago de Sihot y, si está activado, los comensales.

flowchart TD
    A[Inicio o Cierres de caja] --> B{Cierre de ese día ya enviado}
    B -->|sí| X[No se vuelve a enviar]
    B -->|no| C[Lee de Ágora las facturas del día]
    C --> D{Todas las formas de pago asociadas}
    D -->|no| E[Error de mapeo, aviso por correo]
    D -->|sí| F[Envía el cierre a la cuenta del Z-cierre]
    F --> G{Respuesta de Sihot}
    G -->|correcta| H[Estado Enviado]
    G -->|error| I[Estado Error con el mensaje]

El resultado queda en Cierres de caja: Enviado, Error (con el mensaje de Sihot en Error en la respuesta externa) o No hay datos. Si falla antes de enviar (una forma de pago sin asociar, la cuenta del Z-cierre sin obtener, Ágora sin respuesta), el estado no cambia (Creado la primera vez) y el motivo llega por correo a las direcciones de notificaciones. Un cierre enviado no se repite. El aviso del recuadro de Inicio es siempre el mismo, así que el resultado se mira en Cierres de caja.

Comprobar que funciona#

1. La prueba de la URL de API del local da Conexión con éxito y en la integración el buscador de Cliente lista clientes de Ágora; la lista de Método de pago Sihot carga (credenciales correctas).
2. Abre en Ágora un ticket de prueba sin descuentos y pulsa la acción. Busca una habitación ocupada: salen sus huéspedes y los datos de la reserva.
3. Pulsa Cargar (y firma si está activado): debe salir «Se generó el siguiente cargo:» y cerrarse el diálogo.
4. En Ágora queda el albarán impreso con «huésped (Nº hab.: …)» y, si se pidió, la firma bajo FIRMA:.
5. En Sihot, la cuenta del huésped tiene las líneas con la caja esperada.
6. Si usas anulaciones, anula el albarán en Ágora: en Sihot debe aparecer el abono.
7. Si usas Z-cierre, genéralo desde Inicio para un día con ventas y comprueba en Cierres de caja que queda Enviado y en Sihot la cuenta de la habitación del Z-cierre.
8. En Operaciones hoteleras → Cargos están las operaciones con Pedido externo (request) y Pedido externo (response).

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Sihot con Ágora?#

FOS da de alta la integración de hoteles con el proveedor Sihot; tú pones la URL, el usuario, la contraseña y el Id. del hotel, eliges el cliente, haces las asociaciones y creas en Ágora una acción personalizada con la URL del panel, mostrada en un diálogo.

¿Se envían las facturas de Ágora a Sihot?#

No una a una. Las ventas a no alojados llegan agrupadas en el Z-cierre, a la cuenta de la habitación configurada.

¿Cómo se anula un cargo enviado a Sihot?#

Anulando el albarán en Ágora, con la integración de documentos configurada: Connect Manager envía el abono a la misma cuenta de Sihot.

¿Dónde queda la firma del huésped?#

Se guarda en Connect Manager y se imprime en el albarán de Ágora; no se envía a Sihot.

¿Se puede buscar al huésped por nombre?#

No: se busca por número de habitación y luego se elige el huésped en el desplegable Cliente.

Referencias#

• Ficha del catálogo: Sihot
• Visión general de los cargos a habitación: Hotel Hub: cómo funciona
• Otros PMS: Guest Pro, Hospedium, UbikOS y Redforts
• Zero Connect: conectar Ágora sin abrir puertos
• Direcciones IP de Connect Manager