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

La integración de Cloudbeds con Ágora permite cargar un ticket del TPV a la reserva de un huésped con el check-in hecho en Cloudbeds: el camarero pulsa una acción personalizada de Ágora, busca la reserva por habitación o por nombre y Connect Manager crea el albarán en Ágora y el cargo en Cloudbeds, producto a producto. Este manual es para el técnico que la configura: qué datos pedir, dónde meterlos, cómo funciona por dentro y qué hacer cuando falla.

Qué hace la integración#

• Busca las reservas con check-in hecho por número de habitación, nombre o apellido del huésped y muestra, por cada habitación, el huésped, el estado y las fechas, con un botón Cargar.

• Carga el ticket a la reserva producto a producto: nombre, cantidad, identificador del producto de Ágora, familia y precio unitario con el descuento del ticket repartido. Cada línea lleva la nota «Albarán SERIE/000123 del cliente Nombre».

• Con Desglose de impuestos activado, envía cada precio sin IVA y el IVA aparte como impuesto «IVA».

• Si el ticket de Ágora lleva propina en sus cobros, la añade como una línea «Propina».

• Deja en Ágora un albarán a nombre del huésped con su número de habitación.

• Anula el cargo en Cloudbeds cuando se cancela el albarán en Ágora.

• Al dar de alta la integración se suscribe a los cambios de estado de la aplicación en Cloudbeds y avisa por correo si el hotel la desconecta.

Qué no hace#

• No admite tickets con descuentos en efectivo, ni con descuentos por línea y a pie de ticket a la vez: la pantalla lo impide y pide cambiarlos.

• No comprueba el crédito ni el régimen de la reserva, ni recoge la firma del huésped.

• No envía las facturas del TPV en tiempo real. La URL de facturas existe, pero si Ágora le manda una factura Connect Manager responde con un error, así que en Ágora solo hay que enviar albaranes a esa URL.

• El Z-cierre (enviar cada factura del día a una cuenta interna de Cloudbeds) 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.

• La pestaña Centros de venta se puede rellenar, pero el cargo no la usa.

• Si una búsqueda encuentra varias reservas, solo se listan las habitaciones de la última que devuelve Cloudbeds. Afina la búsqueda (habitación o apellido) si no ves la que buscas.

• El aviso de desconexión solo se registra al crear la integración: si después se cambia la Api Key, no se vuelve a registrar.

• No sincroniza reservas ni disponibilidad.

Requisitos#

• Cloudbeds: una Api Key de la cuenta del hotel con acceso a sus reservas y a los cargos. Los huéspedes tienen que tener el check-in hecho para aparecer en la búsqueda.

• Á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 para las anulaciones.

• Conectividad: el albarán se crea desde el propio TPV, pero el local tiene que tener en Connect Manager la URL de API y la API key de Ágora, y esa API debe ser accesible desde fuera (puerto abierto o Zero Connect): Connect Manager la usa para las listas del panel, para las tareas programadas y, en algunos casos, para leer el ticket al cargar.

• 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 la propiedad, el cliente y las opciones y configura Ágora. El hotel facilita la Api Key.

Datos que necesitamos#

Configuración paso a paso#

En Cloudbeds#

1. El hotel obtiene la Api Key de su cuenta de Cloudbeds y se la pasa a FOS.

2. Si se va a usar el Z-cierre, que el hotel cree la cuenta interna donde irán las ventas del TPV.

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 CloudBeds. La URL Api: (https://api.cloudbeds.com/api/v1.3/) se rellena sola y no se puede cambiar.

3. Pega la Api Key: y añade el Email de receptor de notificaciones (escribe la dirección y pulsa Intro).

4. Pulsa Guardar. En ese momento Connect Manager registra en Cloudbeds el aviso de cambio de estado de la aplicación.

En Connect Manager: configuración de los cargos#

1. Vuelve a abrir la integración. Ahora aparece el campo Hotel: elige la propiedad en la lista, que se carga desde Cloudbeds con la Api Key.

2. En Conf. de cargos, elige el Cliente genérico de Ágora. El nombre del albarán se sustituye por el del huésped y su habitación.

3. Marca Dejar abierto el albarán si el hotel quiere poder anular los cargos desde Ágora.

4. Nº de días para cerrar albaranes: plazo tras el que la tarea de cierre marcaría como cancelados los albaranes abiertos (ver el aviso).

5. Desglose de impuestos: márcalo si el hotel quiere el precio sin IVA y el impuesto aparte en cada línea.

6. En Conf. de Z-cierre, la casilla Z-cierre, la Cuenta interna y la Hora de generación fich. contable sirven para enviar cada factura del día a esa cuenta, con sus cobros. En la pestaña Métodos de pago se asigna a cada Método de pago de Agora su Método de pago Cloudbeds; solo lo usa el Z-cierre.

7. Pulsa Guardar y copia del bloque Enlaces la URL botón acción personalizada y la URL para enviar facturas desde Ágora.

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

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 ({ticket_global_id}, {pos_id}…): Á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 el envío de albaranes. No envíes las facturas a esta URL.

[!WARNING] Si Ágora envía facturas a la URL de Cloudbeds, Connect Manager contesta con un error de servidor. Deja marcado solo el envío de albaranes.

Cómo funciona#

Al abrir la acción personalizada, la pantalla lee el ticket desde el propio TPV y comprueba los descuentos. El camarero busca por habitación, nombre o apellido y Connect Manager pide a Cloudbeds las reservas con check-in de esa propiedad. Al pulsar Cargar en una habitación, el TPV crea el albarán, la pantalla se lo pasa a Connect Manager y Connect Manager envía el cargo a Cloudbeds. Si Cloudbeds lo acepta, la pantalla muestra «OK» y se cierra.

sequenceDiagram
    participant C as Camarero
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant CB as Cloudbeds
    C->>TPV: Pulsa la acción personalizada
    TPV->>CM: Abre la pantalla y le pasa el ticket
    C->>CM: Busca por habitación, nombre o apellido
    CM->>CB: getReservations con check-in hecho
    CB-->>CM: Reservas y habitaciones
    C->>CM: Pulsa Cargar en una habitación
    CM->>TPV: Pide crear el albarán desde el TPV
    TPV-->>CM: Albarán creado
    CM->>CB: postCustomItem con las líneas del ticket
    CB-->>CM: Identificador del cargo
    CM-->>C: OK y cierre de la ventana

El cargo lleva el identificador de la reserva y, por cada línea del ticket, el nombre, la cantidad, el identificador del producto de Ágora, el nombre de la familia y el precio unitario. Con descuento a pie de ticket, el descuento se reparte proporcionalmente entre las líneas. Como el albarán se crea antes que el cargo, si Cloudbeds falla el albarán ya existe en Ágora y la pantalla muestra el aviso genérico «No se ha podido generar el albarán».

Anulaciones#

Al cancelar el albarán en Ágora, Ágora envía el documento de cancelación a la URL de documentos. Connect Manager localiza el cargo original y pide a Cloudbeds que anule el producto vendido en esa reserva. Si Cloudbeds no lo acepta, la cancelación se rechaza en Ágora.

sequenceDiagram
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant CB as Cloudbeds
    TPV->>CM: Albarán de cancelación
    CM->>CM: Busca el cargo por serie y número
    CM->>CB: postVoidItem de la reserva y el producto vendido
    CB-->>CM: Respuesta
    CM-->>TPV: Acepta o rechaza la cancelación

Aviso de desconexión#

Al guardar por primera vez la integración, Connect Manager pide a Cloudbeds que le avise de los cambios de estado de la aplicación. Si el hotel la desactiva, Cloudbeds llama a Connect Manager y este envía al Email de receptor de notificaciones un correo con el asunto «Aplicación de Cloudbeds desconectada». Revisa con el hotel la conexión de la aplicación y, si Cloudbeds le da una Api Key nueva, pásasela a FOS para actualizarla.

Z-cierre#

Si está activo y la tarea programada funciona, Connect Manager lee de Ágora las facturas del día y envía cada una a la Cuenta interna de Cloudbeds con sus líneas y sus cobros, usando los métodos de pago asignados. Las devoluciones anulan el producto de la factura original. El estado se guarda en los cierres de caja de la integración.

Comprobar que funciona#

1. Al volver a abrir la integración, la lista Hotel muestra la propiedad: eso confirma que la Api Key funciona.

2. En Ágora, abre un ticket de prueba sin descuentos en efectivo y pulsa la acción personalizada.

3. Busca por número de habitación una reserva con el check-in hecho: debe salir una tarjeta con habitación, cliente, estado y fechas.

4. Pulsa Cargar. Debe salir «OK» y cerrarse la ventana.

5. En Ágora, comprueba el albarán a nombre del huésped con su número de habitación.

6. En Cloudbeds, abre la reserva: deben aparecer los productos del ticket con la nota del albarán.

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

8. Cancela el albarán de prueba en Ágora y comprueba que el cargo queda anulado en Cloudbeds.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Cloudbeds con Ágora?#

FOS da de alta la integración en el local de Connect Manager con la Api Key del hotel. Después se elige la propiedad y el cliente genérico y se crean en Ágora la acción personalizada y la integración de documentos con las URL del bloque Enlaces.

¿Por qué no encuentro al huésped en Cloudbeds?#

Porque solo salen las reservas con el check-in hecho en la propiedad elegida. Si el huésped aún no ha hecho el check-in, no aparece.

¿Puedo cargar a habitación un ticket con descuento?#

Sí, si el descuento es en porcentaje y no se combinan descuentos por línea con uno a pie de ticket. Los descuentos en importe no se admiten.

¿Se puede anular un cargo enviado a Cloudbeds?#

Sí: cancelando el albarán en Ágora, con la integración de documentos configurada. Connect Manager anula en Cloudbeds el producto vendido.

¿Qué pasa si el hotel desconecta la aplicación en Cloudbeds?#

Llega un correo de aviso al email de notificaciones. Hay que revisar con el hotel la conexión de la aplicación y, si cambia la Api Key, actualizarla en Connect Manager.

¿Se envían a Cloudbeds las ventas de clientes no alojados?#

No en tiempo real. Existe un Z-cierre que las enviaría a una cuenta interna, pero depende de una tarea programada que hoy está desactivada.

Referencias#

• Ficha de Cloudbeds en el catálogo de integraciones

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

• Documentación para desarrolladores de Cloudbeds