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

La integración de Mews con Ágora permite cargar un ticket del TPV a la cuenta del huésped alojado en Mews sin salir de Ágora: el camarero pulsa una acción personalizada, busca la habitación, recoge la firma si se pide y Connect Manager crea el albarán en Ágora y el pedido en Mews. Este manual es para el técnico que la pone en marcha: qué pedir al hotel, qué rellenar en Connect Manager y en Ágora, cómo comprobar que funciona y qué hacer cuando falla.

Qué hace la integración#

• Busca al huésped por número de habitación (tal como se llama la habitación en Mews) y muestra su nombre y las fechas de check-in y check-out.

• Carga el ticket a la cuenta del huésped como un pedido de Mews ligado a su reserva, línea a línea, con el descuento del ticket repartido, la categoría contable de cada familia de Ágora y el servicio de Mews del centro de venta del ticket.

• Si se activa, muestra un campo de propina y la envía como una línea «Propina» con su propia categoría contable.

• Si se activa, recoge la firma del huésped en la pantalla y la imprime en el albarán de Ágora.

• Deja en Ágora un albarán a nombre del huésped con su número de habitación, por ejemplo «Ana López (Nº hab.: 101)».

• Anula el cargo cuando se cancela el albarán en Ágora: envía a Mews el mismo pedido con los importes en negativo.

• Trae de Mews cada noche, y al guardar la integración, las habitaciones, los servicios, los outlets y las categorías contables.

Qué no hace#

• No busca por nombre del huésped ni por tarjeta: solo por número de habitación.

• Si en la habitación hay varios huéspedes, carga al primero que devuelve Mews.

• No comprueba el crédito, los bloqueos ni el régimen de la reserva.

• No envía el tipo de IVA de cada línea.

• No envía las facturas del TPV en tiempo real: la URL de facturas acepta las facturas sin procesarlas y solo trabaja con los albaranes (anulaciones e impresión de la firma).

• El Z-cierre (enviar a Mews las facturas del día) y el cierre de albaranes a los N días están programados, pero dependen de tareas nocturnas que en la versión actual del motor están desactivadas. El botón Exportar de Cierres de caja tampoco lanza el Z-cierre de Mews.

• No sincroniza reservas ni disponibilidad.

Requisitos#

• Mews: el hotel tiene que conectar la integración en Mews y facilitar el Access Token de su propiedad. Hace falta un servicio de tipo adicional para los consumos (Connect Manager solo importa los servicios adicionales) y las categorías contables con las que se quiera contabilizar.

• Ágora: licencia del Módulo de Servicios de Integración (API del integrador), una acción personalizada en el TPV y la integración de documentos con sistemas externos para las anulaciones y la firma impresa.

• Conectividad: el local tiene que tener en Connect Manager la URL de API y la API key de Ágora. Con Usar el API externa de Ágora activada (por defecto), esa API tiene que ser accesible desde fuera (puerto abierto o Zero Connect); desactivada, el albarán lo crea el propio TPV.

• 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 la configuración, los mapeos y la parte de Ágora. El hotel facilita el token y decide servicios y categorías contables.

Datos que necesitamos#

Configuración paso a paso#

En Mews#

1. El hotel conecta la integración de Connect Manager en su Mews y obtiene el Access Token de la propiedad.

2. Comprueba con el hotel que existe el servicio adicional donde se cargarán los consumos (por ejemplo «Restaurante») y las categorías contables.

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 Mews. La URL Api: (https://api.mews.com/) y el Client Token: se rellenan solos y no se pueden cambiar.

3. Pega el Access Token: del hotel y añade el Email de receptor de notificaciones (escribe la dirección y pulsa Intro; admite varias).

4. Pulsa Guardar. Connect Manager pide a Mews la configuración de la propiedad, rellena el Id. del hotel (solo lectura) y empieza a importar servicios, categorías contables, outlets y habitaciones. Mientras importa, junto a las listas se ve un indicador de carga.

5. Si el Id. del hotel se queda vacío, revisa el token y pulsa el botón de recarga que aparece junto al campo.

En Connect Manager: configuración de los cargos#

Las listas de Mews solo aparecen después de guardar la integración por primera vez. En el bloque Conf. de cargos:

• Usar el API externa de Ágora: activada, Connect Manager lee el ticket y crea el albarán llamando a la API de Ágora; desactivada, lo hace la pantalla a través del TPV. Déjala activada si la API es accesible desde fuera: los mensajes de error son más claros.

• Solicitar firma: muestra un recuadro de firma. La firma no es obligatoria: si el huésped no firma, el cargo se hace igual.

• Mostrar campo para propinas: añade el campo Propina en la pantalla de cargo.

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

• Servicio y Categoría de contabilidad: los valores por defecto del cargo cuando el centro de venta o la familia no están mapeados.

• Categoría contable de propinas: sin ella, la propina no se envía aunque se teclee.

• Outlet y Método de pago: valores por defecto que solo usa el Z-cierre.

• Nº de días para cerrar albaranes: en Mews el albarán se deja siempre abierto para poder anularlo; este plazo es el que usaría la tarea de cierre (ver el aviso de más abajo).

En Conf. de Z-cierre están la casilla Z-cierre y la Hora de generación fich. contable. Si se activan, Connect Manager envía a Mews cada factura del día como una cuenta de outlet con sus líneas y sus cobros.

[!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.

Después, en las pestañas de la integración:

1. Centros de venta: para cada Centro de venta de Ágora, el Servicio de Mews donde se cargan sus tickets y el Outlet para el Z-cierre.

2. Familias: para cada Familia de Ágora, su Categoría de contabilidad en Mews.

3. Métodos de pago: para cada Método de pago de Agora, su Método de pago Mews (una categoría contable). Solo lo usa el Z-cierre.

Por último, en el bloque Enlaces copia 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 {user_id}, {pos_id}, {ticket_id}, {ticket_global_id}, {ticket_line_index} e {introduced_value}: Ágora los rellena solo. Marca que la URL se muestre en un diálogo.

2. La acción crea un permiso: añádelo a los perfiles de los usuarios que vayan a cargar a habitación.

3. 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 que se envíen los albaranes. Sin esto no se anulan los cargos en Mews ni se imprime la firma.

Cómo funciona#

Con el ticket abierto, el camarero pulsa la acción personalizada y se abre la pantalla de Connect Manager. Teclea el número de habitación: Connect Manager la busca entre las habitaciones importadas de Mews y pide a Mews el huésped de esa habitación. Si lo encuentra, muestra nombre y fechas. Al pulsar Cargar, primero se crea el albarán en Ágora y después se envía el pedido a Mews. Si todo va bien, la pantalla muestra «Se generó el siguiente cargo:» con el número de pedido de Mews y se cierra sola a los dos segundos.

sequenceDiagram
    participant C as Camarero
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant M as Mews
    C->>TPV: Pulsa la acción personalizada
    TPV->>CM: Abre la pantalla con el ticket y el TPV
    C->>CM: Teclea el número de habitación
    CM->>M: customers/search con la habitación
    M-->>CM: Huésped y reserva
    C->>CM: Firma si se pide y pulsa Cargar
    CM->>TPV: Crea el albarán a nombre del huésped
    CM->>M: orders/add con las líneas del ticket
    M-->>CM: Número de pedido
    CM-->>C: Se generó el siguiente cargo

El pedido que llega a Mews lleva el identificador de la propiedad, el cliente y la reserva, la fecha de consumo, el servicio (el del centro de venta o el de por defecto) y una línea por cada producto o cabecera de menú con importe distinto de cero. Cada línea lleva nombre, unidades, importe unitario en euros con el descuento repartido y categoría contable. Las cantidades con decimales se envían como una unidad con el importe total. La nota del pedido dice «Albarán SERIE/000123 del cliente Nombre».

Como el albarán se crea antes que el pedido, si Mews no responde o rechaza el cargo el albarán ya existe en Ágora y la pantalla pide devolverlo. La firma, si se recoge, se guarda como imagen y, cuando Ágora envía el albarán a la URL de documentos, Connect Manager le devuelve la firma para imprimirla debajo del texto «FIRMA:».

Anulaciones#

Al cancelar el albarán en Ágora, Ágora envía el documento de cancelación a la URL de documentos. Connect Manager busca el cargo original por serie y número y envía a Mews un pedido igual con los importes en negativo y la nota «Albarán X (Cancelación del Y)». Si Mews lo rechaza, Connect Manager responde a Ágora con el rechazo.

sequenceDiagram
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant M as Mews
    TPV->>CM: Albarán de cancelación
    CM->>CM: Busca el cargo por serie y número
    CM->>M: orders/add con importes en negativo
    M-->>CM: Respuesta
    CM-->>TPV: Acepta o rechaza la cancelación

Tareas programadas#

Cada noche se vuelven a traer de Mews habitaciones, servicios, outlets y categorías contables; si falla, llega un aviso al email de notificaciones. El Z-cierre lee de Ágora las facturas del día y las envía a Mews como cuentas de outlet (una línea por producto y otra por cada cobro), con el resultado en Operaciones hoteleras → Cierres de caja; el cierre de albaranes marca como cancelados en Ágora, sin tocar Mews, los albaranes que siguen abiertos pasado el plazo. Estas dos últimas dependen de las tareas del aviso anterior.

Comprobar que funciona#

1. Tras guardar, el Id. del hotel está relleno y las listas de Servicio, Outlet y Categoría de contabilidad tienen datos.

2. En Ágora, abre un ticket de prueba con un par de productos y pulsa la acción personalizada.

3. Busca una habitación ocupada: deben salir el nombre del huésped y sus fechas.

4. Pulsa Cargar (firma antes si está activado). Debe salir «Se generó el siguiente cargo:» con un número y cerrarse la ventana.

5. En Ágora, comprueba que hay un albarán a nombre del huésped con su número de habitación y, si pediste firma, que sale impresa.

6. En Mews, abre la cuenta del huésped: debe estar el pedido con sus líneas y la nota del albarán.

7. En Connect Manager, en Operaciones hoteleras → Cargos, abre el registro: el Id. de pedido externo debe estar relleno.

8. Cancela el albarán de prueba en Ágora y comprueba en Mews que aparece el pedido en negativo.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Mews con Ágora?#

FOS da de alta la integración de Mews en el local de Connect Manager con el Access Token del hotel. Después se eligen servicio y categorías contables y se crean en Ágora la acción personalizada y la integración de documentos con las URL del bloque Enlaces.

¿Qué tengo que pedirle al hotel para integrar Mews?#

El Access Token de su propiedad en Mews, el servicio donde se cargarán los consumos, la categoría contable por defecto y, si quiere detalle, la categoría de cada familia y la de las propinas.

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

No. La integración solo busca por número de habitación, que tiene que coincidir con el nombre de la habitación en Mews.

¿Cómo se anula un cargo a habitación hecho por error?#

Cancelando el albarán en Ágora. Si la integración de documentos está configurada, Connect Manager envía a Mews el mismo pedido en negativo.

¿Las propinas llegan a Mews?#

Sí, si se activa Mostrar campo para propinas y se elige una Categoría contable de propinas. La propina va como una línea «Propina» del mismo pedido.

Referencias#

• Ficha de Mews en el catálogo de integraciones

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

• Direcciones IP salientes de Connect Manager

• Web oficial de Mews