Integración de Protel con Ágora: cargos a habitación y facturas

La integración de Protel con Ágora lleva al PMS Protel los consumos de los huéspedes y las ventas del TPV: permite cargar un ticket a la reserva de un huésped desde una acción personalizada de Ágora y enviar a Protel cada factura del TPV con sus cobros y propinas. Tiene dos formas de trabajar, con albaranes o con una forma de pago de cargo a habitación, y este manual explica las dos para que el técnico elija la adecuada, la configure y sepa resolver los fallos.

Qué hace la integración#

• Busca la reserva en Protel por número de habitación y, además, por número de tarjeta o, en el modo con albaranes, por apellidos (según la opción Buscar por...).

• Muestra el huésped, las fechas de llegada y salida, las notas de restaurante y el límite de crédito; en el modo con albaranes, también el package, la tarifa y el saldo.

• Impide el cargo si la reserva está bloqueada en Protel, salvo que se active Permitir cargos bloqueados.

• Modo con albaranes: crea el albarán en Ágora a nombre del huésped y envía a Protel el cargo a la reserva con el detalle de artículos: importe, nombre, familia, tipo de IVA, producto y cantidad.

• Modo con albaranes: anula el cargo en Protel cuando se cancela el albarán en Ágora.

• Modo con forma de pago: deja la reserva elegida asociada al ticket. Cuando el ticket se cobra con la forma de pago de cargo a habitación, la factura llega a Protel con ese cobro cargado a la reserva, después de validarla en Protel.

• Envía a Protel cada factura del TPV en el momento en que se emite, con sus líneas, sus cobros por forma de pago y la propina como concepto aparte. Así Protel recibe también las ventas de clientes no alojados.

• En las devoluciones de facturas cobradas con cargo a habitación, comprueba antes en Protel la reserva de la venta original.

Qué no hace#

• No recoge la firma del huésped.

• No envía la propina con el cargo a habitación del modo con albaranes: solo con las facturas.

• No traduce identificadores: envía los Id. de Ágora del TPV, el usuario, la familia, el IVA, el producto y la forma de pago tal cual. La correspondencia la tiene que hacer el interfaz de Protel. No hay pestañas de mapeo en Connect Manager.

• No funciona con una URL https para los cargos y las facturas: el envío abre una conexión directa sin cifrar al servidor y puerto de la URL.

• Con Enviar facturas diferidas marcado, las facturas no se envían en el momento: se enviarían de noche con una tarea que en la versión actual del motor está desactivada. Lo mismo pasa con el cierre de albaranes a los N días.

• No sincroniza reservas ni disponibilidad.

Requisitos#

• Protel: el interfaz de Protel que atiende las peticiones de búsqueda de reservas, validación y cierre de factura tiene que estar accesible desde Connect Manager por http, en un servidor y un puerto. Abre ese puerto a las direcciones IP salientes de Connect Manager.

• Á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 las facturas (y los albaranes en el modo con albaranes). En el modo con forma de pago, una forma de pago «Cargo habitación».

• Conectividad con Ágora: el local tiene que tener en Connect Manager la URL de API y la API key de Ágora. En el modo con albaranes, si se deja activada Usar el API externa de Ágora, la API tiene que ser accesible desde fuera (puerto abierto o Zero Connect).

• 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 elige el modo, completa las opciones y configura Ágora. El hotel y Protel ponen en marcha el interfaz y las correspondencias.

Datos que necesitamos#

Configuración paso a paso#

Elegir el modo#

• Con albaranes (casilla Utilizar albaranes marcada, la opción por defecto): el cargo a habitación se hace al pulsar Cargar, queda un albarán en Ágora y se puede anular cancelando el albarán. Es el modo que se parece al resto de PMS.

• Con forma de pago (casilla desmarcada): el botón solo elige la reserva; el cargo se hace al cobrar el ticket con la forma de pago «Cargo habitación», y llega a Protel dentro de la factura.

En Protel#

1. Que Protel o la informática del hotel pongan en marcha el interfaz, abran el puerto a las IP de Connect Manager y te den la URL y el Id. del hotel.

2. Pásales el listado de TPV, usuarios, familias, tipos de IVA, productos y formas de pago de Ágora con sus Id. para que hagan las correspondencias.

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 Protel.

3. En URL Api: escribe la URL del interfaz con http://, el puerto y la barra final. En Id. del hotel, el de Protel. Protel no pide usuario ni contraseña en Connect Manager.

4. Añade el Email de receptor de notificaciones y pulsa Guardar.

En Connect Manager: opciones de los cargos#

En el bloque Conf. de cargos:

• Buscar por...: segunda búsqueda de la pantalla del modo con albaranes, Número de tarjeta o Nombre del cliente (busca por apellidos). En el modo con forma de pago la pantalla busca siempre por habitación y por tarjeta.

• Permitir cargos bloqueados: si está desmarcada, la pantalla no deja cargar a reservas que Protel marca como bloqueadas.

• Utilizar albaranes: elige el modo, como se explica arriba.

• Solo en el modo con albaranes: Usar el API externa de Ágora (activada, el albarán lo crea Connect Manager por la API de Ágora; desactivada, lo crea el TPV), Cliente (el genérico de los albaranes), Dejar abierto el albarán (márcalo para poder anular cargos desde Ágora) y Nº de días para cerrar albaranes.

• Método de pago de Agora: en el modo con forma de pago, la forma de pago «Cargo habitación». Con albaranes, el panel avisa «Por favor, deshabilite el método de pago en Ágora.»: desactívala en Ágora para que nadie cargue a habitación cobrando el ticket.

En Conf. de Z-cierre está la casilla Enviar facturas diferidas con su Hora de generación fich. contable. Déjala desmarcada para que las facturas se envíen en el momento.

[!WARNING] El envío diferido de facturas y el cierre automático de albaranes dependen de tareas programadas que, en la versión actual del motor, están desactivadas. Con Enviar facturas diferidas marcado, hoy las facturas no llegarían a Protel.

Pulsa Guardar y 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 facturas y, en el modo con albaranes, también el de albaranes.

3. Modo con forma de pago: crea la forma de pago «Cargo habitación» y elígela en Método de pago de Agora. Modo con albaranes: desactívala.

Cómo funciona#

La búsqueda#

Connect Manager abre una transacción para el ticket, consulta a Protel la reserva por habitación, tarjeta o apellidos, guarda su número y muestra los datos; si Protel contesta con un error, la pantalla muestra su texto tal cual. Todas las peticiones llevan las cabeceras Transaction (el número de la transacción) y Outlet (el TPV de Ágora).

Modo con albaranes#

Al pulsar Cargar, se crea el albarán en Ágora y Connect Manager envía a Protel la petición de cierre de factura con una línea de ingreso por artículo y un cobro por el total del albarán cargado al número de reserva. Si Protel lo acepta, el cargo queda como aceptado; si no, se muestra el texto de error de Protel.

sequenceDiagram
    participant C as Camarero
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant P as Protel
    C->>CM: Busca por habitación, tarjeta o apellidos
    CM->>P: FindReservationByRoom, ByKey o ByName
    P-->>CM: Reserva, huésped y bloqueo
    C->>CM: Pulsa Cargar
    CM->>TPV: Crea el albarán a nombre del huésped
    CM->>P: CloseInvoice con artículos y cobro a la reserva
    P-->>CM: Aceptado o texto de error
    CM-->>C: Mensaje del resultado

Al cancelar el albarán en Ágora, Connect Manager envía a Protel otra petición de cierre con las líneas del albarán de cancelación y el cobro a la misma reserva. Si Protel la rechaza, la cancelación se rechaza en Ágora.

Modo con forma de pago#

Al pulsar Cargar, Connect Manager solo confirma la reserva elegida para ese ticket («Se han guardado los datos.») y la ventana se cierra. El camarero cobra entonces el ticket con «Cargo habitación». Cuando Ágora emite la factura y la envía a la URL de documentos, Connect Manager valida la reserva en Protel y envía la factura con el cobro de cargo a habitación ligado al número de reserva.

sequenceDiagram
    participant C as Camarero
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant P as Protel
    C->>CM: Busca la reserva y pulsa Cargar
    CM->>CM: Asocia la reserva al ticket
    C->>TPV: Cobra el ticket con Cargo habitación
    TPV->>CM: Envía la factura a la URL de documentos
    CM->>P: ValidateReservation
    P-->>CM: Reserva válida
    CM->>P: CloseInvoice con líneas, cobros y propina
    P-->>CM: Aceptado
    CM-->>TPV: Factura aceptada

Si se cobra con «Cargo habitación» sin haber elegido reserva, Connect Manager rechaza la factura. Si se buscó la reserva pero no se pulsó Cargar, la factura sale con esa forma de pago como un cobro normal, sin número de reserva.

Las facturas#

En los dos modos, cada factura que Ágora envía a la URL de documentos se manda a Protel con una línea de ingreso por artículo (importe, nombre, familia, tipo de IVA, producto y cantidad), un cobro por cada forma de pago (importe más propina) y, si hay propina, una línea de propina aparte. Si Protel contesta con error, Connect Manager rechaza la factura en Ágora con el texto de Protel. Las facturas enviadas se ven en Operaciones hoteleras → Facturas.

Comprobar que funciona#

1. En Ágora, abre un ticket de prueba y pulsa la acción personalizada. Busca una habitación ocupada: deben salir el huésped y sus fechas.

2. Con albaranes: pulsa Cargar, comprueba el albarán en Ágora y el cargo en la cuenta de la reserva en Protel. En Operaciones hoteleras → Cargos, el Id. de pedido externo debe ser «ACCEPTED». Cancela el albarán y comprueba la anulación en Protel.

3. Con forma de pago: pulsa Cargar, cobra el ticket con «Cargo habitación» y comprueba que la factura aparece en Protel cargada a la reserva.

4. Cobra otro ticket con tarjeta o efectivo y comprueba que también llega a Protel y que en Operaciones hoteleras → Facturas sale como «Aceptado».

5. Prueba una reserva bloqueada para confirmar que la pantalla no deja cargar (o que sí, si activaste Permitir cargos bloqueados).

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Protel con Ágora?#

FOS da de alta la integración con la URL del interfaz de Protel y el Id. del hotel. Después se elige el modo, se crean en Ágora la acción personalizada y la integración de documentos, y Protel hace las correspondencias con los Id. de Ágora.

¿Qué modo elijo, con albaranes o con forma de pago?#

Con albaranes el cargo es inmediato y se puede anular cancelando el albarán. Con forma de pago el cargo viaja dentro de la factura al cobrar con «Cargo habitación».

¿Se pueden enviar a Protel las ventas de clientes no alojados?#

Sí. Cada factura que Ágora envía a la URL de documentos llega a Protel con sus cobros, se haya cobrado como se haya cobrado.

¿Se puede buscar en Protel por apellido?#

Sí, en el modo con albaranes, eligiendo Nombre del cliente en Buscar por... La búsqueda por habitación está siempre.

Referencias#

• Ficha de Protel en el catálogo de integraciones

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

• Direcciones IP salientes de Connect Manager