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

La integración de Redforts con Ágora permite cargar en la reserva del huésped lo que consume en el restaurante o el bar del hotel. El camarero busca la reserva desde el TPV por habitación o por nombre, pulsa Cargar y el ticket pasa a un albarán en Ágora y a un cargo en Redforts, línea a línea, con familia, producto, impuesto, cantidad y precio. Todo pasa por Connect Manager, que guarda el registro de cada cargo.

Este manual es para el técnico de FOS o del distribuidor que la configura: qué datos pedir, dónde meterlos, cómo funciona por dentro, 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 en Redforts las reservas por número de habitación o por nombre del huésped (buscadores Nº de habitación y Cliente) y solo muestra las que tienen el check-in hecho.
• Enseña una tarjeta por reserva con la habitación, el cliente (nombre y apellidos y, si la hay, la empresa entre paréntesis), la tarifa del día y las fechas de llegada y salida.
• Crea el albarán en Ágora desde el propio TPV, a nombre del cliente configurado con el número de habitación (HUÉSPEDES HOTEL (Nº hab.: 101)), y lo imprime.
• Envía el cargo a la reserva línea a línea: familia (identificador y nombre), formato de venta (identificador y nombre), impuesto (identificador, nombre y porcentaje), cantidad y precio unitario sin IVA, con los descuentos del ticket repartidos entre las líneas.
• Guarda en Connect Manager cada operación: el ticket, el albarán y lo enviado a Redforts.

Qué no hace#

• No comprueba el crédito ni los bloqueos de la reserva.
• No anula en Redforts el cargo de un albarán anulado. Si devuelves el albarán en Ágora, el cargo hay que quitarlo en Redforts.
• No pide firma, no envía facturas ni el cierre del día, y no hay familias ni formas de pago que asociar en Connect Manager: viajan los identificadores de Ágora tal cual.
• Propina: la tarjeta tiene un campo Propina y se envía como línea aparte, pero con la cantidad de la última línea del ticket. Si esa línea lleva más de una unidad, el importe que calcula Redforts no cuadra. Hasta que FOS lo confirme, no uses el campo Propina con Redforts.
• El número que muestra la pantalla al terminar («Se generó el siguiente cargo: 10000») es fijo: no es un identificador de Redforts.
• No sincroniza reservas, disponibilidad ni tarifas.

Requisitos#

• Connect Manager: el local dado de alta en app.connectmanager.es con la URL de la API y la API key de Ágora. 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, y un cliente genérico para los albaranes de cargos a habitación.
• Conectividad: el cargo lo hace el propio TPV a través del diálogo, con su API local; la API de Ágora no tiene que estar abierta a Internet para cargar. Sí la necesita el panel para buscar el Cliente al configurar: Connect Manager debe llegar al puerto 8984 de Ágora, publicado o con Zero Connect.
• Redforts: la URL de su API y el código de conexión de la API de TPV del hotel. Conviene acordar con Redforts cómo asociará en su lado las familias, productos e impuestos de Ágora que recibe.

Reparto de tareas: FOS da de alta el local y la integración; el distribuidor rellena los campos y configura Ágora; el hotel o Redforts facilita la URL y el código de conexión.

Datos que necesitamos#

Configuración paso a paso#

En Redforts#

1. Pide a Redforts (o al hotel) la URL de la API y el código de conexión para el TPV.
2. Explícales qué recibirán en cada línea (identificador y nombre de familia, de formato de venta y de impuesto) para que lo asocien a sus conceptos.
3. Comprueba que el hotel hace el check-in de las reservas en Redforts: las reservas sin check-in no aparecen en la pantalla de cargo.

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 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 Redforts o, si eres administrador, pulsa Añadir y elige el Proveedor Redforts.
2. En Conf. general rellena URL Api: y Código de conexión:. Redforts no usa Id. del hotel: el código de conexión ya identifica al hotel. El Email de receptor de notificaciones se puede dejar vacío.
3. En Conf. de cargos, elige el Cliente de Ágora para los albaranes. Es la única opción de cargo de Redforts.
4. Pulsa Guardar: sale Se ha guardado la integración de hoteles. Redforts no tiene pestañas de familias ni de formas de pago.
5. En Enlaces, copia la URL botón acción personalizada.

Los campos 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 copiada tal cual, con sus marcadores {user_id}, {pos_id}, {ticket_global_id}…
3. Marca Mostrar Urls en un diálogo de Ágora. Es imprescindible: 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 (o en el menú Otros) y da su permiso a los perfiles de los usuarios que vayan a cargar.

La URL tiene esta forma, precedida del dominio que muestre el panel: /venues/123/hotels/redforts/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}. Redforts no necesita la integración de documentos de Ágora.

Cómo funciona#

Al pulsar la acción, el diálogo carga la pantalla de Connect Manager y esta pide al TPV el ticket abierto con su API local. El camarero busca por habitación o por nombre; Connect Manager consulta a Redforts y enseña las reservas con check-in hecho. En la tarjeta elegida pulsa Cargar: el TPV crea el albarán, Connect Manager lo guarda y envía el cargo a esa reserva. Si Redforts lo acepta, sale «Se generó el siguiente cargo: 10000» 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 RF as Redforts
    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 abierto por la API local
    C->>CM: Busca por habitación o por nombre
    CM->>RF: Consulta de reservas
    RF-->>CM: Reservas encontradas
    CM-->>C: Tarjetas de las reservas con check-in
    C->>CM: Pulsa Cargar
    CM->>AG: Crea el albarán por la API local
    AG-->>CM: Albarán con serie y número
    CM->>RF: Cargo a la reserva línea a línea
    RF-->>CM: success
    CM-->>C: Se generó el siguiente cargo

Connect Manager llama a …/posapi/{código de conexión}/reservations para buscar (con el número de habitación o el nombre del huésped) y a …/posapi/{código de conexión}/charge para cargar, con la reserva y la habitación elegidas y una línea por cada línea del albarán. El precio se envía sin IVA y por unidad, después de repartir el descuento del ticket: si es un porcentaje, se aplica a cada línea; si es un importe, se reparte en proporción al peso de cada línea.

El albarán se crea antes del cargo. Si Redforts no responde o lo rechaza, el albarán ya existe en Ágora y la pantalla dice «No se ha podido generar el albarán…»; el motivo que devuelve Redforts al cargar no se ve en el TPV ni queda guardado en el detalle del cargo. Comprueba en Ágora si el albarán está creado y, si lo está, devuélvelo o carga el importe a mano en Redforts. No hay reintentos ni anulación automática. Si el TPV no contesta a la pantalla en 60 segundos, la petición se corta con «Request timed out».

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.
2. Abre en Ágora un ticket de prueba con dos productos de familias distintas y pulsa la acción.
3. Busca una habitación con check-in hecho: aparece su tarjeta con cliente, tarifa y fechas. Prueba también a buscar por apellido.
4. Pulsa Cargar sin propina: debe salir «Se generó el siguiente cargo: 10000» y cerrarse el diálogo.
5. En Ágora queda el albarán impreso a nombre del cliente genérico con «(Nº hab.: …)».
6. En Redforts, la reserva tiene dos líneas con sus familias, productos, impuestos y precios.
7. En Connect Manager, Operaciones hoteleras → Cargos muestra la operación con Pedido externo (request) y Pedido externo (response).
8. Anula el albarán de prueba en Ágora y quita el cargo en Redforts.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Redforts con Ágora?#

FOS da de alta la integración de hoteles con el proveedor Redforts; tú pones la URL Api y el código de conexión, eliges el cliente y creas en Ágora una acción personalizada con la URL del panel, mostrada en un diálogo.

¿Por qué no aparece una reserva al buscar?#

La pantalla solo enseña reservas con el check-in hecho en Redforts. Si la reserva existe pero el huésped no ha hecho el check-in, no sale.

¿Se puede buscar por el nombre del huésped?#

Sí: la pantalla tiene un buscador Cliente además del de Nº de habitación.

¿Se anula el cargo en Redforts si anulo el albarán?#

No. La integración no envía anulaciones: el cargo hay que quitarlo a mano en Redforts.

¿Por qué el cargo siempre dice 10000?#

Connect Manager solo comprueba que Redforts ha aceptado el cargo y no guarda ningún número suyo: la pantalla enseña un valor fijo. Para localizar un cargo, usa el número de albarán de Ágora.

Referencias#

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