Integración de Shiji con Ágora: cargos a habitación

La integración de Shiji con Ágora conecta el TPV con el PMS de Shiji mediante sus servicios HTNG: permite cargar un ticket a la reserva de un huésped alojado desde una acción personalizada de Ágora y enviar a Shiji, en el momento, cada factura del TPV con sus formas de pago. Este manual es para el técnico que la configura: qué datos pedir a Shiji, cómo rellenar Connect Manager y Ágora, cómo funciona por dentro y cómo resolver los fallos.

Qué hace la integración#

• Busca la reserva alojada por número de habitación y muestra huésped, estado, check-in, check-out, régimen, límite de crédito, saldo, membresía, preferencias, notas, código de grupo, idioma y nivel VIP.

• Si Shiji indica que la reserva no admite cargos, avisa y no deja cargar.

• Crea el albarán en Ágora a nombre del huésped y envía a Shiji el cargo a la cuenta de la reserva con: centro de ingresos, turno de comida, mesa, comensales, camarero, una línea por producto, el descuento del ticket como línea aparte, el cargo por servicio si lo hay y el texto completo del albarán.

• Elige el turno de comida según la hora del albarán y los turnos que configures.

• Envía a Shiji cada factura del TPV en el momento en que se emite, con sus líneas y sus cobros, usando los códigos de forma de pago de Shiji. Así Shiji recibe también las ventas de clientes no alojados.

• Anula el cargo en Shiji cuando se cancela el albarán en Ágora, con las mismas líneas en negativo.

Qué no hace#

• No busca por nombre ni por tarjeta: solo por número de habitación. Si hay varias reservas, usa la primera que devuelve Shiji.

• No envía propinas ni recoge la firma del huésped.

• No traduce el centro de venta ni las familias: envía los Id. de Ágora y Shiji tiene que tener sus códigos con esos valores.

• Si una forma de pago de Ágora no está asignada a un código de Shiji, o si Shiji no acepta la factura, Connect Manager la rechaza y Ágora no deja cerrarla.

• El Z-cierre y el cierre de albaranes a los N días dependen de tareas nocturnas que en la versión actual del motor están desactivadas.

• No sincroniza reservas ni disponibilidad.

Requisitos#

• Shiji: acceso a sus servicios HTNG de consulta de cuentas y de cargos para el hotel, con usuario y contraseña, y los códigos de cadena y de hotel. En Shiji tienen que existir los centros de ingresos, los códigos de ingreso, los turnos y los códigos de forma de pago que se van a enviar.

• Ágora: licencia del Módulo de Servicios de Integración, una acción personalizada en el TPV y la integración de documentos con sistemas externos enviando albaranes y facturas.

• Conectividad: el albarán se crea siempre desde el propio TPV. Aun así, el local tiene que tener en Connect Manager la URL de API y la API key de Ágora, accesible desde fuera (puerto abierto o Zero Connect), para las listas del panel y las tareas programadas.

• Quién hace qué: FOS da de alta el local y la integración (el botón Añadir solo lo ven los administradores de FOS). El distribuidor completa turnos, formas de pago y opciones, y configura Ágora. Shiji facilita las credenciales y crea los códigos.

Datos que necesitamos#

Configuración paso a paso#

En Shiji#

1. Pide a Shiji la URL de sus servicios, el usuario, la contraseña, el código de cadena y el código de hotel.

2. Pásales el listado de centros de venta, familias (o formatos de venta) y formas de pago de Ágora con sus Id., para que creen en Shiji los centros de ingresos, los códigos de ingreso y las formas de pago con esos valores, y que te den los códigos de los turnos y la cuenta de ingresos.

En Connect Manager: alta de la integración (FOS)#

1. Entra en Administración → Locales, abre el local y revisa URL de API, API key y Zona horaria. Pulsa Guardar.

2. Pulsa Integraciones de hoteles → Añadir y elige el Proveedor Shiji.

3. Rellena URL Api:, Usuario, Password, Id. de la cadena e Id. del hotel, y añade el Email de receptor de notificaciones.

4. Pulsa Guardar.

En Connect Manager: opciones de los cargos#

En el bloque Conf. de cargos:

• Id. del turno: el turno que se envía cuando la hora del albarán no cae en ningún turno de la pestaña Turnos.

• ¿Agrupar productos por familia?: decide qué código de ingreso se envía en cada línea. Con Sí, el Id. de la familia de Ágora; con No, el Id. del formato de venta. En los dos casos va una línea por producto.

• Cuenta de ingresos: la cuenta de Shiji a la que se envían las facturas del TPV.

• Dejar abierto el albarán: márcalo para poder anular los cargos cancelando el albarán en Ágora.

• Nº de días para cerrar albaranes: plazo tras el que la tarea de cierre marcaría como cancelados los albaranes abiertos (7 por defecto).

• Cliente: el cliente genérico de Ágora de los albaranes. El nombre del albarán se sustituye por el del huésped y su habitación.

En Conf. de Z-cierre están la casilla Z-cierre y la Hora de generación fich. contable. Si ya envías las facturas en el momento por la URL de documentos, déjala desmarcada: el Z-cierre vuelve a enviar todas las facturas del día y se duplicarían.

[!WARNING] El Z-cierre y el cierre automático de albaranes dependen de tareas programadas de Connect Manager que, en la versión actual del motor, están desactivadas. Confirma con FOS que están en marcha antes de contar con ellas.

Guarda y completa las pestañas:

1. Turnos: pulsa Añadir por cada turno y rellena Nombre, Id. externo del turno (el código de Shiji), Hora de inicio y Hora de fin. Las franjas no pueden cruzar la medianoche: para un turno de 22:00 a 02:00 crea dos, de 22:00 a 23:59 y de 00:00 a 02:00.

2. Métodos de pago: por cada forma de pago de Ágora, el Método de pago de Agora y su Método de pago Shiji (el código de Shiji, escrito a mano). Asígnalas todas: una forma de pago sin asignar bloquea las facturas que la usen.

Por último, copia del bloque Enlaces la URL botón acción personalizada y la URL para enviar facturas desde Ágora.

En Ágora#

1. En Herramientas → Acciones personalizadas, crea una acción con la URL botón acción personalizada tal cual, con los marcadores entre llaves: Ágora los rellena solo. Marca que la URL se muestre en un diálogo y añade el permiso que crea a los perfiles de usuario.

2. En la integración de documentos con sistemas externos (Activar módulos adicionales → Servicios de integración), pega la URL para enviar facturas desde Ágora, habilita la integración de documentos y marca el envío de albaranes (para las anulaciones) y de facturas (para que lleguen a Shiji).

Cómo funciona#

Al abrir la acción personalizada, la pantalla lee el ticket desde el TPV. El camarero teclea la habitación y Connect Manager pide a Shiji la cuenta de la reserva alojada. Si la reserva admite cargos, se muestran sus datos. Al pulsar Cargar, el TPV crea el albarán y Connect Manager envía el cargo a Shiji. Si Shiji lo acepta, la pantalla muestra «Se generó el siguiente cargo:» con el identificador del cargo y se cierra.

sequenceDiagram
    participant C as Camarero
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant S as Shiji
    C->>TPV: Pulsa la acción personalizada
    TPV->>CM: Abre la pantalla y le pasa el ticket
    C->>CM: Teclea el número de habitación
    CM->>S: AccountLookup de la reserva alojada
    S-->>CM: Huésped, crédito y si admite cargos
    C->>CM: Pulsa Cargar
    CM->>TPV: Pide crear el albarán desde el TPV
    TPV-->>CM: Albarán creado
    CM->>S: ChargePosting con las líneas del albarán
    S-->>CM: Identificador del cargo
    CM-->>C: Se generó el siguiente cargo

El cargo lleva el código del hotel, la cuenta de la reserva, el día de negocio del albarán, el centro de ingresos (Id. del centro de venta del ticket), el camarero (Id. del usuario de Ágora), la mesa, los comensales, el turno y una línea por producto con su código de ingreso, importe, unidades y precio. Si el ticket tiene descuento, se añade una línea de descuento por la diferencia; si tiene cargo por servicio, otra línea «Cargo por servicio». Además viaja el albarán en texto, con los productos, el desglose de IVA y el total. Si Shiji rechaza el cargo, la pantalla muestra el motivo que devuelve Shiji; el albarán ya existe en Ágora porque se crea antes.

Facturas en tiempo real#

Cada vez que Ágora emite una factura y la envía a la URL de documentos, Connect Manager comprueba que todas sus formas de pago están asignadas y la envía a Shiji contra la Cuenta de ingresos, con sus líneas, el descuento, el cargo por servicio y un cobro por cada forma de pago con su código de Shiji. Si Shiji contesta con éxito, la factura queda aceptada; si no, Connect Manager rechaza la factura y Ágora no deja cerrarla.

sequenceDiagram
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant S as Shiji
    TPV->>CM: Factura emitida
    CM->>CM: Comprueba que las formas de pago están asignadas
    CM->>S: ChargePosting contra la cuenta de ingresos
    S-->>CM: Success o error
    CM-->>TPV: Factura aceptada o rechazada

Anulaciones#

Al cancelar el albarán en Ágora, Connect Manager recibe el documento de cancelación y envía a Shiji un nuevo cargo a la misma cuenta con las líneas en negativo. Si Shiji lo rechaza, la cancelación se rechaza en Ágora. Connect Manager no comprueba si el cargo original llegó: si había fallado, la anulación se envía igualmente.

Comprobar que funciona#

1. En Ágora, abre un ticket de prueba en un centro de venta ya codificado en Shiji y pulsa la acción personalizada.

2. Busca una habitación ocupada: deben salir el huésped, el estado y sus fechas.

3. Pulsa Cargar: debe salir «Se generó el siguiente cargo:» con un identificador y cerrarse la ventana.

4. En Ágora, comprueba el albarán a nombre del huésped; en Shiji, el cargo en la cuenta con el turno, la mesa y el texto del albarán.

5. En Connect Manager, en Operaciones hoteleras → Cargos, el Id. de pedido externo debe estar relleno.

6. Cobra otro ticket con tarjeta y emite la factura: debe cerrarse sin error en Ágora y aparecer en Shiji contra la cuenta de ingresos.

7. Cancela el albarán de prueba y comprueba el cargo en negativo en Shiji.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Shiji con Ágora?#

FOS da de alta la integración con la URL, el usuario, la contraseña y los códigos de cadena y hotel que facilita Shiji. Después se configuran turnos y formas de pago y se crean en Ágora la acción personalizada y la integración de documentos.

¿Shiji recibe las ventas de clientes no alojados?#

Sí. Cada factura que Ágora envía a la URL de documentos llega a Shiji contra la cuenta de ingresos, con sus formas de pago.

¿Qué pasa si Shiji está caído cuando se emite una factura?#

Connect Manager no recibe el éxito de Shiji y rechaza la factura, así que Ágora no deja cerrarla hasta que Shiji vuelva a responder.

¿Qué significa Agrupar productos por familia en Shiji?#

Decide el código de ingreso de cada línea: el Id. de la familia de Ágora (Sí) o el del formato de venta (No). Las líneas van siempre una por producto.

¿Se pueden enviar propinas a Shiji?#

No. El campo de propina de la pantalla de cargo está desactivado y las facturas tampoco la envían como línea aparte.

Referencias#

• Ficha de Shiji en el catálogo de integraciones

• Hotel Hub: cómo funcionan los cargos a habitación desde Ágora

• Web oficial de Shiji