# Documentación de Connect Manager (texto completo) Índice: https://connectmanager.es/docs/llms.txt --- # Qué es Connect Manager Portal: General · Primeros pasos URL: https://connectmanager.es/docs/qu-es-connect-manager Actualizado: 2026-10-03 Connect Manager es la plataforma de FOS que conecta el TPV Ágora con lo que un restaurante o un hotel usa además del TPV: las plataformas de delivery, el PMS del hotel, el ERP y la contabilidad, los sistemas fiscales, las reservas, el club de socios o las flotas de reparto. Esta documentación está pensada para los técnicos que ponen en marcha esas integraciones: qué datos hacen falta, dónde se configura cada una, cómo funciona por dentro y qué hacer cuando algo falla. ## Las piezas de Connect Manager Toda integración tiene tres extremos: Ágora, Connect Manager y el sistema del tercero (Uber Eats, Mews, SAP…). Connect Manager habla con Ágora a través de la API del integrador de Ágora y con cada tercero a través de la suya, de modo que ninguno de los dos tiene que conocer al otro. - **Ágora**: el TPV del local, o el ACMS central si es un grupo. Connect Manager le habla por su API del integrador (el servicio que escucha en el puerto 8984 del equipo de Ágora, con su `Api-Token`). Desde Ágora salen también los avisos y botones que usan algunas integraciones: las **acciones personalizadas** que abren una pantalla de Connect Manager dentro del TPV, la integración de validación de documentos y la URL de aviso de los usuarios repartidor. - **Connect Manager App** (`app.connectmanager.es`): el motor de las integraciones de pedidos de Uber Eats, Glovo y Just Eat, de los PMS de hotel, de los sistemas fiscales, de los ERP, de las reservas y del ticketing. Se configura en **Administración → Locales**, local a local. - **El hub** (`hub.connectmanager.es`): los paneles. El del cliente (`/app`: Delivery Hub e informes), Fidelización (`/fidelizacion`), Delivery propio (`/delivery-propio`), el portal del distribuidor (`/distributor-portal`, con las integraciones y las conexiones de sus clientes) y el de administración (`/admin`), donde FOS configura las integraciones propias del hub, como las de las flotas de reparto. - **Zero Connect**: el programa que se instala en el equipo de Ágora para que Connect Manager llegue a su API sin abrir puertos en el router, sin IP fija y sin DNS dinámica. Ver [Zero Connect](https://connectmanager.es/docs/zero-connect-instalacion). El dibujo de abajo resume el camino de los datos: Ágora queda conectado a Connect Manager (directamente o a través de Zero Connect) y Connect Manager se encarga de hablar con cada tercero. ```mermaid flowchart LR TPV[TPV Ágora o ACMS] --- ZC[Zero Connect] ZC --- CM[Connect Manager] CM --- DEL[Uber Eats, Glovo y Just Eat] CM --- PMS[PMS del hotel] CM --- ERP[ERP y contabilidad] CM --- FIS[Sistemas fiscales] CM --- OTR[Reservas, ticketing, flotas y más] ``` ## Cómo está organizada la documentación Los manuales están repartidos en portales, uno por producto, que se eligen en la barra de arriba. Todos se buscan a la vez con **Ctrl + K** (o **⌘ + K** en Mac), y en la [portada de la documentación](https://connectmanager.es/docs) están las integraciones documentadas de la A a la Z. | Portal | Qué encontrarás | | General | Esta introducción, la guía rápida, seguridad y glosario, Zero Connect, Connect Manager IA y las integraciones de ERP, fiscales, reservas, comunicación y pagos. | | Delivery Hub | Pedidos de Uber Eats, Glovo y Just Eat en Ágora: el alta de cada plataforma, las cartas digitales, el panel y los informes. | | Hotel Hub | Cargos a habitación desde Ágora en el PMS del hotel: cómo funciona y la configuración de cada PMS. | | Fidelización | El club de socios conectado a Ágora, la tarjeta en Apple Wallet y Google Wallet, WhatsApp y las reseñas. | | Plataformas de reparto | Riders de las flotas de reparto pedidos desde Ágora: la configuración de cada flota y su seguimiento. | | Delivery propio | La tienda online propia conectada a Ágora: la carta, el ciclo del pedido, los mapas, la medición y la IA. | ## Qué tiene cada manual de integración Los manuales de integración siguen siempre el mismo orden, para que encuentres lo que buscas sin leer todo: - **Qué hace la integración** y, tan importante, qué no hace. - **Requisitos**: versiones, licencias, cuentas en el tercero y quién hace cada parte. - **Datos que necesitamos**: la tabla de lo que hay que pedir al cliente o al tercero antes de empezar. - **Configuración paso a paso**, en cada sistema y en el orden real de trabajo. - **Cómo funciona**, con los flujos dibujados. - **Comprobar que funciona** y **errores frecuentes**, con su causa y su solución. - **Preguntas frecuentes**. > [!NOTE] Los diagramas se dibujan en el navegador. Si no se ven, debajo de cada uno está su versión en texto. ## Quién hace qué En una puesta en marcha intervienen varias partes, y conviene saber desde el principio qué le toca a cada una: - **FOS** da de alta el local y la integración en Connect Manager y da soporte de la capa de Connect Manager. - **El distribuidor de Ágora** prepara Ágora (API del integrador, acciones personalizadas, formas de pago, familias…), instala Zero Connect si hace falta y revisa la configuración siguiendo el manual de la integración. - **El cliente** facilita las credenciales y los datos de su cuenta en el tercero y valida que todo funciona como espera. - **El tercero** (la plataforma, el PMS, el ERP…) da el acceso a su API y responde de su disponibilidad. ## Preguntas frecuentes ### ¿Qué es Connect Manager? Es la plataforma de FOS que conecta el TPV Ágora con plataformas de delivery, PMS de hotel, ERP, sistemas fiscales, reservas, fidelización y flotas de reparto, sin integraciones punto a punto entre cada sistema y Ágora. ### ¿Hay que abrir puertos en el router para conectar Ágora? No. Con Zero Connect, el propio equipo de Ágora abre la conexión hacia fuera, así que no hacen falta puertos abiertos, IP fija ni DNS dinámica. ### ¿Quién da de alta una integración? FOS da de alta el local y la integración en Connect Manager. El distribuidor prepara Ágora y revisa la configuración con los datos que se piden en el manual de cada integración. ### ¿Dónde ve un distribuidor las integraciones de sus clientes? En el portal del distribuidor (`hub.connectmanager.es/distributor-portal`), que enseña las integraciones y las conexiones de sus clientes. ### ¿Qué versión de Ágora hace falta? Depende de la integración: cada manual lo indica en su apartado de requisitos. --- # Guía rápida: de cero a la primera integración Portal: General · Primeros pasos URL: https://connectmanager.es/docs/connectmanager-guia-rapida Actualizado: 2026-10-03 Esta guía rápida es el camino de cualquier puesta en marcha con Connect Manager, de cero a la primera integración funcionando en Ágora. Sirve para todas: los detalles de cada una (qué datos pedir, qué se toca en cada sistema) están en su manual, que enlazamos en cada paso. El proceso tiene siempre la misma forma: comprobar que Ágora se puede conectar, pedir el alta, reunir los datos del tercero, configurar y probar de punta a punta. ```mermaid flowchart TD A[1. Comprobar los requisitos] --> B[2. Conectar Ágora] B --> C[3. Pedir el alta a FOS] C --> D[4. Reunir los datos del tercero] D --> E[5. Configurar Ágora y la integración] E --> F[6. Probar de punta a punta] F --> G[7. Seguir el día a día] ``` ## 1. Comprueba los requisitos - Abre el manual de la integración (los tienes por portal en la [portada de la documentación](https://connectmanager.es/docs)) y lee su apartado **Requisitos**: versión mínima de Ágora, licencias y cuentas que hacen falta en el tercero. - Comprueba que la **API del integrador de Ágora** está activa en el equipo de Ágora (o en el ACMS, si es un grupo) y apunta su `Api-Token`: Connect Manager la necesita para leer y crear tickets, clientes y productos. ## 2. Conecta Ágora Connect Manager tiene que poder llegar a la API de Ágora desde internet. Hay dos formas: - **Con Zero Connect** (la recomendada): un programa que se instala en el equipo de Ágora y abre la conexión hacia fuera, sin tocar el router. Sigue [Zero Connect: conectar Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion). - **Con la API publicada**: IP fija o DNS dinámica y el puerto de la API abierto en el router hacia el equipo de Ágora. Funciona, pero depende de la red del local y de que nadie cambie el router. > [!TIP] Si los buscadores de una pantalla de Connect Manager no encuentran nada (clientes, productos, habitaciones), lo primero que hay que mirar es la conexión con la API de Ágora. ## 3. Pide el alta a FOS FOS da de alta el local y la integración en Connect Manager. Para hacerlo necesita: | Dato | Ejemplo o formato | | Nombre del distribuidor y del local | Informática Demo – Restaurante Centro | | Dirección, ciudad y zona horaria del local | Calle Mayor 1, Madrid, Europe/Madrid | | URL de la API de Ágora (la del local, o la del ACMS si es un grupo) | https://local-demo.connectmanager.live con Zero Connect | | API key (Api-Token) de Ágora | La del local o la del ACMS | | La integración que se quiere activar | Uber Eats, Mews, SAP… | Puedes pedirlo desde la [página de contacto](https://connectmanager.es/contacto) o por teléfono, en el 910 91 92 11. ## 4. Reúne los datos del tercero Cada manual tiene una tabla **Datos que necesitamos** con todo lo que hay que pedir al cliente o al tercero: credenciales de su API, identificadores del hotel o del comercio, correos para los avisos… Tenerlo todo antes de empezar evita la mitad de las idas y venidas. ## 5. Configura Ágora y la integración Sigue el apartado **Configuración paso a paso** del manual, en el orden en que viene. Casi siempre hay una parte en Ágora (acciones personalizadas, formas de pago, familias, usuarios repartidor, clientes genéricos…) y otra en Connect Manager, que FOS deja preparada y tú revisas. ## 6. Prueba de punta a punta Haz la prueba del apartado **Comprobar que funciona** con un caso real: un pedido de prueba, un cargo a una habitación de pruebas, una factura… Si algo falla, el apartado **Errores frecuentes y solución** tiene los síntomas habituales con su causa. ## 7. Sigue el día a día - Los **avisos por correo** de cada integración llegan a la dirección que se configure como receptora de notificaciones. - El cliente ve su operación en su panel (`hub.connectmanager.es/app`). - Como distribuidor, en el portal del distribuidor (`hub.connectmanager.es/distributor-portal`) tienes las integraciones y las conexiones de tus clientes. ## Preguntas frecuentes ### ¿Por dónde empiezo a configurar una integración de Ágora? Por el manual de esa integración: su tabla de datos necesarios dice qué pedir al cliente y al tercero, y su configuración paso a paso, en qué orden tocar cada sistema. ### ¿Necesito Zero Connect? Solo si la API de Ágora no es accesible desde internet. Es la forma recomendada porque no depende del router del local. ### ¿Cómo me entero de que una integración ha fallado? Por los avisos por correo que manda la integración a la dirección receptora de notificaciones. El apartado de errores frecuentes de su manual dice qué significa cada uno y cómo se resuelve. ### ¿A quién llamo si algo no funciona? A soporte de FOS: 910 91 92 11, de lunes a jueves de 9 a 18 h y los viernes de 9 a 15 h, o desde la página de contacto. --- # Seguridad Portal: General · Primeros pasos URL: https://connectmanager.es/docs/seguridad Actualizado: 2026-05-09 ## Seguridad de red y direcciones IP en Connect Manager Este documento describe los principios y medidas de seguridad aplicados a nivel de red en las integraciones basadas en Connect Manager, con especial atención al uso de direcciones IP públicas, control de accesos y buenas prácticas de protección. ## Enfoque general de seguridad Connect Manager está diseñado siguiendo un enfoque de seguridad por capas. Las integraciones no se basan únicamente en credenciales o tokens, sino que combinan controles de red, autenticación y trazabilidad para minimizar riesgos. La exposición de servicios se realiza siempre de forma controlada, limitando superficies de ataque y aplicando el principio de mínimo privilegio. ## Uso de direcciones IP públicas Para determinadas integraciones, especialmente aquellas que requieren acceso desde sistemas externos al entorno del cliente, se utilizan direcciones IP públicas controladas. Estas direcciones IP corresponden a infraestructuras gestionadas por Connect Manager y se utilizan como origen de las comunicaciones iniciadas por Connect Manager hacia sistemas de terceros o hacia servidores de Ágora. ## Lista de IPs públicas autorizadas Cuando un sistema externo requiere filtrado por IP, se facilitará al cliente o proveedor la lista actualizada de direcciones IP públicas desde las que Connect Manager realiza las conexiones. Estas IPs pueden utilizarse para: - Configurar reglas de firewall - Definir listas blancas de acceso - Restringir llamadas a APIs La lista de IPs debe considerarse información técnica sensible y no debe compartirse fuera del contexto de la integración. ## Control de acceso por firewall Es responsabilidad del cliente o del proveedor externo configurar sus sistemas para permitir únicamente el acceso desde las IPs autorizadas. Las reglas recomendadas son: - Permitir solo las IPs necesarias - Limitar los puertos estrictamente requeridos - Restringir el acceso a los endpoints implicados en la integración ## Autenticación y autorización El control por IP nunca sustituye a la autenticación. Todas las integraciones deben utilizar mecanismos de autenticación seguros, como: - API Tokens - Claves API - Credenciales con permisos limitados El control por IP actúa como una capa adicional de protección. ## Comunicaciones cifradas Todas las comunicaciones entre Connect Manager y sistemas externos se realizan mediante protocolos cifrados, habitualmente HTTPS. ## Gestión de cambios en IPs En caso de que sea necesario modificar o ampliar las direcciones IP públicas utilizadas por Connect Manager, Connet Manager notificará el cambio con antelación razonable. Se recomienda no definir reglas excesivamente rígidas que puedan bloquear el servicio ante cambios comunicados. ## Registro y trazabilidad Todas las comunicaciones relevantes quedan registradas en logs técnicos, incluyendo: - Origen de la conexión - Fecha y hora - Resultado de la operación Estos registros permiten auditar accesos, detectar comportamientos anómalos y facilitar el diagnóstico de incidencias. ## Buenas prácticas recomendadas - No exponer servicios innecesarios a Internet - Utilizar siempre listas blancas de IP cuando sea posible - Rotar periódicamente tokens y credenciales - Revisar logs de acceso de forma regular - Coordinar cualquier cambio de seguridad con Connect Manager antes de aplicarlo Este documento forma parte de la documentación general de seguridad de Connect Manager y debe leerse conjuntamente con los manuales específicos de cada integración. --- # Direcciones IP salientes de Connect Manager Portal: General · Primeros pasos URL: https://connectmanager.es/docs/direcciones-ip-connectmanager Actualizado: 2026-07-06 ## Introducción En este artículo conocerás las direcciones IP salientes desde las que Connect Manager realiza solicitudes hacia servicios externos. Esta información es esencial para configurar correctamente firewalls, grupos de seguridad y listas de permisos. Esta referencia te permitirá garantizar que tu aplicación tenga acceso sin restricciones a los servicios que necesita. ### Lista de direcciones IP Connect Manager puede realizar solicitudes salientes desde cualquiera de las siguientes direcciones IP: - 18.134.215.1 - 13.43.41.184 - 35.178.113.65 - 35.177.172.66 - 13.43.150.217 - 35.176.240.172 - 13.134.211.205 - 13.135.101.112 - 13.135.255.197 - 13.135.58.13 - 13.42.204.232 - 13.43.79.206 - 16.61.207.91 - 18.135.31.117 - 3.9.6.209 - 35.176.192.32 - 85.50.165.131 --- # Glosario Portal: General · Primeros pasos URL: https://connectmanager.es/docs/glosario Actualizado: 2026-05-09 ## Glosario de Connect Manager Este glosario recoge los términos clave utilizados en las aplicaciones de integración de Connect Manager. Su objetivo es unificar el lenguaje entre equipos técnicos, clientes y documentación, y servir como referencia transversal para todos los manuales. ## Connect Manager Plataforma de integración que actúa como núcleo de comunicación entre el TPV Ágora y sistemas externos. Centraliza la lógica de integración, controla los flujos de datos y aporta trazabilidad, seguridad y escalabilidad. ## Integración Proceso mediante el cual dos o más sistemas intercambian información de forma automatizada y controlada, siguiendo reglas definidas. ## Aplicación de integración Módulo o servicio específico dentro de Connect Manager que resuelve un caso de uso concreto, como integraciones con ERP, delivery, ticketing, PMS u otros sistemas externos. ## TPV (Terminal Punto de Venta) Sistema principal de operación en el local. En el contexto de esta documentación, hace referencia al TPV Ágora, que actúa como origen o destino de los datos. ## Hub de integración Modelo de arquitectura en el que un sistema central intermedia todas las comunicaciones entre sistemas, evitando integraciones directas punto a punto. ## Sincronización Intercambio de datos entre sistemas. Puede ser programado, en intervalos definidos, o en tiempo real, en respuesta a un evento. ## Job Proceso automático ejecutado por Connect Manager, normalmente de forma programada, encargado de realizar tareas como envíos, recepciones, validaciones o conciliaciones de datos. ## Proceso Pull Modelo de integración en el que Connect Manager consulta activamente a un sistema externo para obtener información. ## Proceso Push Modelo de integración en el que un sistema externo envía información a Connect Manager sin que este la solicite explícitamente. ## Webhook Mecanismo mediante el cual un sistema notifica automáticamente a otro la ocurrencia de un evento mediante una llamada HTTP en tiempo real. ## API (Application Programming Interface) Interfaz que permite la comunicación estructurada entre sistemas de forma segura y controlada. Las integraciones de Connect Manager se basan habitualmente en APIs REST. ## API Key / Token Credencial utilizada para autenticar y autorizar el acceso a una API. Debe tratarse como información sensible y almacenarse de forma segura. ## Credenciales Conjunto de datos necesarios para acceder a un sistema, como usuarios, contraseñas, tokens, claves API o certificados. ## Entorno local Infraestructura ubicada físicamente en el local del cliente, que incluye servidores, TPVs y servicios residentes. ## Entorno cloud Servicios alojados en infraestructura externa accesible a través de Internet, como APIs, plataformas SaaS o servicios centralizados. ## Trazabilidad Capacidad de seguir el recorrido completo de un dato desde su origen hasta su destino, incluyendo estados intermedios, errores y reintentos. ## Log Registro técnico donde se almacena información sobre la ejecución de procesos, eventos relevantes y errores detectados durante el funcionamiento de una integración. ## Reintento Mecanismo automático que vuelve a ejecutar un proceso que ha fallado por causas temporales, como problemas de red o indisponibilidad puntual de un servicio externo. ## Error funcional Incidencia provocada por datos incorrectos, configuraciones erróneas o incumplimiento de reglas de negocio. ## Error técnico Incidencia causada por problemas de infraestructura, conectividad, caídas de servicio o errores internos del sistema. ## SLA (Service Level Agreement) Acuerdo de nivel de servicio que define compromisos de disponibilidad, tiempos de respuesta y resolución ante incidencias. ## Idempotencia Propiedad de un proceso que garantiza que múltiples ejecuciones del mismo producen siempre el mismo resultado sin generar duplicidades. ## Cola de mensajes Mecanismo intermedio utilizado para gestionar procesos asíncronos, desacoplar sistemas y mejorar la tolerancia a fallos. ## URL del servidor de Ágora Dirección web de administración del servidor de Ágora de un local, accesible desde el exterior. Se utiliza para tareas de gestión, integración y comunicación con servicios externos. ## API Token de Ágora Credencial de autenticación que permite a sistemas externos, como Connect Manager, acceder de forma segura a la API del servidor de Ágora del local. ## ACMS (Ágora Central Management System) Plataforma centralizada de Ágora que permite la gestión y supervisión de múltiples locales desde un entorno central. ## URL de ACMS Dirección web de acceso a Ágora Central. Es el punto de entrada para integraciones que operan a nivel centralizado y multi-local. ## API Token de Ágora Central Token de autenticación utilizado para acceder a las APIs de Ágora Central (ACMS). Permite a Connect Manager realizar operaciones globales sobre uno o varios locales de forma controlada. Este glosario es un documento vivo y se ampliará conforme evolucione el ecosistema de Connect Manager. --- # Zero Connect: conectar Ágora sin abrir puertos Portal: General · Conexión URL: https://connectmanager.es/docs/zero-connect-instalacion Actualizado: 2026-10-03 **Zero Connect** es el cliente de túnel de Connect Manager para Windows. Se instala en el equipo donde está Ágora y publica su API (puerto 8984) en una dirección HTTPS del tipo `https://{subdominio}.connectmanager.live`, sin abrir puertos en el router ni montar una VPN. Este manual es para el técnico de FOS o del distribuidor que lo instala: qué datos pedir, cómo se configura, cómo se actualiza y qué hacer cuando no conecta. ## Qué hace la integración - Abre desde el equipo de Ágora una conexión **saliente** y cifrada con el servidor de túneles de Connect Manager y la mantiene abierta. Por ella bajan las peticiones que llegan a la URL pública. - Publica el puerto local de Ágora (por defecto `127.0.0.1:8984`) en `https://{subdominio}.{dominio del servidor}`, normalmente `https://{subdominio}.connectmanager.live`. Esa es la **URL de la API** que se pone en Connect Manager. - Descarga sola su configuración (servidor asignado, credenciales del túnel y subdominios del cliente) desde el hub con un **usuario** y una **clave de acceso**: el técnico no teclea direcciones ni tokens del servidor. - Se instala como servicio de Windows (`ZeroConnectSvc`, «Connect Manager Zero Connect») con arranque automático: funciona aunque nadie inicie sesión en el equipo. - Un segundo servicio, «Connect Manager Zero Connect Updater», vigila el túnel cada 60 segundos (lo arranca si está parado y, tras tres fallos seguidos, lo vuelve a registrar) y busca actualizaciones cada 4 horas. - Comprueba cada 30 segundos que el puerto local responde y avisa al hub cada 30 minutos de los subdominios que tiene activos, para que el panel los vea en línea. - Permite **túneles adicionales** hacia otros puertos o equipos de la red: HTTP y HTTPS siempre, y TCP, UDP o STCP si el cliente tiene el acceso remoto activado, hasta el máximo de túneles de su plan. - Opcional, si FOS lo activa para el cliente: deja en la carpeta `custom-queries` de Ágora los informes XML asignados y envía un inventario de hardware y software del equipo con métricas de CPU, RAM y disco. ### Qué no hace - No sustituye a la seguridad de Ágora: cada llamada a la API sigue necesitando el `Api-Token` de Ágora. Zero Connect solo transporta el tráfico. - No da de alta el cliente ni el subdominio: el usuario y la clave los crea FOS en el hub. El distribuidor ve sus túneles en su portal, pero no puede crearlos ni cambiarlos. - El túnel principal apunta siempre a `127.0.0.1`: Zero Connect tiene que ir en el **mismo equipo** que sirve la API de Ágora. Para llegar a otro equipo de la red hay que usar un túnel adicional. - No hace falta si la API de Ágora ya es accesible desde Internet (por ejemplo, un ACMS alojado en la nube de Ágora). ## Requisitos - **Windows de 64 bits** con .NET Framework 4.7.2 o superior, en el equipo que sirve la API de Ágora: el servidor de Ágora del local o el servidor del ACMS si el grupo lo tiene en su red. - **Permisos de administrador**: el programa los pide al abrirse porque crea servicios, reglas del Firewall de Windows y exclusiones de Windows Defender. - **API de Ágora activa**: licencia del Módulo de Servicios de Integración y, en **Herramientas → Activar Módulos Adicionales**, el servicio de integración con su Api-Token. Por defecto escucha en el puerto 8984. - **Salida a Internet**: HTTPS hacia `hub.connectmanager.es` (configuración y actualizaciones) y TCP hacia el servidor de túneles asignado. No hay que abrir ningún puerto de entrada. Si el firewall corporativo filtra también la salida, pide a FOS el destino y el puerto del servidor de túneles del cliente. - **Antivirus**: el instalador añade exclusiones en Windows Defender para `C:\ConnectManager\ZeroConnect` y `ZeroConnect.exe`. Con otro antivirus, añádelas tú: el motor del túnel es una compilación de FRP y hay antivirus que lo bloquean. - **Quién hace qué**: FOS da de alta el cliente de Zero Connect en el hub (usuario, clave, servidor, subdominios y límites) y lo activa o desactiva. El técnico (FOS o distribuidor) instala el programa en el equipo de Ágora y pone la URL en Connect Manager. El cliente facilita el acceso de administrador y la salida a Internet. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Usuario del cliente de Zero Connect | FOS, campo Usuario (slug) del cliente en el hub | restaurante-demo | Sí | | Clave de acceso | FOS, campo Contraseña FRP; se copia del botón de la llave (Credenciales → «Token / Contraseña»). Por canal privado | Cadena alfanumérica | Sí | | Subdominio | Se acuerda con FOS; puede estar ya reservado en el cliente o escribirse en el asistente | restaurante-demo → https://restaurante-demo.connectmanager.live | Sí | | Puerto de la API de Ágora | Servidor de Ágora (módulo de servicios de integración) | 8984 | Sí (por defecto) | | Api-Token de Ágora | Ágora, Herramientas → Activar Módulos Adicionales. Lo necesitan las integraciones, no el túnel | TU_API_TOKEN | Sí | | Usuario administrador de Windows | Cliente o distribuidor | — | Sí | | Destino y puerto del servidor de túneles | FOS, solo si el cliente filtra la salida a Internet | — | No | ## Configuración paso a paso ### En el hub (lo hace FOS) - Entra en **/admin → ZeroTunnel → Clientes de Túneles** y pulsa **Nuevo cliente**. - Pestaña **Principal / Acceso**: - **Estado de cuenta**: Activo. - **Kill Switch (Forzar desconexión)**: apagado. Encendido, el cliente se desconecta y no puede volver a conectar. - **Expira el**: vacío es sin caducidad. Con fecha, a partir de ese día se rechaza la conexión. - **Distribuidor**: el del cliente. Es lo que hace que el distribuidor vea los túneles en su portal. - **Nombre comercial**, **Servidor FRP** (los marcados [legacy] no tienen control en tiempo real), **Usuario (slug)** (letras, números, guiones, puntos y @) y **Contraseña FRP** (botón **Generar**). - Pestaña **Subdominios** → **+ Añadir subdominio**: tipo Subdominio, el nombre y **Principal** activado. Los que se dan de alta aquí quedan reservados para este cliente; los marcados como **Principal** son los que el asistente de Zero Connect ofrece en la lista. - Pestaña **Plan y límites**: **Máx. túneles simultáneos** (túneles distintos abiertos a la vez entre todos los equipos que usen este usuario), **Ancho de banda** (vacío es sin límite; por ejemplo `10MB`), **Forzar cifrado**, **Forzar compresión** y **Acceso remoto (RDP/VNC)**, necesario para túneles TCP, UDP o STCP y para los que acaban en `_rdp`, `_vnc` o `_ssh`. - Pestaña **Funcionalidades** (opcional): **Informes Agora XML** (Sincronización activada, Intervalo de polling, Informes específicos) e **Inventario y telemetría**. - Guarda. En el listado, el botón de la llave (**Credenciales**) muestra **Usuario (slug)** y **Token / Contraseña** para pasárselos al técnico. ### En el equipo de Ágora - Comprueba antes que la API responde en local. En el propio equipo, abre en el navegador `http://127.0.0.1:8984/api/export-master/?filter=Series`. Si contesta algo, aunque sea un error por no llevar el Api-Token, la API está viva. Si el navegador no puede conectar, Ágora no escucha en ese puerto: arréglalo antes de seguir. - Ejecuta **CM Zero Connect.exe** (pide permisos de administrador). La primera vez pregunta «¿Desea instalar Connect Manager Zero Connect en el sistema?»: responde **Sí**. Copia el programa a `C:\ConnectManager`, crea los accesos directos «Connect Manager Zero Connect», lo registra en Programas y características, instala el servicio de actualización y se vuelve a abrir desde su sitio. Si ya estaba instalado y lo ejecutas desde otra carpeta, **Sí** abre la versión instalada, **No** reinstala y **Cancelar** sale. - En la ventana principal pulsa **Instalar / Configurar**. La primera vez hay que marcar «He leído y acepto los Términos y Condiciones de Uso.» y pulsar **Aceptar e Instalar**. - Paso 1, **Conectar a Zero Connect**: escribe **Usuario** y **Clave de acceso** y pulsa **Conectar →**. El programa pide al hub la configuración del cliente; si algo no vale, el error sale debajo. - Paso 2, **Configura tu túnel**: - **Servidor asignado**: informativo, lo decide FOS. - **Subdominio**: elige uno de la lista (los reservados para el cliente) o escribe uno nuevo, solo con letras, números y guiones. Debajo se ve cómo quedará la URL: `→ https://{subdominio}.connectmanager.live`. - **Nombre del servicio**: propone el nombre del equipo. El túnel se identifica por usuario y subdominio, así que puedes dejarlo. - **Puerto local**: `8984`. Cámbialo solo si la API de Ágora del cliente escucha en otro. Pulsa **Instalar ✓**. - El programa guarda la configuración cifrada, crea las reglas del Firewall y las exclusiones de Defender, instala el servicio y lo arranca. En la tarjeta **Estado del túnel** tiene que salir **Servicio en ejecución** en verde, con **Servidor**, **URL acceso** (botón **Copiar**), **IP local** y **Puerto local**. > [!NOTE] Si en el paso 2 aparece «⚠ Servidor legacy: el túnel funciona, pero no habrá kill switch en tiempo real ni métricas», es solo un aviso sobre el servidor asignado. El túnel funciona igual. ### En Connect Manager - En **Connect Manager App** (`app.connectmanager.es`) → **Administración → Locales** → el local: pega la **URL acceso** de Zero Connect en la URL de la API de Ágora, **sin** `:8984` (el túnel ya lleva a ese puerto), y pon el Api-Token de Ágora en la API key. Guarda. - Si el local usa módulos del hub: **/admin → Seguridad → Locales** → el local → **Datos de Conexión con ágora** → **Local: URL de la API** y **Local: API Token** (o los campos de ACMS si está marcado **¿Utiliza arquitectura ACMS?**). ### Túneles adicionales, cambios y desinstalación - **Servicio → Túneles adicionales...** (o el botón **⊕ Túneles adicionales**) abre una tabla con **Tipo**, **Nombre**, **Subdominio / Puerto**, **IP Local** y **Puerto**. En HTTP y HTTPS la tercera columna es un subdominio; en TCP y UDP, el puerto remoto. **Guardar y aplicar** reinicia el servicio. La cabecera dice cuántos adicionales permite el plan. - **Reconfigurar →** vuelve a lanzar el asistente: sirve para cambiar de usuario, clave, subdominio o puerto. - El botón de la izquierda cambia según el estado (**Iniciar**, **Detener** o **Reiniciar**). El menú **Servicio** tiene además **Reiniciar Servicio** y **Actualizar**; el menú **Ayuda**, **Log** y **Log del updater**. - Cerrar la ventana no corta el túnel: lo mantiene el servicio. > [!WARNING] **Servicio → Desinstalar Servicio** (y la desinstalación desde Programas y características) quita Zero Connect entero y, al terminar, borra la carpeta `C:\ConnectManager` completa, con lo que haya dentro de otras aplicaciones de Connect Manager. Si el servidor tiene también Connect Manager IA (`C:\ConnectManager\MCP`), guarda antes su fichero `identidad.json`: al reinstalarlo con ese fichero en su sitio conserva su dirección; sin él, la dirección cambia y hay que volver a añadir el conector en cada asistente. ## Cómo funciona Al instalar, Zero Connect pide su configuración al hub enviando el usuario en la ruta y la clave en la cabecera `X-Client-Token`. Con lo que recibe abre una conexión cifrada con el servidor de túneles y se identifica con el usuario y la clave. El servidor consulta al hub si el cliente existe y está activo, si el Kill Switch está apagado, si no está bloqueado ni caducado y si la clave es correcta. Después Zero Connect publica su subdominio y el hub vuelve a comprobar: que el subdominio no esté bloqueado ni reservado para otro cliente y que no se supere el máximo de túneles. A partir de ahí, cuando una integración llama a la URL pública, el servidor baja la petición por el túnel ya abierto, Zero Connect la entrega en el puerto 8984 del propio equipo y devuelve la respuesta por el mismo camino. ```mermaid sequenceDiagram participant ZC as Zero Connect participant HUB as Hub Connect Manager participant SRV as Servidor de túneles participant CM as Integración participant AG as API de Ágora ZC->>HUB: Pide su configuración con usuario y clave HUB-->>ZC: Servidor asignado, credenciales y subdominios ZC->>SRV: Conexión saliente cifrada y login SRV->>HUB: Comprueba cliente, estado y clave HUB-->>SRV: Aceptado ZC->>SRV: Publica el subdominio SRV->>HUB: Comprueba límite y subdominio HUB-->>SRV: Aceptado CM->>SRV: Petición HTTPS a la URL del subdominio SRV->>ZC: Reenvía la petición por el túnel ZC->>AG: Petición al puerto 8984 local AG-->>ZC: Respuesta de Ágora ZC-->>SRV: Respuesta por el túnel SRV-->>CM: Respuesta HTTPS ``` Lo que pasa después, sin que nadie intervenga: - **Cortes de red**: si la conexión con el servidor se cae después de haber entrado, el túnel se reconecta solo. - **Rechazo al conectar**: si el servidor rechaza el primer login (clave mal, cliente desactivado…), el motor se cierra en vez de reintentar a ciegas, y el servicio y su vigilante lo vuelven a arrancar. El motivo queda en **Ayuda → Log** (`C:\ConnectManager\ZeroConnect\ZeroConnect.log`). - **Kill Switch y bloqueos**: si FOS desactiva o bloquea al cliente, el servidor corta la sesión en su siguiente comprobación y ya no deja volver a entrar. - **Registro del subdominio**: la primera vez que se conecta, el subdominio queda dado de alta a nombre del cliente en el hub. Cada 30 minutos el vigilante confirma que sigue en línea. - **Informes de Ágora** (opcional): cada Intervalo de polling (60 minutos por defecto) compara la huella SHA-256 de cada XML asignado con el de la carpeta `custom-queries` y solo copia los que han cambiado. La carpeta y una sincronización inmediata están en **Servicio → Sincronizar informes Ágora**. > [!WARNING] Un informe XML sin el nodo `` impide que arranque el servicio de Ágora del cliente («El nodo Columns es obligatorio»). Revisa cualquier informe antes de asignarlo en **/admin → ZeroTunnel → Informes Agora**. ### Actualizaciones automáticas El servicio de actualización pregunta al hub cada 4 horas (la primera vez, dos minutos después de arrancar) si hay una versión nueva, enviando la versión instalada y el usuario del cliente. El hub anota la consulta en **/admin → ZeroTunnel → Parque de clientes**, que es donde FOS asigna el canal: **Estable** por defecto o **Beta**, que recibe la más alta entre la beta y la estable activas. El hub puede además soltar una versión a un porcentaje del parque o forzar una vuelta atrás, que se instala aunque la versión sea anterior. Si hay versión para el cliente, Zero Connect solo la descarga de una dirección HTTPS de `connectmanager.es` o `connectmanager.live`, comprueba su huella SHA-256 y que sea más nueva, para el servicio, sustituye el ejecutable y lo vuelve a arrancar. La configuración del túnel no se toca. El hub no ofrece una versión que no tenga huella. ```mermaid sequenceDiagram participant UPD as Updater participant HUB as Hub Connect Manager participant SVC as Servicio del túnel loop Cada 4 horas UPD->>HUB: Versión instalada y usuario del cliente HUB-->>UPD: Versión de su canal, URL y huella SHA-256 end alt Hay versión nueva para su canal UPD->>HUB: Descarga el paquete UPD->>UPD: Comprueba dominio, huella y versión UPD->>SVC: Para el servicio UPD->>UPD: Sustituye el ejecutable UPD->>SVC: Lo vuelve a arrancar end ``` Para forzarlo a mano: **Servicio → Actualizar**. Si hay versión, enseña el número, el tamaño y las novedades y pregunta «¿Desea actualizar ahora?» (las obligatorias y las vueltas atrás no preguntan). Si no, dice «La aplicación está actualizada». El detalle queda en **Ayuda → Log del updater** (`C:\ConnectManager\Updater\updater.log`). ## Comprobar que funciona - En Zero Connect: **Servicio en ejecución** en verde y la dirección en **URL acceso**. - Desde fuera de la red del local (por ejemplo, un móvil sin wifi), llama a la API con su token: `curl -H "Api-Token: TU_API_TOKEN" "https://restaurante-demo.connectmanager.live/api/export-master/?filter=Series"`. Tiene que devolver las series en JSON. Sin la cabecera, Ágora contesta que falta el token, y eso también demuestra que el túnel llega. - FOS, en **/admin → Seguridad → Test de conexión**, pulsa **Probar** en la fila del local: tiene que salir **Conecta** con la versión de Ágora. - En **/admin → ZeroTunnel → Clientes de Túneles** el cliente sale **Online** y se actualiza el último login. El distribuidor lo ve en **Portal de distribuidores → Zero Connect → Túneles** con el icono de conectado. - Reinicia el equipo de Ágora sin iniciar sesión y repite el paso 2: el túnel tiene que volver solo. - Haz una operación real de la integración que lee Ágora (por ejemplo, un buscador de productos o de habitaciones) para confirmar URL y token en la ficha del local. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Paso 1: «Usuario y clave son obligatorios.» | Falta uno de los dos datos. | Rellena los dos. | | Paso 1: «Error: Error al obtener configuración: Cliente no autorizado» | Usuario o clave incorrectos, o el cliente no está Activo o tiene el Kill Switch encendido. | Copia de nuevo los datos desde Credenciales; FOS revisa el estado en Clientes de Túneles. | | Paso 1: el error termina en «blocked» o «expired» | Cliente bloqueado temporalmente o con la fecha de Expira el pasada. | FOS lo desbloquea o amplía la fecha. | | Paso 1: «Error al obtener configuración» con un error de red | Sin salida HTTPS hacia hub.connectmanager.es (proxy o firewall). | Permite la salida al hub por HTTPS. | | «El subdominio solo puede contener letras, números y guiones (-).» | Caracteres no válidos (puntos, espacios, ñ). | Usa solo a-z, 0-9 y guiones. | | «Error en el servicio» y en rojo «⚠️ El subdominio '…' está reservado para otro cliente.» | El subdominio es de otro cliente. | Reconfigurar → con otro subdominio, o pide a FOS que lo libere. | | En rojo «Error: Autenticación fallida» o «Error: Conexión fallida»; en el log, «Token de autenticación incorrecto.» | La clave del cliente ha cambiado (FOS pulsó Regenerar token). | Reconfigurar → con la clave nueva. | | En el log: «Servicio desactivado por el administrador.», «Cuenta suspendida. Contacte con soporte.», «El servicio expiró el …» o «Acceso bloqueado temporalmente hasta el …» | FOS ha cortado el servicio a ese cliente. | FOS revisa Kill Switch, Estado de cuenta, Expira el y bloqueos. | | En el log: «Límite de túneles alcanzado (N). Cierra uno existente antes de abrir otro.» | Ese usuario tiene ya abiertos todos los túneles de su plan, sumando todos sus equipos. | Quita túneles adicionales o pide a FOS que suba Máx. túneles simultáneos. | | En el log: «Error al conectar con servicio local en [127.0.0.1:8984] … Verifique que el puerto no esté en uso o bloqueado.» | La API de Ágora no escucha en ese puerto: servicio de Ágora parado, módulo de servicios de integración sin activar o puerto distinto. | Arranca Ágora o activa el módulo. Si el puerto es otro, Reconfigurar → con el bueno. | | «Error: No se conecta al servidor»; el log repite «Error al conectar con el servidor» | No hay salida hacia el servidor de túneles. | Permite la salida TCP; pide a FOS destino y puerto. | | «El inicio del servicio tardó demasiado. Comprueba si el antivirus está bloqueando ZeroConnect.exe.» | Antivirus o EDR bloqueando el motor. | Exclusión para C:\ConnectManager\ZeroConnect y ZeroConnect.exe. | | «El servicio no está instalado. Vuelve a instalar Zero Connect.» o «No se encuentra NSSM en: … La instalación puede estar incompleta.» | Instalación incompleta. | Vuelve a pasar por Instalar / Configurar. | | «Acceso remoto (STCP/RDP/VNC/SSH) no habilitado para este cliente.» | Túnel adicional de tipo STCP o con nombre acabado en _rdp, _vnc o _ssh. | FOS activa Acceso remoto (RDP/VNC) en Plan y límites. | | Test de conexión: «No se llega» con «Conexión rechazada: puerto cerrado o servicio parado.» o «No se resuelve el dominio.» | Túnel caído, servicio parado o URL mal escrita. | Revisa el estado en Zero Connect y copia la URL con el botón Copiar. | | Test de conexión: «Token inválido» | El túnel llega, pero el Api-Token de la ficha del local no es el de Ágora. | Corrige el token en la ficha del local. | | Test de conexión: «Responde 404 a un endpoint que existe en todas las versiones: la URL probablemente no apunta a la API de Ágora.» | La URL apunta a otro sitio o el túnel no está publicado. | Comprueba que la URL de la ficha es la de URL acceso. | ## Preguntas frecuentes ### ¿Hay que abrir el puerto 8984 en el router para conectar Ágora con Connect Manager? No. Con Zero Connect la conexión la abre el equipo de Ágora hacia fuera, así que no hace falta abrir puertos de entrada, ni IP fija, ni VPN. Solo necesita salida a Internet. ### ¿Qué URL de API pongo en Connect Manager si uso Zero Connect? La que muestra Zero Connect en **URL acceso**, del tipo `https://{subdominio}.connectmanager.live`, sin `:8984`. El token sigue siendo el Api-Token de Ágora. ### ¿Zero Connect se actualiza solo? Sí. El servicio de actualización consulta el hub cada 4 horas y aplica la versión de su canal (estable o beta, lo decide FOS) comprobando su huella SHA-256. También se puede lanzar desde **Servicio → Actualizar**. ### ¿Qué pasa si se reinicia el servidor de Ágora o se va la luz? Los dos servicios arrancan solos con Windows, sin iniciar sesión, y el túnel se reconecta. Si el motor se cae, el vigilante lo vuelve a levantar en menos de un minuto. ### ¿Puedo usar el mismo usuario de Zero Connect en varios locales? Sí, si FOS lo ha preparado así: cada equipo publica su propio subdominio. Todos cuentan para el mismo **Máx. túneles simultáneos** y se cortan a la vez si se desactiva el cliente. ### ¿Necesito Zero Connect para Connect Manager IA? No. Connect Manager IA trae su propio túnel y su dirección propia. Pueden convivir en el mismo servidor, con cuidado al desinstalar Zero Connect (ver el aviso de desinstalación). ## Referencias - [Connect Manager IA: ChatGPT, Claude, Gemini y Copilot con Ágora](https://connectmanager.es/docs/connect-manager-ia-conectar-asistentes) - [Seguridad de red y direcciones IP en Connect Manager](https://connectmanager.es/docs/seguridad) - [Direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) (si en vez de Zero Connect se abre el puerto y se filtra por origen) - [Glosario de Connect Manager](https://connectmanager.es/docs/glosario) - Proyecto FRP, base del motor del túnel: [github.com/fatedier/frp](https://github.com/fatedier/frp) --- # Usuarios Portal: General · Panel de cliente URL: https://connectmanager.es/docs/manual-usuarios Actualizado: 2026-06-17 ## Usuarios En el apartado **Usuarios** (dentro de Configuración) gestionas todas las personas que acceden al panel de tu restaurante. Aquí asignas permisos, roles, locales autorizados y controlas quién puede entrar. Es el lugar central para crear nuevos usuarios, cambiar sus accesos y administrar su seguridad. ### Cómo usarlo - **Ver la lista de usuarios:** Verás una tabla con todos los usuarios activos e inactivos de tu organización. Puedes buscar por nombre o email en los campos de búsqueda. - **Crear un nuevo usuario:** Haz clic en el botón **Crear** arriba a la derecha. Completa: - **Nombre** (obligatorio) - **Email** (obligatorio, debe ser único) - **Contraseña:** Déjalo en blanco para que se genere una segura de un solo uso que se enviará al email del usuario. Si pones una, debe tener 8+ caracteres, mayúscula, minúscula y símbolo especial. - **Perfil de usuario** (obligatorio): Asigna uno o varios roles como Gerente, Mesero, Caja, etc. Los permisos específicos dependen del rol elegido. - **Grupos de locales** o **Locales autorizados** (mínimo uno): Indica a qué restaurantes o sucursales tiene acceso. Si asignas un grupo, hereda automáticamente todos sus locales. - **Teléfono** y **Usuario Telegram** (opcionales): Contacto adicional del usuario. - **Editar un usuario existente:** Haz clic en el icono de lápiz. Puedes cambiar nombre, email, roles, locales, teléfono y Telegram. **No puedes editar tu propio email ni desactivarte a ti mismo.** - **Activar o desactivar acceso:** Usa el icono de candado abierto/cerrado en la columna **Acceso**. Un usuario inactivo no podrá entrar al panel, pero sus datos permanecen. - **Forzar cambio de contraseña:** En la edición, marca la opción **Forzar cambio de contraseña**. El usuario tendrá que cambiarla al próximo login. - **Eliminar un usuario:** Haz clic en el icono de papelera. Una vez eliminado, no podrá recuperarse fácilmente (confirma antes de borrar). - **Acciones en lote:** Selecciona varios usuarios con las casillas a la izquierda y elimina múltiples registros a la vez con el botón **Eliminar** que aparece. ### Columnas visibles - **Nombre:** Nombre completo del usuario (buscable). - **Email:** Correo electrónico (buscable). - **Perfiles:** Roles asignados (buscable, etiquetas de color). - **Acceso:** ícono que muestra si está activo (✓) o inactivo (✗). - **Creado / Actualizado:** Fechas de registro y última modificación (ocultas por defecto, puedes mostrarlas con el menú de columnas). ### Consejos - **Permisos automáticos:** Los permisos específicos (crear pedidos, ver reportes, etc.) se asignan mediante el rol. Verás un resumen de qué permisos tiene el usuario según sus roles antes de guardar. - **Locales efectivos:** Si asignas un usuario a un grupo, automáticamente tendrá acceso a todos los locales de ese grupo. El panel muestra cuáles son sus locales reales (directos o heredados) al editar. - **Contraseñas seguras:** Usa la opción de autogenerar. Las contraseñas manuales deben ser fuertes (8+ caracteres, mayúscula, minúscula, símbolo). - **No puedes borrar tu propia cuenta:** Si eres administrador, no verás la opción de eliminar tu propio usuario. Pide a otro admin que lo haga si es necesario. --- # Feedback Portal: General · Panel de cliente URL: https://connectmanager.es/docs/manual-feedback Actualizado: 2026-06-17 ## Feedback El apartado **Feedback** es tu canal directo para reportar problemas técnicos que encuentres en el sistema o sugerir mejoras y nuevas funcionalidades. Cada mensaje que envíes queda registrado y nuestro equipo lo analiza para mejorar tu experiencia. Puedes ver el estado de tus reportes en cualquier momento y comentar con nuestro equipo para aclarar detalles. ### Cómo usarlo - Haz clic en el botón **Añadir** para crear un nuevo reporte. - Rellena el **Asunto** con un resumen breve del problema o la mejora (ej: "Problema con la carga de productos"). - En **Explícanos los detalles**, describe lo que te pasó o qué quieres sugerir. Puedes copiar y pegar capturas de pantalla directamente en este campo. - Selecciona el **tipo de comunicación**: - Tengo un problema técnico (Fallo/Bug) si algo no funciona como debería. - Quiero sugerir una mejora o nueva funcionalidad si tienes una idea para mejorar el panel. - Indica el **Nivel de Urgencia**: - Baja — no es urgente. - Media — afecta algunas tareas. - Alta — tu operativa se ve afectada. - Bloqueante — no puedes trabajar sin que se solucione. - Haz clic en **Guardar**. - Desde la lista de reportes, haz clic en **Ver Detalles** para ver el estado (Recibido, En Análisis, En Revisión / Test, Resuelto / Finalizado) y dejar comentarios con el equipo. ### Consejos - Sé específico en tu descripción: cuéntanos qué pasos seguiste, qué esperabas que pasara y qué pasó en su lugar. - Las capturas de pantalla son muy útiles — adjúntalas directamente en el campo de detalles. - Si el problema es bloqueante (no puedes trabajar), selecciona "Bloqueante" para que lo resuelvan lo antes posible. - Usa el apartado de comentarios para responder preguntas del equipo o agregar más información conforme avanza el análisis. --- # Connect Manager IA: ChatGPT, Claude, Gemini y Copilot con Ágora Portal: General · Inteligencia artificial URL: https://connectmanager.es/docs/connect-manager-ia-conectar-asistentes Actualizado: 2026-10-03 **Connect Manager IA** (el servicio Connect Manager MCP) conecta asistentes de inteligencia artificial como Claude o ChatGPT con los datos de Ágora. Se instala en el servidor donde está Ágora, o en el del ACMS si es un grupo, publica un conector MCP en una dirección HTTPS propia y contesta siempre en solo lectura. Este manual es para el técnico que lo instala, gestiona la licencia y da acceso a las personas del cliente. ## Qué hace la integración - Instala un servicio de Windows, «Connect Manager MCP», en el servidor de Ágora. Localiza solo la base de datos leyendo el `hibernate.cfg.xml` de Ágora: no hay que teclear ninguna cadena de conexión. - Crea en SQL Server una cuenta de **solo lectura** (`agora_mcp_ro`) con contraseña aleatoria y comprueba, antes de terminar, que puede leer y que un `UPDATE` es rechazado. Si la cuenta pudiera escribir, la instalación se aborta. - Publica el conector en `https://mcp-{12 caracteres}.connectmanager.live/mcp` con un túnel saliente propio: no necesita Zero Connect ni abrir puertos. La dirección se conserva al reinstalar o actualizar. - Ofrece al asistente ocho herramientas: `info_instalacion` (ficha: versión de Ágora, locales, rango de fechas), `ventas_resumen` (ventas facturadas por local, día, hora, día de la semana, empleado, centro de venta, forma de pago, familia o producto, con fechas como ayer o mes_pasado), `listar_informes`, `ejecutar_informe`, `listar_valores`, `buscar_esquema`, `describir_tabla` y `consulta_sql` (un `SELECT` libre). - Publica como informes el catálogo de FOS y los informes personalizados de la carpeta `custom-queries` de ese Ágora, que se releen cada 30 segundos: para añadir uno basta con dejar el XML en la carpeta. - Ofrece siete análisis listos, que el asistente presenta como puntos de partida (en Claude, al escribir `/`): Radiografía del negocio, Cierre del día, Cierre del mes, Comparar locales, Descuentos e invitaciones, Franjas horarias y salas y Auditoría de fraude. - Da al asistente las reglas de Ágora para no equivocarse con las cifras: filtrar por día de negocio (`BusinessDay`), que `NetAmount` lleva el IVA incluido, el borrado lógico, que lo cobrado es lo pagado menos el cambio, o que el fraude se presenta como indicio y nunca como acusación. - Cada persona entra con su propia cuenta de Connect Manager (OAuth). El servidor lleva la lista de quién se conecta y permite retirarle el acceso. - Se registra solo en el hub, que lleva la licencia: 30 días de prueba la primera vez que se instala en una máquina y activación por FOS. ### Qué no hace - No escribe nada en Ágora: no crea tickets, no cambia precios ni borra datos. Lo impiden tres barreras a la vez: filtro de la sentencia, transacción que se deshace siempre y permisos denegados en SQL Server. - No se actualiza solo: hay que instalar el MSI nuevo encima, y se conservan dirección y token. - No calcula márgenes si la instalación no tiene escandallos (coste en las líneas): retira esas columnas y lo dice. - Devuelve como mucho 1.000 filas por consulta durante la prueba y 2.000 con la licencia activa, y corta las consultas de más de 60 segundos. Los totales se piden ya agregados. - Las cifras del día en curso pueden incluir tickets abiertos: lee sin bloquear el TPV. - El producto solo trae pasos de alta para Claude y ChatGPT. Gemini, Copilot u otros asistentes funcionarán si admiten conectores MCP remotos con autorización OAuth, pero FOS no los documenta. - El cliente final no puede autorizar su instalación por su cuenta: necesita una invitación o que FOS lo añada a la lista. ## Requisitos - **Servidor Windows de 64 bits** con Ágora instalado y su SQL Server en marcha. En un grupo, el servidor del **ACMS**: una sola instalación cubre todos los locales. En un local suelto, su servidor de Ágora. El MSI se niega a instalarse si no encuentra el `hibernate.cfg.xml`. - **Permisos de administrador** para el MSI. La cuenta administrativa de Ágora que guarda el `hibernate.cfg.xml` solo se usa para crear la cuenta de solo lectura; el servicio en marcha no la ve. - **Salida a Internet**: HTTPS hacia `hub.connectmanager.es` (registro, licencia y autorización) y TCP hacia el servidor de túneles. No hay puertos de entrada ni VPN. Sin hub, el servicio aguanta 3 días con el último estado conocido. - No hace falta instalar ningún runtime: el ejecutable es autocontenido. - Cada persona necesita un asistente que admita conectores MCP remotos (Claude, o ChatGPT en modo desarrollador), con el plan que lo permita, y una cuenta de Connect Manager. Si no la tiene, se crea con la invitación. - **Quién hace qué**: FOS entrega el instalador, controla la licencia (activar, ampliar la prueba, suspender) y puede añadir personas a la lista de la instalación. El técnico (FOS o distribuidor) instala el MSI, invita a las personas y comprueba el alta. El cliente decide quién usa el asistente y con qué cuenta. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Servidor de Ágora o del ACMS | Cliente o distribuidor | El equipo donde está hibernate.cfg.xml | Sí | | Nombre de la instalación | Técnico; se ve en el panel y en el asistente | Grupo Demo (propiedad NOMBRE del MSI) | No (por defecto, el nombre del equipo) | | Ruta de hibernate.cfg.xml | Solo si Ágora no está en C:\Program Files (x86)\IGT Microelectronics\Agora | D:\Agora\hibernate.cfg.xml (propiedad HIBERNATECONFIG) | No | | Puerto local del servicio | Técnico | 8787 (propiedad PUERTO) | No | | Correo de cada persona que usará el asistente | Cliente | persona@empresa.es | Sí | | Asistente de cada persona | Cliente | Claude, ChatGPT | Sí | | Cuenta de Connect Manager del técnico | FOS o el distribuidor | La del panel | Sí, para autorizarse | ## Configuración paso a paso ### En el servidor de Ágora - Copia `ConnectManagerMCP-Setup.msi` (te lo facilita FOS) al servidor de Ágora o del ACMS. - Instálalo como administrador con doble clic (licencia, progreso y final) o en silencio: `msiexec /i ConnectManagerMCP-Setup.msi /qn NOMBRE="Grupo Demo" PUERTO=8787`. Admite `NOMBRE`, `PUERTO`, `BIND`, `LOGINSQL` y `HIBERNATECONFIG`. - El instalador deja todo en `C:\ConnectManager\MCP`: localiza Ágora, crea y verifica la cuenta de solo lectura, escribe la configuración restringida a Administradores y SYSTEM, genera el subdominio y el token de la instalación, añade exclusiones de Windows Defender para la carpeta y sus dos ejecutables, y registra el servicio con inicio automático retrasado (SQL Server tiene que estar arriba antes) y reinicio ante fallos. - Al terminar, deja marcada **Abrir la pagina de cuentas y conexion**. Se abre `http://127.0.0.1:8787/usuarios`, que solo funciona desde el propio servidor. Arriba está la dirección pública del conector con el botón **Copiar** y una franja con el estado de la licencia (En prueba y los días que quedan), el nombre de la instalación, el número de locales y el botón **Comprobar licencia**. Debajo, las pestañas **Conectar** y **Cuentas**. > [!TIP] Si la instalación falla, el motivo queda en `C:\ProgramData\Connect Manager MCP\ultimo-error-instalacion.txt`, en `instalacion.log` de esa misma carpeta y en el Visor de eventos (Aplicación, origen «Connect Manager MCP», id 1001). ### En Connect Manager (lo hace FOS) - Al arrancar, el servicio se registra solo. La instalación aparece en **/admin → ZeroTunnel → Conectores MCP** con estado **En prueba** y los días que quedan, tipo (ACMS o Standalone), locales, TPV, versión, túnel y **Último latido**. Late cada hora: si pasan más de dos sin latido, sale en rojo. - Acciones de cada fila: **Datos de conexión**, **Quién tiene acceso** (sesiones abiertas y **Revocar los marcados**), **Usuarios permitidos** (personas que pueden autorizar esta instalación, además de FOS y el distribuidor), **Marcar como activa**, **Ampliar prueba** (Días a añadir, 15 por defecto), **Suspender**, **Reactivar** y **Corregir datos fiscales**. - Antes de que acabe la prueba (el panel la pinta en ámbar 7 días antes), **Marcar como activa**. El hub avisa al servicio en el momento; si el aviso no llega, se entera en su siguiente consulta. En el servidor, **Comprobar licencia** lo fuerza. > [!WARNING] El token de **Datos de conexión** es el del cliente de Zero Connect y da acceso a toda su API. No hace falta para conectar un asistente: no lo envíes al cliente. ### Dar acceso a las personas Pueden autorizar una instalación los usuarios de FOS con acceso global, los usuarios del distribuidor del cliente y las personas que estén en la lista de esa instalación. Al resto se les invita desde la pestaña **Cuentas** de la página del servidor: - **Invitar por correo**: escribe el correo y pulsa **Invitar**. El hub envía un enlace que vale 7 días y un solo uso (como mucho 10 invitaciones por instalación y hora). Al aceptarlo, la persona crea su cuenta de Connect Manager, sin acceso a ningún panel, y queda autorizada para esta instalación y ninguna otra. Si el correo no sale (por ejemplo, porque la instalación aún no se ha registrado en el hub), la página lo dice y la persona queda solo en la lista del servidor: repite la invitación más tarde o pide a FOS que la añada en **Usuarios permitidos**. - **Autorizarme a mí** → **Entrar con mi cuenta de Connect Manager**: para que el técnico se autorice desde el propio servidor. - La tabla enseña **Cuenta**, **Estado** (con acceso o sin conectarse todavía) y **Última vez**. **Retirar acceso** corta a esa persona en su siguiente petición; **Quitar** borra una invitación pendiente. Si sale el bloque **Sin acceso**, son cuentas que se han conectado y esperan **Dar acceso**. Por defecto decide Connect Manager: quien puede autorizar entra y queda anotado en la lista. Si el cliente quiere aprobar además cada cuenta en el servidor, FOS cambia `ExigirAutorizacion` a `auto` o `siempre` en `connect-manager-mcp.json`. ### En el asistente La pestaña **Conectar** lo resume: la dirección de arriba es lo único que hay que pegar en el asistente. **Claude**: - Abre **Configuración** y entra en **Conectores**. - Pulsa **Añadir conector personalizado**. - Pega la dirección (acaba en `/mcp`) y acepta. - Se abre el acceso de Connect Manager: entra con tu correo y contraseña. - Confirma la instalación a la que das acceso. **ChatGPT**: - En **Configuración › Conectores**, abre **Configuración avanzada** y activa el **modo desarrollador**. - Vuelve a **Conectores** y pulsa **Crear**. - Pon un nombre, pega la dirección en **URL del servidor MCP** y elige **OAuth** como autenticación. - Autoriza con tu cuenta y pulsa **Permitir acceso**. **Otros asistentes** (Gemini, Copilot o cualquiera compatible con MCP): añade un servidor o conector MCP remoto con la misma dirección y autenticación OAuth. El asistente descubre solo el servidor de autorización de Connect Manager. En todos, la pantalla de Connect Manager pregunta «¿Le das acceso a los datos de Ágora de este local?», enseña el nombre y el subdominio de la instalación y lo que podrá hacer el asistente (explorar tablas y columnas, listar y ejecutar los informes del catálogo y hacer consultas SELECT libres, según cubra la licencia) y recuerda «Solo consulta: no puede modificar ni borrar nada en Ágora.». Pulsa **Autorizar**. ## Cómo funciona Cuando alguien añade el conector, el asistente llama a la dirección sin credenciales. El servicio contesta que hace falta autorización y le indica el servidor que la da: el hub de Connect Manager. El asistente abre el acceso del hub (OAuth con PKCE), la persona entra con su cuenta y confirma, y el hub comprueba que puede autorizar esa instalación y que la licencia está viva. Si todo está bien, emite un token de una hora firmado para esa instalación y solo esa, con los permisos que cubre la licencia, más un token de renovación que caduca tras 180 días sin uso. Desde ahí, cada pregunta se convierte en llamadas a herramientas. El servicio valida el token en local (firma, emisor, destinatario y permisos), mira la lista de cuentas de la instalación y consulta la base de datos con la cuenta de solo lectura. Todo el tráfico entra por la dirección pública y el túnel lo entrega al puerto local del servicio. ```mermaid sequenceDiagram participant U as Persona participant IA as Asistente participant MCP as Connect Manager MCP participant HUB as Hub Connect Manager participant DB as Base de datos de Ágora U->>IA: Añade el conector con la dirección del MCP IA->>MCP: Primera llamada sin token MCP-->>IA: 401 con el servidor de autorización IA->>HUB: Pide autorización OAuth con PKCE U->>HUB: Entra con su cuenta y confirma la instalación HUB-->>IA: Token de una hora y token de renovación U->>IA: Pregunta por las ventas de ayer IA->>MCP: Llama a una herramienta con el token MCP->>MCP: Valida token, permisos y lista de cuentas MCP->>DB: SELECT con la cuenta de solo lectura DB-->>MCP: Filas MCP-->>IA: Tabla con totales y periodo resuelto IA-->>U: Respuesta en lenguaje natural ``` Cada consulta se ejecuta sin bloquear el TPV, con un tope de filas y de 60 segundos, y dentro de una transacción que se deshace siempre. Toda tabla lleva la suma de sus columnas y avisa si está cortada, y las consultas repetidas en el mismo minuto se sirven de memoria. ### Informes y análisis disponibles El catálogo de FOS viaja con el instalador, en la carpeta `informes`, y el asistente lo ve agrupado así: - **Ventas**: Ventas diarias por usuario, Ventas por centro de venta, Ventas por Local, Familia y Producto y Detalle de líneas vendidas. - **Auditoría**: Auditoría de fraude por usuario y Descuentos por usuario y tipo. - **KPIs FOS**: IQT - Índice de Calidad del Ticket, RPM - Rentabilidad por minuto, Aprovechamiento de cubierto, Score de venta sugerida por camarero, Mesa Perfecta por camarero, Valor futuro del cliente (CLV 12m), Incidencias en mesa por local, Composición gastronómica por local, Potencial desaprovechado por camarero, IGT - Índice Global del Ticket y Monitor de cocina - tiempos por familia. A esos se suman los informes personalizados de la carpeta `custom-queries` de ese Ágora, tal cual. Los análisis listos están en la carpeta `guiones`, que cada actualización reescribe; los hechos a medida para un cliente van en `guiones-cliente`, que el instalador no toca, y si se llaman igual que uno de FOS, manda el del cliente. ### Licencia y registro Al arrancar, el servicio se da de alta en el hub con los datos de la instalación: identificador del equipo, versión, subdominio, versión de Ágora, número de locales y TPV, datos fiscales y licencias de Ágora. El alta es única por máquina: reinstalar en el mismo equipo no reinicia la prueba. Después late cada hora y consulta la licencia cada 6 horas, con un desfase aleatorio para que los servidores no llamen todos a la vez. Cuando FOS activa, amplía o suspende, el hub avisa al servicio para que vuelva a preguntar en ese momento. ```mermaid sequenceDiagram participant MCP as Connect Manager MCP participant HUB as Hub Connect Manager MCP->>HUB: Alta al arrancar con los datos de la instalación HUB-->>MCP: Estado de la licencia, 30 días de prueba la primera vez loop Cada hora MCP->>HUB: Latido con versión, túnel y uso HUB-->>MCP: Estado de la licencia end loop Cada 6 horas MCP->>HUB: Consulta de licencia end HUB->>MCP: Aviso de cambio al activar o suspender MCP->>HUB: Vuelve a consultar la licencia ``` - **En prueba**: todo funciona, con 1.000 filas por consulta. Al vencer, el conector deja de servir datos en su siguiente consulta al hub (como mucho, una hora) y el hub no deja autorizar ni renovar, con el mensaje «El periodo de prueba ha terminado. Contacta con FOS para activar la licencia.» (o «…ha vencido…»). - **Activa**: sin caducidad. El tope pasa a 2.000 filas, que es el de la configuración del servidor. - **Suspendida o cancelada**: deja de servir en su siguiente consulta (como mucho, una hora) y el hub revoca las sesiones abiertas. Al reactivar, el servicio vuelve a funcionar, pero cada persona tiene que autorizar de nuevo el conector. - **Sin hub**: sigue con el último estado conocido durante 3 días. El túnel lo lanza y lo vigila el propio servicio: si se cae, lo reinicia con esperas crecientes, y al parar el servicio se cierra con él. Su estado (publicado, arrancado, caido, error…) se ve en `http://127.0.0.1:8787/health` desde el servidor. El registro del servicio está en `C:\ConnectManager\MCP\logs`. ## Comprobar que funciona - En `http://127.0.0.1:8787/usuarios` sale la dirección pública y la franja de licencia dice En prueba o Licencia activa. - En `http://127.0.0.1:8787/health`, desde el servidor, el estado es `ok`, el túnel publicado y la licencia habilitada. - En **Conectores MCP**, el **Último latido** está en verde. - Añade el conector en Claude o ChatGPT con tu cuenta y lanza Radiografía del negocio o pregunta «¿Cuánto vendimos ayer por local?». La respuesta tiene que citar locales y fechas reales. - En la pestaña **Cuentas** apareces con acceso y con la hora de tu última consulta. - Pide al asistente que cambie un precio: tiene que contestar que no puede, porque el servidor es de solo lectura. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | El MSI se para con «No se ha encontrado Agora en este equipo (falta hibernate.cfg.xml)…» | No es el servidor de Ágora, o Ágora está en otra ruta. | Instala en el servidor de Ágora o del ACMS, o pasa HIBERNATECONFIG="ruta\hibernate.cfg.xml". | | El MSI acaba antes de tiempo con un error genérico | Ha fallado la configuración: Ágora no encontrado, SQL Server inaccesible o «La cuenta ha quedado con permisos de escritura. Se aborta la configuracion.». | Lee ultimo-error-instalacion.txt en C:\ProgramData\Connect Manager MCP y corrige la causa antes de repetir. | | «Esta instalación todavía no tiene dirección pública…» | La configuración se ha quedado sin subdominio o con el túnel desactivado. | Vuelve a instalar el MSI encima; si sigue igual, avisa a FOS. | | La página enseña la dirección, pero en /health el túnel sale sin credenciales, caido o error | Al arrancar no pudo pedir al hub los datos del túnel (sin salida a Internet), o el antivirus impide lanzarlo (en el registro, «Acceso denegado»). | Abre la salida a Internet y reinicia el servicio «Connect Manager MCP»; si es el antivirus, añade a mano las exclusiones de C:\ConnectManager\MCP, connect-manager-mcp.exe y cm-mcp-tunnel.exe. | | «Esta pagina solo se puede abrir desde el propio servidor.» | Se ha abierto la página de cuentas por la dirección pública o desde otro equipo. | Ábrela en el servidor con http://127.0.0.1:8787/usuarios. | | «Tu cuenta no tiene permiso sobre esta instalación.» | La persona no es de FOS, ni del distribuidor, ni está en la lista de la instalación. | Invítala desde Cuentas o pide a FOS que la añada en Usuarios permitidos. | | «Esos datos no son correctos, o la cuenta está desactivada.» | Correo o contraseña de Connect Manager incorrectos, o usuario desactivado. | Revisa la cuenta; si aún no existe, acepta antes la invitación. | | «El recurso indicado no corresponde a ninguna instalacion.» o «La URL del MCP tiene que terminar en /mcp.» | Dirección mal copiada, sin /mcp, o instalación que aún no se ha registrado en el hub. | Copia la dirección con el botón Copiar y comprueba el latido en Conectores MCP. | | «El periodo de prueba ha terminado. Contacta con FOS para activar la licencia.», «El periodo de prueba ha vencido…» o «Instalación suspendida. Contacta con FOS.» | Licencia vencida o suspendida. | FOS: Marcar como activa, Ampliar prueba o Reactivar. | | El asistente recibe «instalacion_no_activa» | Licencia no activa, o el servidor lleva más de 3 días sin hablar con el hub. | Revisa la licencia y la salida a hub.connectmanager.es; luego Comprobar licencia. | | «La cuenta … no tiene acceso a esta instalacion. Se concede desde la pagina de cuentas del propio servidor…» | Se le retiró el acceso o la instalación exige aprobación y está pendiente. | En Cuentas, Dar acceso. | | «El token no fue emitido para esta instalacion.» | El conector se autorizó contra otra instalación. | Borra el conector y añádelo con la dirección correcta. | | La dirección pública responde 404 tunnel_not_found | El subdominio aún no está dado de alta en el servidor de túneles. | Avisa a FOS con el subdominio de la instalación. | | Una consulta se corta o la tabla sale incompleta | Tope de 60 segundos o de filas por consulta. | Acota el periodo o pide el resultado agregado. | ## Preguntas frecuentes ### ¿Cómo conecto Claude a mi TPV Ágora? Instala Connect Manager IA en el servidor de Ágora, copia la dirección que sale en su página de cuentas y añádela en Claude como conector personalizado (**Configuración → Conectores → Añadir conector personalizado**). Entra con tu cuenta de Connect Manager y autoriza la instalación. ### ¿Cómo conecto ChatGPT con Ágora? Activa el modo desarrollador en **Configuración › Conectores › Configuración avanzada**, crea un conector con la dirección del MCP en **URL del servidor MCP** y autenticación **OAuth**, y autoriza con tu cuenta. ### ¿Funciona con Gemini o con Copilot? El servicio sigue el estándar MCP con autorización OAuth, así que funciona con cualquier asistente que admita conectores MCP remotos de ese tipo. El producto solo trae los pasos de Claude y ChatGPT; para los demás, consulta la documentación del asistente. ### ¿La IA puede modificar o borrar datos de Ágora? No. La cuenta de base de datos tiene la escritura denegada, solo se admiten sentencias `SELECT` y todo se ejecuta en una transacción que se deshace siempre. ### ¿Qué pasa cuando terminan los 30 días de prueba? Si FOS no ha activado la licencia, el conector deja de responder con datos y no se puede autorizar. Al activarla, vuelve a funcionar sin reinstalar ni volver a autorizar. ### ¿Se instala en cada local o en el ACMS? En un grupo con ACMS, una sola vez en el servidor del ACMS: ve todos los locales. En un local sin ACMS, en su servidor de Ágora. ## Referencias - [Connect Manager IA](https://connectmanager.es/ia-para-agora) - Fichas del catálogo: [Claude](https://connectmanager.es/integraciones/claude), [ChatGPT](https://connectmanager.es/integraciones/chatgpt), [Google Gemini](https://connectmanager.es/integraciones/google-gemini) y [Microsoft Copilot](https://connectmanager.es/integraciones/microsoft-copilot) - [Zero Connect: conectar Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion) - [Seguridad de red y direcciones IP en Connect Manager](https://connectmanager.es/docs/seguridad) - Especificación oficial de MCP: [modelcontextprotocol.io](https://modelcontextprotocol.io) --- # Integración de Logirest con Ágora: pedidos de compra en EDI Portal: General · ERP y contabilidad URL: https://connectmanager.es/docs/integracion-logirest-agora Actualizado: 2026-10-03 La integración de **Logirest** con **Ágora** envía a Logirest, el operador logístico para restauración del grupo STEF, los pedidos de compra que los locales confirman en el TPV, sin pasarlos a mano. **Connect Manager** revisa Ágora cada dos horas, genera el fichero de cada pedido en el formato de Logirest y lo deja en su servidor por SFTP o FTP, con copia por correo. Este manual es para el técnico que la configura en un cliente. ## Qué hace la integración - Cada dos horas lee de la API de Ágora los pedidos de compra del día y, una vez más de madrugada, los del día anterior. - Selecciona los pedidos en estado Confirmado cuyo proveedor tiene un CIF de los configurados. - Genera un fichero `.Edi` por pedido con el código del almacén que lo recibe, la fecha de entrega y, por línea, el código de artículo de Logirest, la cantidad, las unidades por caja, el precio y la cantidad en unidades. - Identifica cada artículo por su código de barras de Ágora: toma el que empieza por uno de los prefijos configurados. - Pone la fecha de entrega del pedido o, si no la tiene, la de dentro de tres días. - Sube el fichero por SFTP o FTP y envía una copia por correo con el fichero adjunto. - Quita del pedido las líneas cuyo artículo no tiene código válido y avisa por correo con la lista de productos. - Reintenta solo los pedidos que fallan al subirse y permite reenviar un pedido desde **Pedidos → Historial de pedidos**. ### Qué no hace - No envía pedidos en borrador ni pedidos de proveedores que no estén en la lista de CIF. - No vuelve a enviar un pedido que se modifica en Ágora después de haberse enviado: se lee una sola vez. - No envía líneas sin código de barras válido: se quitan del pedido y se avisa. - No recibe nada de Logirest (confirmaciones, albaranes ni facturas): solo envía pedidos. - No permite SFTP con clave privada desde el panel: Clave privada y Frase de contraseña aparecen pero no se guardan. Usa usuario y contraseña. - No permite cambiar desde el panel los tres días de margen para la fecha de entrega. ## Requisitos - Una cuenta en el servidor **SFTP o FTP de Logirest**, con la carpeta donde dejar los pedidos. Si el servidor filtra por IP, autoriza las [direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager). - En Ágora, los pedidos de compra a Logirest gestionados en el TPV: proveedor con su CIF, almacén de destino, unidades de compra con su factor y artículos con el código de Logirest guardado como código de barras. - Dos informes personalizados instalados en Ágora: el de unidades de medida y el de códigos de barras de productos (se descargan desde la propia integración). - La API de Ágora (puerto 8984) accesible desde fuera, directamente o con Zero Connect, y su API key. - Reparto de tareas: FOS da de alta el local y la integración; el técnico instala los informes, configura proveedores, almacenes y prefijos y revisa los artículos; Logirest facilita el servidor y sus códigos. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Servidor de ficheros: método, host, puerto y carpeta | Logirest | SFTP, sftp.logistica-ejemplo.es, 22, /pedidos | Sí | | Usuario y contraseña del servidor | Logirest | Usuario de la cuenta de envío | Sí | | CIF de los proveedores cuyos pedidos van a Logirest | Cliente | B12345678 (vale el principio del CIF) | Sí | | Código de cliente de Logirest de cada almacén de Ágora | Logirest | MAD01 (en el fichero, EMBMAD01) | Sí | | Prefijo de cliente | Logirest | EMB (valor por defecto) | No | | Prefijo de los códigos de barras de Logirest | Logirest | EMBC (valor por defecto) | No | | Código de Logirest de cada artículo | Logirest, guardado en Ágora como código de barras | EMBC001234 | Sí | | Correos para la copia de pedidos y los avisos | Cliente | compras@ejemplo.es | Recomendado | | URL de la API de Ágora y API key | Distribuidor o FOS (datos del local) | https://agora-demo.ejemplo.es:8984 | Sí | ## Configuración paso a paso ### Con Logirest - Pide la cuenta del servidor de ficheros y la carpeta de entrada de pedidos. - Pide el código de cliente de cada punto de entrega (almacén de Ágora) y los códigos de artículo, con el prefijo que usan. ### En Ágora - Abre la integración en Connect Manager (paso siguiente) y, en la tarjeta **Informes personalizados**, descarga el Informe de unidades de medida (`Units_Of_Measurement.xml`) y el Informe de códigos de barras de productos (`Product_Barcodes.xml`). - Cópialos en la carpeta `custom-queries` del servidor de Ágora (en el ACMS si lo hay), por ejemplo `C:\Program Files (x86)\IGT Microelectronics\Agora\custom-queries`. - Añade a cada artículo que se pide a Logirest un código de barras con su código de Logirest (por ejemplo `EMBC001234`). - Revisa que el proveedor Logirest tenga su CIF y que las unidades de compra (caja, pack…) tengan bien su factor de conversión. > [!WARNING] Copia los informes tal cual los descargas. Un informe personalizado mal formado puede impedir que arranque el servicio de Ágora del cliente. ### En Connect Manager - En [app.connectmanager.es](https://app.connectmanager.es/), ve a **Administración → Locales**, abre el local y revisa URL de API y API key. - En **Integraciones de pedidos**, FOS crea la integración con el proveedor **Logirest**. Ábrela por la pestaña **Configuración**. - Rellena Usuario, Password y URL (S)FTP: solo el nombre del servidor, sin `sftp://`. - En CIFs de proveedores, añade el CIF (o su principio) de cada proveedor cuyos pedidos van a Logirest. Sin ningún CIF no se envía nada. - Deja sin marcar Los pedidos son para QBS (esa casilla convierte la integración en la de [QBS](https://connectmanager.es/docs/integracion-qbs-agora)). - Prefijo de cliente: se antepone al código del almacén en el fichero (si el código ya empieza por él, no se repite). Vacío equivale a `EMB`. - Prefijo de código de barras: uno o varios prefijos; de cada artículo se toma el primer código de barras que empieza por uno de ellos. Vacío equivale a `EMBC`. - Email de receptor de notificaciones: uno o varios correos. Reciben la copia de cada pedido, el aviso de códigos de barras y los errores; si lo dejas vacío, la copia llega solo a FOS. - En **Configuración de subida de ficheros**: Método de subida de ficheros (FTP o SFTP), Root (carpeta de destino), Puerto, Timeout y, para FTP, Pasivo y SSL. - Pulsa **Guardar**. - Pestaña **Almacenes**: añade cada almacén de Ágora que recibe pedidos con su Código de almacén (el código de cliente que da Logirest). Un almacén sin configurar sale en el fichero con su nombre de Ágora. ## Cómo funciona Cada dos horas Connect Manager pide a Ágora los pedidos de compra del día, se queda con los confirmados de los proveedores configurados y registra los que no conocía. Después lanza los informes personalizados para saber el factor de cada unidad de compra y el código de barras de cada artículo, genera el fichero de cada pedido nuevo, lo sube al servidor de Logirest y envía la copia por correo. Una pasada de madrugada repite la lectura con los pedidos del día anterior. ```mermaid sequenceDiagram participant CM as Connect Manager participant AG as API de Ágora participant LG as SFTP de Logirest participant M as Correo loop Cada dos horas CM->>AG: Pedidos de compra del día AG-->>CM: Pedidos CM->>CM: Confirmados y de los CIF configurados CM->>AG: Informes de unidades y de códigos de barras AG-->>CM: Factores y códigos CM->>CM: Fichero Edi de cada pedido nuevo CM->>LG: Sube el fichero CM->>M: Copia del pedido con el fichero end ``` ### El fichero Un fichero por pedido, en UTF-8 con BOM, una línea por artículo y campos separados por `|`. El nombre es el código de cliente, el número de pedido y la fecha y hora: `EMBMAD01-PC-000123-20261003101500.Edi`. | Campo | Contenido | | 1 | LOGIREST | | 2 | Vacío | | 3 | Número de pedido: serie y número con seis cifras (PC-000123) | | 4 y 5 | Fecha del pedido (AAAAMMDD) y hora en que Connect Manager lo registró | | 6 | Código de cliente: prefijo + código del almacén | | 7 | Número de línea | | 8 | Código de artículo (el código de barras con prefijo válido) | | 9 | Fecha de entrega (AAAAMMDD): la del pedido o hoy más tres días | | 10 | Cantidad pedida | | 11 | Unidades por caja (factor de la unidad de compra) | | 12 | Precio | | 13 | Descuento en importe de la línea | | 14 | NA | | 15 y 16 | Nombre del artículo y unidad de compra | | 17 | Cantidad en unidades (cantidad por factor) | ### Estados, reintentos y reenvío - Cada pedido aparece en **Pedidos → Historial de pedidos** como Creado, Enviado o Error, con su fecha, local, serie y número de Ágora. - Si la subida falla, el pedido queda en Error con el motivo y se reintenta solo en las pasadas siguientes (hasta cuatro veces con la configuración por defecto). Llega un aviso «Error en aplicación» con el mensaje. - Para reenviar, selecciona hasta diez pedidos en el historial y pulsa **Exportar**. Los que están en Creado o Error se generan y se suben; los que ya están en Enviado se regeneran y se envían por correo, pero no se vuelven a subir. - Si ninguna línea del pedido tiene código válido, no se genera fichero, el pedido queda como Enviado y llega el aviso de códigos de barras. ## Comprobar que funciona - En Ágora, crea un pedido de compra al proveedor Logirest con dos artículos con código de Logirest y confírmalo. - Espera a la siguiente pasada (como mucho dos horas). - En **Pedidos → Historial de pedidos**, el pedido debe aparecer como Enviado. - Comprueba que ha llegado el correo «Pedido Logirest» con el fichero y que el fichero está en la carpeta del servidor. - Abre el fichero: código de cliente con prefijo, códigos de artículo, cantidades y fecha de entrega deben ser los esperados. - Pide a Logirest que confirme que lo ha procesado. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | No aparece ningún pedido en el historial | Pedido sin confirmar, CIF del proveedor no configurado o sin CIF en Ágora, o sin conexión con la API de Ágora. | Confirma el pedido, revisa el CIF en Ágora y en CIFs de proveedores, y la URL y la API key del local. | | Correo «Error en códigos de barras de productos» con la lista de artículos | Esos artículos no tienen un código de barras que empiece por un prefijo configurado. | Añade el código de Logirest como código de barras y reenvía el pedido desde el historial. | | Todos los artículos aparecen en el aviso de códigos de barras | El informe Product_Barcodes.xml no está instalado o los prefijos no coinciden. | Instala el informe y revisa Prefijo de código de barras. | | Pedido en Error con «No se ha podido realizar la subida del fichero …» u otro error de conexión | Host con sftp://, puerto, carpeta, usuario o contraseña incorrectos, o IP no autorizada. | Corrige la configuración de subida y pulsa Exportar en el historial. | | Unidades por caja siempre a 1 | Falta el informe Units_Of_Measurement.xml o la unidad de compra no tiene factor. | Instala el informe y revisa las unidades de compra en Ágora. | | En el fichero sale el nombre del almacén en lugar del código | El almacén no está en la pestaña Almacenes. | Añádelo con su Código de almacén. | | «No se pueden exportar más de 10 pedidos a la vez» | Selección de más de diez pedidos. | Reenvía en tandas de diez. | | Un pedido modificado en Ágora no se reenvía | Cada pedido se lee una sola vez. | Avisa a Logirest del cambio o crea un pedido nuevo. | | Un pedido confirmado días después de su fecha no se envía | Cada pasada lee los pedidos del día en curso y, de madrugada, los del anterior. | Confirma los pedidos el mismo día que los creas o avisa a FOS para que relea esa fecha. | ## Preguntas frecuentes ### ¿Cómo envío los pedidos de compra de Ágora a Logirest? Con la integración Logirest de Connect Manager: configuras el servidor de Logirest, los CIF de proveedor, los códigos de almacén y los prefijos, instalas dos informes en Ágora y, desde entonces, cada pedido confirmado sale solo en las dos horas siguientes. ### ¿Cada cuánto se envían los pedidos? Connect Manager revisa Ágora cada dos horas y, una vez más de madrugada, repasa los pedidos del día anterior. ### ¿Qué pasa con un artículo sin código de Logirest? Se quita del pedido y llega un correo con la lista de artículos sin código válido. Añade el código como código de barras en Ágora y reenvía el pedido desde el historial. ### ¿Puedo reenviar un pedido a Logirest? Sí, desde Pedidos → Historial de pedidos con Exportar. Si el pedido ya estaba enviado, se regenera y se manda por correo, pero no se vuelve a subir al servidor. ### ¿Es la misma integración que QBS? Sí, con la casilla Los pedidos son para QBS marcada cambia el formato y el nombre del fichero. Si el cliente trabaja con un obrador QBS, sigue el [manual de QBS](https://connectmanager.es/docs/integracion-qbs-agora). ## Referencias - Ficha de la integración en el catálogo: [Logirest](https://connectmanager.es/integraciones/logirest). - [Integración de QBS con Ágora](https://connectmanager.es/docs/integracion-qbs-agora), el mismo envío de pedidos con el formato de QBS. - [Direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager). --- # Integración de Prologic con Ágora: envío de facturas al ERP Portal: General · ERP y contabilidad URL: https://connectmanager.es/docs/integracion-prologic-agora Actualizado: 2026-10-03 La integración de **Prologic** con **Ágora** envía al ERP Prologic, por su API, las ventas del TPV: una factura resumen por local y serie con los tickets del día, y una a una las facturas con cliente y los abonos. También permite cargar en Ágora los maestros de Prologic (tarifas, familias, artículos y clientes). No es una integración de hotel (PMS): es un envío de facturas a un ERP, y este manual cuenta qué hay que configurar en cada cliente. > [!WARNING] Esta integración se hizo para un cliente concreto y lleva valores suyos en el código: la empresa de Prologic va fija como `01` y el año de las facturas resumen va fijo como `2026`. Además, el envío no está programado: lo lanza FOS por fecha. Antes de ofrecerla a otro cliente, FOS tiene que adaptarla. ## Qué hace la integración - Lee de la API de Ágora las facturas de un día: tickets, facturas con cliente y sus devoluciones. - Crea en Prologic una **factura resumen** por local y serie con los tickets del día. Sus líneas son los artículos vendidos, agrupados por formato de venta y descuento, con la cantidad total y el precio unitario neto (sin IVA y con los descuentos aplicados). - Envía una a una las **facturas con cliente**, los **abonos de factura** y las **devoluciones de tickets**. Cada abono lleva el año, la serie y el número que Prologic dio a la factura original, también cuando el ticket devuelto iba dentro de una factura resumen. - Usa la serie de Prologic que configures por local y tipo de documento. - Guarda la serie y el número que devuelve Prologic, y en cada ejecución vuelve a intentar lo pendiente y lo que dio error. - Si se vuelve a lanzar el mismo día, solo crea un resumen nuevo con los tickets que no estaban en el anterior. - Avisa por correo y por Telegram (a FOS) de las facturas que Prologic rechaza. - Carga en Ágora, desde Prologic, tarifas, familias, artículos y clientes. Esta carga la lanza FOS y su progreso se ve en **Migraciones → Migraciones Prologic**. ### Qué no hace - No se ejecuta sola: no hay tarea programada ni botón en el panel. FOS lanza el envío de la fecha que haga falta. - No envía las formas de pago ni el desglose de IVA: Prologic deduce el IVA de cada artículo. - De cada factura solo toma las líneas del primer documento que contiene; si una factura agrupa varios tickets, el resto de líneas no se envía. - No envía las líneas sin importe ni los componentes de los menús: el importe del menú va en su línea de cabecera. - No tiene pantalla con las facturas enviadas, ni permite configurar correos o Telegram del cliente para los avisos: los avisos llegan a FOS. - No adapta la empresa (`01`) ni el año de las facturas resumen (`2026`), que van fijos en el código. ## Requisitos - Acceso a la **API REST de Prologic** desde internet, con el nombre de la cabecera de autenticación y su token. - Los artículos de Ágora con el PLU igual al código de artículo de Prologic, y los clientes de Ágora con el código contable igual a su código de cliente en Prologic. La carga de maestros desde Prologic los deja así. - Por cada local de Ágora, un cliente de Ágora para las facturas resumen cuyo Id. coincida con el código de ese cliente en Prologic, y las series de Prologic que se van a usar. - La API de Ágora (puerto 8984) accesible desde fuera, directamente o con Zero Connect, y su API key. - Reparto de tareas: FOS da de alta el local y la integración, lanza la carga de maestros y los envíos; el técnico configura los locales y revisa artículos y clientes en Ágora. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Prologic | Prologic o el cliente | https://prologic.ejemplo.es/ (terminada en /) | Sí | | Nombre de la cabecera de autenticación | Prologic | ApiKey | Sí | | Token de la API | Prologic | Cadena larga que entrega Prologic | Sí | | Cliente de Prologic de cada local para las facturas resumen | Contabilidad del cliente | Cliente de Ágora cuyo Id. es 123, el mismo código que en Prologic | Sí | | Serie de Prologic para tickets de cada local | Contabilidad del cliente | 02 | No (si falta, la de Ágora) | | Serie para devoluciones de tickets, facturas y abonos de factura | Contabilidad del cliente | 03, 04, 05 | No (si falta, la de Ágora) | | URL de la API de Ágora y API key | Distribuidor o FOS (datos del local) | https://agora-demo.ejemplo.es:8984 | Sí | ## Configuración paso a paso ### En Prologic - Pide a Prologic el acceso a su API: la dirección base, el nombre de la cabecera con la que espera el token y el token. - Con la contabilidad del cliente, decide qué serie de Prologic recibirá cada tipo de documento de cada local y qué cliente recibirá las facturas resumen de cada local (siempre con centro 0). ### En Connect Manager: la integración - En [app.connectmanager.es](https://app.connectmanager.es/), ve a **Administración → Locales**, abre el local y revisa URL de API y API key. - En **Otras integraciones**, FOS crea la integración con el proveedor **Prologic**. Ábrela. - Rellena Api Key: con el **nombre de la cabecera** de autenticación que usa Prologic, Access Token: con el token y URL Api: con la dirección base terminada en `/` (la integración le añade `api/Ventas/Facturas` sin poner barra). - Pulsa **Guardar**. ### En Connect Manager: los locales - En la pestaña **Locales** de la integración, pulsa **Añadir** por cada local de Ágora que vende. - Elige el Local y, en Cliente, el cliente de Ágora que recibirá las facturas resumen de ese local. Se envía su Id. de Ágora, así que debe coincidir con el código del cliente en Prologic. - Rellena las series de Prologic: Basic invoice serie (facturas resumen de tickets), Basic refund serie (devoluciones de tickets), Standard invoice serie (facturas con cliente) y Standard refund serie (abonos de factura). Las que dejes vacías usan la serie de Ágora. - Guarda cada local. ### En Ágora - Cada artículo vendido necesita su PLU con el código de Prologic; sin PLU, el código de artículo va vacío o con el Id. del formato de venta y Prologic rechazará la factura. - Los clientes de las facturas necesitan el código contable con su código de Prologic. - Si los maestros se cargaron desde Prologic, artículos y clientes ya vienen con esos códigos. ### Carga inicial de maestros (opcional) Si el cliente parte de Prologic, FOS puede cargar en Ágora sus tarifas, familias, artículos y clientes. La carga trae los datos de Prologic y después los da de alta en Ágora por su API de importación. Puedes seguir el avance en **Migraciones → Migraciones Prologic**: la ficha muestra la Importación de Prologic (tarifas, familias, productos y clientes) y la Exportación a Ágora, con su estado. Revisa en Ágora el resultado antes de empezar a vender. ## Cómo funciona FOS lanza el envío de una fecha. Connect Manager pide a Ágora las facturas de ese día, agrupa los tickets de cada local y serie en una factura resumen, prepara las facturas con cliente y los abonos uno a uno, y los guarda como pendientes. Después envía a Prologic todo lo pendiente o en error de esa integración, uno a uno. Si Prologic acepta, guarda la serie y el número que devuelve y lo marca como enviado; si contesta con un mensaje, lo marca en error, guarda el mensaje y avisa. ```mermaid sequenceDiagram participant FOS as FOS participant CM as Connect Manager participant AG as API de Ágora participant PR as API de Prologic FOS->>CM: Lanza el envío de una fecha CM->>AG: Facturas del día AG-->>CM: Tickets, facturas y devoluciones CM->>CM: Factura resumen por local y serie CM->>CM: Facturas y abonos uno a uno CM->>PR: Envía cada documento pendiente o en error PR-->>CM: Serie y número de Prologic o mensaje de error CM->>CM: Enviado o Error con aviso ``` ### Qué tipo de documento llega a Prologic | Documento de Ágora | Cómo se envía | Tipo de factura en Prologic | Cliente | | Tickets del día de un local y serie | Una factura resumen | 3 | El cliente configurado en el local | | Factura con cliente | Una a una, con su número de Ágora | 0 | Código contable del cliente | | Abono de factura | Uno a uno, enlazado con la factura original | 2 | Código contable del cliente | | Devolución de ticket | Una a una, enlazada con la factura (o el resumen) original | 5 | Código contable del cliente de la devolución; si no tiene cliente, va vacío | ### Qué se envía - **Cabecera**: empresa `01`, borrador nuevo, año (fijo `2026` en los resúmenes; el de la fecha en el resto), serie, tipo de factura, fecha de factura y de recepción (el día exportado), cliente con centro 0 (por ejemplo `123(0)`) y observaciones con el primer y el último ticket del resumen o el número de la factura. - **Abonos**: además, el año, la serie y el número de Prologic de la factura original, si ya se envió. - **Líneas**: código de artículo (el PLU), embalaje 1, cantidad y precio unitario neto con tres decimales. ### Reenviar - Cada vez que FOS lanza un envío se reintentan todos los documentos pendientes o en error de esa integración, sean del día que sean. - Lanzar de nuevo una fecha ya enviada no duplica los resúmenes: solo agrupa los tickets que no estaban en ninguno. - Si un documento falló por configuración (cliente, serie o artículo), corrige el dato y pide a FOS que lance un envío. ## Comprobar que funciona - Con un local configurado, haz dos tickets de prueba, una factura a un cliente con código contable y un abono de esa factura. - Pide a FOS que lance el envío de ese día. - En Prologic, comprueba la factura resumen del local con la serie configurada y las observaciones «primer ticket hasta último ticket», la factura con cliente y el abono enlazado con ella. - Revisa que las cantidades y los precios netos de las líneas cuadran con Ágora. - Pide a FOS que confirme que no han llegado avisos de error y que los documentos constan como enviados. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Prologic rechaza con un mensaje como «No se ha podido asignar el valor a la propiedad ClienteYCentro» | El local no tiene cliente configurado, el cliente de la factura no tiene código contable, o el código no existe en Prologic. Las devoluciones de tickets sin cliente también llegan sin él. | Elige en el local el cliente correcto (su Id. de Ágora debe ser el código de Prologic) o rellena el código contable del cliente. Para devoluciones de tickets, asígnales cliente en Ágora o consulta con FOS. | | Rechazo por artículo inexistente | El artículo de Ágora no tiene PLU o su PLU no existe en Prologic. | Corrige el PLU en Ágora y pide un nuevo envío. | | Las facturas llegan con una serie que Prologic no conoce | Falta la serie de Prologic en el local y se está usando la de Ágora. | Rellena las cuatro series en la pestaña Locales. | | Ninguna llamada llega a Prologic | URL Api: sin la barra final, o cabecera o token equivocados. | Revisa que la URL termine en / y que Api Key: contenga el nombre de la cabecera. | | Avisos de «GeneratePrologicInvoices» con un error de Ágora | Connect Manager no llega a la API de Ágora. | Revisa URL de API y API key del local. | | Una factura con varios tickets llega incompleta | Solo se envían las líneas del primer documento de la factura. | Factura los tickets por separado o avisa a FOS. | | A partir de 2027 los resúmenes llegan con el año 2026 | El año de las facturas resumen va fijo en el código. | Avisa a FOS antes de fin de año. | ## Preguntas frecuentes ### ¿Cómo conecto Prologic con Ágora? FOS crea en el local la integración Prologic en Otras integraciones; tú pones la URL, la cabecera y el token de la API de Prologic y configuras en cada local su cliente y sus series. Los envíos los lanza FOS por fecha. ### ¿Prologic es un PMS? No en esta integración: no hay huéspedes ni habitaciones. Es un envío de las facturas del TPV al ERP Prologic, más una carga opcional de maestros. ### ¿Se envían las ventas a Prologic cada noche? No. No hay tarea programada: FOS lanza el envío del día que haga falta, y en cada envío se reintenta lo que quedó pendiente o en error. ### ¿Llegan a Prologic las formas de pago o el IVA? No. Llegan los artículos con su cantidad y su precio neto; el IVA lo calcula Prologic a partir del artículo. ### ¿Puedo cargar en Ágora los artículos y clientes de Prologic? Sí: FOS puede cargar tarifas, familias, artículos y clientes, que quedan en Ágora con el código de Prologic en el PLU y en el código contable. El avance se ve en Migraciones Prologic. ## Referencias - Ficha de la integración en el catálogo: [Prologic](https://connectmanager.es/integraciones/prologic). - [Glosario de Connect Manager](https://connectmanager.es/docs/glosario). --- # Integración de QBS con Ágora: pedidos de compra al obrador Portal: General · ERP y contabilidad URL: https://connectmanager.es/docs/integracion-qbs-agora Actualizado: 2026-10-03 La integración de **QBS** con **Ágora** envía al programa de gestión del obrador QBS los pedidos de compra que los locales confirman en el TPV, en el formato que QBS lee, sin pasarlos a mano. **Connect Manager** revisa Ágora cada dos horas, genera un fichero por pedido y lo deja en el servidor del obrador por SFTP o FTP, con copia por correo. Este manual es para el técnico que la configura en un cliente. > [!NOTE] En Connect Manager, QBS es la misma integración que [Logirest](https://connectmanager.es/docs/integracion-logirest-agora) con la casilla Los pedidos son para QBS marcada: cambian el nombre del fichero, algunos campos y los prefijos por defecto. Todo lo demás funciona igual. ## Qué hace la integración - Cada dos horas lee de la API de Ágora los pedidos de compra del día y, una vez más de madrugada, los del día anterior. - Selecciona los pedidos en estado Confirmado cuyo proveedor tiene un CIF de los configurados (el obrador). - Genera el fichero de cada pedido con el código del local que lo recibe, la fecha de entrega y, por línea, el código de QBS del artículo, la cantidad, las unidades por caja y la cantidad en unidades. - Identifica cada artículo por su código de QBS, guardado como código de barras en Ágora: toma el primero que empieza por uno de los prefijos configurados. - Pone la fecha de entrega del pedido o, si no la tiene, la de dentro de tres días. - Sube el fichero por SFTP o FTP y envía una copia por correo con el fichero adjunto. - Quita del pedido las líneas cuyo artículo no tiene código de QBS y avisa por correo con la lista de productos. - Reintenta solo los pedidos que fallan al subirse y permite reenviar un pedido desde **Pedidos → Historial de pedidos**. ### Qué no hace - No envía pedidos en borrador ni pedidos de proveedores que no estén en la lista de CIF. - No envía líneas de productos sin código de QBS: se quitan del pedido y se avisa. - No vuelve a enviar un pedido que se modifica en Ágora después de enviarse: se lee una sola vez. - No envía precios: en el fichero de QBS van cantidades. - No recibe nada de QBS (confirmaciones, albaranes ni facturas). - No permite SFTP con clave privada desde el panel: Clave privada y Frase de contraseña no se guardan. Usa usuario y contraseña. ## Requisitos - Una cuenta en el servidor **SFTP o FTP** donde QBS recoge los pedidos. Si filtra por IP, autoriza las [direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager). - En Ágora: el obrador como proveedor, con su CIF y su código contable (da nombre al fichero); los almacenes de destino; unidades de compra con su factor; y los artículos con su código de QBS como código de barras. - Los informes personalizados de unidades de medida y de códigos de barras instalados en Ágora. - La API de Ágora (puerto 8984) accesible desde fuera, directamente o con Zero Connect, y su API key. - Reparto de tareas: FOS da de alta el local y la integración; el técnico instala los informes y configura proveedores, almacenes y prefijos; el obrador facilita el servidor y sus códigos. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Servidor de ficheros: método, host, puerto y carpeta | Obrador o su informático de QBS | SFTP, sftp.obrador-ejemplo.es, 22, /pedidos | Sí | | Usuario y contraseña del servidor | Obrador | Usuario de la cuenta de envío | Sí | | CIF del obrador | Cliente | B12345678 (vale el principio del CIF) | Sí | | Código contable del obrador en Ágora | Obrador | OBR01 | Sí | | Código de cada local de destino (almacén de Ágora) en QBS | Obrador | 0012 | Sí | | Prefijos de los códigos de QBS | Obrador | C, P y Z (valor por defecto) | No | | Código de QBS de cada artículo | Obrador, guardado en Ágora como código de barras | P00123 | Sí | | Correos para la copia de pedidos y los avisos | Cliente | compras@ejemplo.es | Recomendado | | URL de la API de Ágora y API key | Distribuidor o FOS (datos del local) | https://agora-demo.ejemplo.es:8984 | Sí | ## Configuración paso a paso ### Con el obrador - Pide la cuenta del servidor de ficheros y la carpeta de pedidos. - Pide el código de cada local de destino y los códigos de QBS de los artículos, con los prefijos que usan. ### En Ágora - Descarga desde la integración en Connect Manager (tarjeta **Informes personalizados**) el Informe de unidades de medida (`Units_Of_Measurement.xml`) y el Informe de códigos de barras de productos (`Product_Barcodes.xml`). - Cópialos en la carpeta `custom-queries` del servidor de Ágora (en el ACMS si lo hay), por ejemplo `C:\Program Files (x86)\IGT Microelectronics\Agora\custom-queries`. - Añade a cada artículo que se pide al obrador un código de barras con su código de QBS. - En la ficha del proveedor (el obrador), revisa el CIF y rellena el código contable: con él empieza el nombre de cada fichero. - Revisa el factor de conversión de las unidades de compra. > [!WARNING] Copia los informes tal cual los descargas. Un informe personalizado mal formado puede impedir que arranque el servicio de Ágora del cliente. ### En Connect Manager - En [app.connectmanager.es](https://app.connectmanager.es/), ve a **Administración → Locales**, abre el local y revisa URL de API y API key. - En **Integraciones de pedidos**, FOS crea la integración con el proveedor **Logirest**. Ábrela por la pestaña **Configuración**. - Marca Los pedidos son para QBS. - Rellena Usuario, Password y URL (S)FTP (solo el nombre del servidor, sin `sftp://`). - En CIFs de proveedores, añade el CIF del obrador (o su principio). Sin ningún CIF no se envía nada. - Prefijo de código de barras: los prefijos de los códigos de QBS. Vacío equivale a `C`, `P` y `Z`. El Prefijo de cliente no se usa en QBS. - Email de receptor de notificaciones: reciben la copia de cada pedido, el aviso de códigos y los errores; vacío, la copia llega solo a FOS. - En **Configuración de subida de ficheros**: Método de subida de ficheros (FTP o SFTP), Root, Puerto, Timeout y, para FTP, Pasivo y SSL. Pulsa **Guardar**. - Pestaña **Almacenes**: añade cada almacén de Ágora que recibe pedidos del obrador con su Código de almacén en QBS. Un almacén sin configurar sale con su nombre de Ágora. ## Cómo funciona Cada dos horas Connect Manager pide a Ágora los pedidos de compra del día, se queda con los confirmados al obrador y registra los nuevos. Lanza los informes personalizados para obtener el factor de cada unidad de compra y el código de QBS de cada artículo, genera el fichero del pedido, lo sube al servidor y envía la copia «Pedido QBS» por correo. De madrugada repasa los pedidos del día anterior. ```mermaid sequenceDiagram participant CM as Connect Manager participant AG as API de Ágora participant QB as SFTP del obrador participant M as Correo loop Cada dos horas CM->>AG: Pedidos de compra del día AG-->>CM: Pedidos CM->>CM: Confirmados al CIF del obrador CM->>AG: Informes de unidades y de códigos AG-->>CM: Factores y códigos de QBS CM->>CM: Fichero de cada pedido nuevo CM->>QB: Sube el fichero CM->>M: Copia Pedido QBS con el fichero end ``` ### El fichero Un fichero por pedido, en UTF-8 con BOM, una línea por artículo y campos separados por `|`. El nombre es el código contable del obrador, el número de pedido y la fecha y hora: `OBR01-PC-000123-20261003101500.Edi`. | Campo | Contenido | | 1 | QBS | | 2 | Vacío | | 3 | Número de pedido: serie y número con seis cifras (PC-000123) | | 4 y 5 | Fecha del pedido (AAAAMMDD) y hora en que Connect Manager lo registró | | 6 | Código del local de destino (código del almacén, sin prefijo) | | 7 | Número de línea | | 8 | Código de QBS del artículo | | 9 | Fecha de entrega (AAAAMMDD): la del pedido o hoy más tres días | | 10 | Cantidad pedida | | 11 | Unidades por caja (factor de la unidad de compra) | | 12 | Cantidad en unidades (cantidad por factor) | | 13 | Descuento en importe de la línea | | 14 | NA | | 15 y 16 | Nombre del artículo y unidad de compra | | 17 | 0.00 (peso, no se usa) | ### Estados, reintentos y reenvío - Cada pedido aparece en **Pedidos → Historial de pedidos** como Creado, Enviado o Error. - Si la subida falla, queda en Error con el motivo, llega un aviso «Error en aplicación» y se reintenta solo en las pasadas siguientes (hasta cuatro veces con la configuración por defecto). - Para reenviar, selecciona hasta diez pedidos y pulsa **Exportar**: los que están en Creado o Error se suben; los Enviado se regeneran y se mandan por correo, sin volver a subirse. - Si ninguna línea tiene código de QBS, no se genera fichero, el pedido queda como Enviado y llega el aviso de códigos. ## Comprobar que funciona - En Ágora, crea un pedido de compra al obrador con dos artículos con código de QBS y confírmalo. - Espera a la siguiente pasada (como mucho dos horas). - En **Pedidos → Historial de pedidos** debe aparecer como Enviado. - Comprueba el correo «Pedido QBS» con el fichero y que el fichero está en la carpeta del servidor, con el código contable del obrador al principio del nombre. - Abre el fichero y revisa el código del local, los códigos de QBS, las cantidades y la fecha de entrega. - Pide al obrador que confirme que QBS lo ha importado. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | No aparece ningún pedido en el historial | Pedido sin confirmar, CIF del obrador no configurado, o sin conexión con la API de Ágora. | Confirma el pedido, revisa CIFs de proveedores y la URL y la API key del local. | | Correo «Error en códigos de barras de productos» | Esos artículos no tienen un código que empiece por un prefijo de QBS. | Añade su código de QBS como código de barras y reenvía desde el historial. | | Todos los artículos aparecen en el aviso | Falta el informe Product_Barcodes.xml o los prefijos no coinciden. | Instala el informe y revisa Prefijo de código de barras. | | El nombre del fichero no lleva el código del obrador | El proveedor no tiene código contable en Ágora. | Rellena el código contable del obrador. | | Pedido en Error con «No se ha podido realizar la subida del fichero …» u otro error de conexión | Datos de subida incorrectos o IP no autorizada. | Corrige la configuración y pulsa Exportar. | | Unidades por caja siempre a 1 | Falta Units_Of_Measurement.xml o la unidad no tiene factor. | Instala el informe y revisa las unidades de compra. | | El fichero lleva el nombre del almacén en lugar de su código | El almacén no está en la pestaña Almacenes. | Añádelo con su Código de almacén. | | Los ficheros salen con el formato de Logirest | No está marcada Los pedidos son para QBS. | Márcala y guarda; reenvía los pedidos afectados. | ## Preguntas frecuentes ### ¿Cómo envío los pedidos de Ágora al obrador con QBS? Con la integración de pedidos de Connect Manager en modo QBS: configuras el servidor del obrador, su CIF, los códigos de los locales y los prefijos, instalas dos informes en Ágora y cada pedido confirmado al obrador sale solo en las dos horas siguientes. ### ¿Dónde se guarda el código de QBS de cada artículo? Como código de barras del artículo en Ágora, con uno de los prefijos configurados (por defecto C, P o Z). ### ¿Qué pasa si un artículo no tiene código de QBS? Se quita del pedido y llega un correo con la lista de artículos. Añade el código y reenvía el pedido desde el historial. ### ¿Cada cuánto llegan los pedidos al obrador? Connect Manager revisa Ágora cada dos horas y, de madrugada, repasa los pedidos del día anterior. ### ¿En qué se diferencia de Logirest? Es la misma integración: en modo QBS el fichero se nombra con el código contable del obrador, el local va sin prefijo, la columna de precio pasa a ser cantidad en unidades y los prefijos de artículo por defecto son C, P y Z. ## Referencias - Ficha de la integración en el catálogo: [QBS](https://connectmanager.es/integraciones/qbs). - [Integración de Logirest con Ágora](https://connectmanager.es/docs/integracion-logirest-agora). - [Direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager). - Web de QBS: [obradoresqbs.com](https://obradoresqbs.com/). --- # Integración de SAP S/4HANA con Ágora: asientos, facturas y cobros Portal: General · ERP y contabilidad URL: https://connectmanager.es/docs/integracion-sap-s4hana-agora Actualizado: 2026-10-03 La integración de **SAP S/4HANA** con **Ágora** lleva a SAP las ventas que cobra el TPV: los tickets de cada local se contabilizan como un asiento por serie y las facturas con cliente se crean en SAP con su cobro ya compensado, todo a través de **Connect Manager**. Este manual es para el técnico (de FOS o del distribuidor) que la configura junto al consultor SAP del cliente. > [!WARNING] Esta integración se desarrolló para una instalación de SAP concreta y varios datos de organización van fijos en el código (sociedad, cuenta de ingresos, organización de ventas…). Antes de comprometer fechas con un cliente nuevo, revisa con FOS y con su consultor SAP la tabla de valores fijos del apartado Requisitos. ## Qué hace la integración - Lee de la API de Ágora las facturas del día de cada local: tickets (facturas simplificadas), facturas con cliente y sus devoluciones. - Agrupa los tickets por local, tipo de documento y serie, y envía cada grupo a SAP como un **asiento contable**: una línea de ingreso por tipo de IVA, una línea de cobro por cada cuenta de forma de pago y el detalle de impuestos. Las devoluciones de tickets van en su propio asiento. - Crea en SAP cada **factura con cliente** (y cada abono) por separado. Antes busca al cliente por su NIF y, si no existe, lo da de alta como interlocutor comercial con los datos fiscales de la ficha de Ágora. - Registra el **cobro** de cada factura con cliente y lo compensa contra la factura. - Envía solo lo nuevo: si exportas otra vez el mismo día, los tickets que ya se enviaron no se repiten. - Guarda cada envío en **Contabilidad → Facturas SAP S/4HANA**, con sus impuestos, sus cobros y la petición y la respuesta de SAP en cada paso, y permite reenviarlo. - Avisa por correo y por Telegram de los locales, impuestos o formas de pago sin configurar y de los rechazos de SAP. ### Qué no hace - No envía nada automáticamente cada noche en la versión actual del motor: la exportación se lanza desde el panel, por fecha. El campo Hora de generación fich. contable del formulario no programa ningún envío para este proveedor. - No reintenta sola: lo que falla se reenvía a mano desde el listado de facturas. - No envía productos ni familias: a SAP llegan importes por tipo de IVA y por forma de pago. - No adapta los datos de organización de SAP, que van fijos en el código. Un SAP con otra sociedad, otra cuenta de ingresos u otra organización de ventas necesita un desarrollo de FOS. - No trabaja en otra moneda ni en otro país: todo va en euros y con España como país. - No envía los tickets de la serie `T02`: el código la excluye. - La casilla Habilitado de un local no detiene su envío (ver Configuración). - No anula documentos en SAP: una devolución de Ágora se envía como un documento más (abono o asiento de devolución). ## Requisitos - Un sistema **SAP S/4HANA** accesible por HTTPS desde internet y un usuario técnico (usuario y contraseña, autenticación básica) con permiso para estos servicios: - Asientos contables: crear (`journalentrycreaterequestconfi`), modificar (`journalentrybulkchangerequest_`) y compensar (`journalentrybulkclearingreques`). - Solicitud de documento de facturación (`billingdocumentrequest_in`). - Consulta de documentos de facturación (OData `api_billingdocument`). - Interlocutores comerciales (OData `API_BUSINESS_PARTNER`). - En SAP, el campo personalizado de referencia externa en la solicitud de facturación (`YY1_ExternalReference`) y su réplica en la cabecera de la factura (`YY1_ExternalReference_BDH`). Con él localiza Connect Manager la factura que acaba de crear. - La API de Ágora (puerto 8984) accesible desde fuera, directamente o con Zero Connect, con su API key. Si el cliente tiene varios locales en un Ágora central, la del ACMS. - Si SAP filtra por IP, autorizar las [direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager). - Reparto de tareas: FOS da de alta el local y la integración; el técnico completa locales, impuestos y formas de pago con los códigos que le pasa el consultor SAP; el consultor prepara el usuario técnico y los servicios en SAP. Valores fijos en el código (revísalos con el consultor SAP) | Dato de SAP | Valor fijo | Dónde se usa | | Sociedad | 100 | Asientos, facturas, cobros e interlocutores | | Cuenta de ingresos | 700000 | Líneas de ingreso de los asientos de tickets | | Segmento y área funcional | 1000_A y YB10 | Líneas de ingreso | | Organización de ventas, canal y sector | 100, 10 y 00 | Asientos de tickets, facturas e interlocutores | | Centro y grupo de materiales | 100 y L004 | Facturas con cliente | | Clases de documento de ventas | EOX1, EDX1, CIX1 (factura); EOXC, G2N, G2 (abono) | Facturas con cliente | | Condición de precio | PPR0 | Facturas con cliente | | Clases de documento contable | ES (tickets), DZ (cobro), ZV (compensación) | Asientos | | Alta de interlocutor | Agrupación BP02, roles FLCU00, FLCU01 y UDM000, cuenta asociada 430000, condición de pago 0001, tipo de NIF ES1 | Clientes nuevos | | Moneda y país | EUR y ES | Todos los documentos | Los asientos llevan además un usuario creador fijo. Si algo de esta tabla no existe o no es correcto en el SAP del cliente, los envíos fallarán: pásalo a FOS antes de configurar. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Dirección de la API de SAP | Consultor SAP del cliente | https://sap.ejemplo.es (con o sin barra final) | Sí | | Usuario y contraseña del usuario técnico | Consultor SAP del cliente | Usuario de comunicación con los servicios de Requisitos | Sí | | URL de la API de Ágora y API key | Distribuidor o FOS (datos del local) | https://agora-demo.ejemplo.es:8984 | Sí | | Código de cuenta de cada local de Ágora | Contabilidad del cliente o consultor SAP | BAR0001 (código del local en SAP) | Sí, en los locales que envían | | Centro de coste de cada local | Consultor SAP | 1000BAR01 | No (si falta, se usa el código de cuenta) | | Código de impuesto SAP de cada tipo de IVA | Consultor SAP | 05 para el 10 % | Sí | | Material SAP de cada tipo de IVA | Consultor SAP | VENTA10 | Sí | | Nombre SAP de cada tipo de IVA | Consultor SAP | Ingreso al 10% | No | | Cuenta contable de cobro de cada forma de pago | Consultor SAP | 570000 para efectivo | Sí | | Nombre SAP y código de pago de cada forma de pago | Consultor SAP | Efectivo y EF | No | | Correos para los avisos | Cliente | contabilidad@ejemplo.es,it@ejemplo.es | Recomendado | | Id. de chat de Telegram para los avisos | Cliente | -1001234567890 | No | | Visto bueno de los valores fijos | Consultor SAP | Tabla de Requisitos | Sí | ## Configuración paso a paso ### En SAP (consultor del cliente) - Crea el usuario técnico y habilita para él los servicios de la lista de Requisitos. - Comprueba que existe el campo de referencia externa en la solicitud de facturación y en la cabecera de la factura. - Revisa la tabla de valores fijos y confirma que la sociedad, la cuenta de ingresos, la organización de ventas y el resto existen y son los del cliente. - Prepara los códigos de impuesto, un material por tipo de IVA y la cuenta de cobro de cada forma de pago. ### En Connect Manager: el local y la integración - Entra en [app.connectmanager.es](https://app.connectmanager.es/) y ve a **Administración → Locales**. Abre el local. - Revisa URL de API, API key y Zona horaria (con ella se calcula la fecha de los documentos) y pulsa **Guardar**. - En **Integraciones de contabilidad**, FOS crea la integración con el proveedor **SAP HANA (BTP)**. Ábrela por la pestaña **Configuración**. - Rellena Usuario, Password y URL Api (la dirección base de SAP). - En Email de receptor de notificaciones pon uno o varios correos separados por comas, y si el cliente quiere avisos por Telegram, su Id. de chat de Telegram para recibir notificaciones. - Pulsa **Guardar**. El campo Hora de generación fich. contable no tiene efecto en este proveedor: déjalo vacío. ### En Connect Manager: locales, impuestos y formas de pago - Pestaña **Locales**: cada local de Ágora que factura necesita una fila. La primera exportación desde el widget de inicio añade solos todos los locales activos de Ágora; también puedes crearlos con **Añadir**, eligiendo el local en el buscador. En cada fila: - Código de cuenta: código del local en SAP. Sin él, el local no envía. Va en las referencias de los asientos y las facturas. - Cost center: centro de beneficio y de coste de las líneas. Si lo dejas vacío, se usa el código de cuenta. - No enviar excepciones de configuración: márcala solo en los locales que no deben enviar. Así se saltan sin generar avisos; los locales sin código de cuenta y sin esta casilla avisan en cada exportación. - Habilitado: no cambia nada en el envío actual. - Pestaña **Impuestos**: pulsa **Añadir** por cada tipo de IVA que se vende, elige el impuesto de Ágora y rellena Id. de SAP (código de impuesto), Id. material SAP (material con el que se facturan las ventas de ese IVA en las facturas con cliente) y, si quieres, Nombre SAP (texto de asignación; si falta, se usa el código). El impuesto se asocia por porcentaje. - Pestaña **Métodos de pago**: añade cada forma de pago de Ágora con su Id. de SAP (cuenta de cobro). Nombre SAP y Código de pago son opcionales: el código de pago se combina con el código de cuenta del local en la asignación del cobro (si falta, se usa la cuenta). > [!TIP] Si los buscadores de local, impuesto o forma de pago no muestran nada, Connect Manager no llega a la API de Ágora: revisa la URL y la API key del local. ### En Ágora - No hay que instalar informes ni acciones personalizadas: la integración solo lee por la API. - Para las facturas con cliente, la ficha del cliente necesita NIF, nombre fiscal y dirección completa: con esos datos se busca o se crea en SAP. - Los tickets de la serie `T02` no se envían. Si el cliente factura con esa serie, avisa a FOS. ### Lanzar la exportación - Todos los locales a la vez: en **Home**, widget **Exportación SAP S/4HANA**. Elige el Local de Connect Manager y la Fecha y pulsa Click para exportar. Verás «La petición de exportación de facturas se ha enviado.» - Un solo local de Ágora: en la pestaña **Locales** de la integración, botón **Exportar** de su fila. Elige la fecha y confirma; verás «Se ha enviado la solicitud de exportación de facturas». ## Cómo funciona Cuando lanzas una fecha, Connect Manager pide a la API de Ágora las facturas de ese día, local a local. Los tickets se agrupan por local, tipo (venta o devolución) y serie, y cada grupo se convierte en un asiento contable que se envía a SAP. Si SAP devuelve un número de asiento, el grupo queda Enviado; si no, queda en Error de factura con el motivo, y llega un aviso. Las facturas con cliente siguen otro camino, más largo, descrito después. ```mermaid sequenceDiagram participant T as Técnico participant CM as Connect Manager participant AG as API de Ágora participant SAP as SAP S/4HANA T->>CM: Exportar una fecha CM->>AG: Facturas del día de cada local AG-->>CM: Tickets, facturas y devoluciones CM->>CM: Agrupa los tickets por local, tipo y serie CM->>SAP: Asiento contable de cada grupo SAP-->>CM: Número de asiento o error CM->>CM: Estado Enviado o Error de factura ``` ### Qué se envía en el asiento de tickets - **Cabecera**: fecha del día exportado, referencia `FRS_` seguida del código de cuenta del local, y texto con el primer y el último ticket del grupo (serie y número con seis cifras, por ejemplo `T1000123-T1000187`). - **Ingresos**: una línea por tipo de IVA en la cuenta de ingresos fija, con la base imponible, el código de impuesto, el nombre SAP del IVA como asignación y el centro de coste del local. La base se calcula a partir del total con IVA de cada tipo. - **Cobros**: una línea por cuenta de cobro (las formas de pago con la misma cuenta se suman), con el código de cuenta del local y el código de pago como asignación. El importe de la forma de pago con Id. 16 de Ágora («resto sin devolución») se suma a la otra forma de pago del mismo ticket. - **Impuestos**: una línea por tipo de IVA con la cuota y la base. ### Facturas con cliente Cada factura con cliente y cada abono se envían uno a uno y en varios pasos. Primero se busca al cliente en SAP por su NIF y, si no existe, se crea. Después se pide a SAP el documento de facturación, con una posición por tipo de IVA (el material SAP de ese IVA y el importe con IVA) y la referencia externa `FRA-` + código de cuenta + año + serie + número. A los cinco segundos se consulta en SAP la factura por esa referencia para obtener su asiento, se escribe la referencia en el asiento, se crea el asiento de cobro con las cuentas de las formas de pago y, por último, se compensan factura y cobro. ```mermaid sequenceDiagram participant CM as Connect Manager participant SAP as SAP S/4HANA CM->>SAP: Busca el cliente por NIF alt No existe CM->>SAP: Crea el interlocutor comercial end CM->>SAP: Solicitud de factura con una posición por IVA CM->>SAP: Consulta la factura por su referencia externa SAP-->>CM: Número de factura y de asiento CM->>SAP: Escribe la referencia en el asiento CM->>SAP: Asiento de cobro por forma de pago CM->>SAP: Compensa la factura con el cobro ``` Cada paso deja su estado: Facturado, Asiento contable encontrado, Factura asignada, Factura pagada y, al final, Enviado. Si un paso falla, la factura se queda en ese punto (Error de factura, Asiento contable no encontrado, Error de asignación de factura, Error de pago…) y al reenviarla continúa desde ahí, sin repetir lo que ya está hecho. ### El listado de envíos En **Contabilidad → Facturas SAP S/4HANA** ves cada grupo de tickets y cada factura con su local, tipo de documento (Ticket, Devolución, Factura, Devolución de fact.), serie, números inicial y final y estado. Puedes filtrar por Código de local, Estado, serie y fechas. Al abrir uno, la ficha muestra los identificadores de SAP (cliente, factura, asiento y asiento de cobro), los pasos 1 a 5 con la petición, la respuesta y el error de cada uno, y las pestañas de impuestos y de pagos. ### Reenviar un día o un documento - **Volver a exportar la fecha** (widget o botón del local): solo envía los tickets posteriores al último ya enviado de cada serie, y retoma las facturas con cliente que no llegaron a Enviado. Puedes exportar el día en curso y repetir más tarde para mandar el resto. - **Exportar** en el listado: selecciona uno o varios envíos y pulsa **Exportar**. Se vuelven a leer de Ágora con la configuración actual (útil después de corregir un impuesto o una forma de pago) y se reenvían si SAP no los tenía. - **Resetear**: borra los identificadores y estados de SAP de los envíos seleccionados y los manda desde cero. Úsalo solo si has comprobado en SAP que el documento no existe. > [!WARNING] Resetear un documento que ya está en SAP, o reintentar uno que dio tiempo agotado sin comprobarlo, crea un duplicado en SAP. Revisa siempre antes en SAP la referencia `FRS_…` o `FRA-…`. ### Avisos Cualquier error de una exportación (local, impuesto o forma de pago sin configurar, Ágora sin respuesta, rechazo de SAP) genera un correo «Error en aplicación» con el local, la fecha y el mensaje, que llega a FOS y a los correos configurados, y el mismo aviso por Telegram si hay chat configurado. Una asociación que falta (un local, un tipo de IVA o una forma de pago) detiene la exportación de ese local para ese día: lo que quedaba por preparar no se envía hasta que la completes y vuelvas a exportar la fecha. ## Comprobar que funciona - En un local configurado, haz un ticket de prueba y una factura a un cliente de prueba con NIF y dirección. - Lanza la exportación de ese día con el botón **Exportar** del local. - Abre **Contabilidad → Facturas SAP S/4HANA** y filtra por la fecha. El grupo de tickets debe estar en Enviado con su ID de asiento contable SAP; la factura, en Enviado con ID de cliente SAP, ID de factura SAP y los dos asientos. - En SAP, busca el asiento con la referencia `FRS_` del local y la factura con la referencia `FRA-`; comprueba el interlocutor creado y que el cobro está compensado. - Vuelve a exportar la misma fecha: no debe aparecer nada nuevo ni duplicarse nada en SAP. - Repite con el widget **Exportación SAP S/4HANA** para un día completo y revisa que los demás locales salen en Enviado y que los que no deben enviar no generan avisos. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Aviso «El local con id. 3 (Terraza) no está configurado. Configúrelo para poder enviar la facturación.» | Un local de Ágora sin Código de cuenta. | Rellena el código de cuenta o, si ese local no debe enviar, marca No enviar excepciones de configuración. | | Aviso «El método de pago con id. 5 (…) no está configurado. Configúrelo para poder enviar la facturación.» | Forma de pago de Ágora sin Id. de SAP. | Añádela en Métodos de pago y reenvía con Exportar. | | Aviso «El impuesto 10% no está configurado. Configúrelo para poder enviar la facturación.» | Tipo de IVA sin Id. de SAP o sin Id. material SAP. | Complétalo en Impuestos y reenvía. | | Los buscadores de local, impuesto o forma de pago no cargan | Sin conexión con la API de Ágora. | Revisa URL de API y API key del local y que el puerto 8984 sea accesible. | | «La URL de SAP es obligatoria.» o «El usuario y la password de SAP son obligatorios.» | Pestaña Configuración incompleta. | Completa URL Api, Usuario y Password y guarda. | | Envío en Error de factura, a veces con «No se encontró el elemento JournalEntryBulkCreateConfirmation» | SAP rechazó el documento: cuenta, código de impuesto o centro de coste inexistentes, periodo cerrado, permisos… | Abre el envío y lee Error de respuesta de factura del paso 1. Corrige en SAP o en la asociación y pulsa Exportar. | | «La respuesta de SAP para creación de cliente no tiene el formato esperado.» o «Error (código) : mensaje» | SAP no aceptó el alta del interlocutor (NIF, dirección, país…). | Corrige la ficha del cliente en Ágora, o crea el cliente en SAP con ese NIF, y reenvía. | | «No se ha podido obtener un token de autenticación.» | La búsqueda de clientes no devolvió el token de seguridad de SAP. | Revisa que el usuario técnico tenga acceso al servicio de interlocutores comerciales. | | Factura en Asiento contable no encontrado: «No se han encontrado facturas para la referencia externa FRA-…» | SAP aún no había generado el asiento a los cinco segundos, o falta el campo de referencia externa. | Espera unos minutos y pulsa Exportar. Si se repite, revisa el campo YY1_ExternalReference con el consultor. | | Tras exportar desde el widget llega un aviso con «Call to a member function delete() on null» y no se envía nada | Ágora tiene un local dado de baja que nunca llegó a la lista de Locales de la integración. | Exporta local a local con el botón Exportar de cada fila y avisa a FOS. | | «No tienes esta integración contratada. Por favor, contacta con soporte@fos.systems.» | El local elegido en el widget no tiene la integración SAP HANA (BTP). | Elige el local de Connect Manager donde está configurada. | | Faltan tickets de un día en SAP | Son de la serie T02, el local tiene marcada No enviar excepciones de configuración o el grupo quedó en error. | Revisa el listado filtrando por local y estado y reenvía lo que esté en error. | | Documentos duplicados en SAP | Se usó Resetear sobre algo que ya estaba en SAP, o se reintentó tras un tiempo agotado. | Anula el duplicado en SAP y, en adelante, comprueba la referencia antes de resetear. | ## Preguntas frecuentes ### ¿Cómo conecto SAP S/4HANA con Ágora? Con Connect Manager: FOS crea en el local la integración de contabilidad SAP HANA (BTP); tú pones la dirección y el usuario técnico de SAP y asocias locales, tipos de IVA y formas de pago a sus códigos de SAP. Después lanzas la exportación por fecha desde el panel. ### ¿La contabilidad se envía sola a SAP cada noche? No en la versión actual del motor. La exportación se lanza desde el widget Exportación SAP S/4HANA de Home o desde el botón Exportar de cada local, eligiendo la fecha. ### ¿Qué pasa si el cliente de una factura no existe en SAP? Connect Manager lo busca por NIF y, si no lo encuentra, lo crea como interlocutor comercial con el nombre fiscal, la dirección y el NIF de la ficha de Ágora. Si SAP rechaza el alta, la factura se queda en error con el mensaje de SAP. ### ¿Puedo volver a enviar un día sin duplicar? Sí: volver a exportar la misma fecha solo envía lo que falta, y el botón Exportar del listado reenvía únicamente lo que SAP no tiene. Lo único que puede duplicar es Resetear algo que ya estaba en SAP. ### ¿Sirve para cualquier SAP S/4HANA? No tal cual: la sociedad, la cuenta de ingresos, la organización de ventas y otros datos van fijos en el código. Si el SAP del cliente usa otros valores, FOS tiene que adaptar la integración antes de ponerla en marcha. ## Referencias - Ficha de la integración en el catálogo: [SAP S/4HANA](https://connectmanager.es/integraciones/sap-s4hana). - [Direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager), para autorizar el acceso a SAP. - [Glosario de Connect Manager](https://connectmanager.es/docs/glosario). - Documentación oficial de las API de SAP: [SAP Business Accelerator Hub](https://api.sap.com/). --- # Integración de Workday con Ágora: ficheros de facturas y compras Portal: General · ERP y contabilidad URL: https://connectmanager.es/docs/integracion-workday-agora Actualizado: 2026-10-03 La integración de **Workday** con **Ágora** genera cada noche, desde **Connect Manager**, los ficheros de carga de Workday con las ventas del día anterior (facturas y abonos), y prepara también los pedidos de compra y los albaranes de entrada, con un circuito de aprobación de pedidos por importe. El intercambio es por ficheros: se suben por SFTP o FTP y se envían por correo. Este manual es para el técnico que la configura junto al equipo de Workday del cliente. > [!WARNING] La integración se construyó para un cliente con teatros y eventos, y varias reglas de ese cliente van fijas en el código (códigos de cliente y proveedor por defecto, reglas para unos clientes concretos, calendario de subida de fin de semana). Antes de ofrecerla a otro cliente, FOS tiene que revisar esas reglas con él. ## Qué hace la integración - Cada noche, a la hora configurada, lee de la API de Ágora las facturas del día anterior y las convierte en **facturas de cliente de Workday**, con numeración propia correlativa. - Asigna a cada línea compañía, moneda, cliente, condiciones de pago, tipo de factura, categoría de ingreso, aplicabilidad e IVA, centro de coste, split, proyecto, teatro y producción, a partir de lo configurado en locales, teatros, familias e impuestos. - Distingue las ventas hechas durante un **evento** (una franja horaria configurada por teatro): esas líneas usan los valores «para eventos» de la familia y llevan el nombre del evento como proyecto. - Agrupa los tickets en facturas de Workday por teatro, tipo de sesión y serie, de hasta 1.500 € cada una (valor por defecto), y abre una factura nueva cuando cambia el cliente. - Envía importes netos, sin IVA y con los descuentos repartidos; en el memo pone el rango de tickets, lo cobrado por forma de pago y las devoluciones con su ticket original. - Separa los abonos en su propio fichero. - Sube el CSV de facturas por SFTP o FTP y envía por correo el CSV y una versión en Excel. - Lee cada noche los **pedidos de compra** y los **albaranes de entrada** del día anterior. Los pedidos pasan por aprobación por niveles de importe en Connect Manager, con aviso por correo a los aprobadores. - Cada lunes y cada día 1 envía por correo el Excel de pedidos de compra y el de albaranes del periodo. - Permite generar por fechas, desde Home, los ficheros de facturas, devoluciones, pedidos y entregas, y consultar exportaciones y pedidos en el menú **Workday**. ### Qué no hace - No conecta con Workday por API: solo genera ficheros. - No sube por SFTP o FTP los ficheros de pedidos ni de albaranes: solo van por correo. - No sube el fichero de abonos: ese paso falla en el código y, cuando hay método de subida configurado, el fichero de abonos tampoco sale por correo. Los abonos se obtienen con el widget Devoluciones entre fechas (Workday). - La aprobación de pedidos no cambia nada en Ágora ni decide qué pedidos van al fichero semanal: el Excel incluye todos los pedidos del periodo. - No permite SFTP con clave privada desde el panel: Clave privada y Frase de contraseña aparecen en el formulario pero no se guardan. Usa usuario y contraseña. - No vuelve a leer de Ágora un día que ya se generó bien, ni regenera un día si ya hay días posteriores generados (para no romper la numeración): eso lo hace FOS. - No tiene pantalla para las equivalencias de clientes y proveedores de Workday: FOS las carga en el motor. ## Requisitos - Un tenant de **Workday** con las cargas de facturas de cliente preparadas para leer el fichero (columnas en Cómo funciona) y los identificadores de compañía, clientes, centros de coste, categorías, proyectos, teatros, producciones y códigos de impuesto. - Un servidor SFTP o FTP del cliente donde dejar los ficheros, con usuario y contraseña. Si filtra por IP, autoriza las [direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager). - La API de Ágora (puerto 8984) accesible desde fuera, directamente o con Zero Connect. Si hay varios locales en un Ágora central, la URL y la API key del ACMS. - En Ágora, todas las familias que se venden asociadas en la integración y todos los locales con ventas incluidos en algún teatro; para compras, los almacenes que reciben pedidos configurados. - Reparto de tareas: FOS da de alta el local y la integración, carga las equivalencias de clientes y proveedores y es quien puede lanzar desde Home Generar contabilidad Workday y Generar compras Workday; el técnico completa la configuración con los códigos que da el equipo de Workday del cliente. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Compañía, moneda, condiciones de pago, deferred revenue, tipo de factura y descripción de línea | Equipo de Workday del cliente | COMP-01, EUR, Immediate, No, POS, Venta TPV | Sí | | Códigos de cliente de cada local: general, pago en efectivo y pago con tarjeta | Equipo de Workday | CUST-0001 | Recomendado | | Teatros: nombre, locales que incluye y sus Split, Project, Theater y Production | Equipo de Workday y controller | Teatro Centro, TH01 | Sí | | Eventos: teatro, nombre, inicio y fin | Cliente | Gala benéfica, 03/10 19:00–23:30 | No | | Por familia: Split, Cost center, Revenue category, Tax applicability, sus variantes para eventos, Spend category y Cost object | Equipo de Workday | CC-BAR, Food_Beverage | Sí (las cuatro primeras) | | Tax code de cada tipo de IVA de Ágora | Equipo de Workday | ES_IVA_10 | Sí (si falta, la columna va vacía) | | Por almacén: Buyer id., Bill to contact, Ship to contact, Production purpose, moneda, Project, Theater y Production | Equipo de Workday | BUYER-01 | Sí, si se usan compras | | Niveles de aprobación de pedidos: importes y usuarios | Cliente | 0–500 € un responsable; desde 500 € dirección | No | | Servidor de ficheros: método, host, puerto, carpeta, usuario, contraseña | IT del cliente | SFTP, sftp.ejemplo.es, 22, /entrada/ventas | Sí, para subir el CSV | | Correos y chat de Telegram para ficheros y avisos | Cliente | finanzas@ejemplo.es | Recomendado | | Equivalencias de clientes y proveedores de Workday | Cliente, a FOS | Nombre fiscal o código de Ágora y su Id. en Workday | Según el caso | ## Configuración paso a paso ### En Workday (equipo del cliente) - Prepara la carga de facturas de cliente que leerá los ficheros `…-CI-workday_invoices.csv` (facturas) y `…-CN-workday_invoices.csv` (abonos) desde la carpeta del servidor de ficheros. - Pasa al técnico los identificadores de la tabla anterior, con los mismos códigos que existen en Workday. ### En Connect Manager: la integración - En [app.connectmanager.es](https://app.connectmanager.es/), ve a **Administración → Locales**, abre el local y revisa URL de API y API key. - En **Integraciones de contabilidad**, FOS crea la integración con el proveedor **Workday**. Ábrela por la pestaña **Configuración**. - Rellena Compañía, Código de moneda, Payment terms, Deferred revenue, Customer invoice type y Line item description. Cliente para tickets es obligatorio en el formulario, pero no se usa: el cliente de cada factura sale de los códigos de los locales y de las equivalencias. - Email de receptor de notificaciones (varios separados por comas) e Id. de chat de Telegram para recibir notificaciones: ahí llegan los ficheros y los avisos de error. Si los dejas vacíos, solo llegan a FOS. - Hora de generación fich. contable: hora de la pasada nocturna, entre 1:00 y 7:00 en tramos de 10 minutos. Recomendado: entre las 3:00 y las 7:00. - En **Configuración de subida de ficheros**: Método de subida de ficheros (FTP o SFTP; con «-» no se sube nada y solo se envía por correo), Usuario y Password, URL (S)FTP (solo el nombre del servidor, sin `sftp://`), Root (carpeta de destino), Puerto y Timeout en segundos; para FTP, Pasivo y SSL según el servidor. - Pulsa **Guardar**. ### En Connect Manager: locales, teatros y eventos - Pestaña **Teatros**: crea un teatro por cada unidad que Workday contabiliza aparte. Pon Nombre, elige en Locales los locales de Ágora que le pertenecen y rellena Split, Project, Theater y Production. Las ventas se agrupan por el valor de Theater. Todo local con ventas debe estar en algún teatro. - Pestaña **Locales**: añade cada local de Ágora con sus tres códigos de cliente: Cód. de cliente, Código de cliente pago en Efectivo y Código de cliente pago en Tarjeta. El formulario pide también Split, Project y Theater; para las facturas mandan los del teatro. - Pestaña **Eventos** (opcional): para cada evento, Nombre, el teatro en Theater y Fecha de inicio, Hora de inicio, Fecha de fin y Hora de fin. Los tickets de ese teatro hechos dentro de la franja se tratan como venta de evento. ### En Connect Manager: familias e impuestos - Pestaña **Familias**: añade cada familia de Ágora que se vende con Split, Cost center, Revenue category y Tax applicability. Si las ventas de evento van a otros códigos, rellena Split para eventos, Cost center para eventos, Revenue category para eventos y Tax applicability para eventos (vacíos = se usan los normales). Marca No es aplicable a eventos si esa familia nunca debe llevar el evento como proyecto. Spend category y Cost object se usan en los pedidos de compra. - Pestaña **Impuestos**: añade cada tipo de IVA de Ágora con su Tax code de Workday. ### En Connect Manager: compras - Pestaña **Almacenes**: añade cada almacén de Ágora que recibe pedidos con Buyer id., Bill to contact, Ship to contact, Production purpose, Código de moneda, Project, Theater y Production. Configura todos: un pedido de un almacén sin configurar puede salir con datos de otro o hacer fallar la lectura. - Pestaña **Intervalos de aprobación** (opcional): crea los niveles de menor a mayor importe, porque se numeran por orden de creación. En cada uno, Importe mínimo, Importe máximo, los usuarios aprobadores y, si hace falta, Tiene que ser aprobado por todos. Sin niveles, todos los pedidos quedan aprobados. ### En Ágora - Revisa que todas las familias con ventas estén en la pestaña **Familias**: una familia sin asociar detiene la generación del día. - Para que una factura con cliente lleve su código de Workday, el cliente de Ágora debe tener el código contable correcto o estar en las equivalencias que carga FOS. - En compras, los proveedores necesitan su código contable y las líneas, su unidad de compra. ## Cómo funciona De madrugada, cada diez minutos, Connect Manager busca las integraciones de Workday cuya hora de generación coincide con la hora actual (hora de Madrid) y procesa el día anterior. Pide a Ágora las facturas de ese día, las agrupa y guarda las líneas de Workday en su base de datos. Según el día de la semana de las ventas, genera y sube el fichero y lo envía por correo. En paralelo, lee los pedidos de compra y los albaranes de entrada del mismo día. ```mermaid sequenceDiagram participant CM as Connect Manager participant AG as API de Ágora participant FTP as SFTP del cliente participant M as Correo y Telegram CM->>AG: Facturas del día anterior AG-->>CM: Tickets, facturas y abonos CM->>CM: Agrupa por teatro, sesión y serie CM->>CM: Guarda las líneas con su numeración CM->>FTP: Sube el CSV de facturas CM->>M: Envía el CSV y el Excel CM->>AG: Pedidos de compra y albaranes del día AG-->>CM: Pedidos y albaranes CM->>M: Avisa a los aprobadores si hace falta ``` ### Calendario de subida | Día de las ventas | Qué pasa en la pasada de la noche siguiente | | Lunes a jueves | Se genera, se sube y se envía el fichero de ese día. | | Viernes y sábado | Se guardan las líneas, pero no se sube nada. | | Domingo | Se sube y se envía un único fichero con viernes, sábado y domingo. | Si un día no hay ventas, el fichero se genera vacío y se sube igualmente. ### El fichero de facturas Es un CSV en UTF-8 con BOM y campos separados por barra vertical (`|`), llamado `AAAAMMDD-HHMMSS-CI-workday_invoices.csv` (abonos: `…-CN-…`). Cada fila es una línea de factura con estas columnas: Invoice ID, Company, Currency, Customer, Date, Payment Terms, Customer Invoice Type, Memo, Row ID, Revenue Category, Line Item Description, Tax Applicability, Tax Code, Extended Amount, Deferred Revenue, Cost Center, Project, Theater, Split, Production y Movement. El Excel que va por correo lleva los mismos datos sobre la plantilla de carga de Workday. - **Agrupación**: por teatro, por tipo de sesión (evento o normal) y por serie. Dentro, los tickets se acumulan hasta 1.500 € o hasta que cambia el cliente; entonces empieza otra factura con el siguiente número. - **Líneas**: una por combinación de tipo de IVA, categoría de ingreso, centro de coste, split, proyecto y aplicabilidad. El importe es neto: total de la línea con los descuentos repartidos, dividido por (1 + IVA), en valor absoluto. - **Cliente**: en las facturas con cliente, su equivalencia de Workday si existe, si no su código contable de Ágora y, si tampoco lo tiene, el del local; en los tickets, el código del local según la forma de pago (efectivo con la forma de pago 1 de Ágora, tarjeta con la 2, si no el general) y, si el local no tiene códigos, uno fijo del código. - **Eventos**: en las ventas de evento, el proyecto es el nombre del evento y la producción va vacía, salvo en las familias marcadas como no aplicables. ### Pedidos de compra y albaranes Cada pedido de compra del día se guarda con su compañía, proveedor, moneda, comprador y contactos (del almacén), y sus líneas con artículo, cantidad, unidad (un, kilo, litro y caja se convierten en EA, KGM, LTR y BX), coste unitario, centro de coste, split, spend category y cost object (de la familia). Si el total del pedido llega al importe mínimo del primer nivel, el pedido queda pendiente y los aprobadores reciben el correo «Pedido pendiente de aprobación» con el botón Revisar. ```mermaid flowchart TD A[Pedido leído de Ágora] --> B{Hay niveles de aprobación} B -- No --> C[Aprobado] B -- Sí --> D{Total igual o mayor que el mínimo del nivel 1} D -- No --> C D -- Sí --> E[Pendiente en el nivel y correo a sus aprobadores] E -- Rechaza --> R[Rechazado] E -- Aprueba --> F{Total igual o mayor que el máximo del nivel} F -- Sí --> G[Pasa al siguiente nivel] G --> E F -- No --> C ``` Se aprueba o rechaza en **Workday → Pedidos pendientes de aprobación**, con los botones Aprobar y Rechazar; la ficha muestra la Cadena de aprobación. Si el nivel exige que aprueben todos, el pedido no avanza hasta que lo hayan hecho todos sus usuarios. Cada lunes y cada día 1, la pasada nocturna envía por correo el Excel de pedidos de compra y el de albaranes del periodo: los siete días anteriores, sin cruzar de mes (el día 1 sale lo que queda del mes que se cierra). Los errores de esta lectura no generan aviso: revisa **Workday → Pedidos de compra**. ### Generar o reenviar un periodo - Desde Home, los widgets Facturas entre fechas (Workday), Devoluciones entre fechas (Workday), Pedidos entre fechas (Workday) y Entregas entre fechas (Workday) generan el fichero de un rango con lo ya guardado y te lo envían por correo. No suben nada al servidor. - FOS dispone de Generar contabilidad Workday y Generar compras Workday para lanzar una fecha concreta. Si ese día ya se generó bien, no se vuelve a leer de Ágora: solo se repite la subida según el calendario. - Un día que falló por configuración (una familia o un local sin asociar) se regenera completo al relanzarlo después de corregir, siempre que no haya días posteriores ya generados. Si los hay, llega el aviso «Existen facturas posteriores al día solicitado. Contacte con soporte@fos.systems.» Las exportaciones generadas se consultan en **Workday → Exportaciones**, con su fecha, local, tipo y base imponible. ## Comprobar que funciona - Configura la hora de generación y espera a la pasada de esa noche (o pide a FOS que lance Generar contabilidad Workday para ayer). - En **Workday → Exportaciones** deben aparecer las exportaciones del día, de facturas y de abonos, con su base imponible. - Comprueba que ha llegado el correo «Archivo facturas Workday» con el CSV y el Excel, y que el CSV está en la carpeta del servidor (si las ventas son de lunes a jueves). - Revisa unas cuantas líneas: teatro, centro de coste, categoría e importe neto deben cuadrar con las ventas de Ágora de ese día. - Pide al equipo de Workday que cargue el fichero de prueba y confirme que no hay rechazos. - Para compras: confirma en Ágora un pedido de prueba por encima del primer nivel, comprueba al día siguiente el correo «Pedido pendiente de aprobación» y apruébalo en **Pedidos pendientes de aprobación**. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Aviso «La familia Postres no está configurada.Por favor, revise la configuración de familias y genere el archivo de nuevo.» | Una familia vendida ese día no está en la pestaña Familias. | Añádela con sus códigos y pide a FOS que relance la fecha. | | Aviso «El workplace con id. 4 no ha sido configurado. Por favor, revise la configuración e inténtelo de nuevo.» | El local de Ágora no está en ningún teatro. | Inclúyelo en el teatro que corresponda y relanza la fecha. | | Aviso «Existen facturas posteriores al día solicitado. Contacte con soporte@fos.systems.» | Se intenta regenerar un día cuando ya hay días posteriores generados. | Contacta con FOS: regenerarlo cambiaría la numeración. | | No llega el fichero al servidor y sí por correo | Método de subida en «-», host con sftp://, puerto o carpeta incorrectos, o ventas de viernes o sábado. | Revisa la configuración de subida y el calendario. El mensaje «No se ha podido realizar la subida del fichero …» indica fallo de escritura en el servidor. | | El fichero de abonos no llega | Su subida falla en el código cuando hay método de subida configurado. | Genéralo con Devoluciones entre fechas (Workday) y avisa a FOS. | | No se genera nada a la hora configurada | Integración sin hora o con una hora que cae fuera de la ventana de la pasada nocturna del servidor. | Pon una hora entre las 3:00 y las 7:00 y comprueba al día siguiente. | | Una columna Tax code va vacía | El tipo de IVA no está en Impuestos. | Añádelo con su Tax code. | | «There are no approval users assigned to the next approval level» | El pedido supera el máximo del nivel y no hay nivel siguiente. | Crea el siguiente intervalo o sube el importe máximo del último. | | «The order has already been APPROVED» o «With this user you cannot approve or cancel the order» | El pedido ya está resuelto o el usuario no es aprobador de su nivel. | Revisa la cadena de aprobación y los usuarios del intervalo. | | Los buscadores de locales, familias o almacenes no cargan | Sin conexión con la API de Ágora. | Revisa URL de API y API key del local. | ## Preguntas frecuentes ### ¿Cómo conecto Workday con Ágora? Con Connect Manager: FOS crea en el local la integración de contabilidad Workday y tú configuras compañía, teatros, familias, impuestos y el servidor de ficheros. Cada noche se generan los ficheros de carga y Workday los importa desde el servidor. ### ¿Se envían las ventas a Workday por API? No. La integración genera ficheros CSV (y su versión Excel) que se suben por SFTP o FTP y se envían por correo; la carga en Workday la hace el propio Workday. ### ¿Por qué no se subió el fichero del viernes? Porque las ventas de viernes y sábado se suben el lunes, junto con las del domingo, en un único fichero. ### ¿Puedo regenerar un día que salió mal? Si falló por configuración, sí: corrige y relanza la fecha. Si el día ya se generó bien o hay días posteriores generados, tiene que hacerlo FOS para no romper la numeración de facturas. ### ¿La aprobación de pedidos bloquea el pedido en Ágora? No. La aprobación queda registrada en Connect Manager y avisa por correo, pero no cambia nada en Ágora ni filtra el Excel semanal de pedidos. ### ¿Sirve para un cliente que no sea un teatro? Los teatros son la forma de agrupar locales y pueden representar cualquier unidad de negocio, pero varias reglas del cliente original están fijas en el código. FOS tiene que revisarlas antes de usarla con otro cliente. ## Referencias - Ficha de la integración en el catálogo: [Workday](https://connectmanager.es/integraciones/workday). - [Direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager), para autorizar el acceso al servidor de ficheros. - [Glosario de Connect Manager](https://connectmanager.es/docs/glosario). --- # Integración de ARCA (AFIP) con Ágora: factura electrónica Portal: General · Fiscales y retail URL: https://connectmanager.es/docs/integracion-argentina-arca-agora Actualizado: 2026-10-03 La integración de **ARCA (antes AFIP)** con **Ágora** autoriza en ARCA cada factura y cada nota de crédito que emite el TPV: Connect Manager pide el CAE al web service de factura electrónica, devuelve a Ágora lo que hay que imprimir (CUIT, número de comprobante, CAE con su vencimiento y código QR) y guarda cada comprobante para consultarlo después. Si ARCA no responde, el local sigue facturando con un CAEA de contingencia. Este manual es para el técnico de FOS o del distribuidor que deja la integración funcionando en un local de Argentina. En las pantallas de Connect Manager la integración sigue apareciendo con el nombre antiguo, **AFIP**. ## Qué hace la integración - Recibe cada factura de Ágora al emitirla, por la integración de documentos de Ágora, y Ágora no la cierra hasta que ARCA la autoriza o la rechaza. - Elige el tipo de comprobante (Factura, Nota de crédito o Nota de débito, A o B) y el punto de venta de ARCA según la **serie** de Ágora. - Numera cada comprobante con el siguiente al último autorizado en ARCA para ese punto de venta y tipo. - Identifica al receptor por su CUIT: el de la ficha del cliente de Ágora o el que se asigna al ticket con el botón **CUIT** del TPV. Sin CUIT, sale a consumidor final sin identificar. - Asocia cada nota de crédito a su factura original, si esa factura se autorizó con esta integración. - Devuelve a Ágora el bloque que se imprime al final del ticket: CUIT del cliente (en los comprobantes A, también nombre, domicilio, código postal y provincia), número de comprobante, CAE o CAEA, vencimiento del CAE, la leyenda del régimen de transparencia fiscal (Ley 27.743) con el IVA contenido en los comprobantes que no son A, y el código QR de ARCA. - Si no consigue hablar con ARCA, emite el comprobante con el **CAEA** vigente de la quincena para que la caja no se pare. Los CAEA se piden solos dos veces al día. - Rechaza las facturas sin CUIT que superan el importe máximo general o el de la forma de pago con la que se cobran. - Avisa por correo y por Telegram si encuentra saltos en la numeración de los comprobantes. - Guarda todos los comprobantes con lo enviado y lo respondido por ARCA, para consultarlos, verificarlos contra ARCA y exportarlos a Excel desde **Listados fiscales**. - Si Ágora reenvía una factura que ya tiene CAE (misma serie y número), no pide otro: devuelve el que ya tenía. ### Qué no hace - No factura en otra moneda que el peso argentino. - No emite comprobantes de servicios: todos salen con el concepto «Productos». - No emite Factura C, M, recibos ni Factura de Crédito Electrónica MiPyMEs: solo comprobantes A y B. - No envía tributos, importes exentos ni no gravados: van siempre a cero. - No informa por sí sola a ARCA los comprobantes emitidos con CAEA durante una caída: esa tarea está desactivada en la versión actual y la lanza FOS. Avísalo en cuanto veas comprobantes «Sin enviar». - No anula comprobantes: en ARCA lo autorizado se corrige con una nota de crédito. ## Requisitos - **Local en Connect Manager** (`https://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 distribuidor revisa y completa el resto. - **API de Ágora accesible desde Internet** (puerto abierto o [Zero Connect](https://connectmanager.es/docs/zero-connect-instalacion)), solo para configurar: el buscador de formas de pago de **Límites de pago** la consulta. Las facturas las envía Ágora a Connect Manager. - **Ágora** con el módulo **Servicios de integración** (integración de documentos con sistemas externos), **Acciones personalizadas** y una **plantilla de factura ESC/POS**: el bloque con el CAE y el QR llega como datos de impresión y Ágora solo lo imprime en plantillas ESC/POS. - **En ARCA** (contador o cliente, con su clave fiscal): certificado digital del CUIT emisor autorizado para el web service de factura electrónica (`wsfe`) y los puntos de venta de web service para CAE y para CAEA. - **TPV con Internet**: la ventana del botón CUIT se carga desde Connect Manager. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | CUIT del emisor | Cliente o su contador | 11 dígitos sin guiones: 30123456789 | Sí | | Certificado digital | Contador, desde ARCA, para el servicio de factura electrónica | Fichero PEM (.crt o .pem) | Sí | | Clave privada del certificado | Quien generó la solicitud del certificado | Fichero PEM sin contraseña | Sí | | URL Api (web service de factura) | ARCA | Producción: https://servicios1.afip.gov.ar/wsfev1/service.asmx | Sí | | URL Auth (autenticación) | ARCA | Producción: https://wsaa.afip.gov.ar/ws/services/LoginCms | Sí | | Series de Ágora y tipo de comprobante de cada una | Configuración de series de Ágora y contador | Serie T → Factura B; serie F → Factura A | Sí | | Punto de venta de ARCA para CAE y para CAEA, por serie | Contador | 10 y 11 | Sí | | Condición ante el IVA del receptor, por serie | Contador | Consumidor Final o IVA Responsable Inscripto | Sí | | Último número emitido con CAEA, por serie | Contador (0 si nunca se ha usado CAEA) | 0 | Sí | | Importe máximo sin CUIT, general y por forma de pago | Cliente o contador | 100000; tarjeta → 50000 | No | | Correos y chat de Telegram para avisos | Cliente o distribuidor | avisos@ejemplo.com | No | ## Configuración paso a paso ### En ARCA (contador o cliente) - Genera el certificado digital del CUIT emisor, autorízalo para el servicio de factura electrónica (`wsfe`) y guarda la clave privada sin contraseña: la integración no admite claves protegidas. - Da de alta los puntos de venta de web service para CAE y para CAEA y apunta sus números. - Para las pruebas, pide también un certificado de homologación (ver **Comprobar que funciona**). ### En Connect Manager - En `https://app.connectmanager.es`, ve a **Administración → Locales**, abre el local, revisa la **URL de API** y la **API key** de Ágora y pulsa **Guardar**. Se habilitan los módulos de la derecha. - Entra en **Integraciones fiscales**, pulsa **Añadir** y en **Proveedor** elige **AFIP** (no se puede cambiar después de guardar). - Rellena la pestaña **Configuración**: - **URL Api:** la del web service de factura. Ponla siempre: vacía se usa la dirección por defecto del servidor, que no tiene por qué ser la de producción. - **URL Auth:** la de autenticación de ARCA, sin `?WSDL` al final. - **Certificado** y **Clave privada**: sube los dos ficheros; verás «Certificado subido» y «Private key subida». - **CUIT:** el del emisor, sin guiones. - **Límite de pago sin CUIT:** importe máximo de una factura sin CUIT. Vacío o 0, sin límite. - **Email de receptor de notificaciones** (varias direcciones separadas por comas) e **Id. de chat de Telegram para recibir notificaciones**: reciben el aviso de saltos de numeración (ver [Telegram](https://connectmanager.es/docs/integracion-telegram-agora)). - **Simular caída del servicio AFIP**: desmarcada. Marcada, todas las llamadas a ARCA fallan; solo sirve para probar la contingencia. - Pulsa **Guardar**. Al pie aparecen, con su botón de copiar, la **URL para enviar facturas desde Ágora** (termina en `/fiscals/afip/generate-receipt`) y la **URL de botón de asignación de CUIT**. Cópialas tal cual, sin tocar los marcadores entre llaves. - En la pestaña **Puntos de venta AFIP**, pulsa **+ Añadir** y crea una fila por cada serie con la que emite Ágora (simplificadas, nominales y sus devoluciones) con: **Serie de fact. en Agora** (nombre exacto), **Tipo de factura por defecto**, **Código del punto de venta (CAE)**, **Código del punto de venta (CAEA)**, **Condición ante el IVA del receptor** (Consumidor Final en las series B, IVA Responsable Inscripto en las A) y **Último nº de documento CAEA**. - Si hay límites por forma de pago, en la pestaña **Límites de pago** pulsa **+ Añadir**, elige el **Método de pago** de Ágora y escribe la **Cantidad**. > [!WARNING] El tipo de comprobante se decide por la serie, no por el tipo de documento. Si las devoluciones salen con la misma serie que las facturas, irían a ARCA como facturas: comprueba en Ágora que cada tipo de documento tiene su propia serie. ### En Ágora - En **Herramientas → Activar módulos adicionales → Servicios de integración**, pega la **URL para enviar facturas desde Ágora** en la integración de documentos con sistemas externos y actívala para las facturas. - Crea el botón en **Herramientas → Acciones personalizadas** → **Nuevo**: **Texto** `CUIT`, **Tipo** **Url/Aplicación** y, en **Acción**, la **URL de botón de asignación de CUIT**. Deja marcada **Mostrar Urls en un diálogo de Ágora** y pulsa **Aceptar**. - Colócalo en **Herramientas → Configuración de botones**, en el perfil que use el local, y da el permiso de la acción a los perfiles de usuario que vayan a usarla. - En las fichas de cliente pon el CUIT en el campo del CIF, con 11 dígitos y sin guiones. A los clientes que reciben Factura A márcales el **recargo de equivalencia**: la integración lo usa como señal de factura nominal. ## Cómo funciona Cuando se emite una factura, Ágora la manda a Connect Manager y espera. Connect Manager comprueba la serie, el CUIT y los límites; obtiene de ARCA un ticket de acceso firmado con el certificado del cliente (lo reutiliza mientras no caduca); pregunta el último número autorizado de ese punto de venta y tipo, y pide el CAE con el siguiente. Si ARCA lo aprueba, guarda el CAE y su vencimiento y contesta a Ágora con el bloque que se imprime. Si lo rechaza, contesta con el código y el texto de ARCA y Ágora no cierra la factura. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant AUTH as ARCA WSAA participant FE as ARCA WSFE TPV->>CM: Factura emitida CM->>CM: Valida serie, CUIT y límites CM->>AUTH: Ticket de acceso firmado con el certificado AUTH-->>CM: Token y firma CM->>FE: Último comprobante autorizado FE-->>CM: Último número del punto de venta CM->>FE: Solicitud de CAE con el número siguiente FE-->>CM: CAE y fecha de vencimiento CM-->>TPV: Aceptada con datos de impresión y QR TPV->>TPV: Cierra e imprime la factura ``` **Qué se envía:** el punto de venta CAE y el tipo de la serie; el CUIT emisor; el receptor con CUIT (tipo de documento 80) si la ficha del cliente lo tiene y es válido o si se asignó con el botón, o con tipo 99 si no; la condición ante el IVA de la serie; la fecha de negocio de Ágora; total, neto gravado e IVA con su desglose por alícuota (cada tipo de IVA de Ágora se traduce al código de ARCA con una tabla interna, y uno que no esté en ella se manda como 21 %), y en las notas de crédito los datos de la factura original. El número del comprobante en ARCA no es el de Ágora: Ágora conserva su serie y número, y los dos quedan guardados juntos. ### Contingencia con CAEA Si la factura no supera las validaciones o ARCA la rechaza, Ágora recibe el motivo. Si lo que falla es la comunicación (ARCA no responde, error de red o de autenticación), Connect Manager usa el CAEA de la quincena de la fecha de negocio: numera el comprobante en el punto de venta CAEA (siguiente al último emitido con CAEA o al **Último nº de documento CAEA** configurado), lo deja «Sin enviar» y Ágora imprime el CAEA. Sin CAEA para ese periodo, la factura se rechaza. ```mermaid flowchart TD A[Factura de Ágora] --> B{Pasa las validaciones} B -- No --> R1[Rechazada con el motivo] B -- Sí --> C{Respuesta de ARCA} C -- Aprobada --> OK[CAE impreso en el ticket] C -- Rechazada --> R2[Rechazada con el código de ARCA] C -- Sin conexión o error de autenticación --> D{Hay CAEA de la quincena} D -- Sí --> E[Sin enviar con el CAEA impreso] D -- No --> R3[Rechazada sin CAEA] ``` > [!WARNING] Un certificado mal subido o caducado no da un error de certificado en el TPV: la integración lo trata como una caída y factura con CAEA. Si aparecen comprobantes «Sin enviar» sin que ARCA esté caída, revisa certificado, clave y URL Auth, y pide a FOS que informe a ARCA los comprobantes emitidos con CAEA. ### Tareas programadas y botón CUIT - **CAEA:** dos veces al día se pide el de la quincena en curso (días 1 a 15 y 16 a fin de mes) y, del 11 al 15 y en los últimos cinco días del mes, también el de la siguiente. Se ven en **Listados fiscales → CAEAs**. - **Saltos de numeración:** cada hora se revisan los comprobantes de las dos últimas horas de cada punto de venta CAE y tipo; si un número no sigue al anterior, se avisa a FOS y a los correos y al chat de la integración («Error documentos AFIP»). - **Botón CUIT:** abre en Ágora la ventana «CUIT para la factura», con teclado en pantalla y el CUIT ya asignado si lo había. Al pulsar **Asignar**, el CUIT se valida (11 dígitos y dígito de control) y queda ligado al ticket abierto: hay que asignarlo **antes** de emitir la factura. ## Comprobar que funciona - Empieza con las URL y un certificado de homologación. - Emite una factura simplificada pequeña: debe imprimirse con número de comprobante, CAE, vencimiento y QR. - En **Listados fiscales → AFIP documentos** debe aparecer **Aceptado** con tipo, punto de venta, número y código. - Asigna un CUIT con el botón a un ticket abierto y factúralo: el CUIT debe salir impreso. - Emite una factura nominal a un cliente con CUIT y recargo de equivalencia: debe salir como Factura A con sus datos. - Devuelve la primera factura y comprueba que sale como nota de crédito. - Si hay límite sin CUIT, intenta superarlo sin CUIT: Ágora debe mostrar el rechazo. - Para la contingencia (solo en homologación y con un CAEA ya visible en **CAEAs**), marca **Simular caída del servicio AFIP**, factura, comprueba que sale con CAEA y queda «Sin enviar», y desmarca la casilla. - Pasa a las URL, el certificado y la clave de producción y repite la primera prueba. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «La serie X de Agora no está configurada.» | La serie no tiene fila en Puntos de venta AFIP o le falta el punto de venta CAE o el tipo. | Añade la serie completa. | | «No se pueden generar facturas nominales sin cliente asociado…» o «…si el CUIT del cliente no es válido…» | Factura nominal sin cliente, o con un CIF vacío, con guiones o con el dígito de control mal. | Asigna el cliente o corrige su CUIT (11 dígitos, sin guiones). | | «No se pueden generar facturas nominales para clientes que no tienen el recargo de equivalencia activado…» o «No se pueden generar facturas simplificadas para clientes con recargo de equivalencia activado…» | El tipo de factura no casa con la marca de recargo de equivalencia del cliente. | Marca el recargo a los Responsables Inscriptos y emite simplificada al resto. | | «El total de la factura supera el máximo permitido. Asigne un CUIT a la factura para poder continuar» | Factura sin CUIT por encima del Límite de pago sin CUIT. | Asigna el CUIT con el botón o al cliente. | | «El total de la factura supera el máximo permitido para el método de pago…» | Se cobra con una forma de pago con límite y el total lo alcanza. | Asigna un CUIT o cobra con otra forma de pago. | | «No existe código CAEA correspondiente al periodo actual» | No se pudo hablar con ARCA y no hay CAEA de la quincena. Si pasa desde el primer día, casi siempre es el certificado, la clave o la URL Auth. | Revisa certificado, clave sin contraseña, CUIT y URL, y que haya código en CAEAs. | | Rechazo con «código - mensaje» de ARCA | ARCA rechaza el comprobante (punto de venta, condición de IVA, importes…). | Corrige según el texto de ARCA; la respuesta completa está en el detalle del documento. | | «El CUIT proporcionado no es válido» en el botón | No tiene 11 dígitos o falla el dígito de control. | Escríbelo sin guiones ni espacios. | | La factura se cierra sin el CAE ni el QR impresos | La plantilla de la factura no es ESC/POS. | Cambia a una plantilla ESC/POS. | | El buscador de Método de pago no muestra nada | Connect Manager no llega a la API de Ágora del local. | Revisa la URL de API y la API key, o Zero Connect. | ## Preguntas frecuentes ### ¿Cómo conecto ARCA (AFIP) con Ágora? Con Connect Manager: se da de alta la integración fiscal AFIP del local con certificado, clave y CUIT, se mapea cada serie de Ágora a un tipo de comprobante y punto de venta, y en Ágora se pega la URL de facturas en la integración de documentos. ### ¿Qué pasa si ARCA se cae mientras el local está facturando? Si hay CAEA de la quincena, las facturas salen con CAEA y quedan «Sin enviar»; después hay que informarlas a ARCA, y eso lo lanza FOS. Sin CAEA, la factura se rechaza. ### ¿Cómo emito una Factura A desde Ágora? Con una factura nominal a un cliente con el CUIT en el CIF y el recargo de equivalencia marcado, emitida con una serie mapeada a Factura A. ### ¿Puedo poner el CUIT de un cliente sin darlo de alta en Ágora? Sí: con el botón CUIT se asigna al ticket abierto antes de facturar. ### ¿Dónde veo el CAE de una factura? Impreso en el ticket y en **Listados fiscales → AFIP documentos**, columna Código, con el detalle de lo enviado y lo recibido. ### ¿Sirve para monotributistas? No: emite comprobantes A y B; la Factura C no está disponible. ## Referencias - Ficha de la integración: [ARCA en el catálogo de Connect Manager](https://connectmanager.es/integraciones/argentina-arca). - [Avisos de las integraciones por Telegram](https://connectmanager.es/docs/integracion-telegram-agora). - [Zero Connect: publicar la API de Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion). - [Global Blue](https://connectmanager.es/docs/manual-configuracion-global-blue), otra integración fiscal que se configura en la misma pantalla. - Web services de ARCA: [https://www.afip.gob.ar/ws/](https://www.afip.gob.ar/ws/). - Especificación del código QR de los comprobantes: [https://www.afip.gob.ar/fe/qr/](https://www.afip.gob.ar/fe/qr/). --- # Integración de El Corte Inglés con Ágora Portal: General · Fiscales y retail URL: https://connectmanager.es/docs/manual-configuracion-el-corte-ingles Actualizado: 2026-10-03 ## **Manual de Integración con El Corte Inglés (Ágora) en Connect Manager** ### **1. Introducción** Este manual describe paso a paso cómo configurar la integración entre **El Corte Inglés** y **Ágora** a través de **Connect Manager**. El objetivo es dejar operativo el envío/recepción de pedidos en el entorno de El Corte Inglés, pasando primero por un entorno de pruebas (PRE) y finalizando en el entorno real de producción (PRO). El proceso implica la coordinación de tres partes: el distribuidor, El Corte Inglés y (en la fase final) los informáticos de El Corte Inglés, que son quienes activan la integración en su propio terminal. ### **2. Solicitud de precredenciales** Se debe enviar un correo a [**extensibilidadpuntodeventaECI@elcorteingles.es**](mailto:extensibilidadpuntodeventaECI@elcorteingles.es) indicando a quién se le va a realizar la integración, y solicitando los datos necesarios en el entorno de **Pre** (pruebas): - **Matrícula** - **Referencia interna del producto a enviar** > **Nota:** El Corte Inglés distingue entre **Pre** (entorno de pruebas) y **Pro** (entorno real/producción). En esta primera solicitud siempre se piden los datos de Pre. ### **3. Datos recibidos de El Corte Inglés** El Corte Inglés responde con los datos de matrícula y referencia interna del producto, diferenciados por entorno: **Entorno PRE (pruebas)** - Matrícula: `00000000` - Referencia interna del producto: `000000` **Entorno PRO (producción)** - Matrícula: `00000000` - Referencia interna del producto: - `00000000` (IVA 21%) - `00000000` (IVA 10%) > Estos datos de PRO se guardan de referencia, pero **no se utilizan hasta que El Corte Inglés confirme las pruebas** (ver punto 8). ### **4. Credenciales de acceso** En un correo aparte, El Corte Inglés envía las credenciales de acceso a la integración: - **Client ID:** `00000000000` - **Client Secret:** `0000000000000` > ⚠️ Estas credenciales dan acceso directo a la plataforma. Deben tratarse como información confidencial y no compartirse fuera del equipo de configuración. ### **5. Endpoints del entorno de pruebas (PRE)** Para realizar las pruebas se deben usar siempre estos endpoints: - **URL API:** `https://api-manager-nft.pre.elcorteingles.es/` - **URL AUTH:** `https://identity-services.nft.elcorteingles.es/oauth2/token` ### **6. Configuración de la acción personalizada (botón) en Ágora** - Dentro de la integración se genera una **URL** propia de la integración. - Esa URL se coloca en Ágora, dentro de una **Acción personalizada**, para crear un **botón**. > ⚠️ **Importante:** No se debe configurar en el servicio de Ágora el **envío de documentos**. ### **7. Pruebas** - Con el botón ya creado, se genera un **ticket** de prueba. - Se **cierra la operación** utilizando la acción personalizada (el botón) creada en el paso anterior. ### **8. Aviso a El Corte Inglés y confirmación** Una vez realizadas las pruebas, se envía un correo a El Corte Inglés indicando que las pruebas se han completado, quedando a la espera de su **confirmación**. Cuando El Corte Inglés confirme el resultado de las pruebas (**OK**), facilitará los **datos definitivos de producción**. ### **9. Paso a producción** Tras la confirmación de El Corte Inglés, se deben **sustituir todos los datos de PRE por los de PRO**: - Matrícula (PRE → PRO) - Referencia interna del producto (PRE → PRO) - Client ID / Client Secret (nuevos, de producción) - URL API y URL AUTH del entorno PRO - Actualizar/regenerar la URL de la acción personalizada en Ágora si corresponde al nuevo entorno ### **10. Configuración final por parte de El Corte Inglés** Con los datos de producción ya sustituidos, el proceso pasa a manos del **equipo informático de El Corte Inglés**, que desde su terminal debe: - Configurar la **integración 55**. - Seleccionar el **local correspondiente** a la integración. ### **11. Verificación final** - Comprobar que la integración aparece activa. - Confirmar que los pedidos de prueba/producción se reciben correctamente en Ágora. - Verificar que el botón de la acción personalizada funciona correctamente y no está configurado el envío de documentos. --- # Integración de Global Blue con Ágora Portal: General · Fiscales y retail URL: https://connectmanager.es/docs/manual-configuracion-global-blue Actualizado: 2026-10-03 ## Guía para la integración de Global Blue ## 1. Datos del Local 1- En el menú lateral izquierdo, pincha en las 3 rayas laterales 2- Accede a Administración. 3- Haz clic en Locales. 4- Buscamos el local que nos han asignado (los distribuidores no tienen la capacidad de crear sus propios locales). ## 2. Datos del Local (campos a completar) En la pantalla de detalle del local, completa o revisa los siguientes campos: - **Cliente**: Ponemos el nombre del distribuidor. EJ. "Informática Pepe" - **Nombre**: Lo nombramos siempre de la siguiente forma: Nombre distribuidor – Nombre del local – Donde se encuentra el local (Retiro/Sol/Bernabeu) - **URL de API**: Si es un Cloud usamos la URL del ACMS. Si es solo un local tenemos que poner la URL correspondiente al local - **API key**: Usamos la Api Key del ACMS en caso de que sean varios locales. Si es un único local usamos la Api Key del local en cuestión. - **Dirección:**Introducir la dirección del local correspondiente - **Ciudad:**Introducir la ciudad correspondiente - **Zona horaria**Introducir la zona horaria correspondiente Una vez completados los datos, pulsa **Guardar**. En ese momento los módulos del lado derecho estarán habilitados. ## 3. Integraciones fiscales Si prestamos atención a la derecha, vemos la casilla de "integraciones fiscales" dentro de estas debemos encontrar "Global Blue", pinchamos en ella y configuramos los campos que aparecen a continuación. - **URL Api:** URL Global Blue del cliente final - **Usuario:** Usuario registrado en Global Blue - **Password:** Contraseña para acceder a Global Blue - **Borrar caché:** En principio no se marcaría, para que vaya más fluido. Si en algún momento es necesario, se marcará a futuro Una vez introducidos estos datos, pulsa el botón **"Guardar"** (parte inferior derecha) para que la configuración quede registrada. En la parte inferior de esta misma pantalla de Configuración aparecen dos URLs que se generan automáticamente. Son necesarias para terminar la integración en Ágora, así que cópialas usando el icono de copiar situado a la izquierda de cada una: - URL para enviar facturas desde Ágora: es la dirección a la que Ágora enviará las facturas para que Global Blue las procese. Debe pegarse en la configuración de Ágora del cliente. - URL de botón de búsqueda de facturas: es la dirección que permite localizar y consultar las facturas ya emitidas desde el propio TPV. También se configura en Ágora. Recomendación: pega ambas URLs en un documento o correo junto con los datos del cliente para tenerlas localizadas durante la instalación en Ágora. ## 4. Puntos de venta Después de guardar la configuración, accede a la pestaña "Puntos de venta" (en la parte superior, junto a "Configuración"). Aquí se indica a qué punto de venta (POS) del local corresponde cada caja o terminal de Global Blue. Para dar de alta un punto de venta: Pulsa el botón "+ Añadir" (parte superior derecha). Se abrirá el formulario "Punto de venta". - Punto de venta (POS): despliega la lista y selecciona el POS del local que quieres integrar. Estos POS provienen de la configuración del local en Ágora; si la lista aparece vacía, asegúrate de que el local tiene POS creados y la configuración guardada. - Shop id de Global blue: introduce el identificador de tienda (Shop ID) que proporciona Global Blue para ese establecimiento. Es un campo obligatorio. - Desk id de Global blue: introduce el identificador de caja/mostrador (Desk ID) facilitado por Global Blue para ese punto de venta. Es un campo obligatorio. Pulsa **"Guardar"**. El punto de venta aparecerá en la lista con su Id y su POS asociado. Repite el proceso por cada punto de venta que el local tenga que integrar con Global Blue. Si un local tiene varias cajas, cada una necesita su propio Shop id y Desk id. ## 5. Configuración en Ágora y verificación Con la integración ya creada en Connect Manager, el último paso es enlazarla con Ágora: La integración con Global Blue se completa en Ágora en dos lugares dentro del menú Herramientas: primero se crea una "Acción personalizada" con la URL y después se coloca como botón en el TPV. Crear la acción con la URL. Ve a Herramientas y, en la columna "Visualización", entra en "Acciones Personalizadas". Pulsa "+ Nuevo" (o selecciona la acción existente y pulsa "Editar") y rellena: - "Texto" escribe el nombre que verá el usuario en el botón (por ejemplo "TAX FREE") - "Tipo" selecciona "Url/Aplicación" - "Acción" pega la **"URL de botón de búsqueda de facturas"**que copiaste de Connect Manager. - Deja marcada la casilla "Mostrar Urls en un diálogo de Ágora" para que las facturas se abran dentro de Ágora. - Opcionalmente asigna un icono en "Img. Tema Claro" e "Img. Tema Oscuro". Pulsa "Aceptar" para guardar. Colocar el botón en el TPV. Vuelve a Herramientas y, en "Visualización", entra en "Configuración de Botones". Selecciona el perfil que usa el local (por ejemplo "Básica" o "Tablet") y pulsa "Editar". En la rejilla de "Botones de acción", arrastra o asigna la acción que acabas de crear a una celda libre para que quede visible en la pantalla de venta. Pulsa "Aceptar" para guardar. A partir de ese momento, el botón (p. ej. "TAX FREE") aparecerá en el TPV y, al pulsarlo, abrirá la pantalla de búsqueda de facturas de Global Blue. Configuración de la**“URL para enviar facturas desde Ágora”** - Qué es y para qué sirve: es la dirección que Ágora utiliza para enviar de forma automática cada factura emitida al sistema de Global Blue, de modo que la operación de tax free quede registrada. A diferencia de la URL de búsqueda, esta no se coloca en un botón visible del TPV: actúa de forma interna cuando se genera la factura. - De dónde se obtiene: igual que la URL de búsqueda, se genera en Connect Manager. Abre la integración fiscal del local (Integraciones fiscales del proveedor Global Blue) y ve a la pestaña Configuración. En la parte inferior verás el campo “URL para enviar facturas desde Ágora”. Pulsa el icono de copiar situado a su izquierda para copiar la dirección completa. - Cómo se aplica en Ágora: El proceso a seguir es exactamente el mismo que la configuración de la URL mencionada anteriormente Importante: copia y conserva esta URL junto con el resto de datos de la integración. Si el responsable de la instalación te indica que debe introducirse en algún punto concreto del local, utilízala tal cual la copiaste, sin modificarla. Comprobación final: realiza una venta de prueba en el TPV y verifica que la factura llega correctamente a Global Blue y que el botón de búsqueda muestra la factura. Si algo no aparece, revisa que las credenciales (Usuario y Password), el Shop id y el Desk id sean correctos, y que la configuración esté guardada en Connect Manager. Nota: si en algún momento los datos no se actualizan correctamente, marca la casilla “Borrar caché” en la pestaña Configuración, guarda, y vuelve a desmarcarla una vez resuelto. --- # Integración de efsta con Ágora: certificación fiscal en Portugal Portal: General · Fiscales y retail URL: https://connectmanager.es/docs/integracion-portugal-at-agora Actualizado: 2026-10-03 La integración de **efsta** con **Ágora** certifica en Portugal los documentos del TPV: cada factura, factura simplificada y nota de crédito que emite Ágora se registra en efsta, el middleware fiscal que se encarga de la comunicación con la AT, y Ágora imprime el documento certificado que devuelve efsta. Connect Manager hace de puente, valida los datos antes de enviarlos y guarda cada documento. Este manual es para el técnico de FOS o del distribuidor que configura la integración en un local de Portugal. En Connect Manager el proveedor se llama **Efsta (PT)**. Los mensajes que ve el camarero en el TPV están en portugués. ## Qué hace la integración - Registra en efsta cada documento de Ágora al emitirlo: **FT** (factura) si lleva cliente, **FS** (factura simplificada) si no, y **NC** (nota de crédito) para las devoluciones, enlazada con el documento original. Ágora no cierra el documento hasta que efsta lo acepta. - Envía las líneas con sus descuentos, los descuentos del ticket, los pagos y el desglose de impuestos, cada pago con su código de efsta y cada IVA con su grupo de impuesto, además del local, el terminal y el usuario que factura. - Pide a efsta el documento certificado ya maquetado y se lo devuelve a Ágora para que lo imprima. - Valida el NIF portugués del cliente (9 dígitos con dígito de control; admite el prefijo `PT`). Los NIF de otros países se envían con su prefijo de país, sin validar. - Añade desde el TPV los datos fiscales del cliente al ticket (NIF, nombre, dirección y país) con el botón **Dados da fatura**, sin darlo de alta en Ágora. Si el NIF ya es de un cliente de Ágora, lo avisa. - Emite e imprime facturas proforma certificadas del ticket abierto desde un botón. Si el ticket no ha cambiado de importe, reimprime la misma proforma; si ha cambiado, registra una nueva. - Impide cerrar el documento si una forma de pago o un tipo de IVA no está configurado, si una venta sin NIF supera el importe máximo o si el importe cobrado con una forma de pago alcanza su límite. - Exporta desde el TPV los documentos certificados de un año o de un periodo, con la exportación de efsta. - Permite al usuario de Ágora cambiar su contraseña desde un botón del TPV. - Guarda cada documento con lo enviado y lo respondido. En **Listados fiscales → Efsta documentos** se consultan, se abre su PDF y se envía por correo. - Si Ágora reenvía un documento ya certificado (misma serie y número), no lo vuelve a registrar. ### Qué no hace - No anula una factura proforma ya emitida: el botón **Anular** del listado no la anula en efsta. - No factura si efsta no responde: no hay modo de contingencia en Connect Manager y el documento se rechaza hasta que efsta vuelve. - No envía avisos por correo ni por Telegram: los campos de notificación de la pantalla no se usan en esta integración. - La casilla **Enviar facturas a integraciones de hotel** no tiene efecto en la versión actual. - No exporta a Excel los documentos de efsta desde el panel: para eso están las exportaciones por año y por periodo. ## Requisitos - **efsta** instalado, licenciado y dado de alta para el contribuyente. Lo gestiona efsta o su partner: la comunicación con la AT es cosa de efsta, no de Connect Manager. - **URL del servicio de efsta accesible desde Connect Manager**, que llama a efsta para registrar, imprimir y sacar el PDF de cada documento. Si efsta está en el local, publícalo con su propia URL o con un túnel adicional de [Zero Connect](https://connectmanager.es/docs/zero-connect-instalacion). Los botones de exportación abren esa misma URL desde el TPV, así que el TPV también tiene que llegar a ella. - **Local en Connect Manager** con la URL de la API y la API key de Ágora: los buscadores de formas de pago y de impuestos de la configuración consultan la API del local. El alta del local y de la integración la hace FOS. - **Ágora** con **Servicios de integración** (integración de documentos con sistemas externos), **Acciones personalizadas** y plantillas de impresión **ESC/POS**: el documento de efsta llega como datos de impresión ESC/POS. - Los dos **informes personalizados** que se descargan de la integración, instalados en Ágora. Los usan las ventanas de datos del cliente y de proforma. > [!WARNING] Connect Manager llama a efsta sin credenciales. No dejes su URL abierta a todo Internet: limita el acceso a las [direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) y a la IP pública del local. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL del servicio de efsta | efsta o su partner | https://efsta-demo.ejemplo.pt/ (con / final) | Sí | | Código de efsta de cada forma de pago de Ágora | efsta o su partner | Efectivo → el código de pago en efectivo de efsta | Sí, todas las que se usen | | Grupo de impuesto de efsta de cada IVA de Ágora | efsta o su partner | 23 % → A | Sí, todos los que se usen | | Importe máximo sin NIF | Cliente o su contabilista | 1000 | No | | Límite por forma de pago | Cliente o su contabilista | Efectivo → 3000 | No | | Nombre de la impresora de Ágora para las proformas | Configuración de impresoras de Ágora | BARRA | Sí, si se usan proformas | | Terminal en efsta: por TPV o por local | efsta o su partner | Por TPV (valor por defecto) | Sí | ## Configuración paso a paso ### En efsta - efsta o su partner instala y da de alta el servicio para el contribuyente y te facilita su URL. - Pídele los códigos de forma de pago y los grupos de impuesto que espera, y confirma si registra un terminal por cada TPV o uno por local. ### En Connect Manager - En `https://app.connectmanager.es`, ve a **Administración → Locales**, abre el local, revisa la **URL de API** y la **API key** de Ágora y pulsa **Guardar**. - Entra en **Integraciones fiscales**, pulsa **Añadir** y elige el **Proveedor** **Efsta (PT)**. - En la pestaña **Configuración** rellena: - **URL Api:** la de efsta, terminada en `/`: Connect Manager le añade las rutas de efsta detrás. - **Límite de pago FS:** importe máximo de un documento sin NIF. Por encima, Ágora pide asignar un cliente. Vacío o 0, sin límite. - **Usar el local como punto de venta**: márcala si efsta registra un único terminal por local; desmarcada, cada TPV de Ágora es un terminal. - **Enviar facturas a integraciones de hotel**: déjala desmarcada. - Pulsa **Guardar**. Al pie aparecen la **URL para enviar facturas desde Ágora**, la **URL de botón de asignación de CUIT** (es la de **Dados da fatura**), la **URL de botón cambiar password**, la **URL de botón generación factura proforma**, la **URL de botón de exportación anual de documentos** y la **URL de botón de exportación de documentos por periodo**. - Descarga los informes **Informe de datos del cliente** (`Customer_Data_For_Ticket.xml`) e **Informe de clientes filtrados por NIF** (`Customers_Filtered_By_CIF.xml`). - En la pestaña **Métodos de pago**, pulsa **+ Añadir** por cada forma de pago de Ágora que use el local: **Método de pago**, **Código del método** (el de efsta) y, si procede, **Límite de pago del método**. - En la pestaña **Impuestos**, pulsa **+ Añadir** por cada tipo de IVA de Ágora: el impuesto y su **Código del impuesto** en efsta. > [!NOTE] Una forma de pago o un IVA sin mapear no da error al configurar: bloquea la venta en el TPV la primera vez que se usa. Mapea todos los que existan en Ágora, aunque se usen poco. ### En Ágora - Copia los dos informes descargados, sin modificarlos, en la carpeta `custom-queries` del servidor de Ágora. - En **Herramientas → Activar módulos adicionales → Servicios de integración**, pega la **URL para enviar facturas desde Ágora** en la integración de documentos con sistemas externos y actívala para las facturas. - En **Herramientas → Acciones personalizadas**, crea una acción de tipo **Url/Aplicación** por cada botón, con **Mostrar Urls en un diálogo de Ágora** marcado: **Dados da fatura**, **Proforma**, **Exportar ano**, **Exportar período** y **Mudar password**, cada una con su URL. A la de la proforma añádele al final, detrás de `printer_name=`, el nombre exacto de la impresora de Ágora. - Coloca las acciones en **Herramientas → Configuración de botones** y da el permiso de cada acción a los perfiles de usuario que deban usarla. - Comprueba que las plantillas de impresión de los documentos son ESC/POS. > [!WARNING] Ágora lee la carpeta `custom-queries` al arrancar sus componentes de servidor, y un informe mal formado puede impedir que el servicio arranque. Copia los ficheros tal cual se descargan. ## Cómo funciona Al emitir un documento, Ágora lo manda a Connect Manager. Connect Manager comprueba serie, número, NIF, formas de pago, límites e impuestos; si algo falla, contesta con el motivo y Ágora no cierra el documento. Si todo está bien, lo registra en efsta, que le devuelve el número fiscal del documento; con ese número pide a efsta el ticket certificado en formato ESC/POS y se lo entrega a Ágora para imprimirlo. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant EF as efsta TPV->>CM: Documento emitido CM->>CM: Valida NIF, pagos, límites e impuestos CM->>EF: Registro del documento EF-->>CM: Resultado OK y número fiscal CM->>EF: Documento certificado en ESC/POS EF-->>CM: Ticket maquetado CM-->>TPV: Aceptado con los datos de impresión TPV->>TPV: Cierra e imprime el documento ``` ### Qué se envía - Fecha, local (`TL`), terminal (`TT`: el TPV, o el local si está marcada la opción), tipo (FT, FS o NC), número de Ágora (`serie/número`), total y usuario. - Cliente: NIF, nombre, dirección y país de la ficha de Ágora o de los datos añadidos con **Dados da fatura**. - Líneas con cantidad, precio, grupo de impuesto y descuentos; descuentos del ticket; pagos con su código; impuestos con su grupo y porcentaje. - En las notas de crédito, el número fiscal del documento original. Si efsta devuelve un error de NIF, el TPV muestra «O NIF inserido não está correto» o «O cliente não possui NIF»; cualquier otro error se muestra con su código. Si efsta no contesta, el documento queda como «Sin enviar» en el listado y Ágora recibe el rechazo. ### Botones del TPV - **Dados da fatura**: ventana con **País**, **NIF**, **Nome** y **Endereço** y los botones **Manter** y **Cancelar**. Antes de guardar busca el NIF entre los clientes de Ágora con el informe de clientes; si existe, avisa con el nombre del cliente para que se asigne ese cliente. Los datos quedan ligados al ticket abierto, así que se rellenan antes de emitir el documento. - **Proforma**: lee el ticket abierto y los datos del cliente desde Ágora, registra la proforma en efsta y la imprime en la impresora indicada en la URL. - **Exportar ano** y **Exportar período**: piden el año o las fechas y abren la exportación de documentos de efsta para el local. - **Mudar password**: cambia la contraseña del usuario de Ágora que pulsa el botón. Las ventanas de datos del cliente y de proforma hablan con Ágora a través del propio TPV, así que no necesitan que la API de Ágora esté abierta a Internet. ## Comprobar que funciona - Emite una factura simplificada sin cliente: debe imprimirse el documento certificado de efsta. - En **Listados fiscales → Efsta documentos** debe aparecer como **Aceptado**, con su código; abre **Exportar PDF** y comprueba el documento. - En un ticket nuevo, pulsa **Dados da fatura**, introduce un NIF portugués válido de pruebas, nombre y dirección, guarda y emite: debe salir como factura con esos datos. - Haz una devolución de la primera venta: debe certificarse como nota de crédito. - Cobra con una forma de pago sin mapear o vende un producto con un IVA sin mapear: el TPV debe bloquear el cierre con el mensaje correspondiente. - Pulsa **Proforma** en un ticket abierto: debe imprimirse en la impresora configurada. - Prueba las dos exportaciones desde el TPV. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «A forma de pagamento 'X' não está configurada. Configure para continuar» | La forma de pago no está en Métodos de pago. | Añádela con su código de efsta. | | «O produto 'X' tem um imposto de N% associado. Altere para um imposto válido para continuar» | Ese tipo de IVA no está en Impuestos. | Añade el impuesto con su grupo de efsta. | | «O total da fatura excede o máximo permitido. Atribua um cliente à fatura para continuar» | Venta sin NIF por encima del Límite de pago FS. | Asigna un cliente o usa Dados da fatura. | | «O total da fatura excede o máximo permitido (…) para a forma de pagamento …» | El importe cobrado con esa forma de pago alcanza su límite. | Cobra con otra forma de pago. | | «O CIF do cliente não é válido…» o «O cliente não possui um número de IVA…» | El cliente asignado tiene un NIF incorrecto o vacío. | Corrige la ficha del cliente en Ágora. | | «O NIF fornecido não é válido» en Dados da fatura | NIF portugués que no supera el dígito de control. | Revísalo con el cliente. | | «… : O NIF inserido não está correto» o «… : O cliente não possui NIF» | efsta rechaza el NIF del documento. | Corrige el NIF y vuelve a emitir. | | Todos los documentos se rechazan con un error de conexión | Connect Manager no llega a la URL de efsta, o efsta está parado. | Comprueba la URL (con / final), el túnel o el acceso por IP y el servicio de efsta. | | El documento se certifica pero no se imprime | La plantilla de impresión no es ESC/POS. | Cambia a una plantilla ESC/POS. | | La proforma no se imprime | Falta el nombre de la impresora al final de la URL o no coincide con Ágora. | Corrige el valor de printer_name en la acción personalizada. | | Los buscadores de formas de pago o impuestos no muestran nada | Connect Manager no llega a la API de Ágora del local. | Revisa la URL de API y la API key, o Zero Connect. | ## Preguntas frecuentes ### ¿Cómo conecto Ágora con la AT de Portugal? A través de efsta: Connect Manager envía cada documento de Ágora a efsta, que lo certifica, y devuelve a Ágora el documento certificado para imprimirlo. ### ¿Qué pasa si efsta no responde? El documento se rechaza en el TPV y queda «Sin enviar» en el listado. Connect Manager no tiene modo de contingencia para efsta. ### ¿Puedo poner el NIF del cliente sin crearlo en Ágora? Sí, con el botón **Dados da fatura**, antes de emitir el documento. ### ¿Se pueden anular las proformas? No. Si el importe del ticket cambia, se emite una proforma nueva; la anterior no se anula. ### ¿Dónde consigo el PDF de una factura certificada? En **Listados fiscales → Efsta documentos**, desde el detalle del documento: **Exportar PDF** o **Enviar mail**. ## Referencias - Ficha de la integración: [Portugal (AT, efsta) en el catálogo de Connect Manager](https://connectmanager.es/integraciones/portugal-at). - [Integración de ARCA con Ágora](https://connectmanager.es/docs/integracion-argentina-arca-agora), la otra integración fiscal con la misma pantalla de configuración. - [Zero Connect: publicar servicios del local sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion). - [Direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager). - efsta: [https://www.efsta.eu](https://www.efsta.eu). --- # Integración de Fourvenues con Ágora: entradas canjeables Portal: General · Reservas y ticketing URL: https://connectmanager.es/docs/integracion-fourvenues-agora Actualizado: 2026-10-03 La integración de **Fourvenues** con **Ágora** lleva al TPV las entradas que el local vende en Fourvenues: cada 15 minutos Connect Manager descarga los eventos próximos y sus entradas, y las carga en Ágora como entradas canjeables (cupones) hasta que termina el evento. Así, en barra o en caja se puede canjear lo que incluye cada entrada leyendo su código, y las entradas anuladas dejan de valer. Este manual es para el técnico de FOS o del distribuidor que configura la integración en un local que vende con Fourvenues. ## Qué hace la integración - Cada 15 minutos descarga de Fourvenues los eventos del local desde el día anterior hasta los próximos días, y de cada evento las entradas creadas o modificadas desde la última descarga. - Carga cada entrada en Ágora como entrada canjeable (cupón), con el código de la entrada de Fourvenues, el tipo de entrada de Ágora que le corresponda y válida hasta el final del evento (24 horas después del inicio si Fourvenues no indica la hora de fin). - Asigna el tipo de entrada de Ágora por el nombre de la tarifa de Fourvenues: primero con la tabla de **Tipos de entrada**, después con los **Patrones de búsqueda** y, si no encaja ninguno, con el tipo de entrada por defecto. - Cuando una entrada deja de estar activa en Fourvenues, la vuelve a cargar en Ágora ya caducada, para que no se pueda canjear. - Permite anular una entrada desde el panel, leyendo su código con la cámara o escribiéndolo, y restaurarla después; en los dos casos actualiza Ágora en el momento. - Guarda todas las entradas en **Entradas**, con su estado, si se han enviado a Ágora y el dato original de Fourvenues, y deja cambiar el tipo de entrada de una o varias y reenviarlas. ### Qué no hace - No carga las entradas cuyo tipo no tiene correspondencia en Ágora (ni por tabla, ni por patrón, ni por defecto): se quedan en Connect Manager como «No se ha enviado a Ágora». - No vende entradas ni crea eventos: solo lee lo que ya está en Fourvenues. - No avisa a Fourvenues de lo que se canjea en Ágora. - No factura las entradas. La pantalla tiene una sección **Config. de facturas** y otra de **Config. de envío de cancelación**, pero en la versión actual no generan facturas ni correos: no las actives sin hablar con FOS. ## Requisitos - **Cuenta de Fourvenues** del local con acceso de integración: un **Id. de integración** y su **Secret**, o una **X Api Key**. Los facilita Fourvenues. - **Local en Connect Manager** con la URL de la API y la API key de Ágora. FOS da de alta el local y la integración. - **API de Ágora accesible desde Internet**, con puerto abierto o con [Zero Connect](https://connectmanager.es/docs/zero-connect-instalacion): las entradas se cargan desde Connect Manager con la API de importación de Ágora. - **Tipos de entrada creados en Ágora** (la configuración de entradas o cupones), uno por cada cosa distinta que se canjea, con su identificador numérico. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Id. de integración y Secret | Fourvenues | int-12345 / •••••••• | Sí (o la X Api Key) | | X Api Key | Fourvenues | •••••••• | Sí (o Id. de integración y Secret) | | Nombres de las tarifas de Fourvenues | Panel de Fourvenues del local | ENTRADA GENERAL + COPA | Sí | | Id. de cada tipo de entrada en Ágora | Configuración de entradas de Ágora | 3 | Sí | | Tipo de entrada por defecto | Ágora (uno de los anteriores) | 1 | Recomendado | ## Configuración paso a paso ### En Fourvenues - Pide a Fourvenues las credenciales de integración del local (Id. de integración y Secret, o X Api Key). - Saca la lista de tarifas que vende el local con su nombre exacto: es lo que se usará para elegir el tipo de entrada en Ágora. ### En Ágora - Crea un tipo de entrada por cada cosa que se canjea (por ejemplo, una consumición o un acceso) y apunta su identificador. - Decide cuál será el tipo por defecto para las tarifas nuevas que aparezcan sin configurar. ### En Connect Manager - En `https://app.connectmanager.es`, ve a **Administración → Locales**, abre el local y revisa la **URL de API** y la **API key** de Ágora. Pulsa **Guardar**. - Entra en **Integraciones de entradas**, pulsa **Añadir** y en **Proveedor** elige **Four venues**. - En **Configuración de autenticación** rellena **Id. de integración.:** y **Secret**, «… o …» la **X Api Key**. Si están los dos primeros, se usan ellos. - En **Id. de entrada por defecto** pon el identificador del tipo de entrada de Ágora para las tarifas sin configurar. Si lo dejas vacío, esas entradas no se cargan. - Deja desmarcadas **Enviar por email los tickets cancelados** y **Generar facturación diaria**, y pulsa **Guardar**. - En la pestaña **Tipos de entrada**, pulsa **Añadir** por cada tarifa: **Nombre de entrada en el proveedor** (el nombre de la tarifa en Fourvenues) e **Id. de tipo de entrada en Agora**. El nombre se compara sin distinguir mayúsculas ni espacios al principio o al final. - Si muchas tarifas comparten una parte del nombre, usa la pestaña **Patrones de búsqueda**: **Patrón de búsqueda** es una expresión regular con sus delimitadores (por ejemplo `/VIP/i` para todo lo que contenga «VIP») y su **Id. de tipo de entrada en Agora**. La primera vez que una tarifa encaja con un patrón o con el tipo por defecto, se añade sola a la tabla de **Tipos de entrada**. > [!TIP] Revisa la tabla de **Tipos de entrada** después del primer evento: verás las tarifas que se han asignado solas al tipo por defecto y podrás corregirlas. ## Cómo funciona Cada 15 minutos, Connect Manager pide a Fourvenues los eventos del local y, para cada uno, las entradas modificadas desde la última vez (con cinco minutos de margen), de 500 en 500 y hasta 5.000 por evento en cada pasada. Guarda las entradas, decide el tipo de entrada de Ágora de cada una y manda a Ágora, en un único envío por evento, las que son nuevas o han cambiado. Si Ágora las acepta, quedan marcadas como enviadas. ```mermaid sequenceDiagram participant CM as Connect Manager participant FV as Fourvenues participant AG as API Ágora loop Cada 15 minutos CM->>FV: Eventos del local FV-->>CM: Eventos de ayer a los próximos días CM->>FV: Entradas modificadas de cada evento FV-->>CM: Entradas con código, tarifa y estado CM->>CM: Asigna el tipo de entrada de Ágora CM->>AG: Importa las entradas nuevas o cambiadas AG-->>CM: Importación correcta CM->>CM: Marca las entradas como enviadas end ``` ### Qué se envía a Ágora - **Tipo de entrada**: el de la tabla, el del patrón o el de por defecto. - **Código**: el código de la entrada de Fourvenues, que es el que se lee al canjear. - **Fecha de creación** y **validez**: hasta el final del evento. Las entradas que ya no están activas en Fourvenues, o que se anulan desde el panel, se envían con una validez pasada y dejan de poder canjearse. ### Anular y restaurar desde el panel En **Entradas → Canc. entrada** se lee el código de barras o QR con la cámara del dispositivo (o se escribe) y la entrada se anula: Connect Manager la marca como cancelada y la reenvía a Ágora caducada. En **Entradas → Rest. entrada** se listan las anuladas y se restauran, volviendo a enviarlas con la validez del evento. En resumen, una entrada llega a Ágora solo si su tarifa tiene tipo de entrada (por la tabla, por un patrón o por el de por defecto); si no, se queda sin enviar. Una vez cargada, se puede canjear hasta el final del evento mientras siga activa en Fourvenues; si deja de estarlo o se anula en el panel, se vuelve a cargar caducada. ```mermaid flowchart LR A[Entrada en Fourvenues] --> B{Tarifa con tipo de Ágora} B -- Tabla, patrón o por defecto --> C[Se carga en Ágora] B -- Ninguno --> D[No se envía a Ágora] C --> E{Sigue activa} E -- Sí --> F[Canjeable hasta el fin del evento] E -- No o anulada en el panel --> G[Se recarga caducada] ``` ### Si algo falla - Si Fourvenues no responde, la descarga de ese evento se reintenta tres veces y, si sigue fallando, se avisa a FOS; la siguiente pasada vuelve a pedir lo pendiente. - Si Ágora rechaza el envío o no responde, las entradas siguen como no enviadas y se reintentan en la siguiente pasada. - Si aparecen tarifas sin tipo de entrada, FOS recibe un aviso con la lista para darlas de alta. ## Comprobar que funciona - Con un evento publicado en Fourvenues para los próximos días, vende o emite una entrada de prueba. - Espera a la siguiente pasada (como mucho 15 minutos) y busca la entrada en **Entradas**: debe aparecer con su código y «Enviado a Ágora». - En Ágora, canjea la entrada leyendo su código: debe aceptarla con el tipo de entrada esperado. - Anúlala en **Canc. entrada** e intenta canjearla otra vez en Ágora: debe rechazarla. - Restáurala en **Rest. entrada** y comprueba que vuelve a ser válida. - Anula una entrada en Fourvenues y comprueba, tras la siguiente pasada, que en Ágora ha dejado de valer. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Las entradas aparecen en Connect Manager pero «No se ha enviado a Ágora» | Su tarifa no tiene tipo de entrada y no hay tipo por defecto. | Añade la tarifa en Tipos de entrada o rellena Id. de entrada por defecto; desde Entradas puedes asignar el tipo y reenviarlas con Cambiar tipo de entrada. | | No llega ninguna entrada | Credenciales de Fourvenues incorrectas, o el evento está fuera de la ventana de días. | Revisa Id. de integración y Secret o X Api Key, y la fecha del evento. | | Las entradas no se marcan como enviadas | Connect Manager no llega a la API de Ágora o el tipo de entrada no existe en Ágora. | Comprueba la URL de API y la API key del local (o Zero Connect) y los identificadores de los tipos de entrada. | | Una entrada se canjea con el tipo equivocado | La tarifa se asignó por patrón o por defecto. | Corrige su fila en Tipos de entrada y cambia el tipo de las entradas ya cargadas desde Entradas. | | Una entrada válida aparece caducada en Ágora | En Fourvenues ya no está activa, o se anuló desde el panel. | Revisa su estado en Fourvenues y, si procede, restáurala en Rest. entrada. | | Un patrón no encaja con nada | Falta el delimitador de la expresión regular. | Escríbelo con barras: /texto/i. | ## Preguntas frecuentes ### ¿Cómo conecto Fourvenues con Ágora? Dando de alta en Connect Manager una integración de entradas «Four venues» con las credenciales de Fourvenues y relacionando cada tarifa con un tipo de entrada de Ágora. ### ¿Cada cuánto llegan las entradas vendidas? Cada 15 minutos. Una entrada vendida justo después de una pasada tarda como mucho ese tiempo en poder canjearse. ### ¿Qué pasa con una entrada anulada en Fourvenues? En la siguiente pasada se vuelve a cargar en Ágora caducada y ya no se puede canjear. ### ¿Hasta cuándo se puede canjear una entrada en Ágora? Hasta el final del evento que indica Fourvenues, o 24 horas después del inicio si el evento no tiene hora de fin. ### ¿Se facturan las entradas en Ágora? No. La facturación de entradas que aparece en la configuración no está funcionando en la versión actual. ## Referencias - Ficha de la integración: [Fourvenues en el catálogo de Connect Manager](https://connectmanager.es/integraciones/fourvenues). - [Zero Connect: publicar la API de Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion). - Fourvenues: [https://www.fourvenues.com](https://www.fourvenues.com). --- # Integración de TheFork con Ágora: reservas Portal: General · Reservas y ticketing URL: https://connectmanager.es/docs/manual-the-fork Actualizado: 2026-10-03 ## Manual de uso: Integración de Reservas TheFork con Ágora Este manual explica, paso a paso, cómo configurar la integración de reservas entre **TheFork**, **Connect Manager** y **Ágora POS**, asegurando la correcta sincronización de reservas en el sistema. ### **1. Creación o edición del local en Connect Manager** - En el menú lateral izquierdo, accede a **Administración**. - Haz clic en **Locales**. - Selecciona el local que quieres editar. ### **2. Datos del Local** En la pantalla de detalle del local, completa o revisa los siguientes campos: - **Cliente**: Ponemos el nombre del distribuidor. EJ. “Informática Pepe” - **Nombre**: Lo nombramos siempre de la siguiente forma: Nombre distribuidor – Nombre del local Donde se encuentra el local (Retiro/Sol/Bernabeu) - **URL de API**: Si es un Cloud usamos la URL del ACMS. Si es solo un local tenemos que poner la URL de la terminal Ágora perteneciente al local. - **API key**: Usamos la Api Key del ACMS en caso de que sean varios locales. Si es un único local tenemos que poner la API Key de la terminal Ágora perteneciente al local. - **Dirección:**La dirección correspondiente - **Ciudad:**En que ciudad se ubica el local - **Zona horaria**La zona horaria Una vez completados los datos, pulsa **Guardar**. En ese momento los módulos del lado derecho estarán habilitados. Posteriormente pinchamos en "Integraciones de Reservas" y accedemos a la sección que pone "The Fork" ### **3. Creación de la integración de reservas** En la sección Configuración, completa: - **Proveedor:** Tendrás TheFork asignado. - **URL API:** [https://api.thefork.io/](https://api.thefork.io/) (Es siempre la misma url para todos los locales) - **Id. de cliente:** Se genera al final de forma automática - **Email receptor de notificaciones:** El email a donde llegarán los correos avisando de cualquier cambio. - Verifica que el sistema muestra el **Token de Ágora y TheFork** correctamente. Aparece en color verde, proporcionado por The Fork. Guardas, sales y al entrar de nuevo debería aparecer de forma automática. ### **4. Configuración de Mesas** - Accede a **Mesas**. - Pulsa **Añadir** para crear una nueva mesa. - Introduce: - **Id de la mesa:**El Id de las mesas debe de ser igual al id de las mesas que hay en Ágora, de lo contrario no se generará una conexión. - **Nombre** Guarda los cambios ### **5. Configuración de Turnos** - En el paso 3 del asistente, accede a **Turnos**, se encuentra al lado de la sección de "Mesas" - Pulsa **Añadir**. - Introduce los datos del turno: - **Id** - **Nombre** (por ejemplo: Todo el día) - **Hora de inicio** - **Hora de fin** - Guarda la configuración. Nota: El rango horario debe cubrir el horario real del restaurante para que las reservas se reciban correctamente. Es Obligatorio. ### **6. Activación del módulo de reservas en Ágora** - Abre Ágora y accede a **Herramientas** (arriba a la izquierda) **Activar Módulos Adicionales**. - Marca la opción correspondiente al módulo de reservas online. - En el desplegable **Módulo de reservas online**, selecciona: Personalizado - En la sección **Configure los parámetros de reservas de Ágora**, introduce la siguiente URL que siempre es la misma [https://api.connectmanager.es](http://api.connectmanager.es)**.**Luego introduce la API Key que aparece en la siguiente imagen, que se copia en la sección de configuración: - - Pulsa **Probar conexión** para verificar que la comunicación es correcta. - Si la conexión es exitosa, pulsa **Aceptar** para guardar los cambios. ### **7. Activación en TheFork Manager** Una vez configurado Connect Manager, es necesario vincular el POS desde TheFork Manager. - Accede a **TheFork Manager**. - En el menú lateral, pulsa **Ajustes** (icono de engranaje). - Entra en **Integraciones y herramientas**. - Haz clic en **Integraciones**. Se abrirá la pantalla de integraciones disponibles. - En la sección **Punto de venta**, localiza **Ágora**. - Si aparece como disponible, pulsa para activarlo. - Si ya aparece como activo, verifica que el estado figure como **ACTIVADO**. Nota: Si Ágora no está activado en TheFork Manager, las reservas no se enviarán al POS aunque la configuración técnica esté correcta. Esos módulos son activados por The Fork. --- # Correo electrónico: proveedores de envío de Fidelización y tienda Portal: General · Comunicación URL: https://connectmanager.es/docs/correo-proveedores-de-envio Actualizado: 2026-10-03 Los correos de Fidelización y de la tienda online del delivery propio de Connect Manager, la plataforma que conecta servicios con **Ágora**, salen por el **Amazon SES** de la plataforma o por el proveedor de correo del propio club: SMTP, Amazon SES con sus claves, Resend, Brevo, Mailgun, Postmark, Mailjet, MailerSend o Mailchimp Transactional. Este manual es para el técnico que elige y configura ese proveedor: qué datos pedir, dónde se ponen en cada panel, qué hay que preparar en el dominio, cómo funciona el seguimiento de aperturas y rebotes y qué hacer cuando un correo no llega. ## Qué hace la integración - **Un proveedor de correo por grupo**, compartido por Fidelización y por la tienda online: la pantalla de correo de la tienda edita la misma configuración que Fidelización. - **«Servicio propio»** (el de serie): los correos salen por el envío de la plataforma, sin que el club contrate nada. Cuando FOS tiene activo el Amazon SES de la plataforma, salen por él con un remitente del dominio de la plataforma propio de cada club y el nombre del club; si no, por el correo general de la plataforma. - **Proveedor del club con sus propias claves**: SMTP de cualquier proveedor, Amazon SES por SMTP o por API, Resend, Brevo, Mailgun, Postmark, Mailjet, MailerSend, Mailchimp Transactional (Mandrill) y Bird. - **Por ese proveedor salen todos los correos del grupo**: el acceso al área del socio, la bienvenida, el envío de la tarjeta del móvil, los avisos de cupón, nivel, cumpleaños y recuperación, las campañas, las tarjetas regalo, los correos de socios, las entradas y los recordatorios de eventos, y en la tienda el enlace de acceso, el pedido confirmado, el «listo / en camino» y el aviso interno de pedidos que no entran en el TPV. - **Seguimiento propio de las campañas**, con cualquier proveedor: aperturas por un píxel, clics por enlaces firmados y bajas por un enlace en el pie. - Con el Amazon SES de la plataforma, además, **entregas, rebotes y quejas** de cada correo de campaña, y la dirección que rebota en duro o se queja como spam se suprime sola. - **Lista de supresiones por grupo** (bajas, rebotes, quejas y altas manuales) que deja fuera esas direcciones de las campañas. - Las campañas por correo llevan la **cabecera de baja en un clic** que piden Gmail y Yahoo cuando salen por el envío de la plataforma, por SMTP o por Amazon SES. - Las campañas se envían a un ritmo limitado (de serie, 13 correos por segundo) para no pasar la cuota del envío. ### Qué no hace - Los proveedores por API (Resend, Brevo, Mailgun, Postmark, Mailjet, MailerSend y Mailchimp Transactional) y Bird envían solo el HTML: **sin adjuntos** (como el justificante en PDF de las entradas), sin la cabecera de baja en un clic y sin registro de rebotes ni quejas. - Los rebotes y las quejas solo se registran solos con el Amazon SES de la plataforma. - La lista de supresiones solo frena las campañas: los correos de servicio (acceso, pedidos, entradas) se siguen enviando. - No configura el DNS del dominio del cliente: los registros SPF y DKIM los añade quien gestione ese dominio. - En la pantalla de correo de la tienda solo se ofrecen «Servicio propio», «SMTP» y «Amazon SES SMTP» (si el grupo ya tenía otro proveedor, se conserva). - Con «Servicio propio» el remitente no es una dirección del dominio del restaurante: las respuestas se recogen con «Responder a». - El botón «Enviar prueba» de la tienda y la prueba del «Email de acceso» de Fidelización salen por el correo general de la plataforma, no por el proveedor elegido. ## Requisitos - **Con «Servicio propio»**: nada que contratar. FOS mantiene el Amazon SES de la plataforma (dominio verificado con DKIM y cuenta fuera del modo de pruebas) y el correo general. - **Con un proveedor del club**: cuenta activa en el proveedor, el dominio o la dirección remitente **verificados** en él (con sus registros DKIM y SPF en el DNS del dominio) y las credenciales de envío. En Amazon SES, además, la cuenta fuera del modo sandbox. - **Permisos**: `Fidelización: Activar por grupo` para el portal de Fidelización y `Delivery: Configurar locales` para la pantalla de correo de la tienda. - **Quién hace qué**: el cliente contrata el proveedor y verifica su dominio (o pide a su informático que añada los registros DNS); el distribuidor pone las credenciales y prueba; FOS mantiene el envío de la plataforma, las colas y el seguimiento de Amazon SES. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Proveedor elegido | Cliente | Servicio propio, SMTP, Amazon SES SMTP, Amazon SES (API), Resend, Brevo, Mailgun, Postmark, Mailjet, MailerSend, Mailchimp Transactional o Bird | Sí | | Nombre del remitente | Cliente | «Restaurante Demo» | Sí | | Responder a | Cliente: un buzón que se lea | hola@restaurante-demo.es | Recomendado | | Remitente (email) verificado | Cliente, verificado en su proveedor | club@restaurante-demo.es | Con proveedor propio | | SMTP: servidor, puerto, usuario, contraseña y cifrado | Proveedor de correo del cliente | smtp.proveedor-demo.com · 587 · tls (o 465 · ssl) | Con SMTP | | Amazon SES SMTP: usuario, contraseña y región | Consola de AWS del cliente: credenciales SMTP de SES (no la clave de API de AWS) | Región eu-west-1 | Con Amazon SES SMTP | | Amazon SES API: Access Key ID, secreto y región | Consola de AWS del cliente | Región eu-west-1 | Con Amazon SES (API) | | API Key | Panel de Resend, Brevo, MailerSend o Mailchimp Transactional; en Postmark, el Server Token | Cadena secreta | Con esos proveedores | | Mailgun: API Key, dominio y región | Panel de Mailgun | Dominio mg.restaurante-demo.es · región eu (vacío: EE. UU.) | Con Mailgun | | Mailjet: API Key y Secret | Panel de Mailjet (clave pública y clave privada) | Dos cadenas secretas | Con Mailjet | | Bird: Workspace ID, Access Key y Channel ID | Panel de Bird | Identificadores de Bird | Con Bird | | Registros DNS de verificación (DKIM, SPF) | Los da el proveedor; los añade quien gestiona el dominio | Registros TXT o CNAME | Con proveedor propio | | Correos de los avisos internos de la tienda | Cliente | encargado@restaurante-demo.es | Recomendado si hay tienda | ## Configuración paso a paso ### En el proveedor de correo (solo si el club usa el suyo) - Da de alta el dominio o la dirección remitente y verifícalo con los registros DNS que indique el proveedor (DKIM y, si lo pide, SPF). - Genera las credenciales: usuario y contraseña SMTP o una clave de API con permiso de envío. En Amazon SES, las credenciales SMTP se generan aparte en la consola de SES y no son la clave de API de AWS. - En Amazon SES, pide el acceso de producción si la cuenta sigue en modo sandbox; en Mailgun, anota el dominio de envío y si la cuenta es de la región europea. ### En Connect Manager: Fidelización - En `/fidelizacion`, ve a **Configuración → Portal público de clientes**, abre el grupo y entra en la sub-página **Fidelización**. - En «Servicios de comunicación (proveedores)», en el desplegable **Email**, elige el proveedor. Aparecen solo los campos que necesita y, en SMTP, Amazon SES SMTP, Mailgun, Postmark y Mailjet, una nota con lo que significa cada uno. Rellénalos y guarda. - En la sub-página **Comunicaciones**, con «Email de acceso (enlace mágico)» seleccionado, revisa **Nombre del remitente**, **Email remitente** y **Responder a (reply-to)**, y personaliza y activa cada comunicación. > [!WARNING] Con «Servicio propio», deja **Email remitente** vacío salvo que FOS te confirme que esa dirección está verificada en el envío de la plataforma: el envío por Amazon SES solo admite remitentes verificados. Para recibir las respuestas usa «Responder a». ### En Connect Manager: la tienda online - En `/delivery-propio`, ve a **Configuración → Tienda pública → Correo**. - En «Quién envía»: **Nombre del remitente**, **Dirección del remitente** (solo aparece con un proveedor del club) y **Responder a**. - En «Correo de acceso a la tienda», si quieres cambiar el texto por defecto: **Asunto**, **Texto** y **Pie**, con los marcadores `{customer_name}`, `{tienda}`, `{magic_link}` y `{minutos}`. En blanco sale el texto por defecto. - En «Servicio de envío», elige **Servicio** («Servicio propio», «SMTP» o «Amazon SES SMTP») y rellena sus campos. Es la misma configuración de Fidelización: cambiarla aquí la cambia para todo el grupo. - En «Avisos internos», rellena **Avisar a** con los correos que deben enterarse de un pedido cobrado que no entra en el TPV. - Pulsa **Guardar**. ### Seguimiento con el Amazon SES de la plataforma (lo hace FOS) - En la cuenta de AWS de la plataforma, crea un **Configuration Set** de SES que publique los eventos de entrega, rebote y queja en un tema de SNS, y desactiva en él el seguimiento de aperturas y clics de SES (se usa el propio). - Suscribe ese tema por HTTPS a `https://hub.connectmanager.es/api/loyalty/webhooks/ses`; la suscripción se confirma sola. - Pon el nombre del Configuration Set en la configuración del servidor y deja activa la comprobación de la firma de SNS. ## Cómo funciona ### Por dónde sale cada correo Cada correo del club o de la tienda pasa por un único punto de envío que mira el proveedor de email del grupo. Con «Servicio propio» y el Amazon SES de la plataforma activo, sale por él con el remitente del club en el dominio de la plataforma (el «Email remitente» si lo hay o uno que se forma con el nombre corto del grupo); la excepción es el enlace de acceso de la tienda, que con servicio propio sale siempre por el correo general de la plataforma, porque es un correo suelto que alguien espera con la pantalla abierta. Con SMTP o Amazon SES, el correo se encola y se envía con las credenciales del club (por SMTP, con 8 segundos de espera máxima por intento y un reintento si la conexión se había cerrado). Con los proveedores por API y con Bird se llama directamente a su API con el remitente, el destinatario, el asunto y el HTML. ```mermaid flowchart TD M[Correo del club o de la tienda] --> P{Proveedor de email del grupo} P -- Servicio propio --> T{Enlace de acceso de la tienda} T -- Sí --> G[Correo general de la plataforma] T -- No --> S{Amazon SES de la plataforma activo} S -- Sí --> SES[Amazon SES de la plataforma] S -- No --> G P -- SMTP o Amazon SES --> Q[Cola de envío con las credenciales del club] P -- Proveedor por API --> API[API del proveedor, solo HTML] P -- Bird --> B[API de Bird, solo HTML] ``` ### El seguimiento de las campañas Cada destinatario de una campaña tiene un identificador propio. El cuerpo se monta para él con un píxel de apertura, los enlaces reescritos y firmados para contar los clics sin permitir redirecciones a cualquier sitio, y un enlace de baja; los accesos de escáneres de correo se descartan. Cuando el correo sale por el envío de la plataforma, por SMTP o por Amazon SES, lleva además la cabecera de baja en un clic y una cabecera con el identificador del destinatario. Con el Amazon SES de la plataforma, SES publica en SNS la entrega, el rebote o la queja y SNS los manda a Connect Manager, que comprueba la firma, encuentra al destinatario por esa cabecera, actualiza la campaña y suprime la dirección si el rebote es duro o es una queja. El enlace de baja abre una página de confirmación (así los escáneres de correo no dan de baja a nadie por error) y, al confirmar, suprime la dirección en ese grupo; se puede deshacer desde la misma página. La baja desde el enlace de otros correos del club, además, retira el consentimiento de correo de la ficha del cliente. ```mermaid sequenceDiagram participant H as Connect Manager participant S as Amazon SES participant C as Destinatario participant N as SNS H->>S: Campaña con píxel, enlaces firmados y cabecera del destinatario S->>C: Entrega el correo C->>H: Abre el correo o pulsa un enlace S->>N: Evento de entrega, rebote o queja N->>H: Notificación firmada al webhook de SES H->>H: Actualiza el destinatario y suprime si rebota en duro o se queja ``` ### Dónde se ve - En **Administración → Campañas** de `/fidelizacion`, los resultados de cada campaña: enviados, entregados, aperturas, clics, rebotes, quejas y bajas, con la opción de reenviar a quien no la abrió. - En **Administración → Supresiones**, las direcciones que no reciben campañas con su motivo: «Baja», «Rebote», «Spam» o «Manual». Se pueden añadir a mano y quitar. - En la ficha de cada cliente, su historial de comunicaciones, incluidos los enlaces de acceso que pidió. ## Comprobar que funciona - Guarda el proveedor. En Fidelización → **Comunicaciones**, selecciona una comunicación de email que no sea la de acceso (por ejemplo «Email de bienvenida») y pulsa **Enviar prueba** con un correo tuyo: esa prueba sí sale por el proveedor elegido. - Revisa la bandeja de entrada y la de spam, y en las cabeceras del mensaje comprueba que SPF y DKIM pasan. - Si se van a mandar campañas, crea una en Administración → Campañas y usa su **Enviar prueba**: sale por el proveedor real y no da de alta a nadie. - Si hay tienda online, pide el enlace de acceso desde la tienda con un correo de un cliente de prueba y haz un pedido de prueba para recibir el correo de pedido confirmado. - Con el Amazon SES de la plataforma, después de enviar una campaña de prueba debe aparecer la entrega en sus resultados. > [!NOTE] «Enviar prueba» en Tienda pública → Correo, y en Fidelización con la comunicación «Email de acceso (enlace mágico)», salen por el correo general de la plataforma: sirven para revisar el texto, no las credenciales del proveedor. Además, la prueba de Comunicaciones y la de la tienda dan de alta (o reutilizan) en el club un cliente con ese correo: usa una dirección interna. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «Guarda antes la configuración» al enviar la prueba de la tienda | El grupo todavía no tiene configuración guardada | Pulsa Guardar y vuelve a probar | | La prueba de la tienda llega pero los correos reales no | La prueba sale por el correo de la plataforma; el proveedor elegido falla | Prueba el proveedor desde Fidelización → Comunicaciones con otra comunicación y revisa sus credenciales y su remitente | | Con un proveedor por API no sale nada | Remitente sin verificar, clave equivocada o sin permiso de envío | Verifica el remitente en el proveedor y revisa la clave; el registro del servidor guarda el código de error del proveedor | | Mailchimp Transactional dice que acepta pero no entrega | Mandrill contesta bien aunque rechace al destinatario (lista negra, dominio sin reputación) | Connect Manager lo cuenta como fallido; revisa el motivo de rechazo en el panel de Mailchimp Transactional | | Amazon SES rechaza el envío por remitente no verificado | La dirección o el dominio no están verificados en esa cuenta, o la cuenta está en sandbox | Verifica el dominio con DKIM y pide el acceso de producción | | SMTP no conecta | Puerto y cifrado no casan | Usa tls con el puerto 587 o ssl con el 465, y revisa usuario y contraseña | | Los correos llegan a spam | Dominio sin DKIM o SPF, o remitente que no corresponde al dominio verificado | Añade los registros DNS del proveedor; con servicio propio no cambies el remitente | | Las respuestas de los clientes se pierden | No hay «Responder a» y el remitente es de solo envío | Rellena «Responder a» con un buzón que se lea | | Un cliente no recibe las campañas | Está en Supresiones (baja, rebote o spam) | Quítalo solo si él lo pide expresamente | | No aparecen rebotes ni quejas en los resultados | El proveedor no es el Amazon SES de la plataforma, o falta el Configuration Set y el tema de SNS | Es lo esperado con otros proveedores; con el SES de la plataforma, avisa a FOS | | Las entradas llegan sin el justificante en PDF | El proveedor es de API o Bird, que no admiten adjuntos | Usa SMTP, Amazon SES o servicio propio si se necesitan adjuntos | | El enlace de acceso no llega a buzones corporativos de Microsoft 365 | Cuarentena o protección contra suplantación del servidor del destinatario | Que el cliente revise su cuarentena; mira el historial de comunicaciones del cliente para confirmar que se envió | ## Preguntas frecuentes ### ¿Qué proveedor de correo uso para Fidelización y la tienda online de Ágora? Si el club no tiene uno propio, «Servicio propio»: sale por el envío de la plataforma, con Amazon SES y el seguimiento completo de rebotes. Si quiere enviar desde su dominio, elige su proveedor (SMTP, Amazon SES, Resend, Brevo, Mailgun, Postmark, Mailjet, MailerSend o Mailchimp Transactional) y verifica el dominio en él. ### ¿Puedo enviar los correos desde el dominio del restaurante? Sí, con un proveedor propio en el que ese dominio esté verificado. Con «Servicio propio» el remitente es del dominio de la plataforma y las respuestas van a «Responder a». ### ¿Cómo se registran las aperturas y los rebotes de las campañas? Las aperturas, los clics y las bajas los cuenta Connect Manager con su píxel y sus enlaces, con cualquier proveedor. Las entregas, los rebotes y las quejas solo llegan con el Amazon SES de la plataforma, a través de SNS. ### ¿Por qué no llegan los adjuntos con Brevo, Resend o Mailgun? Porque con esos proveedores se envía solo el HTML por su API. Si hacen falta adjuntos, como el justificante de las entradas, usa SMTP, Amazon SES o el servicio propio. ### Si cambio el proveedor en la tienda, ¿cambia también el del club? Sí. La tienda y Fidelización comparten la misma configuración de correo del grupo. ### ¿Qué pasa cuando un cliente se da de baja de las campañas? Su dirección entra en Supresiones con el motivo «Baja» y deja de recibir campañas de ese grupo. Los correos de servicio, como el acceso o los pedidos, le siguen llegando. Si se arrepiente, puede deshacerlo desde la misma página de baja. ## Referencias - [Ficha de Amazon SES en el catálogo](https://connectmanager.es/integraciones/amazon-ses) y las de [Resend](https://connectmanager.es/integraciones/resend), [Brevo](https://connectmanager.es/integraciones/brevo), [Mailgun](https://connectmanager.es/integraciones/mailgun), [Postmark](https://connectmanager.es/integraciones/postmark), [Mailjet](https://connectmanager.es/integraciones/mailjet), [MailerSend](https://connectmanager.es/integraciones/mailersend) y [Mailchimp Transactional](https://connectmanager.es/integraciones/mailchimp-transactional) - [Fidelización: conectar el club con Ágora](https://connectmanager.es/docs/fidelizacion-conectar-con-agora) y [WhatsApp y Bird: mensajes y campañas del club](https://connectmanager.es/docs/fidelizacion-whatsapp-bird) - [Delivery propio: conectar la tienda online con Ágora](https://connectmanager.es/docs/delivery-propio-conectar-con-agora) - [Redsys: pasarela de pago de la tienda y de Fidelización](https://connectmanager.es/docs/pagos-redsys) - [Guía de Amazon SES](https://docs.aws.amazon.com/ses/latest/dg/Welcome.html) - [Credenciales SMTP de Amazon SES](https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html) --- # Integración de Telegram con Ágora: avisos de las integraciones Portal: General · Comunicación URL: https://connectmanager.es/docs/integracion-telegram-agora Actualizado: 2026-10-03 La integración de **Telegram** con **Ágora** hace llegar a un chat o a un grupo de Telegram los avisos de error y los ficheros que generan las integraciones de Ágora de un local: un salto en la numeración de las facturas de ARCA, un pedido de la tienda online que no entra en Ágora, un fallo de una exportación contable o el PDF de un informe. Cada integración tiene su propio campo de chat, así que cada aviso puede ir a quien le toca. Este manual es para el técnico de FOS o del distribuidor que deja configurados esos avisos. No es una integración que se dé de alta por separado: es un campo más en las integraciones que lo admiten, en `https://app.connectmanager.es`. ## Qué hace la integración - Manda los mensajes desde el bot de Telegram de Connect Manager al chat que indiques: una conversación privada con el bot o un grupo en el que esté el bot. - **Integraciones fiscales (AFIP / ARCA)**: avisa de los saltos de numeración de los comprobantes que encuentra la revisión de cada hora. - **Integraciones de pedidos (WooCommerce)**: avisa cuando un pedido no se puede procesar, por ejemplo porque falta configuración en la integración o porque el proceso falla. - **Integraciones de contabilidad (Workday, Querry (SII), GSD (SAP) y SAP HANA (BTP))**: avisa de los errores de la generación o del envío, con el local, la fecha y el mensaje del error. - **Integraciones de informes** (Ventas por periodo del día, JDE Avanza, Informe de cierre de caja) **y de etiquetas** (Cambios de precio): envía el PDF al chat cada vez que se genera, además de por correo. - Permite un chat distinto en cada integración del local, y deja el campo vacío para no usar Telegram en esa integración. - Además, FOS recibe los mismos avisos de error en su propio canal interno, aunque no haya chat configurado. ### Qué no hace - No genera los informes por sí misma: solo entrega lo que generan las integraciones. Si un informe no llega tampoco por correo, el problema está en la integración de informes, no en Telegram. - No permite elegir el chat en las integraciones de Uber Eats, Glovo y Just Eat: su pantalla no muestra el campo de Telegram y sus avisos se configuran por correo. - No envía avisos en la integración fiscal de efsta (Portugal), aunque su pantalla tenga el campo. - No sirve para hablar con el bot: el chat está pensado solo para recibir avisos. ## Requisitos - Una cuenta de **Telegram** y, si el aviso es para varias personas, un **grupo**. - El **nombre del bot de Connect Manager**, que facilita FOS. - La integración del local ya creada en Connect Manager (fiscal, de pedidos, de contabilidad, de informes o de etiquetas). El alta la hace FOS. - No hace falta abrir nada en la red del local: los mensajes salen de los servidores de Connect Manager hacia Telegram. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Nombre del bot de Connect Manager | FOS | @nombre_del_bot | Sí | | Grupo o persona que recibe los avisos | Cliente | Grupo «Avisos Local Demo» | Sí | | Id. del chat | FOS, una vez que el bot está en el chat | Grupo: -1001234567890; persona: 123456789 | Sí | | Integraciones que deben avisar a ese chat | Cliente y distribuidor | ARCA y Workday al grupo de administración | Sí | ## Configuración paso a paso ### En Telegram - Crea el grupo que recibirá los avisos (o usa una conversación privada si es para una sola persona). - Añade el bot de Connect Manager al grupo. Si es una conversación privada, abre el chat con el bot y pulsa **Iniciar**: un bot no puede escribir a quien no ha hablado antes con él. - Pide a FOS el id. de ese chat. Copia el número completo: en los grupos empieza por un signo menos, y sin él no funciona. ### En Connect Manager - En `https://app.connectmanager.es`, ve a **Administración → Locales** y abre el local. - Entra en el módulo de la integración y abre la integración: - **Integraciones fiscales** (AFIP): campo **Id. de chat de Telegram para recibir notificaciones**. - **Integraciones de pedidos** (WooCommerce): campo **Id. de chat de Telegram para recibir notificaciones**. - **Integraciones de contabilidad** (Workday, Querry (SII), GSD (SAP), SAP HANA (BTP)): campo **Id. de chat de Telegram para recibir notificaciones**. - **Integraciones de informes** (salvo los informes generales y tabulares en TPV) y **de etiquetas** (Cambios de precio): campo **Id. de chat de Telegram para recibir el archivo**. - Pega el id. del chat, sin espacios, y pulsa **Guardar**. - Repite en cada integración que deba avisar a ese chat. Para no usar Telegram en una integración, deja el campo vacío. > [!TIP] Usa grupos por tema (fiscal, pedidos, contabilidad) en lugar de uno para todo: cada integración tiene su campo y los avisos llegan a quien puede resolverlos. ## Cómo funciona Cuando una integración termina un proceso con error, o genera un fichero, prepara el mensaje y lo envía por dos caminos a la vez: al canal interno de FOS y, si la integración tiene chat configurado, al chat del cliente. El envío a Telegram se hace en segundo plano desde los servidores de Connect Manager a través del bot; si el aviso lleva un PDF, llega como documento adjunto con un texto que lo identifica. ```mermaid sequenceDiagram participant INT as Integración del local participant CM as Connect Manager participant TG as Bot de Telegram participant CHAT as Chat del cliente INT->>CM: Error o fichero generado CM->>CM: Prepara el aviso con local, fecha y detalle CM->>TG: Mensaje al canal interno de FOS CM->>TG: Mensaje o PDF al chat configurado TG-->>CHAT: Aviso en el grupo o en el chat privado ``` ### Qué mensajes llegan - **ARCA**: «Ocurrió un error en la numeración de documentos de AFIP:» seguido de los comprobantes afectados. - **WooCommerce**: «Generar pedido de WooCommerce (Error)» con el local, el proveedor y el error, o el aviso de revisar la configuración. - **Contabilidad**: «Ocurrió un error en …» con el nombre del proceso, el local, la fecha y el mensaje de la excepción. - **Informes y etiquetas**: el PDF generado, por ejemplo al pulsar **Generar facturación por periodos** o **Generar PDF** en el **Inicio** del panel. Cada aviso de error va siempre al canal interno de FOS. Al cliente le llega por Telegram solo si la integración tiene el id. de chat rellenado; si no, solo por correo, cuando la integración tiene correos configurados. ```mermaid flowchart LR A[Evento de una integración] --> B{Tiene chat de Telegram} B -- Sí --> C[Aviso al chat del cliente] B -- No --> D[Solo correo si lo tiene] A --> E[Aviso al canal interno de FOS] ``` ## Comprobar que funciona - Con el bot ya en el grupo, guarda el id. del chat en una integración de informes o de etiquetas. - En el **Inicio** de `https://app.connectmanager.es`, genera ese informe con su widget (**Generar facturación por periodos** o **Generar PDF**). - En unos minutos debe llegar el PDF al grupo y al correo configurado. - Si el chat es para avisos de error, comprueba con FOS que el id. es el del grupo correcto: no hay mensaje de prueba y el primer aviso llegará con el primer error real. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | No llega nada al grupo | El bot no está en el grupo o lo han expulsado. | Vuelve a añadir el bot y comprueba el id. con FOS. | | No llega nada al chat privado | La persona nunca ha iniciado la conversación con el bot. | Abre el chat con el bot y pulsa Iniciar. | | Funciona el correo pero no Telegram | Id. de chat mal copiado (sin el signo menos, con espacios) o de otro grupo. | Copia de nuevo el número completo. | | Los avisos llegan a un grupo equivocado | Varias integraciones comparten el id. de chat. | Revisa el campo en cada integración del local. | | No aparece el campo de Telegram en la integración | Ese tipo de integración no lo admite (Uber Eats, Glovo, Just Eat, informes generales y tabulares en TPV…). | Usa el correo de notificaciones de esa integración. | | El grupo pasó a supergrupo y dejó de recibir | Telegram cambia el id. del chat al convertir un grupo en supergrupo. | Pide a FOS el id. nuevo y actualízalo en las integraciones. | ## Preguntas frecuentes ### ¿Cómo recibo en Telegram los avisos de las integraciones de Ágora? Añade el bot de Connect Manager a un grupo, pide a FOS el id. de ese chat y pégalo en el campo de Telegram de cada integración del local. ### ¿Puedo mandar cada integración a un grupo distinto? Sí. Cada integración tiene su propio campo de chat. ### ¿Cuesta algo usar Telegram? No hace falta contratar nada aparte: es un canal más de las integraciones del local. ### ¿Llegan por Telegram los pedidos de Uber Eats, Glovo o Just Eat que fallan? No se puede configurar desde el panel: esas integraciones avisan por correo. ### ¿Puedo recibir el informe de ventas en PDF por Telegram? Sí: si la integración de informes tiene chat configurado, el PDF llega al chat cada vez que se genera. ## Referencias - Ficha de la integración: [Telegram en el catálogo de Connect Manager](https://connectmanager.es/integraciones/telegram). - [Integración de ARCA con Ágora](https://connectmanager.es/docs/integracion-argentina-arca-agora). - [Integración de WooCommerce con Ágora](https://connectmanager.es/docs/integracion-woocommerce-agora). - Bots de Telegram: [https://core.telegram.org/bots](https://core.telegram.org/bots). --- # Redsys: pasarela de pago de la tienda y de Fidelización Portal: General · Pagos URL: https://connectmanager.es/docs/pagos-redsys Actualizado: 2026-10-03 **Redsys** es el TPV virtual de los bancos españoles con el que Connect Manager cobra online en la tienda del delivery propio y en Fidelización: pedidos, tarjetas regalo, cuotas de socio, entradas de la agenda del club y pagos de eventos. El dinero va directo a la cuenta del comercio del cliente; Connect Manager prepara el pago, recibe la confirmación firmada del banco y hace lo que toca después, como meter el pedido cobrado en **Ágora** o emitir allí la factura de anticipo de un evento. Este manual es para el técnico que configura el TPV virtual de un cliente: qué datos pedir al banco, dónde ponerlos según lo que se cobre, cómo probar y qué hacer cuando un pago no cuadra. ## Qué hace la integración - **Cobra con tarjeta en el comercio de Redsys del propio cliente**, con su código de comercio (FUC), su terminal y su clave secreta SHA-256. El dinero no pasa por FOS. - **Pedidos de la tienda online**: un TPV por local. Si el banco los tiene activos en el terminal, el cliente puede elegir también **Bizum** o **Apple Pay / Google Pay** antes de ir al banco. - **Tarjetas regalo de la tienda online**: cobra el TPV del local que vende cada tarjeta. - **Tarjetas regalo del club, cuotas de socio** (alta y renovación) y **entradas de la agenda del club**: un TPV para todo el grupo. - **Pagos de las ofertas de eventos**: el TPV de cada local emisor; al conciliar el cobro se emite la factura de anticipo en Ágora. - **Entorno de pruebas o de producción** en cada comercio, para probar sin mover dinero. - **Solo da un pago por bueno con la notificación firmada** que Redsys manda de servidor a servidor: comprueba la firma con las credenciales que se usaron para ese pago (guardadas con el pago, así que cambiar la clave no rompe los pagos en curso), toma el importe del dato firmado por el banco y no repite nada si Redsys reintenta el aviso. - **Evita cobrar dos veces**: si el cliente vuelve atrás o abre otra pestaña con el mismo importe, se reutiliza el mismo número de pedido y el banco rechaza el repetido. - **Guarda la respuesta del banco para conciliar**: código de respuesta y de autorización con cada pago. En los pedidos de la tienda y en las entradas se guarda solo una lista cerrada de datos (fecha, número de pedido, importe, respuesta, autorización, marca y país de la tarjeta) con la tarjeta enmascarada a sus cuatro últimas cifras. - Devuelve al cliente a una pantalla de resultado con un **enlace firmado que caduca a las 4 horas**; esa pantalla lee el estado real del pago, no lo que diga el enlace. ### Qué no hace - No devuelve dinero: las devoluciones se hacen en el panel de Redsys. Cancelar un pedido, una tarjeta regalo, una membresía o una entrada en Connect Manager no reembolsa el cargo. - No cobra cuotas recurrentes de forma automática ni guarda tarjetas: cada renovación la paga el socio. - No recarga monederos del club con tarjeta desde la web. - Bizum y Apple Pay / Google Pay solo se eligen en los pedidos de la tienda online; en el resto se abre la página de pago estándar de Redsys. - No se entera de las devoluciones o anulaciones hechas en el panel de Redsys. - No trabaja con otras pasarelas de pago. ## Requisitos - Un **TPV virtual de Redsys** contratado por el cliente con su banco, con firma SHA-256: uno por local para la tienda online, uno de grupo para Fidelización y uno por local emisor para eventos (pueden ser el mismo comercio si el banco lo permite). - **Las credenciales de pruebas y las de producción**: la clave de pruebas y la real son distintas. - Si se quieren en la tienda, **Bizum y Apple Pay / Google Pay activados por el banco** en ese terminal. - Que el terminal tenga activada la **notificación online** (por HTTP): Connect Manager manda en cada pago la dirección a la que Redsys debe avisar. - En Ágora, la **forma de pago** con la que deben entrar los cobros online (pedidos y anticipos de eventos). - **Permisos en Connect Manager**: `Delivery: Configurar locales` para la tienda; además `Fidelización: Añadir saldo` para las tarjetas regalo de la tienda; `Fidelización: Activar por grupo` para el TPV del grupo; `Fidelización: Configurar eventos` para los locales de eventos. - **Quién hace qué**: el cliente contrata el TPV y consigue sus datos del banco; el distribuidor los pone en Connect Manager y hace la prueba; FOS mantiene la plataforma, que es la que recibe las notificaciones. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Código de comercio (FUC) | Banco del cliente | 123456789 | Sí | | Terminal | Banco del cliente | 1 | Sí | | Clave secreta (SHA-256) | Banco del cliente o módulo de administración de Redsys | Cadena secreta: pásala por un canal seguro | Sí | | Entorno | Lo decides tú: primero pruebas | Pruebas / Producción | Sí | | Credenciales del entorno de pruebas | Banco; en la tienda online se pueden usar las del comercio de demostración público de Redsys, que el panel rellena solo | FUC, terminal y clave de pruebas | Para probar | | Bizum, Apple Pay o Google Pay activos | Banco | Sí / No | No | | Forma de pago de Ágora para cobros online | Ágora (se elige de la lista en el panel) | «Tarjeta web» | Sí, para pedidos; recomendada en eventos | | Local que vende cada tarjeta regalo de la tienda | Cliente | «Restaurante Centro» | Solo tarjetas regalo de la tienda | ### Dónde se configura cada TPV | Qué se cobra | Dónde se ponen los datos de Redsys | De quién es el TPV | | Pedidos de la tienda online | /delivery-propio → Configuración → Locales → (local) → Pasarela de pago | Del local | | Tarjetas regalo de la tienda online | Se elige el local en Configuración → Tienda pública → Tarjetas regalo; cobra su pasarela | Del local que la vende | | Tarjetas regalo del club | /fidelizacion → Configuración → Portal público de clientes → (grupo) → Tarjetas regalo, apartado «TPV virtual del grupo (Redsys)» | Del grupo | | Cuotas de socio | El mismo TPV del grupo | Del grupo | | Entradas de la agenda del club | El mismo TPV del grupo | Del grupo | | Pagos de ofertas de eventos | /fidelizacion → Configuración → Configuración de eventos → Locales → (local emisor), apartado «Pago online (Redsys)» | Del local emisor | ## Configuración paso a paso ### En el banco (Redsys) - Pide al banco el TPV virtual con firma SHA-256 y anota FUC, terminal y clave, de pruebas y de producción. - Si el cliente quiere Bizum o Apple Pay / Google Pay en la tienda, pide que los activen en ese terminal. - Confirma con el banco que el terminal tiene la notificación online activada. No hace falta escribir ninguna dirección en Redsys: Connect Manager la manda en cada pago. ### En Connect Manager: pedidos de la tienda online - Ve a **Configuración → Locales**, abre el local y entra en **Pasarela de pago**. - Enciende **Cobrar por la pasarela**. - Elige el **Entorno**: «Pruebas» (el valor por defecto) o «Producción (cobra de verdad)». Al cambiar el entorno a Pruebas, los campos que estén vacíos se rellenan solos con el comercio de demostración público de Redsys. - Rellena **Código de comercio (FUC)**, **Terminal** y **Clave secreta (SHA-256)**. La clave se guarda cifrada y no se vuelve a enseñar: el campo vacío significa «no la cambies». - Enciende **Bizum** y **Apple Pay y Google Pay** solo si el banco los tiene activos en el terminal. - Pulsa **Guardar**. En el listado de locales, la columna «Cobro» indica si el local cobra y en qué entorno. - En **Reparto**, **Recogida** y **En mesa**, revisa la **Forma de pago** de Ágora con la que entran los pedidos pagados online. ### En Connect Manager: tarjetas regalo de la tienda online - El grupo tiene que tener configurado su club de fidelización (el saldo de la tarjeta vive en el monedero del club). - Ve a **Configuración → Tienda pública → Tarjetas regalo** y enciende **Vender tarjetas regalo**. - Crea cada tarjeta con su **Título**, el **Local que la vende** (solo salen los locales que pueden cobrar; en la plataforma real, solo los que tienen la pasarela en producción) y su importe fijo o libre. - Guarda. Si después cambian los datos de la pasarela de ese local, la tarjeta deja de venderse hasta que alguien con permiso para añadir saldo vuelva a guardar esta pantalla. ### En Connect Manager: TPV del grupo (tarjetas regalo del club, socios y entradas) - En `/fidelizacion`, ve a **Configuración → Portal público de clientes**, abre el grupo y entra en **Tarjetas regalo**. - En «TPV virtual del grupo (Redsys)», rellena **Código de comercio (FUC)**, **Terminal** y **Clave secreta (SHA-256)**, y elige el **Entorno** («Pruebas» o «Producción»; vacío, el global de la plataforma). - Guarda. Ese mismo TPV cobra las tarjetas regalo del club, las cuotas de socio (**Configuración → Configuración de socios**) y las entradas de la agenda (**Socios → Agenda**). > [!WARNING] Las tarjetas regalo y el alta de socios tienen un «modo demostración» que simula el pago sin banco y solo funciona mientras el grupo no tiene TPV configurado. La tienda de tarjetas regalo en demostración solo la ve quien ha entrado en el panel del club; el alta de socios en demostración, no. Apágalo en cuanto termines de enseñarlo: un pago simulado da saldo o membresía reales. ### En Connect Manager: pagos de eventos - En `/fidelizacion`, ve a **Configuración → Configuración de eventos → Locales** y abre el local emisor (rol emisora o ambos). - En «Pago online (Redsys)»: **Aceptar pagos con tarjeta (Redsys)** (encendido por defecto; apagarlo quita el botón de pago sin borrar las credenciales), **Código de comercio (FUC)**, **Terminal** y **Clave secreta (SHA-256)** (vacía, se mantiene la guardada; «Quitar la clave guardada» la borra). - **Entorno del TPV**: «Pruebas (sin cargos reales)» o «Producción (cobros reales)»; vacío, el global de la plataforma. Usa las credenciales del entorno elegido. - **Forma de pago (cobros por pasarela)**: la forma de pago de Ágora con la que se factura el anticipo cuando el cliente paga con tarjeta; sin ella se usa la de transferencia. ## Cómo funciona ### El recorrido de un pago Cuando el cliente pulsa pagar, Connect Manager crea un intento de pago con un número de pedido propio (cuatro cifras y seis letras o números) y guarda con él las credenciales del comercio. Con ellas firma un formulario con el importe, el número de pedido, el nombre del comercio, la dirección de notificación y las direcciones de vuelta, y el navegador del cliente lo envía a la página de pago de Redsys. El cliente paga allí (con la autenticación de su banco). Redsys avisa entonces a Connect Manager de servidor a servidor: se comprueba la firma con las credenciales guardadas en el intento, se toma el importe firmado por el banco y, bajo bloqueo para que un aviso repetido no haga nada dos veces, se marca el pago como cobrado y se lanza lo que toca. Por último Redsys devuelve al cliente a la pantalla de resultado, que lee el estado real del pago. ```mermaid sequenceDiagram participant C as Cliente participant H as Connect Manager participant R as Redsys participant A as Ágora C->>H: Pagar H->>H: Intento con número de pedido y credenciales guardadas H-->>C: Formulario firmado con importe y direcciones C->>R: Envía el formulario y paga R->>H: Notificación firmada servidor a servidor H->>H: Verifica la firma y lee el importe firmado H->>H: Marca cobrado una sola vez H->>A: Pedido cobrado o factura de anticipo, según el caso R-->>C: Vuelta a la pantalla de resultado C->>H: Resultado con el estado real ``` ### Qué pasa al confirmar el pago | Qué se cobra | Al llegar la notificación | | Pedido de la tienda online | El pedido pasa a cobrado, recibe su número de recogida y se manda al TPV del local con la forma de pago del servicio y la referencia de Redsys en las notas del pago (ver el ciclo del pedido) | | Tarjeta regalo (del club o de la tienda) | La tarjeta queda pagada y se entrega al momento o el día elegido: alta del destinatario en el club, saldo en su monedero y correo | | Cuota de socio | El alta queda pagada y se activa la membresía; la renovación alarga su vigencia | | Entradas de la agenda | Se emiten las entradas y se envían por correo | | Pago de una oferta de evento | Se crea el cobro en Conciliación y se concilia con el vencimiento; se emite la factura de anticipo en Ágora y, si la oferta no estaba aceptada, el pago la acepta | ### Las direcciones de notificación Cada tipo de pago tiene su dirección en `https://hub.connectmanager.es`, y viaja dentro de cada pago: no hay que escribirlas en Redsys. - Pedidos de la tienda: `/api/delivery/redsys/notification` - Tarjetas regalo (club y tienda): `/api/loyalty/gift-cards/redsys/notification` - Cuotas de socio: `/api/loyalty/memberships/redsys/notification` - Entradas de la agenda: `/api/loyalty/club-events/redsys/notification` - Pagos de eventos: `/api/loyalty/events/redsys/notification` La de pedidos contesta siempre «OK» o «KO» con un código 200 para que Redsys no reintente lo que ya está decidido; las de Fidelización contestan con un error 400 cuando la firma no es válida o el pago no existe. ### Casos raros que se protegen - **Tarjeta denegada o pago abandonado**: no se confirma nada y el cliente puede reintentar. En los pedidos de la tienda, los intentos que se van al banco y no vuelven en 20 minutos se marcan como caducados, y si el banco confirma tarde el pago se da por bueno igual. - **El banco cobra un importe distinto**: un pedido cobrado de menos no se manda a la cocina y queda como incidencia (cobrado de más, entra y queda anotado para devolver la diferencia); una tarjeta regalo o una cuota con importe distinto no se entrega ni se activa sola; un sobrepago de un evento queda en Conciliación para decidir. - **Cobro sobre algo cancelado** (un pedido, una tarjeta regalo o una oferta de evento cancelada o caducada) o segundo cobro de un pedido que ya está en marcha: no se aplica solo y queda registrado para devolverlo desde Redsys. - **Pagos de pruebas**: en eventos se marcan con `[TEST]` en Conciliación; una tarjeta regalo de la tienda pagada en el entorno de pruebas no se entrega en la plataforma real, porque el saldo sería real. ## Comprobar que funciona - Con el comercio en **Pruebas**, haz un pago real de punta a punta con la tarjeta de prueba que publica Redsys en su documentación: un pedido de la tienda, una tarjeta regalo, un alta de socio, una entrada o un vencimiento de evento, según lo que vaya a usar el cliente. - Comprueba que la pantalla de resultado dice que el pago está hecho y que la consecuencia ocurre: el pedido llega a «En el TPV», la tarjeta se entrega, la membresía se activa, llegan las entradas o el cobro aparece conciliado en Eventos. - En el panel de pruebas de Redsys, busca la operación por su número de pedido y mira que la notificación se entregó bien. - Haz un pago denegado o abandónalo en la página del banco: no debe confirmarse nada. - Cambia a **Producción** con las credenciales reales, haz un cobro pequeño, compruébalo y devuélvelo desde el panel de Redsys. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «Este local no puede cobrar ahora mismo.» | Pasarela apagada, sin FUC o sin clave, o clave ilegible tras un cambio en la plataforma | Revisa la Pasarela de pago del local y vuelve a escribir la clave | | «Este local no acepta Bizum.» o «Este local no acepta Apple Pay ni Google Pay.» | Interruptor apagado en la Pasarela de pago | Enciéndelo solo si el banco lo tiene activo | | Error en la página del banco al elegir Bizum o la cartera | El banco no lo tiene activo en ese terminal | Apaga la opción o pide al banco que la active | | El cliente ha pagado y el pedido sigue «Sin pagar» | La notificación de Redsys no ha llegado o no ha pasado la firma (clave o entorno que no corresponden al terminal) | Mira en Redsys el estado de la notificación de esa operación; revisa clave y entorno. Si llega tarde, se completa solo; si no, resuélvelo a mano y devuelve o sirve el pedido | | La tarjeta de prueba no funciona | El comercio está en Producción | Pon el entorno en Pruebas con credenciales de pruebas | | Pedido «No ha entrado en el TPV» con «El banco ha cobrado X € de un total de Y €.» | El banco cobró menos que el total | Revisa la operación en Redsys antes de preparar el pedido | | «La venta de tarjetas regalo no está disponible.» | Venta apagada, sin importes o sin TPV del grupo | Revisa la sub-página Tarjetas regalo del portal | | «El grupo no tiene el TPV configurado.» | Falta FUC o clave en el TPV del grupo | Rellénalos en Portal público de clientes → Tarjetas regalo | | La tienda no ofrece una tarjeta regalo | El local que la vende no cobra en producción, o su pasarela cambió desde que se guardó la tarjeta | Revisa la Pasarela del local y vuelve a guardar Tienda pública → Tarjetas regalo con un usuario con permiso para añadir saldo | | Tarjeta regalo cobrada pero sin entregar | Se canceló con el pago en vuelo, o el importe cobrado no coincide | Si estaba cancelada, devuelve el cargo en Redsys; si no, revisa y usa «Entregar ahora» en el panel | | «El alta de socios no está disponible.» | Socios sin activar o sin TPV del grupo | Activa el alta en Configuración de socios y configura el TPV del grupo | | «El club todavía no tiene la pasarela de pago configurada.» | Entradas de pago sin TPV del grupo | Configura el TPV del grupo | | «La oferta no admite pago online.» o «El emisor no acepta pagos con tarjeta.» | Oferta caducada o local emisor sin Redsys activo | Revisa la oferta y el apartado «Pago online (Redsys)» del local emisor | | «No se pudo iniciar el pago. Inténtalo de nuevo en unos minutos.» | Error inesperado al preparar el pago | Reintenta; si se repite, revisa las credenciales y avisa a FOS | ## Preguntas frecuentes ### ¿Qué datos de Redsys necesito para cobrar online con Connect Manager y Ágora? El código de comercio (FUC), el terminal y la clave secreta SHA-256 del TPV virtual, de pruebas y de producción. Los da el banco del cliente. ### ¿Tengo que configurar la URL de notificación en el panel de Redsys? No. Connect Manager envía la dirección de notificación y las de vuelta dentro de cada pago. Lo que sí debe estar activo en el terminal es la notificación online. ### ¿Puedo usar un mismo TPV virtual para todos los locales? En la tienda online cada local tiene su pasarela, pero puedes poner los mismos datos en varios locales si el cliente cobra todo en un único comercio. En Fidelización hay un TPV para todo el grupo, y en eventos uno por local emisor. ### ¿Cómo devuelvo un pago hecho con Redsys? Desde el panel de Redsys, buscando la operación por su número de pedido. Cancelar en Connect Manager no devuelve el dinero. ### ¿Cómo pruebo sin cobrar de verdad? Pon el entorno en Pruebas, usa las credenciales de pruebas (en la tienda se rellenan solas las del comercio de demostración de Redsys) y paga con la tarjeta de prueba de Redsys. ### ¿Se puede pagar con Bizum en la tienda online? Sí, si el banco tiene Bizum activo en el terminal del local y enciendes la opción en su Pasarela de pago. Lo mismo para Apple Pay y Google Pay. ## Referencias - [Ficha de Redsys en el catálogo de integraciones](https://connectmanager.es/integraciones/redsys) - [Delivery propio: conectar la tienda online con Ágora](https://connectmanager.es/docs/delivery-propio-conectar-con-agora) - [Fidelización: conectar el club con Ágora](https://connectmanager.es/docs/fidelizacion-conectar-con-agora) - [Correo electrónico: proveedores de envío](https://connectmanager.es/docs/correo-proveedores-de-envio) (los correos de tarjetas regalo, socios y entradas) - [Portal de desarrolladores de Redsys](https://pagosonline.redsys.es/) --- # Integración de CiberSuite con Ágora: PIN de wifi desde el TPV Portal: General · Otras integraciones URL: https://connectmanager.es/docs/integracion-cibersuite-agora Actualizado: 2026-10-03 La integración de **CiberSuite** con **Ágora** añade al TPV un botón que genera un PIN de acceso a la wifi del local: el camarero lo pulsa, Connect Manager pide el PIN a CiberSuite y Ágora imprime un ticket con el código, la tarifa, la duración y los dispositivos permitidos para dárselo al cliente. Este manual es para el técnico de FOS o del distribuidor que configura la integración en un local que gestiona su wifi con CiberSuite. ## Qué hace la integración - Abre desde una acción personalizada de Ágora la ventana **Solicitud de WIFI**, que pide al momento un PIN nuevo a CiberSuite. - Muestra en pantalla el PIN, la tarifa asignada, la duración, los dispositivos permitidos y si se pueden usar redes P2P y streaming. - Imprime esos mismos datos en la impresora de Ágora configurada, con una cabecera opcional (por ejemplo, el nombre de la red o un saludo) y corte de papel. - Imprime de dos maneras: a través del propio TPV, sin abrir Ágora a Internet, o desde Connect Manager con la API de Ágora. - Se autentica en CiberSuite con un token permanente o con la pareja de claves del cliente, con la que obtiene un token en cada petición. - Guarda cada petición con la respuesta de CiberSuite. ### Qué no hace - No deja elegir desde el TPV la duración ni el número de dispositivos: la petición va siempre con 1 dispositivo y 1 hora, y se imprime lo que CiberSuite confirma según la tarifa. - No asocia el PIN al ticket ni al cliente de Ágora, ni lo cobra: es un ticket aparte. - No anula ni consulta PIN ya generados. ## Requisitos - **CiberSuite** con acceso a su API para TPV y las credenciales del local: un **token permanente**, o una **Customer key** y un **Customer token**. Las facilita CiberSuite. - **Local en Connect Manager**. FOS da de alta el local y la integración. - **Ágora** con **Acciones personalizadas** y una impresora de tickets dada de alta. - Solo si se marca **Imprimir usando la API de Agora**: la URL de la API y la API key de Ágora en el local, y la API accesible desde Internet (puerto abierto o [Zero Connect](https://connectmanager.es/docs/zero-connect-instalacion)). Sin esa opción, el ticket lo imprime el propio TPV y no hace falta. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de CiberSuite | CiberSuite | https://cibersuite.ejemplo.com/ (con / final) | Sí | | Token permanente | CiberSuite | •••••••• | Sí, o la pareja de claves | | Customer key y Customer token | CiberSuite | •••••••• | Sí, si no hay token permanente | | Nombre de la impresora de Ágora | Configuración de impresoras de Ágora | BARRA | Sí | | Cabecera del ticket | Cliente | WIFI HOTEL DEMO | No | ## Configuración paso a paso ### En CiberSuite - Pide a CiberSuite la URL de su API y las credenciales del local: token permanente, o Customer key y Customer token. - Comprueba con CiberSuite qué tarifa se aplica a los PIN generados desde el TPV: de ella salen la duración, los dispositivos y los permisos que se imprimen. ### En Connect Manager - En `https://app.connectmanager.es`, ve a **Administración → Locales**, abre el local y pulsa **Guardar** para habilitar los módulos. Si vas a imprimir por API, revisa antes la **URL de API** y la **API key** de Ágora. - Entra en **Otras integraciones**, pulsa **Añadir** y en **Proveedor** elige **CiberSuite**. - Rellena la pestaña **Configuración**: - **URL Api:** la de CiberSuite, terminada en `/`. - **Impresora:** el nombre exacto de la impresora de Ágora. - **Imprimir usando la API de Agora**: márcala solo si el TPV no puede imprimir desde la ventana y la API de Ágora es accesible desde Internet. - **Utilizar token permanente**: márcala si CiberSuite te ha dado un token permanente y escríbelo en **Token permanente:**. Desmarcada, rellena **Customer key:** y **Customer token:**. - **Cabecera del ticket WIFI:** texto opcional que se imprime arriba. - Pulsa **Guardar** y copia la **URL del botón de petición de WIFI** que aparece al pie. ### En Ágora - En **Herramientas → Acciones personalizadas**, pulsa **Nuevo**: en **Texto** escribe, por ejemplo, `WIFI`; en **Tipo**, **Url/Aplicación**; en **Acción**, la **URL del botón de petición de WIFI**. Deja marcada **Mostrar Urls en un diálogo de Ágora** y pulsa **Aceptar**. - Coloca la acción en **Herramientas → Configuración de botones**, en el perfil que use el local, y da su permiso a los perfiles de usuario que vayan a generar PIN. ## Cómo funciona Al pulsar el botón, Ágora abre la ventana de Connect Manager, que pide un PIN a CiberSuite. Si la integración usa la pareja de claves, primero obtiene un token con ellas; con token permanente, lo usa directamente. CiberSuite devuelve el PIN y los datos de su tarifa, la ventana los enseña y el ticket se imprime: por defecto, la ventana se lo pasa a Ágora y es el TPV quien lo imprime; con **Imprimir usando la API de Agora**, lo manda Connect Manager a la API de Ágora. Si la impresión va bien, la ventana se cierra sola. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant CS as CiberSuite TPV->>CM: Abre la ventana Solicitud de WIFI CM->>CS: Token con la Customer key, si no hay token permanente CS-->>CM: Token CM->>CS: Genera un PIN para 1 dispositivo y 1 hora CS-->>CM: PIN, tarifa, duración y dispositivos CM-->>TPV: Muestra los datos y el ticket listo TPV->>TPV: Imprime el ticket del PIN y cierra la ventana ``` ### Qué se imprime - La cabecera configurada, si la hay. - Código PIN, tarifa asignada, duración en horas y dispositivos permitidos. - Si se pueden usar redes P2P y streaming. - El corte de papel al final. ### Si algo falla Los errores salen en la ventana en rojo, precedidos de «Ocurrió un error:». Si CiberSuite contesta con un error, se ve su texto; si no contesta, «No se ha recibido respuesta de la api de CiberSuite». Si falla la impresión por la API de Ágora, la ventana enseña el PIN igualmente y el motivo del fallo, para que el camarero pueda dárselo al cliente. No hay reintentos automáticos: se vuelve a pulsar el botón y se genera un PIN nuevo. ## Comprobar que funciona - Pulsa el botón WIFI en el TPV: la ventana debe mostrar «Realizando la petición...» y después el PIN con sus datos. - Comprueba que el ticket sale por la impresora configurada, con la cabecera y el corte de papel. - Conecta un móvil a la wifi con ese PIN y comprueba la duración y los dispositivos de la tarifa. - Si usas impresión por API, prueba también con la impresora apagada: la ventana debe mostrar el PIN y el error de impresión. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «Ocurrió un error: El token no es válido» | Token permanente vacío o incorrecto, o CiberSuite no ha devuelto token con la pareja de claves. | Revisa el token o la Customer key y el Customer token con CiberSuite. | | «Ocurrió un error: No se ha recibido respuesta de la api de CiberSuite» | CiberSuite no responde o la URL Api está mal. | Comprueba la URL (terminada en /) y el servicio de CiberSuite. | | Mensaje de error de CiberSuite en la ventana | CiberSuite rechaza la petición (por ejemplo, por la tarifa o la cuenta). | Revísalo con CiberSuite. | | Se ve el PIN pero no se imprime | El nombre de la impresora no coincide con Ágora, o la acción no se abre en un diálogo de Ágora. | Corrige el campo Impresora y marca Mostrar Urls en un diálogo de Ágora. | | «Error: …» al imprimir con la opción de API | Connect Manager no llega a la API de Ágora del local. | Revisa la URL de API y la API key, o desmarca Imprimir usando la API de Agora. | | El botón no aparece en el TPV | Falta colocarlo en la configuración de botones o el permiso en el perfil del usuario. | Añádelo al perfil de botones y da el permiso. | ## Preguntas frecuentes ### ¿Cómo imprimo un PIN de wifi de CiberSuite desde Ágora? Con la acción personalizada que crea la integración: el camarero pulsa el botón y Ágora imprime el ticket con el PIN. ### ¿Puedo elegir cuántas horas dura el PIN? No desde el TPV. La duración y los dispositivos los marca la tarifa que aplica CiberSuite. ### ¿Hace falta abrir Ágora a Internet? No, salvo que se marque **Imprimir usando la API de Agora**. Por defecto imprime el propio TPV. ### ¿Puedo cambiar el texto de la cabecera del ticket? Sí, en **Cabecera del ticket WIFI** de la configuración de la integración. ## Referencias - Ficha de la integración: [CiberSuite en el catálogo de Connect Manager](https://connectmanager.es/integraciones/cibersuite). - [Zero Connect: publicar la API de Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion). --- # Integración de Power BI con Ágora: informes en Connect Manager Portal: General · Otras integraciones URL: https://connectmanager.es/docs/integracion-power-bi-agora Actualizado: 2026-10-03 La integración de **Microsoft Power BI** muestra informes de Power BI dentro del panel de Analítica de Connect Manager, colgados de cada local, con el filtro de fechas del panel y, si se quiere, seguridad por filas. Sirve para que los clientes de Ágora vean sus cuadros de mando entrando con su cuenta de Connect Manager, sin iniciar sesión en Microsoft. Este manual es para el técnico que da de alta el informe y prepara el modelo para que encaje. ## Qué hace la integración - Añade a un local un informe de Power BI con un nombre y la URL del informe. Los identificadores del área de trabajo y del informe se sacan solos de la URL. - Con la aplicación de Connect Manager en Microsoft Entra ID, pide a Power BI la URL de inserción segura y el modelo del informe y genera un **token de inserción de solo lectura** cada vez que alguien abre el informe. - En el panel de Analítica, cada usuario elige el informe en el buscador de la barra superior (Buscar panel...). Ve los de todos los locales a los que tiene acceso: asignados a él, de sus grupos o, si tiene el permiso de herencia, de su distribuidor. - Filtra el informe por fechas desde la barra: Rango de tiempo... (Esta semana, Semana pasada, Hace 2 semanas, Este mes, Mes pasado, Hace 2 meses, Este año, Año pasado) o Desde... y Hasta.... El filtro se aplica sobre la tabla `Fechas`, columna `Fecha`, y se intenta llevar también a los segmentadores de la página abierta. - Seguridad por filas (RLS) opcional: el informe recibe como identidad el correo del usuario del panel con el rol `TenantRole`, así que cada uno ve solo sus filas. - Muestra la navegación de páginas a la izquierda, oculta el panel de filtros y las cabeceras de los visuales, y tiene un botón de **Modo Presentación** a pantalla completa. ### Qué no hace - No lee Ágora ni lleva datos a Power BI: el modelo, su origen de datos y su actualización se preparan en Power BI. Connect Manager solo enseña el informe ya publicado. - No deja editar ni exportar: el token es de solo lectura y las cabeceras de los visuales están ocultas. - No admite enlaces de «Publicar en la web», URLs sin `/groups/…/reports/…` (como las de `reportEmbed`) ni informes de «Mi área de trabajo». - No usa la cuenta de Microsoft de cada persona: solo filtra por el correo del usuario del panel si se activa RLS. - Trabaja con un único inquilino de Microsoft, el configurado en el servidor de Connect Manager. - No renueva el token con el informe abierto: tras mucho rato hay que volver a elegirlo o recargar la página. - El formulario del local está pensado para un informe por local (ver «Errores frecuentes»). ## Requisitos - Informe publicado en **Power BI Service** en un área de trabajo compartida (no «Mi área de trabajo») del inquilino de Microsoft que usa Connect Manager. - La aplicación **ConnectManager Analytics App** añadida al área de trabajo con rol **Miembro** o **Administrador**. Su registro en Microsoft Entra ID y sus credenciales en el servidor los mantiene FOS. - Para que funcione el filtro de fechas del panel: una tabla llamada exactamente `Fechas` con una columna `Fecha` de tipo fecha, relacionada con los datos del informe. - Para RLS: un rol llamado exactamente `TenantRole` cuyo filtro compare la columna de correo con `USERPRINCIPALNAME()`. Los correos de esa tabla tienen que coincidir con los de las cuentas del panel. - Usuarios con cuenta de Connect Manager, el permiso **Entorno: Acceder a Analytics** y acceso al local donde se cuelga el informe. - **Quién hace qué**: el autor del informe (FOS o el cliente) lo publica, da acceso a la aplicación y prepara las tablas de fechas y de RLS. FOS da de alta la integración en **/admin** y los permisos de los usuarios. El cliente dice qué personas deben verlo. > [!NOTE] Microsoft limita los tokens de inserción de las áreas de trabajo que no están en una capacidad (Power BI Embedded, Premium o Fabric): sin capacidad sirven para desarrollo y pruebas. Confirma con FOS la capacidad del área de trabajo antes de pasar el informe a producción. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL del informe en Power BI Service | Autor del informe: barra de direcciones del navegador con el informe abierto | https://app.powerbi.com/groups/11111111-2222-3333-4444-555555555555/reports/66666666-7777-8888-9999-000000000000/ReportSection | Sí | | Nombre descriptivo | FOS o el cliente; es lo que verán los usuarios en el buscador | Ventas diarias | Sí | | Local del que se cuelga | FOS | Restaurante Demo | Sí | | ¿El modelo tiene el rol TenantRole? | Autor del informe | Sí / No | Sí | | Correos de las personas que verán el informe | Cliente; con RLS, deben estar en la tabla de accesos del modelo | persona@empresa.es | Sí | ## Configuración paso a paso ### En Power BI - Publica el informe desde Power BI Desktop (**Publicar**) en un área de trabajo compartida. - En el área de trabajo, **Administrar acceso** → **Agregar personas o grupos** → busca **ConnectManager Analytics App** → rol **Miembro** (o Administrador) → **Agregar**. - Comprueba que el modelo tiene la tabla `Fechas` con la columna `Fecha`. Sin ella el informe se ve, pero el filtro de fechas del panel no hace nada. - Si cada usuario debe ver solo lo suyo: en Power BI Desktop, **Modelado → Administrar roles**, crea el rol `TenantRole` sobre la tabla de accesos con el filtro `[Tu_Columna_Con_El_Email] = USERPRINCIPALNAME()` y vuelve a publicar. - Abre el informe en el navegador y copia la URL completa. Tiene que contener `/groups/` y `/reports/`. ### En Connect Manager - Entra en **/admin → Seguridad → Locales**, abre el local y, en el bloque **Ecosistema Conectado**, pulsa **Añadir Integración**. - En **Ajustes Generales**, elige en **Servicio / Proveedor** la opción **Microsoft Power BI (Analytics)** y deja activado **Estado Operativo**. - En la sección **Microsoft Power BI**: - **Nombre Descriptivo**: el nombre que verán los usuarios en el buscador, que los ordena alfabéticamente. Conviene incluir el local si el usuario ve varios. - **URL de Embebido (Embed URL)**: la URL copiada del navegador. No hace falta escribir ningún identificador a mano. - **Activar Row-Level Security (RLS)**: solo si el modelo tiene el rol `TenantRole`. Si el modelo tiene roles y lo dejas apagado, Microsoft no genera el token. - Pulsa **Crear**. La fila aparece con el nombre descriptivo, la integración Microsoft Power BI y la categoría analytics. - Para retirarlo sin borrarlo, edita la integración y apaga **Estado Operativo**: deja de salir en el buscador. ### Usuarios - Cada persona necesita el permiso **Entorno: Acceder a Analytics** y acceso al local: asignado a su usuario, a uno de sus grupos o a su distribuidor (con el permiso de herencia). - Entran en `https://hub.connectmanager.es/analytics` con correo y contraseña, o con **Microsoft** o **Google** si su cuenta de Connect Manager tiene ese mismo correo. El menú de usuario lleva a la **Guía de Integración PBI**, un resumen interno de estos pasos; donde habla de Workspace ID, Report ID y «Habilitar RLS», hoy basta con la URL y el interruptor de RLS de este manual. ## Cómo funciona Al entrar en Analítica, el panel reúne los informes de Power BI activos de los locales que puede ver el usuario, pero no carga ninguno hasta que se elige. Cuando el usuario elige uno, el servidor de Connect Manager pide un token a Microsoft Entra ID con la aplicación de Connect Manager, saca de la URL los identificadores del área de trabajo y del informe y pregunta a Power BI por el informe para obtener su URL segura y su modelo. Si la integración tiene RLS, añade como identidad el correo del usuario con el rol `TenantRole`. Después pide a Power BI un token de inserción de solo lectura y se lo pasa a la página, que carga el informe con el SDK de Power BI mientras enseña el aviso «Sincronizando Sistema». Al cambiar las fechas, la página aplica el filtro al informe abierto sin volver a pedir token. ```mermaid sequenceDiagram participant U as Usuario participant P as Panel de Analítica participant CM as Servidor Connect Manager participant AAD as Microsoft Entra ID participant PBI as Power BI U->>P: Elige un informe en el buscador P->>CM: Pide el informe de ese local CM->>AAD: Token de la aplicación de Connect Manager AAD-->>CM: Token de acceso CM->>PBI: Datos del informe a partir de la URL PBI-->>CM: URL de inserción y modelo CM->>PBI: Token de solo lectura, con el correo si hay RLS PBI-->>CM: Token de inserción CM-->>P: Token y URL de inserción P->>PBI: Carga el informe en la página U->>P: Cambia el rango de fechas P->>PBI: Filtro sobre la tabla Fechas, columna Fecha ``` Si el identificador del área de trabajo o del informe no se puede sacar de la URL, el servidor no carga nada: así nunca se cae en un informe por defecto que podría enseñar datos de otro cliente. No hay tareas programadas ni reintentos: todo ocurre al elegir el informe, y si Microsoft no responde el usuario ve el error en ese momento. ## Comprobar que funciona - En Power BI, la aplicación **ConnectManager Analytics App** aparece en **Administrar acceso** del área de trabajo como Miembro o Administrador. - En el bloque **Ecosistema Conectado** del local, la fila del informe tiene marcada la columna **Activo**. - Entra en `/analytics` con un usuario que tenga acceso al local y elige el informe en Buscar panel...: tras «Sincronizando Sistema» se ve el informe con sus páginas a la izquierda. - Elige Este mes en Rango de tiempo... y comprueba que las cifras cambian. - Con RLS, entra con un usuario de la tabla de accesos (ve sus filas) y con otro que no esté (no ve datos). - Pulsa el botón de pantalla completa para comprobar el modo presentación. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «El sistema no detecta ningún conector analítico configurado en tu cuenta. Por favor, solicita acceso a la central.» | El usuario no tiene acceso a ningún local con un informe de Power BI activo. | Da acceso al local o activa Estado Operativo en la integración. | | Aviso «Error cargando integración» con «Fallo de Seguridad Bloqueado: Los IDs del panel no existen ni se pudieron extraer de la URL de este cliente…» | La URL no contiene /groups/…/reports/… (enlace de «Publicar en la web», reportEmbed o similar). | Copia la URL del informe abierto en Power BI Service. | | «Error cargando integración» con un texto que empieza por «Error de Microsoft Power BI:» | Power BI no genera el token: la aplicación no está en el área de trabajo, el informe está en «Mi área de trabajo», el modelo tiene RLS y el interruptor está apagado, o el interruptor está encendido y no existe el rol TenantRole. | Revisa el acceso de la aplicación y que el interruptor de RLS coincida con el modelo. | | Al elegir el informe no pasa nada y no sale ningún mensaje | El servidor no ha conseguido el token de Microsoft Entra ID (credenciales de la aplicación en el servidor). | Avisa a FOS: el motivo queda en el registro del servidor. | | En el recuadro del informe, «Conexión Rechazada» y «Error de token o Iframe cerrado por Microsoft.» | Power BI rechaza la carga, a menudo porque el token ha caducado con el informe abierto mucho rato. | Vuelve a elegir el informe o recarga la página. Si se repite al momento, revisa permisos y capacidad del área de trabajo. | | El filtro de fechas del panel no cambia nada | El modelo no tiene la tabla Fechas con la columna Fecha con esos nombres exactos. | Crea o renombra la tabla y la columna, y vuelve a publicar. | | Con RLS, un usuario no ve ningún dato | Su correo en Connect Manager no coincide con el de la tabla de accesos. | Corrige el correo en el modelo o en la cuenta del panel. | | Al guardar: «Este local ya tiene una integración de tipo «powerbi». Solo se permite una por local.» | El local ya tiene dos informes de Power BI: con dos, el formulario no deja crear un tercero ni guardar cambios en los existentes. | Cuelga el informe de otro local del mismo cliente, o borra uno y vuelve a crearlo. | | En el inicio de sesión con Microsoft o Google vuelve al login con el error account_not_found | No hay cuenta de Connect Manager con ese correo. | FOS crea la cuenta con ese correo y los permisos. | ## Preguntas frecuentes ### ¿Cómo integro un informe de Power BI en Connect Manager? Publica el informe en un área de trabajo compartida, añade la aplicación **ConnectManager Analytics App** como Miembro y, en **/admin → Seguridad → Locales**, añade al local la integración **Microsoft Power BI (Analytics)** con un nombre y la URL del informe. ### ¿Por qué no se aplica el filtro de fechas del panel a mi informe? El panel filtra siempre sobre la tabla `Fechas`, columna `Fecha`. Si el modelo usa otros nombres, el filtro no encuentra dónde aplicarse. ### ¿Puede cada usuario ver solo los datos de su local? Sí, con seguridad por filas: crea en el modelo el rol `TenantRole` con el filtro `[Tu_Columna_Con_El_Email] = USERPRINCIPALNAME()` y activa **Activar Row-Level Security (RLS)** en la integración. Connect Manager envía como identidad el correo del usuario del panel. ### ¿Se puede usar un enlace de «Publicar en la web»? No. La integración necesita la URL del informe con `/groups/` y `/reports/` para generar un token privado; con otros enlaces se bloquea a propósito. ### ¿Connect Manager lleva los datos de Ágora a Power BI? Esta integración no: solo enseña informes ya hechos. Para alimentar un modelo hay dos API de Connect Manager con clave propia: la de pedidos de delivery (**/app → Configuración → Integraciones**) y la de reseñas del club (**/fidelizacion → Configuración → Integraciones**, con las consultas para Power BI Desktop en la pestaña Power BI de «Ver credenciales»). ### ¿Los usuarios necesitan cuenta de Power BI? No para verlo en el panel: entran con su cuenta de Connect Manager y el token lo genera la aplicación de Connect Manager. La cuenta de Power BI la necesita quien construye y publica el informe. ## Referencias - [Ficha de Microsoft Power BI en el catálogo](https://connectmanager.es/integraciones/power-bi) - [Integraciones (API): claves para descargar el histórico de pedidos](https://connectmanager.es/docs/manual-integraciones) - Microsoft: [Insertar contenido de Power BI con una entidad de servicio](https://learn.microsoft.com/power-bi/developer/embedded/embed-service-principal) - Microsoft: [Seguridad de nivel de fila en contenido insertado](https://learn.microsoft.com/power-bi/developer/embedded/embedded-row-level-security) --- # Integración de Wine Advisor con Ágora: carta de vinos en el TPV Portal: General · Otras integraciones URL: https://connectmanager.es/docs/integracion-wine-advisor-agora Actualizado: 2026-10-03 La integración de **Wine Advisor** con **Ágora** lleva la carta de vinos de Wine Advisor al TPV: cada noche, o cuando se pide desde el panel, Connect Manager descarga los vinos y los crea o actualiza en Ágora como productos, con su familia por tipo de vino, su precio de botella y, si se sirven por copas, su formato de copa. Los vinos que dejan de estar disponibles en Wine Advisor dejan de poder venderse en Ágora. Este manual es para el técnico de FOS o del distribuidor que deja la sincronización funcionando en un local. Se configura en el hub de Connect Manager (`https://hub.connectmanager.es`), no en la app de integraciones. ## Qué hace la integración - Descarga todos los vinos de Wine Advisor y los crea o actualiza en Ágora como productos, con el nombre «Nombre (tipo, añada)» y el identificador de Wine Advisor como código de barras. - Crea en Ágora una familia por cada tipo de vino (tinto, blanco…) que aún no exista, dentro de la familia raíz que elijas; los vinos sin tipo van a esa familia raíz. - Pone el precio de botella en todas las tarifas activas de Ágora. Si Wine Advisor no trae precio, conserva el que ya tenga el producto en Ágora. - Crea un formato de venta por cada formato de copa que el vino tenga activo en Wine Advisor («Copa de …»), con su precio y su proporción de la botella. - Marca como no vendibles los vinos que Wine Advisor da como no disponibles, y los vuelve a activar cuando vuelven a estarlo. - Recuerda qué producto de Ágora es cada vino de Wine Advisor, para que un cambio de nombre o de añada no cree un producto duplicado. - Se ejecuta cada noche a las 05:00 (hora de Madrid) y, a mano, desde el panel, con un histórico de cada sincronización que nombra los vinos que no entraron y por qué. - Opcionalmente: vende el vino también como añadido de otro producto, aplica orden y tipo de preparación, calcula el precio de copa como botella entre copas y envía «precio abierto» cuando no hay precio. ### Qué no hace - No envía a Wine Advisor el stock ni las ventas de Ágora: la información va solo de Wine Advisor a Ágora. - No borra de Ágora los vinos que desaparecen de Wine Advisor: siguen como estaban hasta que se quiten a mano. - No crea una copa sin precio: si Wine Advisor no da precio de copa y no está activado el cálculo botella entre copas, la copa nueva no se crea y se avisa en el histórico. - No gestiona el stock en Ágora ni permite elegir un IVA por vino: todos los vinos van con el impuesto configurado. ## Requisitos - **Cuenta de Wine Advisor** con la carta del local y su **token de API** (una clave de unos 32 caracteres que se obtiene en Wine Advisor). El usuario y la contraseña del panel web de Wine Advisor no se usan. - **Local en el hub** con la conexión con Ágora configurada en **Datos de Conexión con ágora**: ACMS, o la URL y el token de la API del local. - **API de Ágora accesible desde Internet**, con puerto abierto o con [Zero Connect](https://connectmanager.es/docs/zero-connect-instalacion): el hub lee el catálogo de Ágora y le importa los productos. Si el local usa ACMS, los vinos se crean en el ACMS del grupo. - En Ágora: el **impuesto** que llevarán los vinos y, si quieres ordenarlos, la **familia raíz**; opcionalmente, el orden y el tipo de preparación. Necesitas el Id. de cada uno. - Permisos en el hub: el alta de la integración se hace en `/admin`; para sincronizar y ver el histórico desde el panel **Integraciones** hacen falta los permisos «Entorno: Acceder a Integraciones» e «Integraciones: Acceder a WineAdvisor». ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Wine Advisor | Wine Advisor (viene rellena) | https://api.wineadvisor.mx | Sí | | Token de API de Wine Advisor | Wine Advisor, desde su panel | Clave de unos 32 caracteres | Sí | | Id. del impuesto (IVA) de Ágora | Configuración de impuestos de Ágora | 2 | Sí | | Id. de la familia raíz | Familias de Ágora | 40 (familia «Vinos») | Recomendado | | Id. del orden de preparación | Ágora | 1 | No | | Id. del tipo de preparación | Ágora | 2 (barra) | No | | Conexión con Ágora del local | Distribuidor (URL y token, o ACMS) | https://local-demo.connectmanager.live | Sí | ## Configuración paso a paso ### En Wine Advisor - Consigue el token de API del local en el panel de Wine Advisor (o pídeselo a Wine Advisor). - Revisa que los vinos que se sirven por copas tienen configurado y activo su formato de copa, con precio y número de copas por botella. El listado de vinos de Wine Advisor no trae el precio de copa por otra vía. - Marca como no disponibles los vinos que no se deben vender. ### En Ágora - Crea, si no existe, la familia raíz de los vinos (por ejemplo «Vinos») y apunta su Id. - Apunta el Id. del impuesto que llevarán los vinos y, si los vas a usar, los del orden y el tipo de preparación. ### En Connect Manager (hub) - En `https://hub.connectmanager.es/admin`, ve a **Locales** y abre el local. En **Datos de Conexión con ágora** comprueba **¿Utiliza arquitectura ACMS?** y, según el caso, **Local: URL de la API** y **Local: API Token** o **ACMS: URL de la API** y **ACMS: API Token**. - En la pestaña de integraciones del local (**Ecosistema Conectado**), pulsa **Añadir Integración** y en **Servicio / Proveedor** elige **WineAdvisor (Others)**. Solo se permite una por local. - Deja activado **Estado Operativo** (desactivado, la sincronización nocturna se salta el local) y rellena la sección **WineAdvisor**: - **URL de la API de WineAdvisor**: normalmente `https://api.wineadvisor.mx`. - **Token de API de WineAdvisor**: el token; se guarda cifrado. - **ID de impuesto (IVA) en Ágora**. - **ID de familia raíz en Ágora**. - **ID de orden de preparación** e **ID de tipo de preparación**, opcionales. - **Precio 0 como «precio abierto»**: si un vino nuevo no tiene precio, Ágora lo pedirá al venderlo en vez de cobrar 0. - **Copa sin precio: calcular botella ÷ copas**: calcula el precio de copa que falta dividiendo el de la botella entre las copas por botella, redondeado a céntimos. - **Permitir venta como añadido**: deja vender el vino como añadido de otro producto. - Guarda y pulsa **Sincronizar vinos** en la fila de la integración para lanzar la primera sincronización. > [!TIP] La primera sincronización de una carta grande puede tardar varios minutos. Mira el resultado en el panel **Integraciones → WineAdvisor**, botón **Histórico**. ## Cómo funciona Cada noche a las 05:00, o al pulsar **Sincronizar ahora**, el hub descarga de Wine Advisor todos los vinos, de 50 en 50; lee de Ágora los productos, las familias y las tarifas; crea las familias de tipo que falten; convierte cada vino en un producto (reutilizando el que ya le corresponde en Ágora) y lo importa en Ágora en lotes de 100. Al terminar guarda qué producto es cada vino y deja en el histórico el resultado. ```mermaid sequenceDiagram participant HUB as Connect Manager hub participant WA as Wine Advisor participant AG as API Ágora HUB->>WA: Lista de vinos por páginas WA-->>HUB: Vinos con tipo, añada, precio, copas y disponibilidad HUB->>AG: Exporta productos, familias y tarifas AG-->>HUB: Catálogo actual del local HUB->>AG: Importa las familias de tipo que faltan HUB->>AG: Importa los productos en lotes de 100 AG-->>HUB: Lote aceptado o producto rechazado HUB->>HUB: Guarda la relación vino y producto y el histórico ``` ### Qué se crea en Ágora - **Producto**: nombre «Nombre (tipo, añada)» de hasta 90 caracteres, familia por tipo, impuesto configurado, código de barras con el Id. de Wine Advisor, vendible si el vino está disponible y precio de botella en cada tarifa activa. - **Formatos de copa**: uno por cada formato de copa activo en Wine Advisor, llamado «Copa de …» (o el nombre del formato), con proporción 1 / copas por botella y su precio. - **Identificadores**: un vino nuevo recibe un Id. libre por encima de los de productos y formatos que ya existen; un vino conocido mantiene su producto. ### Rechazos de Ágora Ágora rechaza un lote entero en cuanto un producto no le cuadra. Cuando su mensaje señala el producto culpable, el hub lo aparta y reenvía el resto; si no lo señala, manda el lote de uno en uno. Así un vino problemático no deja fuera a los demás. Si el error no tiene que ver con un producto (sin conexión, token incorrecto), ese lote se da por perdido y se apunta en el histórico. ```mermaid flowchart TD A[Lote de 100 vinos] --> B{Ágora acepta} B -- Sí --> C[Todos aceptados] B -- No y nombra un producto --> D[Aparta ese producto y reintenta] D --> B B -- No y no nombra producto --> E{Error de producto} E -- Sí --> F[Envía uno a uno] E -- No, conexión o token --> G[Lote perdido y anotado] ``` ### El histórico En **Integraciones → WineAdvisor** cada local integrado muestra la última sincronización (Completada, Error o En curso), la fecha y los productos. El botón **Histórico** lista cada pasada con fecha, estado, vinos, productos, familias nuevas, duración, origen (Programada o Manual) y un mensaje que nombra los primeros vinos rechazados con su error y las copas que no se crearon por falta de precio. Si ya hay una sincronización manual en marcha para ese local, otra petición manual se descarta y no aparece en el histórico: espera a que termine. ## Comprobar que funciona - Lanza **Sincronizar vinos** y, en el **Histórico**, espera a ver la pasada como **Completada** con el número de vinos y de productos. - En Ágora, busca un vino: debe estar en la familia de su tipo, con el precio de Wine Advisor en todas las tarifas. - Busca un vino por copas: debe tener su formato «Copa de …» con precio. - Marca un vino como no disponible en Wine Advisor, sincroniza y comprueba que en Ágora ya no se puede vender. - Cambia un precio en Wine Advisor, sincroniza y comprueba que Ágora lo recoge sin crear un producto nuevo. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «Falta la URL o la API Key de WineAdvisor.» | Campos vacíos en la integración. | Rellena la URL y el token. | | «Falta el ID de impuesto (IVA) de Ágora.» | No se ha indicado el impuesto. | Pon el Id. del impuesto de Ágora. | | «El local «X» no tiene conexión Ágora configurada.» | El local no tiene ni ACMS ni URL y token de la API. | Completa Datos de Conexión con ágora. | | «No se pudieron descargar los vinos de WineAdvisor: WineAdvisor HTTP 401…» | Token incorrecto o regenerado en Wine Advisor. | Copia de nuevo el token. | | «No se pudo leer el catálogo de Ágora: …» | El hub no llega a la API de Ágora o el token no es válido. | Revisa URL, token, puerto o Zero Connect. | | «N de M productos no entraron en Ágora. #Id Nombre: …» | Ágora ha rechazado esos productos (por ejemplo, «Se ha intentado insertar o actualizar un código de barras repetido»). | Busca en Ágora el Id. o el código de barras que choca, corrígelo y vuelve a sincronizar. | | «N copas sin precio en WineAdvisor no se han creado: …» | Vinos marcados por copa sin formato de copa con precio. | Configura el formato de copa en Wine Advisor o activa Copa sin precio: calcular botella ÷ copas. | | «WineAdvisor no devolvió vinos.» | La cuenta no tiene vinos o el token es de otra cuenta. | Revisa la carta en Wine Advisor. | | El local no aparece en Integraciones → WineAdvisor | La integración no está creada en ese local o el usuario no tiene acceso al local. | Créala en /admin o revisa los permisos del usuario. | ## Preguntas frecuentes ### ¿Cómo conecto Wine Advisor con Ágora? En el hub de Connect Manager: se añade la integración WineAdvisor al local con el token de Wine Advisor y el Id. del impuesto de Ágora, y se lanza la primera sincronización. ### ¿Cada cuánto se actualiza la carta de vinos en Ágora? Cada noche a las 05:00 (hora de Madrid) y siempre que se pulse **Sincronizar ahora**. ### ¿Por qué un vino por copas no tiene copa en Ágora? Porque en Wine Advisor no tiene un formato de copa activo con precio. Configúralo allí o activa el cálculo botella entre copas. ### ¿Wine Advisor recibe el stock o las ventas de Ágora? No. La integración solo lleva la carta de Wine Advisor a Ágora. ### Si cambio un precio en Ágora, ¿se mantiene? Solo si Wine Advisor no trae precio para ese vino o copa. Si lo trae, la siguiente sincronización pone el de Wine Advisor. ## Referencias - Ficha de la integración: [Wine Advisor en el catálogo de Connect Manager](https://connectmanager.es/integraciones/wine-advisor). - [Zero Connect: publicar la API de Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion). --- # Integración de Uber Eats con Ágora: pedidos y cartas digitales Portal: Delivery Hub · Plataformas URL: https://connectmanager.es/docs/integracion-ubermarketplace-agora Actualizado: 2026-10-03 ## **Manual de Integración de Pedidos con Uber en Connect Manager** ### **1. Introducción** Este manual describe paso a paso cómo configurar una integración de **Pedidos** en **Connect Manager**, el objetivo es dejar operativa la integración de pedidos y la exportación de cartas digitales en el canal de Uber. **NOTA IMPORTANTE (FOS):**El alta del local y el alta de la plataforma de delivery (Uber) las realiza FOS, no el distribuidor. El distribuidor NO puede crear locales ni dar de alta una plataforma de delivery como Uber. Esa parte la hacemos nosotros (FOS). El distribuidor solo revisa/configura los pasos que se indican a continuación. ### **2. Alta o selección de un Local** - En el menú lateral izquierdo, accede a **Administración**. - Haz clic en **Locales**. - Selecciona el local que quieres editar. ### **3. Datos del Local** En la pantalla de detalle del local, completa o revisa los siguientes campos: - **Cliente**: Ponemos el nombre del distribuidor. EJ. “Informática Pepe” - **Nombre**: Lo nombramos siempre de la siguiente forma: Nombre distribuidor – Nombre del local Donde se encuentra el local (Retiro/Sol/Bernabeu) - **URL de API**: Si es un Cloud usamos la URL del ACMS. Si es solo un local tenemos que poner la URL de la terminal Ágora perteneciente al local. - **API key**: Usamos la Api Key del ACMS en caso de que sean varios locales. Si es un único local tenemos que poner la API Key de la terminal Ágora perteneciente al local. - **Dirección:**La dirección correspondiente - **Ciudad:**En que ciudad se ubica el local - **Zona horaria**La zona horaria Una vez completados los datos, pulsa **Guardar**. En ese momento los módulos del lado derecho estarán habilitados. ### **4. Creación de una integración de Pedidos** - En la pantalla de **Integraciones de pedidos**, pulsa **Uber.** - Se abrirá la pantalla de **Configuración general**. ### **5. Configuración general** - **Proveedor:** Aparecerá preseleccionado Uber - **Nombre de la tienda:** Distribuidor – Nombre Local. - **Email de activación de tiendas:** Aquí te llegará un correo con el enlace en el cual tendrás que pinchar para poder activar la integración. - **Email de registro en Uber:** El correo con el cual registraste la tienda en Uber - **Nombre impresora cancelados:** Mirar nombre en Ágora para conocer - **Email receptor de notificaciones:** Aquí es a donde llegarán todas las notificaciones hablando de los distintos cambios que se han implementado - **Enviar automáticamente las cartas digitales:**Esta casilla se marca para que todos los días a X horas se envíen las cartas de forma automática sin necesidad de que el distribuidor lo haga manualmente. Esta opción también se usa para desbloquear los productos todos los días sin necesidad de que sean los camareros quienes los desbloquen de forma manual. ### **6. Configuración de pedidos** En el bloque **Configuración de pedidos**, revisa y completa: - **URL de la Store (canal):** Pegamos el enlace a la tienda de Uber, la buscamos en Google, la copiamos y la pegamos - **URL Agora API:**Usamos la URL local - **Ágora API key:** Usamos la del propio local - **Serie:** Debemos crear una serie diferente por cada uno de los proveedores que integremos. Estas se crean en Ágora – Administración – Series (creamos la serie) – Añadimos la serie creada en la sección de Locales. Lo ideal sería crear series que fueran U1, U2, U3… - **Contador de pedidos:** Inicio de la serie - **Establecer la cantidad mínima de pedidos a 1:**Esta opción la tenemos que activar siempre. - **Producto de cargo por servicio:**No es necesario marcarlo - **Producto de entrega:** No es necesario marcarlo - **Deshabilitar la impresión de pedidos:** En caso de que quieras ahorrar papel, para que no esté la impresora todo el día gastando. Asocia correctamente: - **Locales:** Tenemos que crearlos en Ágora primero. Si el local no aparece o no se asocia, tenemos que añadir las Qustom Queris y la Configuración de Pago y Pedidos, para ello, saltamos al punto 7 Informes personalizados y posteriormente al punto 8, Configuración de Pagos y Pedidos. - **Punto de venta (POS):** Tenemos que crearlo en Ágora primero - **Centro de venta:** Tenemos que crearlo en Ágora primero - **Nombre del centro de venta en pedidos:** En caso de que el nombre original sea demasiado largo y queramos acortarlo. - **Método de pago:**Tenemos que crearlo en Ágora primero - **Usuario:** Se suele poner "UBER" aunque depende de la decisión del cliente el término que quiera usar para nombrarlo - **Cliente:**Se suele poner "UBER" aunque depende de la decisión del cliente el término que quiera usar para nombrarlo - **Usar consulta personalizada para la búsqueda de clientes:** Se marca cuando la base de datos es muy grande y pesada. Lo que se busca con esta opción es agilizar el tiempo de consultas. - **Tarifa:** Se suele poner "UBER" aunque depende de la decisión del cliente el término que quiera usar para nombrarlo Nota: Si todo está debidamente configurado Connect nos dará la asociación del local de forma automática, (no obstante, debemos revisar que los datos son correctos) Esta revisión se realizará en Ágora, donde ante cualquier duda iremos buscando los locales, puntos de venta, centros de venta, métodos de pago, método de pago para efectivo, usuarios, cliente, tarifa... para ver cual es el que corresponde. ### **7. Informes Personalizados (Se hace una vez por cada local, independientemente del número de canales)** Aquí debes descargar "Consultas personalizadas para integraciones de pedidos" y pegar las Querys en la carpeta de Ágora, dentro de Custom Querys. Una vez descargado el archivo accedemos a este enlace en el ACMS C:\Program Files (x86)\IGT Microelectronics\Agora\custom-queries y pegamos los archivos descargados Y si no tenemos ACMS vamos al terminal TPV y pegamos los archivos descargados. Por último, guardamos los cambios en **Guardar**. ### **8. Configuración de Pago y Pedidos** Para configurar esta sección tenemos que acceder a Ágora "Configuración de pago y Pedidos" y posteriormente crear una sección llamada "Delivery" Una vez creada esta sección volvemos a "Locales" y pinchamos en editar y luego en la sección "Configuración de Pedidos" asignamos el la sección "Delivery" la configuración creada previamente ### **9. Configuración de botones (Se hace una vez por cada local, independientemente del número de canales)** Entramos a "Acciones Personalizadas", copiamos una sección de Artículos y copiamos otra sección de Pedidos. La única diferencia entre copiar y crear uno nuevo es que si lo copiamos ya tenemos las imágenes cargadas y nos saltamos esa tarea Luego en Tipo seleccionamos URL/Aplicación Y en acción pegamos la URL “Visualizar Pedidos” que encontramos en la sección de Connect Manager “Integraciones de pedidos” Ahora repetimos los pasos anteriores, solo que para “Tiendas y productos” El siguiente paso es entrar a “Administración” “Puntos de Venta” buscamos el nombre del local que queremos configurar y pinchamos, una vez dentro, deslizamos hacia abajo y buscamos “Opciones de pantalla” es ahí donde se recoge la configuración del punto de venta actual. Esa será la configuración que tendremos que duplicar posteriormente. Una vez hecho lo anterior pasamos a “Configuración de Botones” buscamos el campo con el nombre en cuestión y le damos a “copiar” luego cambiamos el nombre para no dejarlo como Copia de TPV CORAZON DE MARÍA, lo ideal es que quede como TPV CORAZON DE MARÍA o algún nombre similar Por ultimo, faltaría añadir esos botones deslizando hacia abajo en la sección de "Configuración de Botones" tanto en la primera sección como en la segunda. Posteriormente guardamos todos los cambios. Una vez implementados estos cambios solo quedaría asociar el nuevo TPV que tendría que tener un nombre distinto al original que copiamos para poder distinguir entre ambos. La asociación se hace en "Puntos de Venta" buscamos el nombre del local, pinchamos en "Editar" deslizamos hacia abajo y en "Opciones de Pantalla" "Configuración" asociamos el nuevo TPV. ### **10. Tiendas** En la sección de tiendas probablemente nos aparezca vacía. Por lo tanto, tenemos que volver a configuración, y pinchar en el siguiente icono: El de correo, eso enviará un enlace al email escrito con el enlace de activación de la tienda en cuestión. Cuando pinchemos en el enlace y volvamos a la sección de tiendas ya nos aparecerá la tienda en cuestión. Si no aparece, pinchamos en el botón “refrescar” Esto nos indicará que Uber nos ha dado el visto bueno para el siguiente paso ### **11. Cartas digitales** - Acede a la pestaña **Cartas digitales** dentro de la integración del local. - Pincha en el botón de refrescar - A la izquierda marca la carta que deseas exportar. - Pulsa el botón **Enviar a Uber**. - Espera mientras se realiza el envío - Si sale la palabra “Correcto” la tienda estaría integrada ya oficialmente. Estado de la exportación: **No iniciado**: la carta aún no se ha enviado. **Correcto**: la carta se ha exportado correctamente a Uber. Verifica que el estado sea **Correcto**. ### **12. Desactivación de cartas anteriores.** Con la finalidad de evitar que se produzcan errores en Ágora con esta nueva integración. Tenemos que escribir al Account Manager de Uber para que desactive las cartas de las integraciones anteriores, de lo contrario, nos encontraremos con numerosos fallos en los pedidos debido a los solapamientos que se producirían. --- # Integración de Glovo con Ágora: pedidos y cartas digitales Portal: Delivery Hub · Plataformas URL: https://connectmanager.es/docs/integracion-glovomarketplace-agora Actualizado: 2026-10-03 ## **Manual de Integración de Pedidos con Glovo en Connect Manager** ### **1. Introducción** Este manual describe paso a paso cómo configurar una integración de **Pedidos** en **Connect Manager**, el objetivo es dejar operativa la integración de pedidos y la exportación de cartas digitales en el canal de Glovo. **NOTA IMPORTANTE (FOS):**El alta del local y el alta de la plataforma de delivery (Glovo) las realiza FOS, no el distribuidor. El distribuidor NO puede crear locales ni dar de alta una plataforma de delivery como Glovo. Esa parte la hacemos nosotros (FOS). El distribuidor solo revisa/configura los pasos que se indican a continuación. ### **2. Alta o selección de un Local** - En el menú lateral izquierdo, accede a **Administración**. - Haz clic en **Locales**. Selecciona el local que quieres editar. ### **3. Datos del Local** En la pantalla de detalle del local, completa o revisa los siguientes campos: - **Cliente**: Ponemos el nombre del distribuidor. EJ. “Informática Pepe” - **Nombre**: Lo nombramos siempre de la siguiente forma: Nombre distribuidor – Nombre del local Donde se encuentra el local (Retiro/Sol/Bernabeu) - **URL de API**: Si es un Cloud usamos la URL del ACMS. Si es solo un local tenemos que poner la URL de la terminal Ágora perteneciente al local. - **API key**: Usamos la Api Key del ACMS en caso de que sean varios locales. Si es un único local tenemos que poner la API Key de la terminal Ágora perteneciente al local. - **Dirección:**La dirección correspondiente - **Ciudad:**En que ciudad se ubica el local - **Zona horaria**La zona horaria Una vez completados los datos, pulsa **Guardar**. En ese momento los módulos del lado derecho estarán habilitados. ### **4. Creación de una integración de Pedidos** - En la pantalla de **Integraciones de pedidos**, pulsa **Glovo** - Se abrirá la pantalla de **Configuración general**. ### **5. Configuración general** - **Proveedor:** Aparecerá preseleccionado Glovo - **Store Id:** Se genera automáticamente, guardas, sales, lo memorizas, entras y lo anotas - **Nombre de la tienda:** Distribuidor – Nombre Local. - **ID. interno de tienda en Glovo:** No es necesario que sea completado, se puede dejar en blanco - **Permitir formatos de venta adicionales:** No es necesario marcarlo, lo podemos dejar en blanco - **Nombre impresora cancelados:** Mirar nombre en Ágora para conocer - **Email receptor de notificaciones:** Aquí es a donde llegarán todas las notificaciones hablando de los distintos cambios que se han implementado - **Enviar automáticamente las cartas digitales:**Esta casilla se marca para que todos los días a X horas se envíen las cartas de forma automática sin necesidad de que el distribuidor lo haga manualmente. Esta opción también se usa para desbloquear los productos todos los días sin necesidad de que sean los camareros quienes los desbloquen de forma manual. ### **6. Configuración de pedidos** En el bloque **Configuración de pedidos**, revisa y completa: - **URL de la Store (canal):**Pegamos el enlace a la tienda de Glovo, la buscamos en Google, la copiamos y la pegamos - **URL Agora API:**Usamos la URL local - **Ágora API key:** Usamos la del propio local - **Serie:** Debemos crear una serie diferente por cada uno de los proveedores que integremos. Estas se crean en Ágora – Administración – Series (creamos la serie) – Añadimos la serie creada en la sección de Locales. Lo ideal sería crear series que fueran G1, G2, G3… - **Contador de pedidos:**Inicio de la serie - **Establecer la cantidad mínima de pedidos a 1:** Esta opción la tenemos que activar siempre. - **Producto de cargo por servicio:**No es necesario marcarlo - **Producto de entrega:** No es necesario marcarlo - **Marca la opción Incluir notas generales en las líneas:** solo si aplica para este caso. - **Deshabilitar la impresión de pedidos:** En caso de que quieras ahorrar papel, para que no esté la impresora todo el día gastando. Asocia correctamente: - **Locales:**Tenemos que crearlos en Ágora primero. Si el local no aparece o no se asocia, tenemos que añadir las Qustom Queris y la Configuración de Pago y Pedidos, para ello, saltamos al punto 7 Informes personalizados y posteriormente al punto 8, Configuración de Pagos y Pedidos. - **Punto de venta (POS):**Tenemos que crearlo en Ágora primero - **Centro de venta:** Tenemos que crearlo en Ágora primero - **Nombre del centro de venta en pedidos:** En caso de que el nombre original sea demasiado largo y queramos acortarlo. - **Método de pago:** Tenemos que crearlo en Ágora primero - **Método de pago para efectivo:** Crearlo en Ágora - **Dejar el ticket sin pagar para los pagos en efectivo:**Podemos marcarlo dependiendo de la decisión del cliente final - **Usuario:** Se suele poner "GLOVO" aunque depende de la decisión del cliente el término que quiera usar para nombrarlo - **Cliente:** Se suele poner "GLOVO" aunque depende de la decisión del cliente el término que quiera usar para nombrarlo - **Usar consulta personalizada para la búsqueda de clientes:**Se marca cuando la base de datos es muy grande y pesada. Lo que se busca con esta opción es agilizar el tiempo de consultas. - **Tarifa:** Se suele poner "GLOVO" aunque depende de la decisión del cliente el término que quiera usar para nombrarlo Nota: Si todo está debidamente configurado Connect nos dará la asociación del local de forma automática, (no obstante, debemos revisar que los datos son correctos) Esta revisión se realizará en Ágora, donde ante cualquier duda iremos buscando los locales, puntos de venta, centros de venta, métodos de pago, método de pago para efectivo, usuarios, cliente, tarifa... para ver cual es el que corresponde. ### **7. Informes Personalizados (Se hace una vez por cada local, independientemente del número de canales)** Aquí debes descargar "Consultas personalizadas para integraciones de pedidos" y pegar las Querys en la carpeta de Ágora, dentro de Custom Querys. Una vez descargado el archivo accedemos a este enlace en el ACMS C:\Program Files (x86)\IGT Microelectronics\Agora\custom-queries y pegamos los archivos descargados Y si no tenemos ACMS vamos al terminal TPV y pegamos los archivos descargados. Por último, guardamos los cambios en **Guardar**. ### **8. Configuración de Pago y Pedidos** Para configurar esta sección tenemos que acceder a Ágora "Configuración de pago y Pedidos" y posteriormente crear una sección llamada "Delivery" Una vez creada esta sección volvemos a "Locales" y pinchamos en editar y luego en la sección "Configuración de Pedidos" asignamos el la sección "Delivery" la configuración creada previamente ### **9. Configuración de botones (Se hace una vez por cada local, independientemente del número de canales)** Entramos a "Acciones Personalizadas", copiamos una sección de Artículos y copiamos otra sección de Pedidos. La única diferencia entre copiar y crear uno nuevo es que si lo copiamos ya tenemos las imágenes cargadas y nos saltamos esa tarea Luego en Tipo seleccionamos URL/Aplicación Y en acción pegamos la URL “Visualizar Pedidos” que encontramos en la sección de Connect Manager “Integraciones de pedidos” Ahora repetimos los pasos anteriores, solo que para “Tiendas y productos” El siguiente paso es entrar a “Administración” “Puntos de Venta” buscamos el nombre del local que queremos configurar y pinchamos, una vez dentro, deslizamos hacia abajo y buscamos “Opciones de pantalla” es ahí donde se recoge la configuración del punto de venta actual. Esa será la configuración que tendremos que duplicar posteriormente. Una vez hecho lo anterior pasamos a “Configuración de Botones” buscamos el campo con el nombre en cuestión y le damos a “copiar” luego cambiamos el nombre para no dejarlo como Copia de TPV CORAZON DE MARÍA, lo ideal es que quede como TPV CORAZON DE MARÍA o algún nombre similar Por ultimo, faltaría añadir esos botones deslizando hacia abajo en la sección de "Configuración de Botones" tanto en la primera sección como en la segunda. Posteriormente guardamos todos los cambios. Una vez implementados estos cambios solo quedaría asociar el nuevo TPV que tendría que tener un nombre distinto al original que copiamos para poder distinguir entre ambos. La asociación se hace en "Puntos de Venta" buscamos el nombre del local, pinchamos en "Editar" deslizamos hacia abajo y en "Opciones de Pantalla" "Configuración" asociamos el nuevo TPV. **9. Cartas digitales** - Accede a la pestaña **Cartas digitales** dentro de la integración del local. - Pincha en Refrescar - Si la configuración se realizó de forma correcta, deberían aparecer una o varias cartas correspondientes a ese local. **NO** pinches en el botón enviar a Glovo, ya que queda un paso previo. - Tendrías que escribir a Fos para decirnos que has terminado con la configuración y que quieres tener todo integrado para el día dd/mm/aaaa - Nosotros posteriormente hablaríamos con Glovo para que nos dieran autorización y finalmente enviar la carta, pero esto es algo que haríamos ya nosotros ### **10. Estado de la exportación** - **No iniciado**: la carta aún no se ha enviado. - **Correcto**: la carta se ha exportado correctamente a Glovo. Si la carta esta bien integrada, debería aparecer “Correcto” si no se ha iniciado la integración aparecería “No iniciado” Es responsabilidad de Fos ser quienes integren la carta, el distribuidor simplemente debería chequear una vez se haya terminado la integración que aparece el estado “Correcto” 11. **Verificación final** - Comprueba que la integración aparece activa en la lista de integraciones de pedidos. - Confirma que la carta digital tiene estado **Correcto** Recuerda que esto es un paso que deberías realizar una vez Fos ha realizado la integración como si fuera “un segundo chequeo rápido --- # Integración de Just Eat con Ágora: pedidos y cartas digitales Portal: Delivery Hub · Plataformas URL: https://connectmanager.es/docs/integracion-justeatmarketplace-agora Actualizado: 2026-10-03 ## **Manual de Integración de Pedidos con Just Eat en Connect Manager** ### **1. Introducción** Este manual describe paso a paso cómo configurar una integración de **Pedidos** en **Connect Manager**, el objetivo es dejar operativa la integración de pedidos y la exportación de cartas digitales en el canal de Just Eat. **NOTA IMPORTANTE (FOS):**El alta del local y el alta de la plataforma de delivery (Just Eat) las realiza FOS, no el distribuidor. El distribuidor NO puede crear locales ni dar de alta una plataforma de delivery como Just Eat. Esa parte la hacemos nosotros (FOS). El distribuidor solo revisa/configura los pasos que se indican a continuación. ### **2. Alta o selección de un Local** - En el menú lateral izquierdo, accede a **Administración**. - Haz clic en **Locales**. Selecciona el local que quieres editar. ### **3. Datos del Local** En la pantalla de detalle del local, completa o revisa los siguientes campos: - **Cliente**: Ponemos el nombre del distribuidor. EJ. “Informática Pepe” - **Nombre**: Lo nombramos siempre de la siguiente forma: Nombre distribuidor – Nombre del local Donde se encuentra el local (Retiro/Sol/Bernabeu) - **URL de API**: Si es un Cloud usamos la URL del ACMS. Si es solo un local tenemos que poner la URL de la terminal Ágora perteneciente al local. - **API key**: Usamos la Api Key del ACMS en caso de que sean varios locales. Si es un único local tenemos que poner la API Key de la terminal Ágora perteneciente al local. - **Dirección:**La dirección correspondiente - **Ciudad:**En que ciudad se ubica el local - **Zona horaria**La zona horaria Una vez completados los datos, pulsa **Guardar**. En ese momento los módulos del lado derecho estarán habilitados. ### **4. Creación de una integración de Pedidos** - En la pantalla de **Integraciones de pedidos**, pulsa **Just Eat.** - Se abrirá la pantalla de **Configuración general**. ### **5. Configuración general** - **Proveedor:** Aparecerá preseleccionado Just Eat - **Api key de menús:** Este dato lo rellena los empleados de Connect Manager de forma manual. - **Api Key de pedidos:** Este dato lo rellena los empleados de Connect Manager de forma manual. - **Store Id:** Este dato lo rellena los empleados de Connect Manager de forma manual. - **Nombre de la tienda:** Distribuidor – Nombre Local. - **Nombre impresora cancelados:** Mirar nombre en Ágora para conocer - **Enviar automáticamente las cartas digitales:**Esta casilla se marca para que todos los días a X horas se envíen las cartas de forma automática sin necesidad de que el distribuidor lo haga manualmente. Esta opción también se usa para desbloquear los productos todos los días sin necesidad de que sean los camareros quienes los desbloquen de forma manual. ### **6. Configuración de pedidos** En el bloque **Configuración de pedidos**, revisa y completa: - **URL de la Store (canal):** Pegamos el enlace a la tienda de Just Eat, la buscamos en Google, la copiamos y la pegamos - **URL Agora API:** Usamos la URL local - **Ágora API key:** Usamos la del propio local - **Serie:**Debemos crear una serie diferente por cada uno de los proveedores que integremos. Estas se crean en Ágora – Administración – Series (creamos la serie) – Añadimos la serie creada en la sección de Locales. Lo ideal sería crear series que fueran J1, J2, J3… - **Contador de pedidos.** Inicio de la serie - **Establecer la cantidad mínima de pedidos a 1:** Esta opción la tenemos que activar siempre. - **Producto de cargo por servicio:**No es necesario marcarlo - **Producto de entrega:**No es necesario marcarlo - **Marca la opción Incluir notas generales en las líneas,** solo si aplica para este caso. - **Deshabilitar la impresión de pedidos:** En caso de que quieras ahorrar papel, para que no esté la impresora todo el día gastando. Asocia correctamente: - **Locales:** Tenemos que crearlos en Ágora primero. Si el local no aparece o no se asocia, tenemos que añadir las Qustom Queris y la Configuración de Pago y Pedidos, para ello, saltamos al punto 7 Informes personalizados y posteriormente al punto 8, Configuración de Pagos y Pedidos. - **Punto de venta (POS):** Tenemos que crearlo en Ágora primero - **Centro de venta:**Tenemos que crearlo en Ágora primero - **Nombre del centro de venta en pedidos:**En caso de que el nombre original sea demasiado largo y queramos acortarlo. - **Método de pago:**Tenemos que crearlo en Ágora primero - **Usuario:**Se suele poner "JustEat" aunque depende de la decisión del cliente el término que quiera usar para nombrarlo - **Cliente:** Se suele poner "JustEat" aunque depende de la decisión del cliente el término que quiera usar para nombrarlo - **Usar consulta personalizada para la búsqueda de clientes:**Se marca cuando la base de datos es muy grande y pesada. Lo que se busca con esta opción es agilizar el tiempo de consultas. - **Tarifa:** Se suele poner "JustEat" aunque depende de la decisión del cliente el término que quiera usar para nombrarlo Nota: Si todo está debidamente configurado Connect nos dará la asociación del local de forma automática, (no obstante, debemos revisar que los datos son correctos) Esta revisión se realizará en Ágora, donde ante cualquier duda iremos buscando los locales, puntos de venta, centros de venta, métodos de pago, método de pago para efectivo, usuarios, cliente, tarifa... para ver cual es el que corresponde. ### **7. Informes Personalizados (Se sigue este paso 1 vez por local, independientemente del número de canales que haya)** Aquí debes descargar "Consultas personalizadas para integraciones de pedidos" y pegar las Querys en la carpeta de Ágora, dentro de Custom Querys. Una vez descargado el archivo accedemos a este enlace en el ACMS C:\Program Files (x86)\IGT Microelectronics\Agora\custom-queries y pegamos los archivos descargados Y si no tenemos ACMS vamos al terminal TPV y pegamos los archivos descargados. Por último, guardamos los cambios en **Guardar**. ### **8. Configuración de Pago y Pedidos** Para configurar esta sección tenemos que acceder a Ágora "Configuración de pago y Pedidos" y posteriormente crear una sección llamada "Delivery" Una vez creada esta sección volvemos a "Locales" y pinchamos en editar y luego en la sección "Configuración de Pedidos" asignamos el la sección "Delivery" la configuración creada previamente ### **9. Configuración de botones (Se hace una vez por cada local, independientemente del número de canales)** Entramos a "Acciones Personalizadas", copiamos una sección de Artículos y copiamos otra sección de Pedidos. La única diferencia entre copiar y crear uno nuevo es que si lo copiamos ya tenemos las imágenes cargadas y nos saltamos esa tarea Luego en Tipo seleccionamos URL/Aplicación Y en acción pegamos la URL “Visualizar Pedidos” que encontramos en la sección de Connect Manager “Integraciones de pedidos” Ahora repetimos los pasos anteriores, solo que para “Tiendas y productos” El siguiente paso es entrar a “Administración” “Puntos de Venta” buscamos el nombre del local que queremos configurar y pinchamos, una vez dentro, deslizamos hacia abajo y buscamos “Opciones de pantalla” es ahí donde se recoge la configuración del punto de venta actual. Esa será la configuración que tendremos que duplicar posteriormente. Una vez hecho lo anterior pasamos a “Configuración de Botones” buscamos el campo con el nombre en cuestión y le damos a “copiar” luego cambiamos el nombre para no dejarlo como Copia de TPV CORAZON DE MARÍA, lo ideal es que quede como TPV CORAZON DE MARÍA o algún nombre similar Por ultimo, faltaría añadir esos botones deslizando hacia abajo en la sección de "Configuración de Botones" tanto en la primera sección como en la segunda. Posteriormente guardamos todos los cambios. Una vez implementados estos cambios solo quedaría asociar el nuevo TPV que tendría que tener un nombre distinto al original que copiamos para poder distinguir entre ambos. La asociación se hace en "Puntos de Venta" buscamos el nombre del local, pinchamos en "Editar" deslizamos hacia abajo y en "Opciones de Pantalla" "Configuración" asociamos el nuevo TPV. ### **10. Cartas digitales** - Accede a la pestaña **Cartas digitales** dentro de la integración del local. - Pincha en Refrescar - Si la configuración se realizó de forma correcta, deberían aparecer una o varias cartas correspondientes a ese local. **NO** pinches en el botón enviar a JustEat, ya que queda un paso previo. - Tendrías que escribir a Fos para decirnos que has terminado con la configuración y que quieres tener todo integrado para el día dd/mm/aaaa - Nosotros posteriormente hablaríamos con JustEat para que nos dieran autorización y finalmente enviar la carta, pero esto es algo que haría Fos ### **11. Estado de la exportación** - **No iniciado**: la carta aún no se ha enviado. - **Correcto**: la carta se ha exportado correctamente a Just Eat. Si la carta esta bien integrada, debería aparecer “Correcto” si no se ha iniciado la integración aparecería “No iniciado” Es responsabilidad de Fos ser quienes integren la carta, el distribuidor simplemente debería chequear una vez se haya terminado la integración que aparece el estado “Correcto” ### 12. **Verificación final** - Comprueba que la integración aparece activa en la lista de integraciones de pedidos. - Confirma que la carta digital tiene estado **Correcto** Recuerda que esto es un paso que deberías realizar una vez Fos ha realizado la integración como si fuera “un segundo chequeo rápido --- # Integración de WooCommerce con Ágora: pedidos para recoger Portal: Delivery Hub · Plataformas URL: https://connectmanager.es/docs/integracion-woocommerce-agora Actualizado: 2026-10-03 La integración de **WooCommerce** con **Ágora** lleva al TPV los pedidos de la tienda online para recoger en el local: WooCommerce avisa a Connect Manager de cada pedido, Connect Manager lo asigna al local de recogida que eligió el cliente y lo crea en Ágora como pedido pendiente, con su fecha de recogida y, si ya está pagado, con su cobro. Si el pedido se cancela en la web, se anula también en Ágora. Este manual es para el técnico de FOS o del distribuidor que conecta una tienda WooCommerce con los locales de un cliente. ## Qué hace la integración - Recibe al momento los pedidos de WooCommerce por webhook y comprueba la firma de cada aviso. - Asigna cada pedido a un local según el método de envío que eligió el cliente: cada local tiene su integración y solo se queda con los pedidos cuyo método de recogida coincide con su filtro. - Crea el pedido en Ágora cuando pasa a **Completado** o **En espera**, como pedido pendiente con la serie y el contador configurados, el cliente, el TPV, el usuario, el centro de venta y la tarifa del local. - Pone como fecha de recogida la que el cliente eligió en la web (campo «Fecha de Recogida» del pedido) o, si el pedido no la trae, la de creación más los días configurados. - Registra el cobro con la forma de pago de Ágora configurada y el nombre del método de pago de la web. Los pedidos **En espera** entran sin cobrar. - Anula en Ágora el pedido que se cancela en la web, si Ágora todavía lo tiene abierto. - Copia en las notas del pedido el teléfono, el correo y la nota del cliente, y pone su nombre en los datos del cliente del pedido. - Recupera cada hora, por la API de WooCommerce, los pedidos modificados en las últimas dos horas, por si algún aviso no llegó, y reintenta dos veces al día los que fallaron. - Avisa por correo si un pedido llega con la fecha de recogida vacía, si pasan las horas configuradas sin pedidos, y por correo y Telegram si un pedido no se puede procesar. - Guarda cada pedido en **Pedidos → WooCommerce** con su estado en la web y su estado de envío a Ágora, y permite reenviarlo. ### Qué no hace - No envía la dirección de entrega: los pedidos son para recoger. - No crea en Ágora los pedidos **Pendiente de pago** ni **Procesando**: entran cuando pasan a Completado o En espera. - No envía gastos de envío, recargos ni descuentos de pedido: solo las líneas de producto con su importe. - No busca los productos por nombre: la SKU de WooCommerce tiene que ser el Id. del producto de Ágora. - No elige el IVA de cada producto: todas las líneas van con el impuesto de Ágora de Id. 3. - No anula un pedido que en Ágora ya está facturado o cancelado. ## Requisitos - **WooCommerce** con la API REST disponible y acceso de administrador para crear claves de API y webhooks. - **Un método de envío de recogida por local** en WooCommerce, cada uno con un título distinto (por ejemplo «Recoger en tienda Centro»). - **Fecha de recogida** guardada en el pedido por el plugin de la tienda, en un metadato llamado exactamente `Fecha de Recogida` con formato `AAAA-MM-DD`. - **SKU de cada producto o variación de WooCommerce** igual al Id. del producto en Ágora. - **Ágora**: API accesible desde Internet (puerto abierto o [Zero Connect](https://connectmanager.es/docs/zero-connect-instalacion)), porque Connect Manager crea los pedidos con la API de importación; una serie de pedidos que exista en el local y no sea la activa; y el impuesto de Id. 3 con el IVA que corresponde a estos productos. - **Connect Manager**: local dado de alta con la URL de la API y la API key de Ágora. El alta del local y de la integración la hace FOS. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la tienda | Cliente | https://tienda-demo.com | Sí | | Consumer key y Consumer secret (lectura) | WooCommerce → Ajustes → Avanzado → API REST | ck_… / cs_… | Sí | | Secreto del webhook | Lo inventas tú y lo pones en los dos sistemas | Cadena larga aleatoria | Sí | | Título del método de recogida de cada local | WooCommerce → Ajustes → Envío | Recoger en tienda Centro | Sí | | Serie y último número de pedido | Ágora (serie adicional del local) | Serie WEB, contador 0 | Sí | | Local, TPV, usuario, centro de venta, tarifa, cliente y forma de pago de Ágora | Ágora (se eligen en buscadores) | Cliente «Pedidos web» | Sí | | Días de recogida si el pedido no trae fecha | Cliente | 2 | No | | Horas sin pedidos para avisar | Cliente | 12 | No | | Correos y chat de Telegram para avisos | Cliente o distribuidor | pedidos@ejemplo.com | No | ## Configuración paso a paso ### En WooCommerce - Revisa que cada producto y cada variación tiene como **SKU** el Id. del producto de Ágora. - En **WooCommerce → Ajustes → Envío**, crea un método de recogida por local con un título distinto y apúntalo tal cual. - En **WooCommerce → Ajustes → Avanzado → API REST**, añade una clave con permisos de **Lectura** y guarda el **Consumer key** y el **Consumer secret**. - Los webhooks se crean después, cuando Connect Manager te dé la URL de cada local. ### En Connect Manager - En `https://app.connectmanager.es`, ve a **Administración → Locales**, abre el local, revisa la **URL de API** y la **API key** de Ágora y pulsa **Guardar**. - Entra en **Integraciones de pedidos**, pulsa **Añadir** y en **Proveedor** elige **WooCommerce (AC)**. La otra variante de WooCommerce de la lista tiene reglas propias y no es la de este manual. - Credenciales: - **URL Api**: la URL de la tienda. - **Customer key**: el **secreto del webhook**, el mismo que pondrás en WooCommerce. Con él se comprueba la firma de cada aviso. - **Consumer key:** y **Consumer secret:** las claves de la API REST, para la recuperación horaria. - Envío y avisos: - **Enviar pedidos a Ágora**: márcala. Desmarcada, los pedidos se guardan como «Pausado» y no llegan al TPV. - **Número de horas sin pedidos para notificar** y **Número de días cuando la fecha de entrega está vacía** (2 si se deja vacío). - **Email de receptor de notificaciones** e **Id. de chat de Telegram para recibir notificaciones** (ver [Telegram](https://connectmanager.es/docs/integracion-telegram-agora)). - En **Configuración de pedidos**, escribe en **Filtro por método de entrega** el título exacto del método de recogida de este local. Las opciones **Pausar el envío de pedidos después de** y **Pausar el envío de pedidos a Ágora** las ve y las usa FOS. - Datos de Ágora: **Serie**, **Cont. de pedidos** (último número usado; el siguiente pedido llevará este más uno), **Locales**, **Punto de venta (POS)**, **Centro de venta**, **Método de pago**, **Usuario**, **Cliente** y **Tarifa**. Todos son obligatorios para que el pedido se cree. - Pulsa **Guardar** y copia la **URL del webhook de WooCommerce** de la sección **Enlaces**. - Repite la integración en cada local de recogida, cada uno con su filtro y su serie. ### En WooCommerce (webhooks) - En **WooCommerce → Ajustes → Avanzado → Webhooks**, añade un webhook por local con **Estado** Activo, **Tema** «Pedido actualizado», **URL de entrega** la del local y **Secreto** el mismo que pusiste en **Customer key**. Usa la versión 3 de la API REST. - Añade otro igual con el tema «Pedido creado». > [!WARNING] Si el secreto del webhook no coincide con el campo **Customer key**, Connect Manager descarta el aviso pero contesta a WooCommerce con un 200, así que el webhook parece correcto. En el registro de entregas del webhook verás la respuesta «La firma proporcionada no es válida.». ## Cómo funciona Cada vez que se crea o cambia un pedido, WooCommerce lo manda firmado a la URL de cada local. Connect Manager comprueba la firma, mira si el método de envío coincide con el filtro del local y guarda el pedido. Si su estado es Completado, En espera o Cancelado, le asigna el siguiente número del contador y lo importa en Ágora como pedido de la serie configurada: pendiente si está completado o en espera, cancelado si se canceló. El resultado queda en el listado de pedidos. ```mermaid sequenceDiagram participant WEB as WooCommerce participant CM as Connect Manager participant AG as API Ágora WEB->>CM: Webhook firmado con el pedido CM->>CM: Comprueba firma y método de recogida CM->>CM: Guarda el pedido y asigna serie y número CM->>AG: Importa el pedido pendiente con fecha de recogida AG-->>CM: Importación correcta CM->>CM: Marca el pedido como Enviado Note over CM,AG: Si la web lo cancela se reimporta con el mismo número como cancelado ``` ### Qué se envía a Ágora - **Cabecera**: serie y número, fecha y fecha de negocio de creación en la web, fecha de recogida, estado (pendiente o cancelado), local, TPV, usuario, centro de venta y cliente de Ágora con el nombre, teléfono y correo del comprador. - **Notas**: teléfono, correo y nota del cliente. - **Líneas**: cada producto con su SKU como Id. de producto y de formato, el nombre de la web, la cantidad, el precio, el importe de la línea, la tarifa configurada y el impuesto de Id. 3. - **Cobro**: en los pedidos completados, un pago anticipado por el total con la forma de pago configurada; en los pedidos en espera, ninguno. ### Recuperación, reintentos y estados Cada hora, Connect Manager pide a la API de WooCommerce los pedidos modificados en las dos últimas horas y procesa los que han cambiado de estado o de fecha de recogida. Dos veces al día vuelve a intentar los pedidos que quedaron en error. En el listado, el **Estado envío (Ágora)** puede ser Sin enviar, En proceso, Enviado, Error o Pausado. Cada integración solo atiende los pedidos de su método de recogida. De esos, los Pendientes de pago o Procesando se guardan y esperan; los Completados entran como pedido pendiente cobrado, los En espera como pedido pendiente sin cobrar y los Cancelados anulan el pedido en Ágora. ```mermaid flowchart LR A[Pedido de la web] --> B{Método de recogida del local} B -- No --> X[Lo ignora esta integración] B -- Sí --> C{Estado en la web} C -- Pendiente o Procesando --> D[Se guarda y espera] C -- Completado --> E[Pedido pendiente cobrado] C -- En espera --> F[Pedido pendiente sin cobrar] C -- Cancelado --> G[Pedido cancelado en Ágora] ``` ## Comprobar que funciona - En el registro del webhook de WooCommerce, comprueba que la entrega de prueba recibe un 200. - Haz un pedido de prueba con el método de recogida del local y la fecha de recogida, y márcalo como Completado. - En **Pedidos → WooCommerce** debe aparecer con Estado del pedido «Completado» y Estado envío «Enviado». - En Ágora, el pedido debe estar en la serie configurada, con la fecha de recogida, los productos correctos y el cobro. - Haz otro pedido y déjalo En espera: debe entrar en Ágora sin cobrar. - Cancela uno de los pedidos en la web: en Ágora debe quedar cancelado. - Haz un pedido con el método de recogida de otro local y comprueba que solo entra en ese local. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | No llega ningún pedido y el webhook responde «La firma proporcionada no es válida.» | El secreto del webhook no coincide con Customer key. | Pon el mismo valor en los dos sitios. | | El pedido no aparece en el listado del local | El título del método de envío no coincide exactamente con el Filtro por método de entrega. | Copia el título tal cual, con mayúsculas y espacios. | | El pedido aparece pero no está en Ágora y está «Procesando» | Solo se envían los pedidos Completados, En espera o Cancelados. | Cambia el estado en la web, o revisa el flujo de estados de la tienda. | | Estado envío «Pausado» | Enviar pedidos a Ágora desmarcada o integración pausada por FOS. | Marca la casilla (o pide a FOS que la reactive) y pulsa Enviar a Ágora. | | Estado envío «Error» | Ágora ha rechazado la importación: SKU que no es un Id. de producto, serie activa o inexistente, o API de Ágora inaccesible. | Revisa la Petición Ágora del pedido, corrige y pulsa Enviar a Ágora. | | Aviso «Revise la configuración para el local … y proveedor woocommerce.» | Falta algún dato de Ágora en la integración. | Completa serie, local, TPV, centro de venta, forma de pago, usuario, cliente y tarifa. | | Correo «Revisar pedido de WooCommerce: … ha llegado a Ágora sin fecha de entrega.» | El pedido trae el campo «Fecha de Recogida» vacío. | Revisa el pedido con el cliente; en Ágora lleva la fecha de creación más los días configurados. | | La cancelación de la web no llega a Ágora | El pedido ya estaba facturado o cancelado en Ágora. | Anúlalo o abónalo a mano en Ágora. | ## Preguntas frecuentes ### ¿Cómo conecto WooCommerce con Ágora? Con una integración de pedidos de Connect Manager por local de recogida y un webhook de WooCommerce hacia cada una, con el mismo secreto en los dos sistemas. ### ¿Los pedidos de WooCommerce entran cobrados en Ágora? Los Completados sí, con la forma de pago de Ágora configurada. Los En espera entran sin cobrar. ### ¿Sirve para pedidos a domicilio? No. La integración no envía la dirección de entrega: está pensada para recoger en el local. ### ¿Cómo sabe qué producto de Ágora es cada producto de la web? Por la SKU: en WooCommerce tiene que ser el Id. del producto de Ágora. ### ¿Qué pasa si el cliente cancela el pedido en la web? Se reenvía a Ágora con el mismo número como cancelado, siempre que Ágora no lo haya facturado ya. ### ¿Por qué un pedido «Procesando» no está en el TPV? Porque solo se crean en Ágora los pedidos Completados o En espera; los Cancelados se anulan. ## Referencias - Ficha de la integración: [WooCommerce en el catálogo de Connect Manager](https://connectmanager.es/integraciones/woocommerce). - [Avisos de las integraciones por Telegram](https://connectmanager.es/docs/integracion-telegram-agora). - [Zero Connect: publicar la API de Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion). - Webhooks de WooCommerce: [https://woocommerce.com/document/webhooks/](https://woocommerce.com/document/webhooks/). - API REST de WooCommerce: [https://woocommerce.github.io/woocommerce-rest-api-docs/](https://woocommerce.github.io/woocommerce-rest-api-docs/). --- # Carta digital para delivery en Ágora Portal: Delivery Hub · Plataformas URL: https://connectmanager.es/docs/integracion-cartadigital-agora Actualizado: 2026-10-03 **Manual de Creación de una Carta Digital** Este manual explica paso a paso cómo crear y gestionar una **Carta Digital** en el sistema. **1. Creación del Usuario Delivery** El primer paso para la creación de una **Carta Digital** es configurar el usuario **Delivery**, que será el encargado de gestionar los pedidos realizados desde la carta. **Pasos a seguir:** - Accede al menú **Administración** desde el panel lateral izquierdo. - En la sección **Usuarios**, haz clic en **Usuarios**. - Se mostrará el **Listado de Usuarios**. - Pulsa el botón **+ Nuevo** para crear un nuevo usuario. - Completa los siguientes campos: - **Nombre**: Delivery - **Perfil**: Administrador (o el perfil definido para Delivery según la configuración del negocio) - Guarda los cambios para finalizar la creación del usuario. ✅ Una vez creado, el usuario **Delivery** aparecerá en el listado y podrá ser utilizado para la gestión de la Carta Digital. **2. Creación de la Forma de Pago Delivery** El segundo paso para la correcta configuración de la **Carta Digital** es crear una **Forma de Pago específica para Delivery**, que permitirá identificar y gestionar los pedidos realizados a través de plataformas externas. **Pasos a seguir:** - Accede al menú **Administración** desde el panel lateral izquierdo. - En la sección **Tarifas y Precios**, haz clic en **Formas de Pago**. - Se mostrará el listado de **Formas de Pago** existentes. - Pulsa el botón **+ Nuevo** para crear una nueva forma de pago. - Completa los siguientes campos: - **Nombre**: Glovo (o el nombre de la plataforma de delivery correspondiente) - Permitir usar en documentos de venta - Guarda los cambios para finalizar la creación de la forma de pago. ✅ Una vez creada, la forma de pago **Glovo** aparecerá en el listado y podrá asociarse a los pedidos realizados desde la Carta Digital. **3. Creación de Categorías para la Carta Digital** Una vez creados el usuario y la forma de pago, el siguiente paso es crear las **categorías destinadas exclusivamente a la Carta Digital**. Estas categorías deben estar **claramente identificadas**, por ejemplo añadiendo el prefijo **(QR)** en su nombre. **Pasos a seguir:** - Accede al menú **Administración** desde el panel lateral izquierdo. - En la sección **Catálogo**, haz clic en **Categorías**. - Se mostrará el **Listado de Categorías**. - Pulsa el botón **+ Nuevo** para crear una nueva categoría. - Completa los siguientes campos: - **Nombre**: (QR) Entrantes, (QR) Primeros, (QR) Segundos, (QR) Postres (según las necesidades del negocio). - **Mostrar en TPV**: **No** - **Mostrar en Menús**: **Sí** - Guarda los cambios y repite el proceso para todas las categorías necesarias. ✅ Las categorías creadas aparecerán identificadas con el prefijo **(QR)**, facilitando su uso exclusivo en la Carta Digital sin interferir con el TPV. **4. Creación de la Tarifa Delivery** Para que los productos de la **Carta Digital** puedan tener precios específicos (distintos al salón), es necesario crear una **tarifa exclusiva para Delivery**. **Pasos a seguir:** - Accede al menú **Administración** desde el panel lateral izquierdo. - En la sección **Tarifas y Precios**, haz clic en **Tarifas**. - Se mostrará el **Listado de Tarifas** existentes. - Pulsa el botón **+ Nuevo** para crear una nueva tarifa. - Completa los siguientes campos: - **Nombre**: Delivery - **Tipo**: Impuestos incluidos - Guarda los cambios para finalizar la creación de la tarifa. ✅ Una vez creada, la tarifa **Delivery** aparecerá en el listado y podrá asignarse a los productos de la Carta Digital, permitiendo definir precios específicos para este canal. **5. Creación y Configuración del Centro de Venta Delivery** Para finalizar la configuración de la **Carta Digital**, es necesario crear un **Centro de Venta específico para Delivery**, asociado a la tarifa creada anteriormente y con sus propias ubicaciones. **Pasos a seguir:** - Accede al menú **Administración** desde el panel lateral izquierdo. - En la sección **Tarifas y Precios**, haz clic en **Centros de Venta**. - Pulsa **+ Nuevo** o edita uno existente para configurar el centro de venta. - En el apartado **Centro de Venta**, completa los siguientes campos: - **Nombre**: Glovo - **Tarifa**: Delivery - **Almacén**: Almacén General - **Grupo Inicial**: - **Pedir Comensales**: Nunca - **Pedir Identificador de Ticket**: Nunca - (Opcional) Configura los parámetros adicionales según las necesidades del negocio: - Iniciar pedido telefónico al abrir ubicación - Habilitar tiempo de inactividad - En el apartado **Ubicaciones / Mesas**: - Pulsa **Añadir ubicación/mesa** - Crea Varias ubicación con el nombre Glovo1, Glovo2 Etc (o el nombre que se desee) ✅ El centro de venta **Glovo** quedará correctamente configurado y listo para gestionar pedidos de la **Carta Digital**, utilizando su propia tarifa, categorías y productos. **6. Creación y Configuración de la Carta Digital** Una vez configurados usuarios, tarifas, categorías y centro de venta, el último paso es crear la **Carta Digital** y asociarle las categorías correspondientes para su publicación. **Pasos a seguir:** - Accede al menú **Herramientas** (o **Administración**, según configuración) y haz clic en **Cartas Digitales**. - Se mostrará el **Listado de Cartas Digitales**. - Pulsa el botón **+ Nuevo** para crear una nueva carta. - Completa los siguientes campos principales: - **Nombre**: Delivery - **Tarifa 1**: seleccionar la tarifa que se desee mostrar (por ejemplo General o Delivery, según la estrategia de precios) - Guarda para acceder a la edición de la carta. **Asignación de Categorías a la Carta** - En el apartado **Categorías de la Carta**: - Busca y añade las categorías creadas para la Carta Digital. - Ajusta el orden de las categorías si es necesario utilizando las flechas. **Acceso a la Carta Digital** - En el apartado **Acceso a la Carta**: - El sistema generará automáticamente: - Un **enlace web** para acceder a la carta. - Un **código QR** que puede descargarse pulsando **Descargar QR**. - Este QR podrá utilizarse para acceder a la Carta Digital desde cualquier dispositivo móvil. **** ✅ La **Carta Digital Delivery** quedará creada, publicada y lista para su uso mediante enlace web o código QR. **7. Configuración del Local para Pagos y Pedidos de Carta Digital** Para que la **Carta Digital** funcione correctamente y permita la gestión de pedidos y pagos, es necesario configurar el **Local**, asociando la pasarela de pago y los tipos de pedido. **Configuración de la Pasarela de Pago** - Accede al menú **Administración** y entra en **Locales**. - Selecciona el local correspondiente y haz clic en **Editar**. - En el apartado **Pasarela de Pago**, configura los siguientes campos: - **Pasarela de Pago**: Ágora Payments - **Comercio**: (facilitado por la entidad de pago) - **Tienda**: (facilitado por la entidad de pago) - **Clave** - **Clave Cliente** - **Id. Comercio Google** (opcional) - Una vez introducidos los datos, pulsa **Comprobar credenciales** para validar la configuración. Si no tienes una pasarela de pagos puedes rellenar el campo como por ejemplo 123. Pero deben estar rellenos si o si. **Configuración de Pedidos** - En el apartado **Configuración de Pedidos**, asigna los siguientes valores: - **Scan & Pay**: Scan & Pay - **Pedido en Mesa**: Desactivado (o según operativa del local) - **Take Away**: Desactivado (o según operativa del local) - **Delivery**: Delivery - **Plantilla**: Plantilla A4 Personalizada (o la definida por el negocio) ✅ Con esta configuración, el local quedará preparado para: - Recibir pedidos desde la **Carta Digital** - Gestionar pedidos **Delivery** - Procesar pagos a través de **Ágora Payments** **** **8. Activación de la Pasarela de Pago para la Carta Digital** Una vez configurado el local y los métodos de pago, es necesario **activar la pasarela de pago de la Carta Digital** para que los clientes puedan realizar pagos correctamente desde el enlace o código QR. **Pasos a seguir** - Accede al menú **Ayuda** - En la parte inferior derecha, localiza el apartado **Pasarela de Pago (Carta Digital)**. - Verifica que los datos mostrados sean correctos: - Pulsa el botón **Conectar** para activar la pasarela de pago. **9. Creacion de Tarifa Delivery** Una vez configurado el local y los métodos de pago, es necesario **activar la pasarela de pago de la Carta Digital** para que los clientes puedan realizar pagos correctamente desde el enlace o código QR. **Pasos a seguir** - Accede al menú **Ayuda** - En la parte inferior derecha, localiza el apartado **Pasarela de Pago (Carta Digital)**. - Verifica que los datos mostrados sean correctos: - Pulsa el botón **Conectar** para activar la pasarela de pago. **10. Creación de Series** Una vez configurado el sistema, es necesario crear y configurar las series de numeración para que los documentos (como pedidos) se generen de forma automática y ordenada. **Pasos a seguir** - Accede al menú **Administración**. - Dirígete al apartado **Series**. - Pulsa sobre **Crear**. - En el formulario de Serie, completa los siguientes campos: - **Nombre**: introduce el identificador de la serie (por ejemplo: G14). - **Tipo**: selecciona el tipo de documento al que se aplicará la serie (por ejemplo: Pedido). - **Siguiente Nº**: indica el número con el que comenzará la numeración automática. - Posteriormente debemos Agregar estas series al local. **11. Configuración de Delivery** Es necesario configurar el **tipo de pedido Delivery** para definir su comportamiento, flujo de estados y opciones de pago dentro del sistema. **Pasos a seguir** - Accede al menú **Administración**. - Entra en el apartado **Herramientas**. - Selecciona la configuración correspondiente a **Pagos y Pedidos, crea o edita**. - En la sección de datos generales, verifica que los siguientes campos estén correctamente configurados: - **Nombre**: Delivery. - **Tipo**: Delivery. - **Punto de Venta**: selecciona el TPV correspondiente. - **Usuario**: usuario asignado a los pedidos Delivery. - **Forma de Pago**: selecciona la plataforma o método (por ejemplo, Glovo). - **Tarifa**: tarifa asociada al Delivery. - **Ubicación**: ubicación configurada para este tipo de pedido. **Opciones de Entrega** - En el apartado **Opciones de Entrega**, configura las formas de pago permitidas: - Marca **Permitir pago al realizar pedido** para exigir el pago anticipado. - Marca **Permitir pago al entregar pedido** si se permite el cobro en la entrega. **Gestión de Pedidos** - En el bloque **Gestión de Pedidos**, define el flujo automático de estados: - **Al recibir un nuevo pedido pagado** → pasar a **En Preparación**. - Marca la opción **Emitir una factura** si se requiere facturación automática. - **Al recibir un nuevo pedido sin pagar** → pasar a **Nuevo**. - **Al facturar un pedido** → pasar a **En Preparación**. --- # Inicio (panel principal) Portal: Delivery Hub · Panel URL: https://connectmanager.es/docs/manual-inicio Actualizado: 2026-06-17 ## Inicio (panel principal) El panel principal es el punto de entrada a tu negocio. Aquí ves de un vistazo todos tus pedidos, ingresos y operadores, con filtros para ajustar la fecha y tienda que quieres analizar. Sirve para monitorizar el día a día, detectar tendencias y entender cuál es tu operadora o tienda que genera más ventas. ### Cómo usarlo - **Selecciona tu tienda:** Usa el desplegable "Tienda" arriba a la izquierda para ver datos de una tienda específica o "Todas las tiendas" para una visión global. - **Elige el período:** Haz clic en "Período" para seleccionar entre Hoy, Ayer, Últimos 7 días, Últimos 30 días, Este Mes, Este Año o un rango personalizado con fechas propias. - **Personaliza rangos de fechas:** Si seleccionas "Personalizado", te aparecerán dos campos de fecha (Desde/Hasta). Pon las fechas que quieras consultar. - **Lee tus KPIs principales:** En la parte superior ves el total de pedidos, ingresos totales y cómo se distribuyen entre Uber Eats, Glovo, Just Eat, tu delivery propio y otros canales. - **Consulta el mapa de calor:** Observa en la matriz de horas y días cuándo tienes picos de demanda. Puedes cambiar entre número de pedidos o euros según te interese. - **Analiza tramos horarios por operadora:** Mira en qué franjas del día (mañana, mediodía, tarde, noche) cada canal genera más negocio. Puedes agrupar por horas individuales, bloques de 2 horas o franjas. - **Revisa la evolución del ticket medio:** En el gráfico de línea, ve cómo sube o baja tu costo promedio por pedido a lo largo del tiempo, desglosado por operadora. - **Compara ranking de tiendas:** En la tabla de ventas, ordena tus locales por ingresos, número de pedidos o ticket medio. Pincha en "Ordenar por" para cambiar el criterio. - **Atiende cartas digitales con problemas:** Si alguna carta digital falló en el envío al agregador, la verás en la tabla inferior con un botón de reintento. Pulsa el icono de flecha para re-enviar. ### Consejos - **Usa rangos personalizados para comparativas:** Copia la URL del navegador y comparte con tu equipo; el período que hayas elegido se mantiene cuando abren el enlace. - **Monitoriza cartas fallidas cada día:** Si ves una carta en rojo, no ignores la alerta; re-enviarla puede tardar unos minutos en procesarse en segundo plano. - **Combina filtros para análisis profundo:** Filtra por tienda + período + operadora en cada widget para entender patrones específicos (ej. "¿cuánto vendo en Glovo los viernes en mi local principal?"). - **Espera a que cargue el dashboard en la primera visita:** La primera carga puede tardar unos segundos mientras se sincronizan datos con los agregadores; luego es más rápido gracias a la caché. --- # Pedidos Delivery Portal: Delivery Hub · Panel URL: https://connectmanager.es/docs/manual-pedidos-delivery Actualizado: 2026-06-17 ## Pedidos Delivery Aquí ves todos tus pedidos de los canales de reparto conectados (Uber Eats, Glovo, Just Eat). Puedes filtrar por local, rango de fechas y estado, y actuar sobre ellos directamente: aceptarlos, marcar el tiempo de preparación, rechazarlos o cancelarlos. Cada pedido se sincroniza con Ágora en tiempo real, así que siempre tienes el control. ### Cómo usarlo - **Busca y filtra:** Usa los filtros en la parte superior para encontrar pedidos por local, rango de fechas, canal o estado. También puedes buscar por la referencia del pedido (ID, número de Ágora como `AG25-12`, o referencia del canal). - **Haz clic en un pedido:** Abre el detalle completo con todos los datos: cliente, dirección, artículos, total y notas. Desde ahí puedes actuar sobre el pedido. - **Selecciona pedidos:** Marca la casilla de cada pedido para seleccionar varios. Aparecerá una barra de acciones flotante en la parte inferior. - **Envía a Ágora:** Si el pedido está pendiente de sincronización (por ejemplo, acabas de recibirlo), haz clic en "Enviar a Ágora" para registrarlo en tu sistema de gestión. El estado pasará de "Pendiente" a "Enviado". - **Acciones por canal (Uber Eats solamente):** Si el pedido es de Uber y está seleccionado solo, puedes: - **Aceptar:** Confirma que preparás el pedido. - **Preparación:** Abre un diálogo para indicar la hora estimada de entrega (formato HH:mm). - **Rechazar:** Abre un diálogo para elegir motivo (local cerrado, sin stock, etc.) y dejar un comentario opcional. El cliente lo verá en la app. - **Cancelar:** Cancela un pedido ya aceptado. Requiere motivo y es diferente a rechazar. - **Revisa los estados:** Cada pedido muestra dos estados: - **Estado Canal:** Aceptado, Completado, En Reparto, Entregado, Cancelado o Rechazado (del proveedor). - **Estado Ágora:** Pendiente, Enviado, Entregado, Error o Fallido (tu sincronización con Ágora). ### Consejos - Si ves "Error" o "Fallido" en Estado Ágora, el pedido no llegó bien a tu sistema. Haz clic en "Enviar a Ágora" para reintentar. - Los botones de Aceptar, Preparación, Rechazar y Cancelar solo funcionan con un pedido de Uber Eats a la vez. Para otros canales, sincronizan automáticamente desde el proveedor. - Usa la búsqueda por número Ágora (`AG25-12`) para encontrar rápidamente un pedido que acabas de ver en Ágora. - En móvil, abre los filtros con el botón de menú y desliza hacia arriba para ver la barra de acciones al seleccionar pedidos. --- # Tiendas Portal: Delivery Hub · Panel URL: https://connectmanager.es/docs/manual-tiendas Actualizado: 2026-06-17 ## Tiendas Este apartado te permite ver el estado en tiempo real de tus tiendas en los principales canales de delivery (Uber Eats, Glovo, Just Eat y Delivery). Desde aquí puedes monitorear si cada tienda está abierta o cerrada en cada plataforma, y cerrarla o reabrirla de forma temporal si lo necesitas. ### Cómo usarlo - **Selecciona una tienda:** En el filtro superior, elige una tienda de la lista desplegable. El sistema cargará todas las integraciones activas de esa tienda en los canales de delivery. - **Filtra por canal (opcional):** Si quieres ver solo una plataforma específica (Uber Eats, Glovo, Just Eat o Delivery), usa el segundo filtro. Si lo dejas en blanco, verás todas. - **Consulta el estado:** Para cada integración, verás un badge que indica si la tienda está **Abierta** (verde) o **Cerrada** (rojo). Debajo aparece un detalle de por qué está cerrada si aplica (ej: "fuera de horario", "pausada manualmente"). - **Cierra temporalmente:** Si la tienda está abierta y tienes permisos, selecciona los minutos (30, 60 o 120) y haz clic en **Cerrar Tienda**. Se te pedirá confirmación. - **Reabre la tienda:** Si está cerrada, el botón cambia a **Reabrir Tienda**. Haz clic para volverla a poner operativa. - **Actualiza manualmente:** Usa el botón de recarga (flecha circular) si quieres ver el estado más reciente sin esperar. ### Consejos - **Cierre temporal vs. definitivo:** El cierre temporal expira después del tiempo que especifiques. Es útil para pausas cortas (comida, descansos). No sustituye a la pausa manual desde la plataforma. - **Permisos necesarios:** Necesitas permisos específicos para cerrar o reabrir tiendas. Si ves los botones deshabilitados, contacta con tu administrador. - **Información del ID:** Cada integración muestra un ID único y, en algunos casos, el ID externo de la plataforma. Esto te ayuda a identificarla si hay dudas. - **Sin integraciones activas:** Si no ves resultados, asegúrate de haber conectado esa tienda con los canales de delivery en el panel de Integraciones. --- # Productos (disponibilidad) Portal: Delivery Hub · Panel URL: https://connectmanager.es/docs/manual-productos Actualizado: 2026-06-17 ## Productos (disponibilidad) Aquí marcas qué productos tienes disponibles o agotados en tus plataformas de delivery (Glovo, Uber Eats, Just Eat). Todos los cambios se guardan automáticamente cuando los hagas, así que no tienes que preocuparte por perder datos. Si un producto agotarse hoy pero recupera stock, lo puedes reactivar en cualquier momento. ### Cómo usarlo - **Selecciona tu tienda.** En el desplegable "Tienda" elige la que quieres gestionar. El sistema busca automáticamente todas tus cartas digitales conectadas. - **Elige la carta digital.** Si tienes varias cartas (ej. "Desayunos", "Platos principales"), aparecerá otro desplegable para que selecciones cuál editar. Si solo hay una, se carga directamente. - **Busca y filtra productos.** Usa la barra "Buscar producto..." para encontrar rápidamente lo que buscas. Los botones arriba te dejan ver todos, solo los disponibles o solo los agotados. - **Marca productos como agotados o disponibles.** Haz clic en la tarjeta del producto. El badge "Disponibilidad" cambia a "Agotado" (en rojo) o "Disponible" (en verde). Se guarda automáticamente en el servidor. - **(Opcional) Marca desactivación permanente.** Si un producto está agotado, puedes tocar el botón "Permanente" para indicar que no volverá a estar disponible. Estos cambios persisten hasta que subas una carta nueva. - **Ordena por nombre.** Toca el botón "A-Z" / "Z-A" para cambiar el orden alfabético de los productos listados. ### Consejos - **Guarda siempre tus cambios.** El icono giratorio en la esquina superior derecha te muestra cuándo se está sincronizando. Espera a que desaparezca para estar seguro. - **Diferencia temporal vs. permanente.** "Agotado temporal" es para hoy o esta semana (volverá solo); "Agotado permanente" solo desaparece si subes una nueva carta digital. - **Sincroniza antes de la hora punta.** Actualiza la disponibilidad 10–15 minutos antes de abrir, así los clientes ven los datos correctos desde el inicio. - **Revisa multiples plataformas.** Aunque edites desde aquí, los cambios se replican a Glovo, Uber Eats y Just Eat automáticamente. Verifica en cada app que se hayan aplicado. --- # Cartas Digitales Portal: Delivery Hub · Panel URL: https://connectmanager.es/docs/manual-cartas-digitales Actualizado: 2026-06-17 ## Cartas Digitales Las Cartas Digitales es el apartado donde sincronizas y envías los menús de tu restaurante a las plataformas de delivery (Uber Eats, Glovo y Just Eat). Desde aquí puedes ver el estado de cada envío, enviar catálogos de forma inmediata o programarlos para una fecha y hora concreta, y consultar el historial de envíos para cada local. ### Cómo usarlo - **Ver tus locales y catálogos:** La tabla principal muestra cada local con su catálogo de Ágora. Cada fila te indica el estado actual en cada plataforma: Sincronizado (éxito), En proceso (enviando), Fallido (error) o No iniciado. También ves cuántos envíos se han hecho hoy en cada canal. - **Enviar catálogos:** Para cada local tienes dos opciones: - Botón **Enviar Catálogo (todos)** (el de papelera con avión): envía el menú completo a todos los canales configurados. - Botones individuales de cada plataforma (Uber Eats, Glovo, Just Eat): envía solo a esa plataforma si está configurada. Los envíos se encolan y se procesan de 10 canales en 10, uno tras otro, sin saturar el integrador. - **Programar envíos:** Haz clic en el botón de tres puntos (⋮) **Acciones** y selecciona **Programar envío**. Elige la fecha y hora (en pasos de 5 minutos, hora peninsular) y el catálogo se enviará automáticamente a esa hora. - **Actualizar estado:** Si un envío terminó en la plataforma pero aún ves "En proceso", usa el botón **Actualizar estado** en el menú de acciones para refrescar la información desde Ágora. - **Publicar en SmartMenu:** Desde el menú de acciones (⋮), puedes **Publicar en SmartMenu** configurando las credenciales de administrador de Ágora. El sistema publicará los catálogos en SmartMenu automáticamente. - **Filtrar y buscar:** Usa los filtros encima de la tabla para buscar por local, catálogo o estado. También puedes escribir el nombre del local en el buscador de la esquina superior derecha. - **Acciones en lotes:** Selecciona varios locales con las casillas y usa los botones de acción múltiple: **Enviar Catálogos Seleccionados** o **Programar envío** para procesarlos todos de una vez. - **Historial de envíos:** Haz clic en el botón de reloj (⏱) en la esquina superior derecha o en el botón **Historial de envíos** del menú de acciones para ver todos los envíos pasados de cada local, con detalles de fecha, hora y duración. ### Consejos - **Envíos secuenciales:** Si envías varios catálogos a la vez, se procesan en tandas de 10. La página te muestra una estimación del tiempo (p.ej., «~5 min estimados»). No cierres la página mientras está en curso. - **Estados en tiempo real:** La tabla se actualiza cada 30 segundos mientras está abierta. Si ves "En proceso" en un canal, espera a que termine; la sincronización se detiene en cuanto no queda nada pendiente. - **Envíos programados:** Los catálogos programados se envían automáticamente a la hora indicada. Puedes programar varios para diferentes fechas y horas sin problema. - **Errores:** Si un envío falla, verás un badge rojo con "Fallido" y un error (en letra pequeña). Pasa el ratón sobre el error para ver el mensaje completo, o haz clic para copiarlo. Usa **Actualizar estado** para reintentar después de resolver el problema. --- # Check In Portal: Delivery Hub · Panel URL: https://connectmanager.es/docs/manual-check-in Actualizado: 2026-06-17 ## Check In El Check In te muestra el registro de todos los riders que han ingresado código de acceso en tu local para recoger pedidos de delivery. Aquí ves quién llegó, cuándo se presentó, cuánto tiempo esperó, y si el código que introdujo coincidió con un pedido en el sistema. Es útil para auditar la actividad en tu local y detectar problemas si un rider no encuentra su pedido. ### Cómo usarlo - **Filtra los datos que ves:** - Selecciona un **local específico** (o todos) con el dropdown buscable. - Elige **rango de fechas** (desde–hasta) para acotar la búsqueda. - Filtra por **Estado**: "Pedido encontrado" (el código coincidió) o "No encontrado" (no hay match). - Presiona **Aplicar** para cargar los resultados. - **Revisa la tabla de check-ins:** Cada fila muestra hora del pedido, hora de llegada del rider, minutos de espera, local, código que ingresó, número de pedido interno, código de recogida, canal (Uber Eats, Glovo, Just Eat), estado en Ágora y si fue encontrado. - **Navega entre páginas:** Elige cuántos registros por página (25, 50, 100) y usa los botones de navegación. - **Exporta a Excel:** Presiona el botón verde **Excel** para descargar todos los check-ins filtrados en CSV (compatible con Excel). - **Genera enlace público:** Presiona **Enlace público**, selecciona un local y obtén su QR y URL para compartir con los riders (así acceden sin códigos). - **Elimina registros:** Si tienes permiso, haz clic en el icono de papelera en cada fila, confirma y se borra el check-in. ### Consejos - La tabla se actualiza automáticamente cada 15 segundos, así que verás los nuevos check-ins sin refrescar. - Si el tiempo de espera está **rojo** (más de 45 minutos), significa que el rider esperó mucho; **naranja** (30–45 min) es aceptable; **verde** (menos de 30 min) es óptimo. - Los check-ins sin pedido encontrado ("Sin pedido") pueden indicar un error en el código o un pedido que aún no está registrado en el sistema. - El enlace público del local es permanente: compártelo en el grupo de WhatsApp de riders, en instrucciones o en tu web para que comiencen el check-in sin necesidad de código manual. --- # Integraciones (API) Portal: Delivery Hub · Panel URL: https://connectmanager.es/docs/manual-integraciones Actualizado: 2026-06-17 ## Integraciones (API) Desde aquí puedes generar claves de API para que servicios externos (herramientas de BI, sistemas de reportes, integraciones propias) descarguen el histórico de pedidos de tu grupo de locales. Cada clave proporciona acceso solo de lectura a los pedidos del grupo que selecciones, sin poder modificar ni eliminar información. ### Cómo usarlo - **Crear una nueva clave:** haz clic en «Crear» y rellena: - Grupo de locales: selecciona a qué grupo de locales tendrá acceso la clave. - Nombre / descripción: escribe un nombre descriptivo para identificar para qué sirve (ej.: «Integración BI de pedidos», «Dashboard externo»). - Activa: marca esta casilla para que la clave funcione de inmediato (por defecto está activada). - **Copiar la clave:** al guardar se mostrará la clave en claro. **Cópiala al instante y guárdala en un lugar seguro** (gestor de contraseñas, variable de entorno, etc.). Después solo será visible durante 15 minutos en el modal «Ver credenciales»; pasado ese tiempo solo podrás regenerarla. - **Ver credenciales y ejemplos:** haz clic en «Ver credenciales» en la fila de la clave. Verás: - La URL del endpoint de la API (para descargar pedidos). - La clave (si aún está dentro de los 15 minutos tras crearla o regenerarla). - Un ejemplo cURL listo para copiar y pegar en tu terminal. - Un tab de «Uso de la API» con guía de filtros, paginación, ejemplos y buenas prácticas. - **Activar/desactivar:** usa el botón «Editar» para cambiar el nombre o desactivar una clave sin borrarla (útil si la quieres pausar temporalmente). - **Regenerar una clave:** si crees que se ha filtrado o simplemente quieres cambiarla, haz clic en «Regenerar». La clave anterior dejará de funcionar al instante, así que avisa al servicio externo para que la actualice. - **Eliminar:** usa el botón «Eliminar» para borrar una clave definitivamente. ### Consejos - **Seguridad:** trata la clave como una contraseña. Guárdala en un secreto (GitHub Secrets, variable de entorno, etc.), nunca en código fuente visible. Si se filtra, usa «Regenerar» para invalidarla al instante. - **Límite de uso:** cada clave permite aproximadamente 240 peticiones por minuto. Para descargar históricos grandes, recorre las páginas de forma secuencial y no simultánea. - **Documentación detallada:** si necesitas información completa sobre los filtros de búsqueda, paginación, estructura JSON de respuestas y casos de uso avanzados, consulta la [guía técnica de la API de pedidos](https://connectmanager.es/docs/api-de-pedidos?portal=general). - **Múltiples integraciones:** puedes crear tantas claves como necesites. Usa nombres descriptivos para saber cuál es cuál, y una clave por servicio externo (en lugar de compartir la misma clave entre varios). --- # Ranking de Ventas Portal: Delivery Hub · Informes URL: https://connectmanager.es/docs/manual-ranking-de-ventas Actualizado: 2026-06-17 ## Ranking de Ventas El Ranking de Ventas te muestra cuál de tus locales está generando más ingresos en cada periodo. Desde aquí puedes comparar el desempeño de todos tus establecimientos, ver cuántos pedidos ha tenido cada uno y analizar el importe medio de cada compra. Es ideal para identificar qué locales van mejor y cuáles necesitan más atención. ### Cómo usarlo - **Selecciona el período:** Elige entre «Hoy», «Ayer», «Últimos 7 días», «Últimos 30 días», «Este mes», «Este año» o «Todo el tiempo». Por defecto se muestran los últimos 30 días. - **Filtra por canal:** Puedes ver todas las ventas juntas o solo las de un canal específico (Uber Eats, Glovo, Just Eat, Delivery Propio u Otros). - **Elige cómo ordenar:** Visualiza el ranking por Ventas (€), Número de Pedidos o Ticket Medio. Esto ordena automáticamente tus locales de mayor a menor. - **Lee la tabla resultante:** Verás cada local con su posición, ingresos totales, número de pedidos, importe medio por pedido y su porcentaje del total. - **Consulta los totales:** Al final aparecen los números agregados de todos tus locales para el período seleccionado. ### Consejos - **Compara canales:** Filtra por un solo canal (ej. Uber) para ver qué local tiene mejor rendimiento en esa plataforma. - **Analiza el ticket medio:** Un local con muchos pedidos pero ticket bajo puede indicar que necesitas revisar tus precios o promociones. - **Usa períodos cortos para decisiones rápidas:** Si necesitas actuar hoy, revisa «Hoy» o «Últimos 7 días»; para análisis estratégicos usa «Este mes» o «Este año». - **El porcentaje te dice el peso:** Si un local representa el 40% de tus ventas totales, es uno de tus motores principales. --- # Tramos por Operadora Portal: Delivery Hub · Informes URL: https://connectmanager.es/docs/manual-tramos-por-operadora Actualizado: 2026-06-17 ## Tramos por Operadora Este informe te muestra de un vistazo cómo se distribuyen tus pedidos y ventas entre las operadoras de delivery (Uber Eats, Glovo, Just Eat, Delivery Propio) a lo largo del día. Usa colores intensos para identificar rápidamente los horarios y operadoras más fuertes. Es perfecto para entender cuándo y por dónde llegan más clientes, y optimizar tu staffing en cocina. ### Cómo usarlo - **Elige la tienda:** Por defecto aparecen todas tus tiendas. Si tienes varias sucursales, selecciona una en concreto en el filtro `Tienda`. - **Configura los tramos horarios:** En `Configuración de Tramos` puedes ver los datos agrupados por: - Hora por Hora: cada columna es una hora (desde las 06:00 hasta las 24:00). - Bloques de 2 Horas: agrupa las horas de dos en dos (útil para tendencias generales). - Mañana / Tarde / Noche: resumido en 4 franjas (06:00-12:00, 12:00-16:00, 16:00-20:00, 20:00-06:00). - **Elige la métrica:** Visualiza Pedidos (Volumen) para contar transacciones, o Importe (€) para ver el dinero total por operadora y horario. - **Selecciona el periodo:** Compara Hoy, Ayer, Últimos 7 o 30 días, Este Mes, Este Año, o todo el Histórico. También puedes usar Personalizado... para escoger un rango exacto de fechas. - **Lee la tabla:** Las filas muestran cada operadora (Glovo, Uber Eats, Just Eat, Delivery Propio). Los colores más intensos indican mayor volumen o dinero en ese tramo. Al final de cada fila y columna verás los totales. ### Consejos - **Detecta picos:** Si ves una columna con colores muy oscuros, ese horario es especialmente fuerte. Prepara más ingredientes o personal para no quedar sin stock. - **Compara operadoras:** ¿Glovo domina tu mediodía pero Uber Eats es fuerte por la noche? Ajusta promociones o presencia según la operadora. - **Analiza tendencias semanales:** Usa el filtro Últimos 7 días para ver si hay patrones de lunes a domingo; los sábados y domingos pueden comportarse muy diferente. - **Valida cambios:** Si hace poco cambiaste menú o horas de atención, compara periodos antes y después para medir el impacto. --- # Mapa de calor Portal: Delivery Hub · Informes URL: https://connectmanager.es/docs/manual-mapa-de-calor Actualizado: 2026-06-17 ## Mapa de Calor El Mapa de Calor te muestra en un vistazo cuándo recibas más pedidos o facturas más ingresos. Usa colores verdes (intensidad baja a alta) para visualizar patrones por hora del día y día de la semana. Así identificas rápidamente tus franjas horarias estrella y planificas mejor el personal y stock. ### Cómo usarlo - **Selecciona la tienda:** en el desplegable Tienda elige una tienda específica o Todas las tiendas para ver el consolidado. - **Filtra por canal:** con Canal ve datos de Uber Eats, Glovo, Just Eat, Delivery Propio o de Todos los canales combinados. - **Elige la métrica:** selecciona Pedidos (Volumen) para contar pedidos o Importe (€) para ver ingresos totales. - **Define el período:** pulsa Periodo y elige Hoy, Ayer, Últimos 7 días, Últimos 30 días, Este Mes, Este Año o Histórico Completo. Si quieres un rango específico, marca Personalizado e indica las fechas. - **Lee el gráfico:** cada celda representa una hora de un día. El color verde más intenso = más actividad. Pasa el cursor sobre cualquier celda para ver el valor exacto. ### Consejos - Usa el Mapa de Calor para identificar picos de demanda y ajusta turnos de personal o preparación de ingredientes a esas horas. - Si ves diferencias entre canales (p. ej., Uber tiene picos diferentes a Glovo), adáptate a cada una por separado. - Compara períodos: ayer vs. hoy, o este mes vs. el anterior, para detectar tendencias y variaciones importantes. - Los datos comienzan a las 6:00 de la mañana; cualquier orden anterior se ignora. --- # Evolución de Pedidos Portal: Delivery Hub · Informes URL: https://connectmanager.es/docs/manual-evolucion-de-pedidos Actualizado: 2026-06-17 ## Evolución de Pedidos Este apartado te permite ver cómo ha evolucionado el volumen, importe y ticket medio de tus pedidos a lo largo del tiempo. Es muy útil para identificar tendencias, detectar momentos de alta o baja actividad, y entender el comportamiento de tus canales de reparto (Uber Eats, Glovo, Just Eat y entregas propias). ### Cómo usarlo - **Selecciona la tienda:** En el filtro "Tienda", elige la que quieres analizar o "Todas las tiendas" para verlas juntas. Puedes escribir el nombre para buscar. - **Filtra por canal:** En "Canales", selecciona si quieres ver todos o solo los de Uber Eats, Glovo, Just Eat o tu delivery propio. - **Elige la métrica:** Decide qué visualizar: - **Ticket Medio (€):** importe promedio por pedido - **Importe (€):** ingresos totales - **Volumen (Pedidos):** número total de pedidos - **Define el periodo:** En "Periodo", elige un rango predefinido (hoy, últimos 7 días, últimos 30 días, este mes, etc.) o selecciona "Personalizado..." para especificar fechas exactas. - **Visualiza el gráfico:** El gráfico de líneas se actualiza automáticamente con los datos filtrados. Cada canal aparece con un color diferente (Uber = negro, Glovo = amarillo, Just Eat = naranja, Propio = azul). ### Consejos - Usa "Últimos 30 días" como punto de partida para detectar tendencias generales sin datos demasiado antiguos. - Compara canales diferentes eligiendo la misma métrica: verás rápidamente cuál aporta más volumen o ingresos. - Los periodos cortos (hasta 2 días) muestran datos por hora, lo que te ayuda a identificar picos horarios exactos. - Si notas una caída repentina en tus ingresos, revisa si afecta a todos los canales o solo a uno para investigar la causa. --- # Hotel Hub: cómo funcionan los cargos a habitación desde Ágora Portal: Hotel Hub · Primeros pasos URL: https://connectmanager.es/docs/hotel-hub-como-funciona Actualizado: 2026-10-03 **Hotel Hub** es la parte de Connect Manager que conecta el TPV **Ágora** con el PMS del hotel para cargar los consumos del restaurante, el bar o el room service a la habitación del huésped. Este manual explica lo que tienen en común todas las integraciones de PMS (la acción personalizada que abre la pantalla de cargo, el albarán, las anulaciones, el envío de las ventas de clientes no alojados, los mapeos, la pausa y los avisos) y compara qué hace cada PMS. Es el punto de partida para el técnico antes de abrir el manual de su PMS. ## Qué hace Hotel Hub - Pone en el TPV un botón (una **acción personalizada** de Ágora) que abre, sobre el ticket abierto, la pantalla de cargo a habitación de Connect Manager. - Busca en el PMS la habitación o el huésped y muestra los datos de la reserva antes de cargar. - Aplica las comprobaciones que ofrece cada PMS: reservas alojadas, bloqueos, reservas que no admiten cargos, crédito o fechas. - Recoge la **firma** del huésped en los PMS que lo permiten. - Convierte el ticket en un **albarán** de Ágora a nombre de un cliente genérico, con el nombre del huésped y su habitación. - Envía el **cargo** al PMS con el detalle que acepta cada uno: un total, líneas por producto, por familia o por servicio. - **Anula el cargo** en el PMS cuando se cancela el albarán en Ágora, en los PMS que lo admiten. - Envía al PMS las **ventas de clientes no alojados**, factura a factura en tiempo real o en un cierre diario, según el PMS. - Traduce familias, centros de venta, formas de pago y turnos de comida de Ágora a los códigos del PMS. - Guarda cada cargo, factura y cierre enviados, con lo que se mandó y lo que contestó el PMS, para revisarlos desde el panel. ### Qué no hace - No sincroniza reservas ni disponibilidad, no hace check-in ni check-out y no crea huéspedes en el PMS ni clientes en Ágora: en ningún PMS. - La pausa del envío de cargos solo bloquea la pantalla de cargo: las facturas y cancelaciones que Ágora manda a la URL de documentos se siguen procesando. - Hoy la opción **Nº de días para cerrar albaranes** no cierra nada y el cierre diario de ventas (Z-cierre) no se envía solo: las tareas programadas que los hacen están desactivadas en el planificador de la versión actual del motor (ver más abajo). - Algunas integraciones dan el cargo por bueno sin leer la respuesta del PMS: Winhotel y Ofi-Hotel solo miran que no haya un error de comunicación y Noovy ni siquiera avisa en el TPV si el PMS lo rechaza. ## Las piezas - **Connect Manager** (`app.connectmanager.es`): guarda la ficha del local con la URL y la API key de Ágora, la integración de hoteles con las credenciales del PMS y sus opciones, sirve la pantalla de cargo y recibe los documentos de Ágora. - **Ágora**: la acción personalizada abre la pantalla de cargo con los datos del ticket; la integración de documentos con sistemas externos avisa a Connect Manager de cada albarán y cada factura; la API del integrador permite leer el ticket y crear el albarán. - **El PMS**: responde a las búsquedas y recibe los cargos, las anulaciones y las ventas. Hay, por tanto, dos caminos: el de la pantalla de cargo, que el camarero abre a mano, y el de la URL de documentos, que Ágora usa sola cada vez que crea o cancela un albarán o emite una factura. ```mermaid flowchart LR TPV[TPV Ágora] -- Acción personalizada --> P[Pantalla de cargo] P -- Búsqueda y cargo --> PMS[PMS del hotel] P -- Crea el albarán --> TPV TPV -- Albaranes y facturas --> D[URL de documentos] D -- Anulaciones y ventas --> PMS ``` ## Cómo funciona un cargo a habitación El camarero abre el ticket del huésped y pulsa la acción personalizada. La pantalla de Connect Manager se abre dentro del TPV con el ticket, el TPV y el usuario. El camarero busca la habitación o el huésped, revisa los datos de la reserva, recoge la firma si se pide y pulsa **Cargar**. Connect Manager crea el albarán en Ágora y envía el cargo al PMS. Si todo va bien, la pantalla muestra el resultado y se cierra sola a los dos segundos. ```mermaid sequenceDiagram participant C as Camarero participant TPV as TPV Ágora participant CM as Connect Manager participant PMS as PMS C->>TPV: Pulsa la acción personalizada en el ticket TPV->>CM: Abre la pantalla con el ticket, el TPV y el usuario C->>CM: Busca la habitación o el huésped CM->>PMS: Consulta la reserva PMS-->>CM: Huésped, fechas y datos de la reserva CM-->>C: Reserva o motivo por el que no admite cargos C->>CM: Firma si se pide y pulsa Cargar CM->>TPV: Crea el albarán a nombre del cliente genérico CM->>PMS: Envía el cargo PMS-->>CM: Cargo aceptado o rechazado CM-->>C: Mensaje y cierre de la ventana ``` Hay dos excepciones. En **Protel** sin albaranes, el botón solo elige la reserva y el cargo viaja dentro de la factura al cobrar con una forma de pago de cargo a habitación. **ACI Hotel** no habla con el PMS: busca la habitación entre los clientes de Ágora y deja el albarán con la firma en Ágora. ### La acción personalizada La URL que da Connect Manager lleva unos marcadores entre llaves (`{user_id}`, `{pos_id}`, `{ticket_id}`, `{ticket_global_id}`, `{ticket_line_index}` e `{introduced_value}`) que Ágora sustituye por los datos del ticket al pulsar el botón. Hay que pegarla tal cual. En TPV que no son móviles, la pantalla muestra un teclado en pantalla al tocar los buscadores. ### Buscar la habitación o el huésped Todos los PMS buscan por número de habitación. Algunos añaden búsqueda por nombre o apellido, por tarjeta, por grupo o por folio; la tabla comparativa lo resume. Cuando la búsqueda devuelve varias reservas, unos PMS muestran una lista para elegir (Cloudbeds, Noovy, Hospedium, Redforts…) y otros toman la primera. ### Comprobaciones antes de cargar No hay una comprobación común: cada integración usa lo que devuelve su PMS. Por ejemplo, Ulyses tiene las opciones **Comprobar fechas de reserva** y **Comprobar si hay crédito disponible**; Protel no deja cargar a reservas bloqueadas salvo con **Permitir cargos bloqueados**; Shiji y Lean avisan con «La reserva no admite cargos» cuando el PMS lo indica; Cloudbeds y Redforts solo encuentran reservas con check-in hecho; Sihot solo carga en habitaciones ocupadas. Otros, como Mews o Noovy, no comprueban crédito ni bloqueos. ### La firma En los PMS con firma (Mews, Sihot y Guest Pro con **Solicitar firma**; ACI Hotel siempre), la pantalla muestra un recuadro para firmar con el dedo y un botón **Borrar**. La firma se guarda como imagen junto al cargo. En Mews, Sihot y ACI Hotel, cuando Ágora envía el albarán a la URL de documentos, Connect Manager le devuelve la firma para imprimirla en el propio albarán. ### El albarán en Ágora El albarán se crea desde el ticket abierto, a nombre del **Cliente** que se elige en la integración (un cliente genérico de Ágora), pero con el nombre del huésped y su habitación, por ejemplo «Ana López (Nº hab.: 101)», y se imprime. La opción **Dejar abierto el albarán** decide si queda pendiente, que es lo que permite cancelarlo después desde Ágora para anular el cargo. Mews, Lean y ACI Hotel lo dejan siempre abierto. En la mayoría de los PMS el albarán se crea **antes** de enviar el cargo. Si el PMS rechaza el cargo, el albarán ya existe en Ágora y hay que devolverlo (varias pantallas lo piden en el propio mensaje). Antes de hacerlo, revisa el manual del PMS: en algunos la anulación se envía al PMS aunque el cargo no hubiera entrado. ### Usar el API externa de Ágora En Guest Pro, Lean, Protel, Mews y ACI Hotel existe la casilla **Usar el API externa de Ágora**. Activada, Connect Manager lee el ticket y crea el albarán llamando a la API de Ágora desde internet, así que esa API tiene que ser accesible desde fuera (puerto abierto o Zero Connect). Desactivada, es la propia pantalla la que pide al TPV que lo haga, sin salir de la red del local. En los demás PMS no hay casilla: cada integración lo hace siempre de la misma forma, casi siempre a través del TPV. En todos los casos la API de Ágora tiene que estar accesible para las listas del panel (clientes, formas de pago, familias, centros de venta) y para las tareas programadas. ## Anular un cargo El cargo se anula cancelando el albarán en Ágora. Ágora envía el documento de cancelación a la **URL para enviar facturas desde Ágora**; Connect Manager busca el cargo original por serie y número de albarán y manda al PMS la anulación (el mismo cargo en negativo o la anulación de la línea, según el PMS). Si el PMS la rechaza, Connect Manager rechaza la cancelación y Ágora no la completa. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant PMS as PMS TPV->>CM: Albarán de cancelación a la URL de documentos CM->>CM: Busca el cargo original por serie y número CM->>PMS: Envía la anulación PMS-->>CM: Respuesta CM-->>TPV: Acepta o rechaza la cancelación ``` Para que funcione hacen falta tres cosas: que el PMS admita anulaciones (ver la tabla), que el albarán se haya dejado abierto y que la integración de documentos de Ágora envíe los albaranes a esa URL. ## Cierre de albaranes a los N días Los albaranes abiertos se quedan pendientes a nombre del cliente genérico. El campo **Nº de días para cerrar albaranes** fija cuántos días pueden seguir así: pasado ese plazo, una tarea nocturna de Connect Manager marca esos albaranes como cancelados en Ágora, sin tocar el PMS. En la práctica, el plazo es hasta cuándo se puede anular un cargo desde el TPV. Con el campo vacío o a cero, no se cierran. > [!WARNING] En la versión actual del motor, la tarea que cierra los albaranes y la que lanza el Z-cierre están desactivadas en el planificador. Confirma con FOS que están en marcha antes de contar con ellas. ## Ventas de clientes no alojados Además de los cargos, varios PMS reciben las ventas que no se cargan a habitación. Hay dos formas: - **En tiempo real**: Ágora envía cada factura a la URL de documentos y Connect Manager la reenvía al PMS con sus líneas y sus cobros (Protel, Shiji, Lean y Ulyses). Si el PMS la rechaza, o una forma de pago no está asignada, Connect Manager rechaza la factura y Ágora no deja cerrarla. En los PMS que no reciben facturas, la URL las acepta sin hacer nada; Cloudbeds es la excepción: contesta con error, así que no hay que enviarle facturas. - **Cierre diario (Z-cierre)**: en el bloque **Conf. de Z-cierre** se activa **Z-cierre** y se elige la **Hora de generación fich. contable**. Una tarea que se ejecuta cada 10 minutos por la noche busca las integraciones cuya hora coincide, lee de Ágora las facturas del día de negocio (el mismo día si se ejecuta a partir de las 22:00 y el anterior si es de madrugada) y las envía al PMS. Elige, por tanto, una hora nocturna. En Protel la casilla se llama **Enviar facturas diferidas** y sustituye al envío en tiempo real. Los cierres generados se ven en **Operaciones hoteleras → Cierres de caja** (Creado, Enviado, Error o No hay datos) y las facturas enviadas una a una en **Operaciones hoteleras → Facturas**. El botón **Exportar** de Cierres de caja reenvía un día ya generado, y solo funciona para Sihot, Guest Pro, Prestige y Ubikos. > [!NOTE] Como la tarea del Z-cierre está desactivada en la versión actual del motor, hoy no se generan días nuevos de forma automática. Si el hotel necesita el cierre diario, habla antes con FOS. ## Familias, centros de venta, métodos de pago y turnos de comida Después de guardar la integración se habilitan unas pestañas para traducir los datos de Ágora a los del PMS. Qué pestañas salen depende del PMS: | Pestaña | Para qué sirve | PMS que la usan | | Familias | Producto, servicio, extra o categoría contable del PMS para cada familia de Ágora | Guest Pro, Lean, Mews, Millenium, Prestige, Sihot, Ubikos, Ulyses; en Noovy se llama Productos | | Centros de venta | Servicio, outlet o folio del PMS para cada centro de venta de Ágora | Mews, Millenium, Ulyses y Sihot (si agrupa por centro de venta); Cloudbeds la muestra pero no la usa | | Métodos de pago | Forma de pago del PMS para cada forma de pago de Ágora, para las facturas y el Z-cierre | Cloudbeds, Guest Pro, Lean, Mews, Shiji, Sihot, Ubikos, Ulyses | | Turnos | Turno de comida del PMS según la hora del albarán | Shiji | | Locales y TPVs | Correspondencias de Sihot según la opción «Agrupar cargos por...» | Sihot | Algunos PMS no tienen pestañas porque reciben los identificadores de Ágora tal cual (Protel, y Shiji para el centro de ingresos y los códigos de ingreso): ahí la correspondencia la hace el propio PMS. ## Pausar el envío de cargos Los administradores de FOS ven en **Conf. general** dos campos: **Pausar el envío de cargos al PMS** (casilla) y **Pausar el envío de cargos al PMS después de** (fecha). Cada madrugada, una tarea marca como pausadas las integraciones cuya fecha ya ha pasado. Con la integración pausada, la pantalla de cargo muestra «Integración pausada» y no deja cargar, y el resto de usuarios ve en la integración el aviso «El envío de cargos al PMS está actualmente suspendido. Por favor, contacte con el soporte para reactivarlos.» ## Avisos por correo El campo **Email de receptor de notificaciones** admite varias direcciones. Ahí llegan, con el asunto «Error en aplicación», los fallos de las tareas en segundo plano: Z-cierre, cierre de albaranes, envíos diferidos e importaciones de datos de Mews. En Cloudbeds llega además el aviso «Aplicación de Cloudbeds desconectada» si el hotel desconecta la aplicación. Los errores al cargar desde el TPV no se envían por correo: se ven en la propia pantalla y en **Operaciones hoteleras → Cargos**. ## Comparativa de PMS Resumen de lo que hace cada integración según el código del motor. El detalle y las condiciones están en el manual de cada PMS. | PMS | Búsqueda | Firma | Anulación en el PMS | Ventas de no alojados | Propina | | Mews | Habitación | Sí, opcional | Sí | Cierre diario (Z-cierre) | Sí | | Cloudbeds | Habitación, nombre o apellido | No | Sí | No operativo | Solo si el ticket la trae en sus cobros | | Protel | Habitación, y tarjeta o apellidos | No | Sí, en el modo con albaranes | Sí, cada factura en tiempo real | Solo en las facturas | | Shiji | Habitación | No | Sí | Sí, cada factura en tiempo real | No | | Lean | Habitación y, si se activa, grupo | No | Sí, si el huésped sigue alojado | Sí, facturas simplificadas en tiempo real | Sí | | Noovy | Habitación o nombre | No | Sí, si Ágora envía las cancelaciones a la integración | No | No | | Ulyses | Habitación, o folio con otra URL de acción | No | Sí | Sí, al folio de facturación | No | | Millenium | Habitación | No | No | No | No | | Prestige | Habitación | No | No | Cierre diario (Z-cierre) | No | | Winhotel | Habitación | No | No | No | No | | Ofi-Hotel | Habitación | No | No | No | No | | ACI Hotel | Habitación, entre los clientes de Ágora | Sí | No aplica: el albarán se queda en Ágora | No | No | | Guest Pro | Habitación | Sí, opcional | No | Cierre diario (Z-cierre) | No | | Hospedium | Habitación | No | No | No | Sí | | Ubikos | Habitación, o nombre con todas las habitaciones a la vista | No | Sí | Cierre diario (Z-cierre) | No | | Redforts | Habitación o nombre | No | No | No | Sí | | Sihot | Habitación | Sí, opcional | Sí | Cierre diario (Z-cierre) | No | «Cierre diario (Z-cierre)» depende de la tarea programada que hoy está desactivada (ver el aviso de la sección anterior). En Winhotel, Ofi-Hotel y Noovy, comprueba en el PMS los primeros cargos: las dos primeras no leen lo que contesta el PMS y Noovy no avisa en el TPV de los rechazos. Ningún PMS sincroniza reservas ni disponibilidad. ## Requisitos y reparto de tareas - **Ágora**: licencia del Módulo de Servicios de Integración (activa la API del integrador y la integración de documentos), un cliente genérico para los albaranes y los perfiles de usuario con el permiso de la acción personalizada. - **API de Ágora accesible** desde Connect Manager con la URL y la API key del local (puerto abierto o Zero Connect). - **PMS**: credenciales de su API para el hotel y, según el PMS, los códigos de productos, servicios, formas de pago o turnos. - **FOS** da de alta el local y la integración de hoteles: el botón **Añadir** de Integraciones de hoteles solo lo ven sus administradores, igual que la pausa. - **El distribuidor** revisa la ficha del local, completa las opciones y los mapeos y configura Ágora. - **El hotel** (o su PMS) facilita las credenciales y decide cómo quiere ver los cargos en el PMS. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de API y API key de Ágora del local | Distribuidor | http://servidor:8984 | Sí | | Credenciales del PMS | El hotel o el PMS | Según el PMS: token, API key o usuario y contraseña | Sí | | Identificador del hotel en el PMS | El PMS | 12345 | Según el PMS | | Cliente genérico de Ágora | Distribuidor, en Ágora | «CLIENTES HOTEL» | Sí, salvo ACI Hotel y Protel sin albaranes | | Códigos del PMS para familias, centros de venta, formas de pago o turnos | El hotel o el PMS | Bebidas → «Beverage» | Según el PMS | | Usuarios de Ágora que podrán cargar a habitación | El cliente | Perfil «Camareros» | Sí | | Email para los avisos | Cliente o distribuidor | avisos@hotel-demo.es | Recomendado | ## Configuración común paso a paso ### En Connect Manager - En **Administración → Locales**, abre el local y revisa **Cliente**, **Nombre**, **URL de API**, **API key**, **Dirección**, **Ciudad** y **Zona horaria**. Pulsa **Guardar**. La zona horaria se usa para las fechas de los albaranes y los cargos. - Entra en **Integraciones de hoteles**. FOS pulsa **Añadir** y elige el **Proveedor**. - En **Conf. general**, rellena las credenciales que pida el PMS y el **Email de receptor de notificaciones**, y pulsa **Guardar**. - En **Conf. de cargos**, elige el **Cliente**, decide **Dejar abierto el albarán** y el **Nº de días para cerrar albaranes** si el PMS los muestra, y las opciones propias del PMS. - Si el PMS tiene **Conf. de Z-cierre**, decide si se usa (ver el aviso). - Completa las pestañas de mapeo, que se habilitan después de guardar. - Copia del bloque **Enlaces** la **URL botón acción personalizada** y, si aparece, la **URL para enviar facturas desde Ágora**. ### En Ágora - En **Herramientas → Acciones personalizadas**, crea la acción con la URL tal cual y marca que se muestre en un diálogo. - La acción crea un permiso: añádelo a los perfiles de los usuarios que vayan a cargar a habitación. - 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 (anulaciones e impresión de la firma) y, si el PMS las recibe, de facturas. ## Comprobar que funciona - Las listas del panel (Cliente, formas de pago, familias) cargan datos: hay conexión con la API de Ágora. - En el TPV, con un usuario de prueba, la acción personalizada aparece y abre la pantalla de cargo. - La búsqueda de una habitación ocupada devuelve el huésped. - Al cargar, aparece el albarán en Ágora a nombre del huésped y el cargo en el PMS. - En **Operaciones hoteleras → Cargos**, el registro tiene el **Id. de pedido externo** relleno. - Si el PMS admite anulaciones, cancelar el albarán de prueba anula el cargo en el PMS. - Si el PMS recibe facturas, una factura de prueba se cierra en Ágora y aparece en **Operaciones hoteleras → Facturas** como «Aceptado». ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Los buscadores del panel (Cliente, Método de pago de Agora…) no devuelven nada | Connect Manager no llega a la API de Ágora. | Revisa URL de API y API key del local y que la API sea accesible desde fuera. | | «El parámetro ticket_global_id es obligatorio. Cierre esta ventana e intente generar el ticket de nuevo.» (o user, pos_id) | La URL de la acción personalizada no lleva los marcadores o se abrió fuera de un ticket. | Vuelve a copiar la URL del bloque Enlaces tal cual. | | «El parámetro room_id es obligatorio. Realice la búsqueda para poder realizar el cargo.» | Se pulsó Cargar sin buscar la reserva. | Busca primero la habitación o el huésped. | | «No se ha encontrado el ticket: … Cierre esta ventana e intente generar el ticket de nuevo.» | La pantalla no pudo leer el ticket a través del TPV. | Cierra la ventana y vuelve a abrir la acción desde el ticket. | | «No existe ningún ticket en Ágora con el identificador: …» | Con el API externa activada, la API de Ágora no devuelve el ticket o el ticket no tiene líneas. | Comprueba que el ticket tiene productos y que la API responde. | | «Ocurrió un error: AgoraApiHelper …» | Fallo al llamar a la API de Ágora desde Connect Manager. | Revisa la conectividad o desactiva Usar el API externa de Ágora donde exista. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Falló la creación del albarán o, en algunos PMS, el envío del cargo. | Comprueba en Ágora si el albarán existe antes de repetir. | | Ágora no deja cerrar una factura | El PMS la rechazó o una forma de pago no está asignada. | Lee el motivo y revisa la pestaña Métodos de pago. | | Ágora no deja cancelar un albarán: «Los datos recibidos no son correctos.» u otro motivo | El PMS rechazó la anulación. | Revisa el cargo en el PMS y en Operaciones hoteleras → Cargos. | | «Integración pausada» | FOS ha pausado el envío de cargos. | Contacta con soporte de FOS. | ## Preguntas frecuentes ### ¿Qué es Hotel Hub de Connect Manager? Es el conjunto de integraciones que conectan Ágora con el PMS del hotel para cargar consumos a la habitación, anularlos y, según el PMS, enviar las ventas del TPV. ### ¿Qué PMS se pueden conectar con Ágora? Los de la tabla comparativa: Mews, Cloudbeds, Protel, Shiji, Lean, Noovy, Ulyses, Millenium, Prestige, Winhotel, Ofi-Hotel, ACI Hotel, Guest Pro, Hospedium, Ubikos, Redforts y Sihot. El motor también tiene código para RoomRaccoon, Amenitiz y Oracle OHIP, que no entran en esta comparativa. ### ¿Cómo se carga un ticket a la habitación desde Ágora? Con el ticket abierto, se pulsa la acción personalizada, se busca la habitación, se firma si se pide y se pulsa Cargar. El ticket pasa a un albarán en Ágora y el cargo llega al PMS. ### ¿Se puede anular desde Ágora un cargo a habitación? Sí en los PMS que lo admiten: cancelando el albarán, si se dejó abierto y la integración de documentos de Ágora está configurada. ### ¿Las ventas de clientes no alojados llegan al PMS? En Protel, Shiji, Lean y Ulyses, factura a factura en tiempo real. En otros hay un cierre diario que hoy depende de una tarea desactivada. Algunos PMS no las reciben. ### ¿Hotel Hub sincroniza las reservas del hotel con Ágora? No. Las reservas solo se consultan en el PMS en el momento de cargar; no se copian a Ágora. ## Referencias - [Integración de Mews con Ágora](https://connectmanager.es/docs/integracion-mews-agora), [Cloudbeds](https://connectmanager.es/docs/integracion-cloudbeds-agora), [Protel](https://connectmanager.es/docs/integracion-protel-agora), [Shiji](https://connectmanager.es/docs/integracion-shiji-agora), [Lean](https://connectmanager.es/docs/integracion-lean-agora) y [Noovy](https://connectmanager.es/docs/integracion-noovy-agora) - [Integración de Sihot con Ágora](https://connectmanager.es/docs/integracion-sihot-agora) - [Direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) - [Glosario de Connect Manager](https://connectmanager.es/docs/glosario) --- # Integración de ACI Hotel con Ágora: albaranes con firma Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-aci-hotel-agora Actualizado: 2026-10-03 La integración de ACI Hotel con Ágora no se conecta con el PMS: todo pasa dentro de Ágora. El camarero busca la habitación entre los clientes de Ágora que tienen el número de habitación como nombre fiscal, el ticket se cierra como albarán a nombre de esa habitación y el huésped puede firmar en pantalla; la firma se guarda con el albarán y se imprime en él. Lo que el hotel haga después con esos albaranes queda fuera de Connect Manager. Este manual es para el técnico de FOS o del distribuidor que configura la integración en un local. La visión general de los PMS con Ágora está en [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona). ## Qué hace la integración - Añade a Ágora un botón (acción personalizada) que abre la ventana de cargo dentro del TPV. - Busca la habitación entre los clientes de Ágora con la consulta personalizada `Customers_Filtered_By_Tax_Name`: el cliente cuyo nombre fiscal es el número de habitación. Enseña número, nombre, teléfono y correo. - Recoge la firma del huésped en la pantalla (opcional) y la guarda con el cargo. - Cierra el ticket en Ágora como albarán abierto a nombre de ese cliente. - Devuelve la firma a Ágora para que se imprima en el albarán. - Ofrece una página para consultar los albaranes y sus firmas por habitación y fechas. ### Qué no hace - No envía nada a ACI Hotel: ni cargos, ni facturas, ni anulaciones. El albarán se queda en Ágora. - No comprueba la estancia, las fechas ni el crédito del huésped. - No crea ni actualiza los clientes-habitación de Ágora: tienen que existir antes. - No sincroniza reservas ni disponibilidad. ## Requisitos - **Ágora** con **Herramientas → Acciones personalizadas** y, para imprimir la firma, el módulo **Servicios de integración** y una plantilla de albarán ESC/POS (Ágora solo añade datos externos a la impresión en esas plantillas). - **Clientes-habitación en Ágora**: un cliente por habitación cuyo nombre fiscal sea el número, por ejemplo «101». Alguien tiene que mantenerlos: confírmalo con el hotel. - **La consulta personalizada `Customers_Filtered_By_Tax_Name`** instalada en Ágora: es la que hace la búsqueda. Confirma con FOS cómo se instala si el local no la tiene. - **Conectividad.** En el modo normal todo va por la API local del TPV y no hace falta abrir Ágora a Internet. Con «Usar el API externa de Ágora», Connect Manager llama a la API de Ágora desde sus servidores: tiene que ser accesible a las [IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) o por Zero Connect. - **Quién hace qué.** FOS da de alta el local y la integración. El distribuidor configura Ágora (acción, URL de documentos y plantilla). El hotel mantiene los clientes-habitación. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Clientes de Ágora con la habitación como nombre fiscal | Hotel, en Ágora | Nombre fiscal 101 | Sí | | Consulta personalizada Customers_Filtered_By_Tax_Name | Confírmalo con FOS | Instalada en Ágora | Sí | | URL de API y API key de Ágora del local | Distribuidor | http://servidor-demo:8984/ | Sí | | URL Api y Api Token (los de la API de Ágora) | Distribuidor | http://servidor-demo:8984/, acabada en barra | Solo con «Usar el API externa de Ágora» | | Plantilla de albarán ESC/POS | Distribuidor, en Ágora | — | Para imprimir la firma | ## Configuración paso a paso ### 1. En Ágora, antes de nada - Comprueba que existen los clientes-habitación (nombre fiscal = número de habitación) y quién los da de alta y de baja. - Comprueba que la consulta personalizada `Customers_Filtered_By_Tax_Name` está instalada. ### 2. En Connect Manager: el local (lo hace FOS) - En **Administración → Locales**, abre el local y rellena **Cliente**, **Nombre**, **URL de API**, **API key**, **Dirección**, **Ciudad** y **Zona horaria**. La API key es la que usa la ventana para hablar con Ágora. - **Guardar** → **Integraciones de hoteles** → **Añadir** → proveedor **Aci Hotel**. ### 3. En Connect Manager: Conf. general - **Pausar el envío de cargos al PMS después de** y **Pausar el envío de cargos al PMS**: solo los ve FOS. Con la integración pausada, el botón del TPV abre el aviso «Integración pausada». - **URL Api** y **Api Token**: pese al nombre, son la URL de la API de Ágora (acabada en `/`) y su token, no datos de ACI Hotel. Solo se usan con «Usar el API externa de Ágora». - **Email de receptor de notificaciones**: esta integración no envía avisos. ### 4. En Connect Manager: Conf. de cargos - **Usar el API externa de Ágora**: desmarcado, la ventana busca la habitación y crea el albarán a través de la API local del TPV. Marcado, lo hace Connect Manager desde sus servidores con la URL Api y el Api Token para la búsqueda y la URL de API del local para el ticket y el albarán. Recomendado: desmarcado, salvo que el TPV no pueda usar la API local. Al crear la integración viene marcado. El albarán siempre se crea abierto: esta opción no se puede cambiar para ACI Hotel. ### 5. En Ágora - Copia del bloque **Enlaces** la **URL botón acción personalizada**. Si empieza por `/venues/`, antepón `https://app.connectmanager.es`. - En **Herramientas → Acciones personalizadas** pulsa **Nuevo**: **Texto** «Cargo habitación», **Tipo** «Url/Aplicación», **Acción** la URL copiada (sin tocar los marcadores entre llaves) y marca **Mostrar Urls en un diálogo de Ágora**. Colócala en **Configuración de botones** y da su permiso a los perfiles que vayan a cargar. - Para imprimir la firma, en **Herramientas → Activar módulos adicionales → Servicios de integración** pega la **URL para enviar facturas desde Ágora** y activa **Habilitar integración de documentos** y **Enviar albaranes**. - Si el hotel quiere consultar firmas, crea otra acción con la **URL consulta de cargos habitación**, o ábrela en un navegador. ## Cómo funciona El botón abre la ventana con el ticket y la ventana lo lee por la API local de Ágora. El camarero escribe la habitación; la ventana ejecuta en Ágora la consulta personalizada y toma el primer cliente cuyo nombre fiscal coincide. El huésped firma, si se quiere, y al pulsar **Cargar** Connect Manager guarda la firma y registra el cargo. Después la ventana crea el albarán abierto a nombre de ese cliente. Al crearse, Ágora manda el albarán a la URL de facturas, Connect Manager lo acepta y le devuelve la firma para imprimirla, y la ventana se cierra. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager TPV->>TPV: Lee el ticket por la API local TPV->>CM: Guarda el ticket TPV->>TPV: Busca el cliente con la consulta personalizada TPV->>CM: Cargar con la firma CM->>CM: Guarda la firma y registra el cargo TPV->>TPV: Crea el albarán a nombre de la habitación TPV->>CM: Envía el albarán a la URL de facturas CM-->>TPV: Aceptado con la firma para imprimir TPV->>CM: Guarda el albarán ``` Con «Usar el API externa de Ágora» el recorrido es el mismo, pero la búsqueda, la lectura del ticket y la creación del albarán las hace Connect Manager contra la API de Ágora, y la ventana termina con «Se generó el siguiente cargo». **Qué se guarda:** el ticket, el albarán, la habitación y la imagen de la firma. Las facturas y las anulaciones que lleguen a la URL se aceptan sin hacer nada más. **Consulta de firmas:** la página de la URL de consulta pide «Desde», «Hasta» y «Nº de habitación» y lista los albaranes de esa habitación con su firma y sus líneas. ## Comprobar que funciona - En Ágora, abre un ticket, pulsa el botón y busca una habitación con cliente: salen número, cliente, teléfono y correo. - Firma en la pantalla y pulsa **Cargar**: la ventana confirma y se cierra. - En Ágora, el ticket es un albarán abierto a nombre del cliente-habitación; en la copia impresa sale «FIRMA:» con la imagen. - En la página de consulta de firmas, busca la habitación y la fecha de hoy: aparece el albarán con la firma. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «No se ha encontrado el nº de habitación especificado.» o «No se han encontrado reservas con el criterio especificado» | No hay cliente en Ágora con ese nombre fiscal, o falta la consulta personalizada | Revisa el cliente-habitación y la consulta en Ágora. | | La ventana se queda cargando y sale «Request timed out» | La acción no se abre dentro de Ágora | Marca «Mostrar Urls en un diálogo de Ágora». | | «El cliente es obligatorio. Realice la búsqueda para poder realizar el cargo.» | Se pulsó Cargar sin buscar | Busca primero la habitación. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Ágora no creó el albarán | Revisa que el ticket siga abierto y que el cliente-habitación sea válido. | | La firma no sale impresa | Falta la URL de facturas o «Enviar albaranes», la plantilla no es ESC/POS o no se firmó | Revisa Servicios de integración y la plantilla del albarán. | | «Ocurrió un error: …» con «Usar el API externa de Ágora» | URL Api, Api Token o URL de API del local inaccesibles | Revisa la conexión, o desmarca la opción. | | «Integración pausada» | FOS ha pausado la integración | Contacta con soporte. | ## Preguntas frecuentes ### ¿Qué hace la integración de ACI Hotel con Ágora? Cierra el ticket como albarán a nombre del cliente de Ágora que representa la habitación, con la firma del huésped. No se comunica con ACI Hotel. ### ¿El cargo llega a ACI Hotel? No. El albarán se queda en Ágora; cómo lo recoge después el hotel depende de su forma de trabajar, no de Connect Manager. ### ¿Cómo encuentra la habitación? Con una consulta personalizada de Ágora que busca el cliente cuyo nombre fiscal es el número de habitación, y toma el primero. ### ¿Cómo se imprime la firma en el albarán? Ágora envía el albarán a la URL de facturas de Connect Manager y la respuesta incluye la firma; hace falta «Enviar albaranes» y una plantilla ESC/POS. ### ¿Dónde consulto las firmas de una habitación? En la URL de consulta de cargos de habitación, por número de habitación y fechas. ## Referencias - [Ficha de la integración con ACI Hotel](https://connectmanager.es/integraciones/aci-hotel) - [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona) - [Integración de Sihot con Ágora](https://connectmanager.es/docs/integracion-sihot-agora): la misma configuración de acción personalizada y URL de documentos en Ágora - [Direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) --- # Integración de Cloudbeds con Ágora: cargos a habitación Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-cloudbeds-agora Actualizado: 2026-10-03 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 | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Api Key de Cloudbeds | El hotel, desde su cuenta de Cloudbeds | Cadena alfanumérica | Sí | | Propiedad (hotel) de Cloudbeds | Se elige en la lista del panel tras guardar | «Hotel Demo» | Sí | | Cliente genérico de Ágora para los albaranes | Distribuidor, en Ágora | «CLIENTES HOTEL» | Sí | | URL de API y API key de Ágora del local | Distribuidor | http://servidor:8984 | Sí (en la ficha del local) | | Email para los avisos | Cliente o distribuidor | avisos@hotel-demo.es | Recomendado: recibe el aviso de desconexión | | ¿Desglosar el IVA en Cloudbeds? | El hotel (contabilidad) | Sí / No | No | | Cuenta interna y métodos de pago de Cloudbeds | El hotel | «Restaurante», «Tarjeta Visa» | Solo para el Z-cierre | ## Configuración paso a paso ### En Cloudbeds - El hotel obtiene la **Api Key** de su cuenta de Cloudbeds y se la pasa a FOS. - 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) - Entra en **Administración → Locales**, abre el local y revisa **URL de API**, **API key** y **Zona horaria**. Pulsa **Guardar**. - 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. - Pega la **Api Key:** y añade el **Email de receptor de notificaciones** (escribe la dirección y pulsa Intro). - 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 - 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. - 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. - Marca **Dejar abierto el albarán** si el hotel quiere poder anular los cargos desde Ágora. - **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). - **Desglose de impuestos**: márcalo si el hotel quiere el precio sin IVA y el impuesto aparte en cada línea. - 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. - 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 - 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. - La acción crea un permiso: añádelo a los perfiles de los usuarios que vayan a cargar a habitación. - 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. ```mermaid 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. ```mermaid 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 - Al volver a abrir la integración, la lista **Hotel** muestra la propiedad: eso confirma que la Api Key funciona. - En Ágora, abre un ticket de prueba sin descuentos en efectivo y pulsa la acción personalizada. - 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. - Pulsa **Cargar**. Debe salir «OK» y cerrarse la ventana. - En Ágora, comprueba el albarán a nombre del huésped con su número de habitación. - En Cloudbeds, abre la reserva: deben aparecer los productos del ticket con la nota del albarán. - En Connect Manager, en **Operaciones hoteleras → Cargos**, el registro debe tener el **Id. de pedido externo** relleno. - Cancela el albarán de prueba en Ágora y comprueba que el cargo queda anulado en Cloudbeds. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «No se han encontrado reservas con el criterio especificado» | No hay reservas con check-in que coincidan, o la propiedad elegida no es la del huésped. | Comprueba que el check-in está hecho en Cloudbeds y que el campo Hotel es la propiedad correcta. | | «Debe introducir un criterio de búsqueda» | Se buscó con los campos vacíos. | Rellena habitación, nombre o apellido. | | «No se pueden efectuar cargos con descuentos en efectivo. Realice el descuento en porcentaje e inténtelo de nuevo» | El ticket tiene un descuento en importe. | Cambia el descuento a porcentaje en Ágora. | | «No se pueden efectuar cargos con descuentos por línea y a pie de ticket. Modifique los descuento e inténtelo de nuevo» | El ticket combina los dos tipos de descuento. | Deja solo uno de los dos. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Falló la creación del albarán o el envío del cargo a Cloudbeds. | Mira en Ágora si el albarán existe. Si existe, el fallo fue en Cloudbeds: revisa la respuesta en Operaciones hoteleras → Cargos antes de repetir. | | La lista Hotel sale vacía | Api Key incorrecta o sin permisos. | Pide a FOS que corrija la Api Key. | | Correo «Aplicación de Cloudbeds desconectada» | El hotel ha desconectado la aplicación en Cloudbeds. | Que el hotel la vuelva a conectar y facilite la Api Key nueva a FOS. | | Ágora no deja cancelar el albarán | Cloudbeds rechazó la anulación o el cargo original no llegó a Cloudbeds y no hay producto que anular. | Revisa el cargo en Cloudbeds y en Operaciones hoteleras → Cargos. | | Error al emitir facturas en Ágora | La integración de documentos envía facturas a la URL de Cloudbeds. | Desmarca el envío de facturas y deja solo el de albaranes. | | La pantalla muestra «Integración pausada» | FOS ha pausado el envío de cargos. | Contacta con soporte de FOS. | ## 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](https://connectmanager.es/integraciones/cloudbeds) - [Hotel Hub: cómo funcionan los cargos a habitación desde Ágora](https://connectmanager.es/docs/hotel-hub-como-funciona) - [Documentación para desarrolladores de Cloudbeds](https://developers.cloudbeds.com) --- # Integración de Guest Pro con Ágora: cargos a habitación Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-guestpro-agora Actualizado: 2026-10-03 La integración de **Guest Pro** (GuestPro) con **Ágora** permite cargar a la habitación del huésped lo que consume en el restaurante o el bar del hotel: el camarero busca la habitación desde el TPV, pulsa Cargar y el ticket pasa a un albarán en Ágora y a un cargo en Guest Pro, agrupado por extras. 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, 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 la habitación en Guest Pro por número y muestra el huésped y las fechas de la estancia (Desde y Hasta). - Si activas Solicitar firma, recoge la firma del huésped en pantalla y envía a Guest Pro el enlace de la imagen con el cargo. - Pasa el ticket a un **albarán de Ágora** sobre el cliente que configures, con el nombre del huésped y la habitación (`Nombre Apellido (Nº hab.: 101)`), y lo imprime. - Envía el cargo a Guest Pro **agrupado por extras**: cada familia de Ágora puede ir a un extra distinto y el resto va al extra por defecto. Cada extra lleva el importe, con los descuentos del ticket repartidos, y en el comentario la lista de productos con unidades e importes. - Guarda en Connect Manager cada operación: el ticket, el albarán, lo enviado a Guest Pro y su respuesta. - Puede mandar a Guest Pro el **cierre de ventas del día** (las facturas de Ágora de la jornada) como una factura genérica, agrupada por extras y formas de pago. Lee antes sus limitaciones. ### Qué no hace - **No anula en Guest Pro un cargo ya enviado.** Si devuelves o anulas el albarán en Ágora, el cargo hay que quitarlo en Guest Pro. - **No busca por número de tarjeta.** La pantalla enseña el buscador Nº de tarjeta, pero Connect Manager no envía ese dato a Guest Pro: solo funciona Nº de habitación. - No comprueba crédito ni bloqueos de la reserva, no envía propinas (no hay campo) y no envía las facturas de Ágora una a una. - No sincroniza reservas, disponibilidad ni tarifas. - **Cierre del día:** el envío automático a la Hora de generación fich. contable depende de una tarea programada del motor que hoy no está activa, y el panel no tiene botón para generar un cierre nuevo de Guest Pro (el de la pantalla de Inicio es solo para Sihot y UbikOS): solo se puede reenviar uno que ya exista en Cierres de caja. Confírmalo con FOS antes de ofrecerlo. ## 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 cargos a habitación (por ejemplo, `HUÉSPEDES HOTEL`). - **Conectividad**: Connect Manager tiene que llegar a la API de Ágora (puerto 8984), publicada o con [Zero Connect](https://connectmanager.es/docs/zero-connect-instalacion). La usan el panel (búsqueda de clientes, familias y formas de pago), el cierre del día y, con Usar el API externa de Ágora marcada, que es el valor por defecto, el propio cargo. Si el cliente filtra por IP, consulta las [direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager). - **Guest Pro**: acceso a su API (Access Token y Access Token Secret), el identificador del hotel y los extras de los cargos ya creados. Reparto de tareas: **FOS** da de alta el local y la integración; el **distribuidor** rellena los campos, asocia familias y formas de pago y configura Ágora; el **hotel o Guest Pro** facilita credenciales, Id. del hotel, extras y, si se usa el cierre, la serie de facturación. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Ágora (o del ACMS central) | Distribuidor, de la instalación de Ágora | https://hotel-demo.ejemplo.es:8984 | Sí | | API key de Ágora | Distribuidor, desde Ágora | Cadena alfanumérica | Sí | | Access Token y Access Token Secret | Guest Pro | Dos cadenas que entrega Guest Pro | Sí | | Id. del hotel en Guest Pro | Guest Pro | 12345 | Sí | | URL Api | Guest Pro, solo si indica otra | Vacía = https://admin.guestpro.com/apiv2/ | No | | Cliente de Ágora para los albaranes | Distribuidor u hotel (cliente genérico en Ágora) | HUÉSPEDES HOTEL | Sí, en la práctica | | Extra por defecto y, si se quiere, extra por familia | Hotel, de los extras de Guest Pro | Consumos restaurante; Bebidas → Bar | El extra por defecto, sí | | Correos para avisos de error | Hotel o distribuidor | avisos@hotel-demo.es | No | | Cierre: serie de facturación de Guest Pro | Guest Pro u hotel | 12 (identificador de la serie) | Solo con cierre | | Cierre: datos fiscales del cliente de facturación | Hotel | Nombre, CIF, dirección, código postal, ciudad y región | Solo con cierre | | Cierre: forma de pago de Guest Pro por cada una de Ágora | Hotel | Efectivo → Efectivo | Solo con cierre | ## Configuración paso a paso ### En Guest Pro - Pide al hotel o a Guest Pro el Access Token, el Access Token Secret y el identificador del hotel. - Comprueba que existen los extras de los cargos: uno por defecto y, si se quiere separar conceptos, uno por grupo de familias (bar, restaurante…). - Si se va a usar el cierre, pide el identificador de la serie de facturación y las formas de pago de Guest Pro. ### En Connect Manager: datos del local - Entra en `https://app.connectmanager.es` y ve a **Administración → Locales**. Abre el local. - Revisa **URL de API** y **API key** (las de Ágora o las del ACMS si es un grupo) y pulsa el botón de prueba junto a la URL: debe salir Conexión con éxito. - Pulsa **Guardar**. ### En Connect Manager: la integración de hoteles - En la columna de la derecha, entra en **Integraciones → Integraciones de hoteles**. Abre la de Guest Pro o, si eres administrador, pulsa Añadir y elige el **Proveedor** Guest Pro. - En **Conf. general** rellena **URL Api:** (vacía para la de Guest Pro), **Access Token:**, **Access Token Secret:**, **Id. del hotel** y, si quieres avisos, **Email de receptor de notificaciones** (escribe cada dirección y pulsa Intro). Ahí llegan los errores del cierre del día; los fallos de un cargo no se avisan por correo. - En **Conf. de cargos** ajusta las opciones de la tabla de abajo y elige el **Cliente**. - Pulsa **Guardar**: sale Se ha guardado la integración de hoteles y se activan las pestañas **Familias** y **Métodos de pago**. - Ya guardada, aparece **Entidad externa (servicio, etc.)** con los extras de Guest Pro: elige el extra por defecto y guarda otra vez. - En **Familias**, pulsa Añadir por cada familia con extra propio: **Familia** (de Ágora) y **Entidad externa (servicio, etc.)**. - **Métodos de pago** solo lo usa el cierre: por cada forma de pago de Ágora, **Método de pago de Agora** y **Método de pago Guest pro**. Las que no asocies van como la forma de pago 1 de Guest Pro. - Solo con cierre: en **Conf. de Z-cierre** marca **Z-cierre** y rellena **Serie de facturación**, **Nombre de cliente fact.**, **CIF fact.**, **Dirección fact.**, **Cód. postal fact.**, **Ciudad fact.**, **Región fact.** y **Hora de generación fich. contable**. El país va fijo a España. - En **Enlaces**, copia la **URL botón acción personalizada**. | Opción | Qué hace | Valor recomendado | | Usar el API externa de Ágora | Marcada: Connect Manager lee el ticket y crea el albarán llamando a la API de Ágora desde fuera. Desmarcada: lo hace el propio TPV a través del diálogo, con su API local. | Desmárcala si la API de Ágora no es accesible desde fuera de forma estable. | | Solicitar firma | Muestra un recuadro para la firma del huésped (con botón Borrar) y envía la imagen a Guest Pro. | Según pida el hotel. | | Cliente | Cliente de Ágora del albarán; el documento sale con el nombre del huésped y su habitación. | Un cliente genérico solo para cargos a habitación. | | Entidad externa (servicio, etc.) | Extra para las familias sin asociar. Vacío, el motor usa un extra fijo (700001) que probablemente no exista en tu Guest Pro. | Configúralo siempre. | **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. > [!NOTE] En el hub (`hub.connectmanager.es`, **/admin → Locales → Añadir integración**) hay un proveedor GuestPro (PMS) con Código Interno del Hotel, Client Secret (Token) y Forma de Pago Ágora ID. Ese formulario solo guarda datos: ningún proceso los usa ni da URLs para Ágora. No lo des de alta: la integración que carga en Guest Pro es la de `app.connectmanager.es`, que aparece en el hub en solo lectura tras Sincronizar Integraciones. ### En Ágora - Si no existe, crea el cliente genérico para los cargos a habitación y comprueba que es el elegido en Cliente. - 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}`… que rellena Ágora. - Marca **Mostrar Urls en un diálogo de Ágora**. Es obligatorio: la pantalla habla con el TPV a través de ese diálogo y, en un navegador aparte, no puede leer el ticket. - 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/guest-pro/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}`. Guest Pro no necesita la integración de documentos de Ágora. ## Cómo funciona El camarero pulsa la acción con el ticket del huésped abierto. Se abre en un diálogo la pantalla de Connect Manager («Busque por nº de habitación o nº de tarjeta.»). Al escribir la habitación, Connect Manager consulta a Guest Pro y enseña habitación, cliente y fechas. Si se pide, el huésped firma. Al pulsar Cargar, primero se crea el albarán en Ágora, que cierra el ticket, y después se envía el cargo a Guest Pro. Si Guest Pro lo acepta, sale «Se generó el siguiente cargo:» con su identificador y el diálogo se cierra a los dos segundos. ```mermaid sequenceDiagram participant C as Camarero participant AG as Ágora participant CM as Connect Manager participant GP as Guest Pro C->>AG: Pulsa la acción Cargo habitación AG->>CM: Abre la pantalla de cargo en un diálogo C->>CM: Escribe el nº de habitación CM->>GP: Consulta la habitación con el Id. del hotel GP-->>CM: Huésped y fechas de la estancia C->>CM: Firma si se pide y pulsa Cargar CM->>AG: Crea el albarán del ticket AG-->>CM: Albarán con serie y número CM->>GP: Envía el cargo agrupado por extras GP-->>CM: Cargo aceptado con su identificador CM-->>C: Se generó el siguiente cargo ``` El cargo lleva el Id. del hotel, la habitación devuelta por la búsqueda, serie, número y fecha del albarán, el enlace de la firma si la hay y una línea por extra (una unidad, el importe y un comentario del tipo `Agua (2 unid.): 4,00€` por producto). Solo cuentan las líneas normales y las cabeceras de menú con importe. Cada petición a Guest Pro se intenta hasta tres veces, con medio segundo entre intentos. Como el albarán se crea **antes** del cargo, si Guest Pro lo rechaza el albarán ya existe en Ágora y no hay anulación automática: hay que devolverlo a mano (en un rechazo de Guest Pro, el mensaje indica su serie y número). Con Usar el API externa de Ágora marcada, si Connect Manager no llega a la API de Ágora el cargo no se hace. ### El cierre del día Al lanzarse un cierre, Connect Manager pide a Ágora las facturas de ese día de negocio, suma los importes por extra (con las asociaciones de familias) y por forma de pago, y crea en Guest Pro una factura genérica con la serie y los datos fiscales configurados. El resultado queda en **Operaciones hoteleras → Cierres de caja** (Creado, Enviado, Error o No hay datos), con la solicitud, la respuesta y el error en el detalle. Si falla la lectura de Ágora, se avisa por correo. ```mermaid flowchart TD A[Lanzamiento del cierre de un día] --> B[Connect Manager pide a Ágora las facturas del día] B --> C[Suma importes por extra y por forma de pago] C --> D[Crea una factura genérica en Guest Pro] D --> E{Respuesta de Guest Pro} E -->|success| F[Estado Enviado] E -->|error| G[Estado Error con el mensaje] ``` > [!WARNING] Reenviar con Exportar un cierre de Guest Pro ya Enviado lo manda otra vez entero: Connect Manager no lo impide y en Guest Pro quedaría duplicado. Y si la URL de API del local es la de un ACMS con varios locales, solo se envía el primero que devuelve Ágora. ## Comprobar que funciona - La prueba de la URL de API del local da Conexión con éxito; en la integración, Cliente lista clientes de Ágora y Entidad externa (servicio, etc.) lista extras de Guest Pro. - Abre en Ágora un ticket de prueba con un producto barato y pulsa la acción: se abre el diálogo con los buscadores. - Busca una habitación ocupada de prueba: salen cliente y fechas. - Pulsa Cargar (y firma si está activado): debe salir «Se generó el siguiente cargo:» y cerrarse el diálogo. - En Ágora queda el albarán impreso a nombre de «huésped (Nº hab.: …)». - En Guest Pro, el cargo está en la habitación con el extra correcto y el detalle en el comentario. - En **Operaciones hoteleras → Cargos** aparece la operación con Pedido externo (request) y Pedido externo (response). - Anula el albarán de prueba en Ágora y quita el cargo a mano en Guest Pro. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Al guardar: «Access Token es obligatorio.» o «Access Token Secret es obligatorio.» | Falta una de las dos credenciales. | Rellena las dos con los datos de Guest Pro. | | Los buscadores de Cliente, familias o formas de pago no devuelven nada | Connect Manager no llega a la API de Ágora. | Revisa URL de API, API key, la prueba de conexión, el puerto 8984 o Zero Connect. | | No aparece Entidad externa (servicio, etc.) o su lista sale vacía | La integración no se ha guardado, o las credenciales, el Id. del hotel o la URL Api no son correctos. | Guarda y vuelve a abrirla; si sigue vacía, revisa los datos con Guest Pro. | | El TPV muestra «Integración pausada» | FOS ha pausado el envío de cargos. | Contacta con soporte de FOS. | | «No se ha encontrado el ticket: … Cierre esta ventana e intente generar el ticket de nuevo.» o «Request timed out» | La acción no se abre en un diálogo de Ágora o el ticket no existe. | Marca Mostrar Urls en un diálogo de Ágora y lánzala desde un ticket abierto con productos. | | «No existe ningún ticket en Ágora con el identificador: …» | El ticket no tiene líneas o la API de Ágora no lo encuentra. | Añade productos al ticket y repite; revisa la conexión con la API. | | «No se pudo enviar a Guest Pro. Por favor, devuelva el ticket N de la serie S.» | Guest Pro rechazó el cargo después de crearse el albarán. | Devuelve ese albarán en Ágora, mira el motivo en Pedido externo (response) y repite desde un ticket nuevo, o carga a mano en Guest Pro. | | Un aviso que solo dice «true» | El cargo falló con Usar el API externa de Ágora marcada; esa pantalla no muestra el detalle. | Mira el motivo en Operaciones hoteleras → Cargos y comprueba en Ágora si se creó el albarán. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Con la opción desmarcada: falló el albarán en el TPV o el envío posterior a Guest Pro. | Comprueba en Ágora si el albarán existe y en Cargos la respuesta antes de repetir. | | «Ocurrió un error: HTTP request returned status code …» | Guest Pro respondió con error HTTP (credenciales, URL o caída). | Revisa credenciales y URL Api; si persiste, consulta con Guest Pro. | | Cargos en el extra 700001 o rechazados por el extra | No hay extra por defecto y la familia no está asociada. | Configura Entidad externa (servicio, etc.) y las familias. | | Un cierre en estado Error | Guest Pro rechazó la factura (serie, datos fiscales, formas de pago). | Lee Error en la respuesta externa en el detalle, corrige y reenvíalo con Exportar. | ## Preguntas frecuentes ### ¿Cómo conecto Guest Pro con Ágora? FOS da de alta la integración de hoteles con el proveedor Guest Pro en Connect Manager; tú rellenas Access Token, Access Token Secret e Id. del hotel, eliges el cliente y el extra por defecto y creas en Ágora una acción personalizada con la URL del panel, mostrada en un diálogo. ### ¿Se puede anular desde Ágora un cargo enviado a Guest Pro? No. Anular o devolver el albarán en Ágora no toca Guest Pro: el cargo hay que quitarlo a mano allí. ### ¿Se puede buscar al huésped por tarjeta o por nombre? No. Aunque la pantalla muestra el buscador de tarjeta, solo funciona la búsqueda por número de habitación. ### ¿Qué pasa si no asocio las familias? Todo el ticket va al extra por defecto, en una línea con el detalle de productos en el comentario. Asócialas solo si el hotel quiere separar conceptos. ### ¿Para qué sirve el proveedor GuestPro (PMS) del hub? Para nada operativo: guarda datos pero no carga nada en Guest Pro. La integración que funciona es la de app.connectmanager.es. ## Referencias - Ficha del catálogo: [Guest Pro](https://connectmanager.es/integraciones/guestpro) - Visión general de los cargos a habitación: [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona) - Otros PMS: [Sihot](https://connectmanager.es/docs/integracion-sihot-agora), [Hospedium](https://connectmanager.es/docs/integracion-hospedium-agora), [UbikOS](https://connectmanager.es/docs/integracion-ubikos-agora) y [Redforts](https://connectmanager.es/docs/integracion-redforts-agora) - [Zero Connect: conectar Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion) - [Direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) --- # Integración de Hospedium con Ágora: cargos a habitación Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-hospedium-agora Actualizado: 2026-10-03 La integración de **Hospedium** con **Ágora** permite cargar en la cuenta de la habitación lo que el huésped consume en el restaurante o el bar del hotel. El camarero busca la habitación desde el TPV, pulsa Cargar y el ticket pasa a un albarán en Ágora y a un cargo en Hospedium, desglosado por tipo de IVA y con el detalle de productos. 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. - Pide a Hospedium las cuentas abiertas del hotel y enseña las que coinciden con lo que se escribe en Nº de habitación: una tarjeta por cuenta, con la habitación y la tarifa. - Deja añadir una **propina** en cada tarjeta antes de cargar. - 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 cuenta de Hospedium **desglosado por tipo de IVA**: un concepto por cada tipo, con el número de albarán, el importe con IVA, la fecha y la hora, el nombre del TPV, el identificador del ticket y el detalle de productos (nombre, cantidad, precio con IVA, importe, IVA y referencia del formato de venta). - Envía la propina como concepto aparte, `Propina SERIE/000123`, con IVA 0. - Puede trabajar contra el entorno de pruebas de Hospedium (staging) o contra el real. - Guarda en Connect Manager cada operación: el ticket, el albarán y lo que se envió a Hospedium. ### Qué no hace - No comprueba si el huésped sigue alojado, su crédito ni bloqueos: lista las cuentas que Hospedium devuelve. - **No anula en Hospedium el cargo de un albarán anulado.** Si devuelves el albarán en Ágora, el cargo hay que quitarlo en Hospedium. - No pide la firma del huésped. - No envía facturas ni el cierre de ventas del día, y no hay familias ni formas de pago que asociar. - No sincroniza reservas, disponibilidad ni tarifas. - La búsqueda no es exacta: el texto se compara con el nombre de la habitación, así que «1» encuentra la 1, la 10 o la 101. Hay que pulsar Cargar en la tarjeta correcta. ## 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 de hoteles 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 cargos a habitación. - **Conectividad**: el cargo lo hace el propio TPV a través del diálogo, con su API local, así que 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](https://connectmanager.es/docs/zero-connect-instalacion). Los TPV necesitan salida a Internet para abrir la pantalla de cargo. - **Hospedium**: la URL de su API, la firma de integración y el identificador del hotel, y que el hotel abra cuenta a cada habitación ocupada. Reparto de tareas: **FOS** da de alta el local y la integración; el **distribuidor** rellena los campos y configura Ágora; el **hotel o Hospedium** facilita la URL, la firma y el Id. del hotel, y dice si son de producción o de pruebas. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Ágora (o del ACMS central) | Distribuidor, de la instalación de Ágora | https://hotel-demo.ejemplo.es:8984 | Sí | | API key de Ágora | Distribuidor, desde Ágora | Cadena alfanumérica | Sí | | URL Api de Hospedium | Hospedium | https://hospedium.ejemplo.es (sin /api/external) | Sí, no tiene valor por defecto | | Firma | Hospedium (clave de integración del hotel) | Cadena que entrega Hospedium | Sí | | Id. del hotel | Hospedium | 12345 | Sí | | Entorno (producción o pruebas) | Hospedium | Usar API staging marcada o no | Sí | | Cliente de Ágora para los albaranes | Distribuidor u hotel (cliente genérico creado en Ágora) | HUÉSPEDES HOTEL | Sí, en la práctica | | Correo de notificaciones | Hotel o distribuidor | avisos@hotel-demo.es | No (ningún proceso de Hospedium lo usa) | ## Configuración paso a paso ### En Hospedium - Pide a Hospedium (o al hotel) la URL de la API, la **firma** de integración y el **identificador del hotel**. - Pregunta si esos datos son del entorno real o del de pruebas: de eso depende la casilla Usar API staging. - Confirma con el hotel que las habitaciones ocupadas tienen cuenta abierta en Hospedium: es lo que lista la pantalla de cargo. ### En Connect Manager: datos del local - Entra en `https://app.connectmanager.es` y ve a **Administración → Locales**. Abre el local. - Revisa **URL de API** y **API key**. Pulsa el botón de prueba junto a la URL: debe salir Conexión con éxito. - Pulsa **Guardar**. ### En Connect Manager: la integración de hoteles - En la columna de la derecha, entra en **Integraciones → Integraciones de hoteles**. Abre la integración de Hospedium o, si eres administrador, pulsa Añadir y elige el **Proveedor** Hospedium. - En **Conf. general** rellena **URL Api:**, **Firma:** e **Id. del hotel**. El **Email de receptor de notificaciones** se puede dejar vacío: con Hospedium no hay ningún proceso que envíe avisos. - En **Conf. de cargos**, revisa **Usar API staging** y elige el **Cliente** de Ágora para los albaranes. - Pulsa **Guardar**: sale Se ha guardado la integración de hoteles. Hospedium no tiene pestañas de familias ni de formas de pago. - En **Enlaces**, copia la **URL botón acción personalizada**. > [!WARNING] Al crear una integración de Hospedium, **Usar API staging** viene marcada. Con ella marcada los cargos van al entorno de pruebas de Hospedium (`/api/external/staging/accounts`) y no aparecerán en el PMS real. Desmárcala antes de ponerla en producción. | Opción | Qué hace | Valor recomendado | | Usar API staging | Envía la consulta y los cargos al entorno de pruebas de Hospedium en lugar del real. | Desmarcada en producción. | | Cliente | Cliente de Ágora del albarán; su nombre sale en el documento con el número de habitación. | Un cliente genérico solo para cargos a habitación. | 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 - Si no existe, crea el cliente genérico para los cargos a habitación y comprueba que es el elegido en Cliente. - 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}`… - 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. - En **Herramientas → Configuración de Botones**, coloca la acción en un botón del perfil que usa el local (o en el menú Otros). - Da el permiso de la acción 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/hospedium/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}`. Hospedium 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 escribe la habitación y Connect Manager trae de Hospedium las cuentas abiertas, filtradas por ese texto. En la tarjeta elegida puede poner una propina y pulsar Cargar: el TPV crea el albarán, Connect Manager lo guarda y envía el cargo a esa cuenta de Hospedium. Si todo va bien sale «Se generó el siguiente cargo:» seguido del número interno de Connect Manager (Hospedium no devuelve uno propio) y el diálogo se cierra a los dos segundos. ```mermaid sequenceDiagram participant C as Camarero participant AG as TPV Ágora participant CM as Connect Manager participant HO as Hospedium 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: Escribe el nº de habitación CM->>HO: Pide las cuentas abiertas HO-->>CM: Cuentas con habitación y tarifa CM-->>C: Tarjetas que coinciden con el texto C->>CM: Propina opcional y Cargar CM->>AG: Crea el albarán por la API local AG-->>CM: Albarán con serie y número CM->>HO: Cargo en la cuenta por tipo de IVA HO-->>CM: Respuesta correcta CM-->>C: Se generó el siguiente cargo ``` Connect Manager se identifica ante Hospedium como `agora-pos` y firma cada petición con la Firma y el Id. del hotel (cabecera `X-Signature`). La consulta va a `…/api/external/accounts` y el cargo a `…/api/external/accounts/{cuenta}/`; con Usar API staging, a las mismas rutas con `/staging` detrás de `/external`. El cargo lleva un concepto por cada tipo de IVA del albarán (`SERIE/000123`, cantidad 1 y el importe con IVA de ese tipo) con sus líneas de producto, y la propina como concepto propio con IVA 0. El albarán se crea **antes** de enviar el cargo. Si Hospedium no responde o lo rechaza, el albarán ya existe en Ágora y la pantalla dice «No se ha podido generar el albarán…»: comprueba en Ágora si el albarán está creado y, si lo está, devuélvelo o carga el importe a mano en Hospedium. 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 - En los datos del local, la prueba de la URL de API da Conexión con éxito y en la integración el buscador de Cliente lista clientes de Ágora. - Usar API staging está en el valor que corresponde al entorno que te dio Hospedium. - Abre en Ágora un ticket de prueba con un producto de cada tipo de IVA que se use (comida y bebida, por ejemplo) y pulsa la acción. - Escribe una habitación con cuenta abierta: aparece su tarjeta con la tarifa. - Pon una propina de prueba (con coma decimal, por ejemplo `1,50`) y pulsa Cargar. Debe salir «Se generó el siguiente cargo:» y cerrarse el diálogo. - En Ágora queda el albarán impreso a nombre del cliente genérico con «(Nº hab.: …)». - En Hospedium, la cuenta tiene un concepto por tipo de IVA y otro de propina. - En Connect Manager, **Operaciones hoteleras → Cargos** muestra la operación con Pedido externo (request) y Pedido externo (response). - Anula el albarán de prueba en Ágora y quita el cargo en Hospedium. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Al guardar: «Ocurrió un error: The auth data field is required.» | El campo Firma está vacío. | Rellena la firma que entregó Hospedium. | | El buscador de Cliente no devuelve nada | Connect Manager no llega a la API de Ágora. | Revisa URL de API, API key, la prueba de conexión, el puerto 8984 o Zero Connect. | | El TPV muestra «Integración pausada» | FOS ha pausado el envío de cargos. | Contacta con soporte de FOS. | | «No se ha encontrado el ticket: … Cierre esta ventana e intente generar el ticket de nuevo.» o «Request timed out» | La acción no se abre en un diálogo de Ágora o el ticket no existe. | Marca Mostrar Urls en un diálogo de Ágora y lánzala desde un ticket abierto con productos. | | «No se han encontrado reservas con el criterio especificado» | Hospedium no devolvió ninguna cuenta abierta (o se consulta el entorno equivocado). | Revisa Usar API staging y que el hotel tenga cuentas abiertas. | | Se busca y no aparece ninguna tarjeta | Hay cuentas, pero ninguna coincide con el texto escrito. | Escribe la habitación tal como se llama en Hospedium. | | «Ocurrió un error: HTTP request returned status code 401…» (o 403) | Firma, Id. del hotel o entorno incorrectos. | Comprueba los tres datos con Hospedium. | | «Ocurrió un error: cURL error…» | La URL Api es incorrecta o Hospedium no responde. | Revisa la URL (solo la base, sin rutas) y vuelve a probar. | | «La propina tiene que ser un número (entero o con coma).» | La propina se escribió con punto o con letras. | Escríbela con coma decimal: 2,50. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Falló el albarán en el TPV o Hospedium rechazó el cargo después de crearlo. | Mira en Ágora si el albarán existe y en Cargos qué se envió antes de repetir. | | «No existe albarán asociado con el ticket. Por favor, cierre la ventana e inténtelo de nuevo.» | El albarán no llegó a guardarse en Connect Manager antes del cargo. | Cierra el diálogo, comprueba el ticket en Ágora y repite. | | Los cargos no aparecen en el Hospedium del hotel | Usar API staging sigue marcada. | Desmárcala, guarda y repite la prueba. | ## Preguntas frecuentes ### ¿Cómo conecto Hospedium con Ágora? FOS da de alta la integración de hoteles con el proveedor Hospedium; tú pones la URL Api, la firma y el Id. del hotel, desmarcas Usar API staging para producción, eliges el cliente y creas en Ágora una acción personalizada con la URL del panel, mostrada en un diálogo. ### ¿Por qué viene marcada «Usar API staging»? Es el valor por defecto al crear la integración, pensado para probar contra el entorno de pruebas de Hospedium. En producción hay que desmarcarla. ### ¿Se anula el cargo en Hospedium si anulo el albarán en Ágora? No. La integración no envía anulaciones: el cargo hay que quitarlo a mano en Hospedium. ### ¿Por qué el cargo llega en varios conceptos? Porque se envía un concepto por cada tipo de IVA del ticket, con sus productos dentro, y otro para la propina si la hay. ### ¿Hay que abrir el puerto de la API de Ágora? Para cargar no: lo hace el TPV desde el diálogo. Para que el panel busque el cliente al configurar, Connect Manager necesita llegar a la API, publicada o con Zero Connect. ## Referencias - Ficha del catálogo: [Hospedium](https://connectmanager.es/integraciones/hospedium) - Visión general de los cargos a habitación: [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona) - Otros PMS: [Guest Pro](https://connectmanager.es/docs/integracion-guestpro-agora), [UbikOS](https://connectmanager.es/docs/integracion-ubikos-agora), [Redforts](https://connectmanager.es/docs/integracion-redforts-agora) y [Sihot](https://connectmanager.es/docs/integracion-sihot-agora) - [Direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) - [Zero Connect: conectar Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion) --- # Integración de Lean PMS con Ágora: cargos a habitación Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-lean-agora Actualizado: 2026-10-03 La integración de **Lean PMS con Ágora** permite cargar un ticket del TPV a la reserva de un huésped alojado, o a una reserva de grupo, desde una acción personalizada de Ágora, y enviar a Lean las facturas simplificadas del TPV con sus formas de pago. Connect Manager agrupa los consumos por familias con los productos de Lean que elijas. Este manual es para el técnico que la configura: qué pedir, dónde meterlo, cómo funciona y qué hacer cuando falla. ## Qué hace la integración - Busca la reserva **con check-in** por **número de habitación** y, si se activa **Habilitar cargos a grupos**, por **número de grupo**. - Muestra el huésped (o el contacto del grupo), las fechas, el programa de fidelización y, con un botón, los extras de la reserva que elijas en la configuración. - Si Lean indica que la reserva **no admite cargos del TPV**, avisa y no deja cargar. - Crea el albarán en Ágora y envía a Lean el cargo a la reserva o al grupo como **cargos agrupados por familia**: uno por cada producto de Lean asignado a una familia de Ágora, más un cargo general «Bar/Rest/Room Service – SERIE/000123» con el resto del importe. - Muestra un campo de **propina** y la envía como un cargo aparte con el producto sin IVA. - **Anula el cargo** al cancelar el albarán en Ágora, enviando los mismos cargos en negativo como devolución, siempre que el huésped siga alojado (en los grupos no se comprueba). - Envía a Lean **cada factura simplificada** del TPV en el momento en que se emite, con sus cargos por familia, la propina y los cobros por forma de pago. Así Lean recibe también las ventas de clientes no alojados. ### Qué no hace - No admite **facturas completas** (con datos del cliente): si Ágora envía una a la URL de facturas, Connect Manager la rechaza con «No está permitido crear facturas normales» y Ágora no deja cerrarla. - No comprueba el crédito ni el régimen de la reserva. - No recoge la firma del huésped: la opción no está en el panel para Lean. - No busca por nombre. La pantalla tiene un campo **Nº de tarjeta**, pero lo que se teclea se busca en Lean como número de habitación. - El cierre de albaranes a los N días depende de una tarea nocturna que en la versión actual del motor está desactivada. - No sincroniza reservas ni disponibilidad. ## Requisitos - **Lean**: usuario y contraseña de su API para el hotel, el identificador del hotel y los productos de Lean con los que se va a cargar (al menos uno para el consumo general y otro sin IVA para las propinas). - **Á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 simplificadas. - **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). Si la desactivas, 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 elige productos, familias y formas de pago y configura Ágora. Lean facilita las credenciales. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Lean | Lean | https://api.lean-demo.es/ | Sí | | Usuario y contraseña de la API | Lean | usuario-demo | Sí | | Id. del hotel en Lean | Lean | 2 | Sí | | Producto de Lean para el consumo general (IVA 10%) | El hotel, de la lista que trae Lean | «Restaurante» | Sí | | Producto de Lean sin IVA para las propinas (IVA 0%) | El hotel | «Propinas» | Sí, si se usan propinas | | Producto de Lean por familia de Ágora | El hotel | Menús → «Media pensión extra» | No | | Extras de Lean que se muestran en pantalla | El hotel | «Desayuno incluido» | No | | Forma de pago de Lean de cada forma de pago de Ágora | El hotel | Visa → «Tarjeta» | Sí, si se envían facturas | | Cliente genérico de Ágora para los albaranes | Distribuidor, en Ágora | «CLIENTES HOTEL» | Sí | | URL de API y API key de Ágora del local | Distribuidor | http://servidor:8984 | Sí (en la ficha del local) | | Email para los avisos | Cliente o distribuidor | avisos@hotel-demo.es | Recomendado | ## Configuración paso a paso ### En Lean - Pide a Lean la URL de la API, el usuario, la contraseña y el Id. del hotel. - Comprueba con el hotel que existen en Lean los productos para el consumo general y para las propinas, y los que quiera usar por familia. ### En Connect Manager: alta de la integración (FOS) - Entra en **Administración → Locales**, abre el local y revisa **URL de API**, **API key** y **Zona horaria**. Pulsa **Guardar**. - Pulsa **Integraciones de hoteles → Añadir** y elige el **Proveedor** **PMS Lean**. - Rellena **URL Api:**, **Usuario**, **Password** e **Id. del hotel**, y añade el **Email de receptor de notificaciones**. - Pulsa **Guardar**. Las listas de Lean aparecen al volver a abrir la integración. ### En Connect Manager: opciones de los cargos En el bloque **Conf. de cargos**: - **Usar el API externa de Ágora**: activada, Connect Manager lee el ticket y crea el albarán por la API de Ágora; desactivada, lo hace la pantalla a través del TPV. Con ella activada los mensajes de error son más claros. - **Habilitar cargos a grupos**: añade en la pantalla la búsqueda por **Nº de grupo** y permite cargar a una reserva de grupo. - **Agrupar familias para productos estándar**: desmarcada, solo las líneas de menú se reparten por familias y los productos sueltos van al cargo general; marcada, también los productos sueltos se agrupan por su familia. - **Nº de días para cerrar albaranes**: en Lean el albarán se deja siempre abierto para poder anularlo; este plazo es el que usaría la tarea de cierre (ver el aviso). - **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, o por el nombre del grupo y su número. - **Extras**: los extras de Lean que el camarero verá con el botón de extras de la reserva (admite varios). - **Producto IVA 10%**: el producto de Lean del cargo general. - **Producto IVA 0%**: el producto de Lean de las propinas. > [!WARNING] El cierre automático de albaranes depende de una tarea programada de Connect Manager que, en la versión actual del motor, está desactivada. Confirma con FOS que está en marcha antes de contar con ella. Guarda y completa las pestañas: - **Familias**: por cada **Familia** de Ágora que quieras separar, su **Producto IVA 10%** de Lean. Marca **Enviar cuando el importe es cero** si quieres que el cargo de esa familia llegue a Lean aunque valga cero (por ejemplo, platos incluidos en un menú). - **Métodos de pago**: por cada **Método de pago de Agora**, su **Método de pago de Lean**. Asígnalos todos: 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 - 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. - 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. > [!WARNING] Con las facturas enviándose a Lean, Ágora no podrá emitir facturas completas con datos del cliente en ese local: Connect Manager las rechaza. Coméntalo con el hotel antes de activarlo. ## Cómo funciona Al pulsar la acción personalizada se abre la pantalla de Connect Manager. Connect Manager se identifica en Lean con el usuario y la contraseña (guarda el acceso durante un día) y busca las reservas con check-in en esa habitación, o la reserva de grupo. Si la reserva admite cargos del TPV, se muestran sus datos. Al pulsar **Cargar**, se crea el albarán en Ágora y después se envían los cargos a Lean. Si todo va bien, la pantalla muestra «Se generó el siguiente cargo:» con el número de Lean y se cierra. ```mermaid sequenceDiagram participant C as Camarero participant TPV as TPV Ágora participant CM as Connect Manager participant L as Lean C->>TPV: Pulsa la acción personalizada TPV->>CM: Abre la pantalla con el ticket y el TPV C->>CM: Busca por habitación o por grupo CM->>L: reservations o groupreservations L-->>CM: Reserva y si admite cargos del TPV C->>CM: Propina si la hay y pulsa Cargar CM->>TPV: Crea el albarán a nombre del huésped CM->>L: charges por familia, cargo general y propina L-->>CM: Identificadores de los cargos CM-->>C: Se generó el siguiente cargo ``` Cada cargo lleva el hotel, la reserva (o el grupo), la fecha y el día de producción del albarán, el producto de Lean, una descripción con el nombre del producto y el número del albarán, las unidades y el importe con el descuento del ticket repartido. Las líneas de familias sin producto asignado se suman al cargo general. Si Lean no devuelve el cargo, la pantalla pide devolver el albarán, que ya está creado en Ágora. ### Anulaciones Al cancelar el albarán en Ágora, Connect Manager comprueba en Lean que la reserva sigue con check-in (en los grupos no lo comprueba) y envía los mismos cargos con el importe en negativo como devolución y la descripción «SERIE/000124 (Cancelación de …)». Si el huésped ya no está alojado, responde «El albarán no se puede devolver» y Ágora no deja cancelarlo. Solo se anulan los cargos que llegaron a Lean. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant L as Lean TPV->>CM: Albarán de cancelación CM->>L: ¿La reserva sigue con check-in? L-->>CM: Sí CM->>L: charges en negativo como devolución L-->>CM: Respuesta CM-->>TPV: Acepta o rechaza la cancelación ``` ### Facturas simplificadas Cada factura simplificada que Ágora envía a la URL de documentos se manda a Lean como factura simplificada del hotel, con los cargos repartidos igual que en el cargo a habitación, la propina con el producto sin IVA y un cobro por cada forma de pago asignada. Las devoluciones se envían como devolución. Las facturas de importe cero se aceptan sin enviarlas. Si Lean responde con error, Connect Manager rechaza la factura con el texto de Lean. Las facturas enviadas se ven en **Operaciones hoteleras → Facturas**. ## Comprobar que funciona - Al volver a abrir la integración, las listas de **Extras**, **Producto IVA 10%** y **Producto IVA 0%** tienen datos: eso confirma usuario, contraseña e Id. del hotel. - En Ágora, abre un ticket de prueba y pulsa la acción personalizada. Busca una habitación con check-in: deben salir el huésped, sus fechas y el programa de fidelización. - Teclea una propina de prueba y pulsa **Cargar**. Debe salir «Se generó el siguiente cargo:» y cerrarse la ventana. - En Lean, comprueba en la reserva los cargos por familia, el cargo general y la propina. - En Connect Manager, en **Operaciones hoteleras → Cargos**, el **Id. de pedido externo** debe estar relleno. - Emite en Ágora una factura simplificada cobrada con tarjeta y comprueba que en **Operaciones hoteleras → Facturas** sale como «Aceptado». - Cancela el albarán de prueba y comprueba la devolución en Lean. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «No se ha podido obtener un token de Autenticación.» o «No se pudo obtener un token de autenticación» | Usuario, contraseña o URL de Lean incorrectos. | Revisa las credenciales y la URL con Lean. | | «No se han encontrado reservas con el criterio especificado» | No hay reserva con check-in en esa habitación o grupo. | Comprueba la reserva en Lean. | | «La reserva no admite cargos» | La reserva no acepta cargos del TPV en Lean. | Que recepción lo revise en Lean. | | «Ocurrió un error: No se pudo enviar a Lean. Por favor, devuelva el ticket N de la serie S.» | Lean no devolvió el cargo. El albarán ya está creado. | Devuelve el albarán en Ágora y repite el cargo. | | «El albarán no se puede devolver» | Se intenta cancelar un albarán de un huésped que ya no está alojado. | Corrige el cargo directamente en Lean. | | Ágora no deja cerrar una factura: «No está permitido crear facturas normales» | Es una factura completa y Lean solo acepta simplificadas. | Emite una factura simplificada o quita el envío de facturas en Ágora para ese local. | | Ágora no deja cerrar una factura: «El método de pago X no está asignado a ningún método de pago de Lean. Por favor, asígnelo para poder continuar» | Falta la forma de pago en la pestaña Métodos de pago. | Asígnala y vuelve a emitir la factura. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Con el API externa desactivada, falló la creación del albarán o el envío a Lean. | Mira en Ágora si el albarán se creó y el detalle en Operaciones hoteleras → Cargos. | | Las listas de productos salen vacías | Credenciales o Id. del hotel incorrectos. | Corrígelos y guarda. | | La pantalla muestra «Integración pausada» | FOS ha pausado el envío de cargos. | Contacta con soporte de FOS. | ## Preguntas frecuentes ### ¿Cómo conecto Lean PMS con Ágora? FOS da de alta la integración con la URL, el usuario, la contraseña y el Id. del hotel de Lean. Después se eligen los productos, las familias y las formas de pago y se crean en Ágora la acción personalizada y la integración de documentos. ### ¿Se puede cargar a una reserva de grupo en Lean? Sí, activando Habilitar cargos a grupos. La pantalla muestra entonces la búsqueda por número de grupo. ### ¿Cómo se reparten los consumos en Lean? En un cargo por cada producto de Lean asignado a una familia de Ágora y un cargo general con el resto. La opción Agrupar familias para productos estándar decide si los productos sueltos también se reparten por familia. ### ¿Por qué Ágora no me deja hacer una factura con datos del cliente? Porque con las facturas enviándose a Lean, Connect Manager solo acepta facturas simplificadas y rechaza las completas. ### ¿Se envían las propinas a Lean? Sí. La pantalla de cargo tiene un campo Propina que se envía como cargo aparte con el Producto IVA 0%, y las propinas de las facturas también se envían. ## Referencias - [Ficha de Lean en el catálogo de integraciones](https://connectmanager.es/integraciones/lean) - [Hotel Hub: cómo funcionan los cargos a habitación desde Ágora](https://connectmanager.es/docs/hotel-hub-como-funciona) --- # Integración de Mews con Ágora: cargos a habitación Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-mews-agora Actualizado: 2026-10-03 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 | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Access Token de Mews | El hotel, desde Mews, al conectar la integración | Cadena larga de letras y números | Sí | | Servicio de Mews para los consumos | El hotel (responsable de Mews) | «Restaurante» | Sí | | Categoría contable por defecto | El hotel (contabilidad) | «Food & Beverage» | Sí | | Categoría contable de propinas | El hotel | «Propinas» | Solo si se usan propinas | | Categoría contable por familia de Ágora | El hotel | Bebidas → «Beverage» | No (recomendado) | | Servicio y outlet por centro de venta | El hotel | Terraza → servicio «Terraza» | No | | Outlet y método de pago por defecto, métodos de pago por forma de pago | El hotel | Efectivo → «Cash» | Solo para el Z-cierre | | Cliente genérico de Ágora para los albaranes | Distribuidor, en Ágora | «CLIENTES HOTEL» | Sí | | URL de API y API key de Ágora del local | Distribuidor | http://servidor:8984 | Sí (en la ficha del local) | | Email para los avisos | Cliente o distribuidor | avisos@hotel-demo.es | Recomendado | | Si se pide firma y si se muestra propina | El hotel | Sí / No | No | ## Configuración paso a paso ### En Mews - El hotel conecta la integración de Connect Manager en su Mews y obtiene el **Access Token** de la propiedad. - 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) - Entra en **Administración → Locales**, abre el local y revisa **URL de API**, **API key** y **Zona horaria**. Pulsa **Guardar**. - 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. - Pega el **Access Token:** del hotel y añade el **Email de receptor de notificaciones** (escribe la dirección y pulsa Intro; admite varias). - 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. - 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: - **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. - **Familias**: para cada **Familia** de Ágora, su **Categoría de contabilidad** en Mews. - **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 - 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. - La acción crea un permiso: añádelo a los perfiles de los usuarios que vayan a cargar a habitación. - 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. ```mermaid 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. ```mermaid 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 - Tras guardar, el **Id. del hotel** está relleno y las listas de **Servicio**, **Outlet** y **Categoría de contabilidad** tienen datos. - En Ágora, abre un ticket de prueba con un par de productos y pulsa la acción personalizada. - Busca una habitación ocupada: deben salir el nombre del huésped y sus fechas. - Pulsa **Cargar** (firma antes si está activado). Debe salir «Se generó el siguiente cargo:» con un número y cerrarse la ventana. - 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. - En Mews, abre la cuenta del huésped: debe estar el pedido con sus líneas y la nota del albarán. - En Connect Manager, en **Operaciones hoteleras → Cargos**, abre el registro: el **Id. de pedido externo** debe estar relleno. - Cancela el albarán de prueba en Ágora y comprueba en Mews que aparece el pedido en negativo. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «El número de habitación solicitado no existe.» | Esa habitación no está entre las importadas de Mews: es nueva o se teclea distinto que en Mews. | Escríbela como en Mews. Si es nueva, guarda la integración para reimportar o espera a la sincronización nocturna. | | «No se han encontrado reservas con el criterio especificado» | Mews no devuelve ningún huésped en esa habitación. | Comprueba en Mews que la reserva está alojada en esa habitación. | | «Ocurrió un error: No se pudo enviar a Mews. Por favor, devuelva el ticket N de la serie S.» | Mews contestó sin número de pedido. El albarán ya está creado en Ágora. | Devuelve el albarán en Ágora y revisa la cuenta del huésped en Mews: la anulación se envía aunque el cargo no hubiera entrado, así que puede quedar un importe en negativo que hay que quitar en Mews. | | «Ocurrió un error:» seguido de un mensaje de Mews | Mews rechazó la petición (token caducado, servicio o categoría que ya no existe…). | Revisa el Access Token y que el servicio y las categorías elegidas siguen activas en Mews. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Con el API externa desactivada, falló la creación del albarán o el envío a Mews. | Mira en Ágora si el albarán se creó: si existe, el fallo fue en Mews y el detalle está en Operaciones hoteleras → Cargos. | | Error «AgoraApiHelper getReceiptFromAgora» al cargar | Con el API externa activada, Connect Manager no llega a la API de Ágora. | Revisa URL de API, API key y que la API sea accesible desde fuera, o desactiva Usar el API externa de Ágora. | | Id. del hotel vacío y listas sin datos | Access Token incorrecto o sin permisos. | Corrige el token, guarda y usa el botón de recarga del Id. del hotel. | | La firma no sale en el albarán | Ágora no envía los albaranes a la URL de documentos. | Revisa la integración de documentos de Ágora y que esté marcado el envío de albaranes. | | La pantalla muestra «Integración pausada» | FOS ha pausado el envío de cargos de esta integración. | Contacta con soporte de FOS para reactivarla. | ## 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](https://connectmanager.es/integraciones/mews) - [Hotel Hub: cómo funcionan los cargos a habitación desde Ágora](https://connectmanager.es/docs/hotel-hub-como-funciona) - [Direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) - [Web oficial de Mews](https://www.mews.com) --- # Integración de Millenium con Ágora: cargos a habitación Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-millenium-agora Actualizado: 2026-10-03 La integración de Millenium con Ágora permite cargar a la habitación el importe de un ticket desde el propio TPV: el camarero busca la habitación, ve el titular y las fechas de la estancia y, al cargar, Connect Manager manda el cargo a Millenium y cierra el ticket en Ágora como albarán. El concepto que ve el hotel puede llevar el detalle de productos o un texto único con el TPV o el centro de venta. Este manual es para el técnico de FOS o del distribuidor que configura la integración en un local. La visión general de los PMS con Ágora está en [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona). ## Qué hace la integración - Añade a Ágora un botón (acción personalizada) que abre la ventana de cargo dentro del TPV. - Busca la habitación en Millenium y enseña el número, el titular y las fechas de entrada y salida. - Carga a la habitación el total del ticket con IVA y, si el centro de venta del ticket está asociado, con su código de concepto del PMS. - Escribe en el concepto los productos con sus unidades e importes o, con «Concepto único», el nombre del TPV (o del centro de venta) y la serie y número del albarán. - Con «Agrupar productos por familia», divide el ticket en un cargo por familia, cada uno con su código de concepto. - Al cargar, avisa si Millenium responde que la habitación está libre. - Cierra el ticket en Ágora como albarán a nombre del cliente configurado, con el titular y la habitación en el nombre fiscal. - Guarda cada cargo en Connect Manager con lo enviado y la respuesta de Millenium. ### Qué no hace - No busca por nombre del huésped ni por tarjeta: solo por número de habitación. - No anula en Millenium el cargo de un albarán anulado en Ágora: hay que anularlo a mano en el PMS. - No envía facturas, propinas ni el desglose de IVA. - No sincroniza reservas ni disponibilidad. - No comprueba crédito ni fechas: carga a la habitación que devuelva Millenium. ## Requisitos - **API de Ágora accesible desde Connect Manager.** Con Millenium, Connect Manager lee el ticket y crea el albarán llamando desde sus servidores a la URL de API del local. Sin esa conexión no se puede cargar. Abre el puerto a las [IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) o publícalo con Zero Connect. - **Ágora** con **Herramientas → Acciones personalizadas**. - **Acceso a la API de Millenium** desde Internet: URL, usuario, contraseña, id. de cadena e id. de hotel. - **Quién hace qué.** FOS da de alta el local y la integración con los datos de acceso que facilita Millenium. El distribuidor revisa la configuración de cargos, asocia centros de venta y familias y configura el botón en Ágora. El cliente valida con una prueba real. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Millenium | Millenium | https://pms.ejemplo.com:8443/ (acabada en barra) | Sí | | Usuario y contraseña | Millenium | usuario-demo | Sí | | Id. de la cadena e Id. del hotel | Millenium | 1 y 1 | Sí | | Código de concepto (id_pms) por centro de venta | Hotel o Millenium | BAR | Recomendado | | Código de concepto por familia | Hotel o Millenium | BEB | Con «Agrupar productos por familia» | | Cliente genérico de Ágora | Ágora del local | Cargos a habitación | Sí | | URL de API y API key de Ágora | Distribuidor | http://servidor-demo:8984/ | Sí | | Correos para avisos | Cliente o distribuidor | avisos@hotel-demo.com | Opcional | ## Configuración paso a paso ### 1. En Millenium - Pide a Millenium el acceso de integración: URL de la API, usuario, contraseña, id. de cadena e id. de hotel. - Pide al hotel los códigos de concepto de Millenium que quiere para cada centro de venta y, si se van a agrupar, para cada familia. ### 2. En Connect Manager: el local (lo hace FOS) - En **Administración → Locales**, abre el local y rellena **Cliente**, **Nombre**, **URL de API**, **API key**, **Dirección**, **Ciudad** y **Zona horaria**. - Pulsa el icono de prueba del campo URL de API (sale con la URL y la API key rellenas): debe salir «Conexión con éxito». Con Millenium es imprescindible. - **Guardar** → **Integraciones de hoteles** → **Añadir** → proveedor **Millenium**. ### 3. En Connect Manager: Conf. general - **Pausar el envío de cargos al PMS después de** y **Pausar el envío de cargos al PMS**: solo los ve FOS. Con la integración pausada, el botón del TPV abre el aviso «Integración pausada». - **URL Api**: la de Millenium, acabada en `/`. Connect Manager le añade `BookingEngine` justo detrás, sin barra. - **Usuario** y **Password**: los de Millenium. - **Id. de la cadena** e **Id. del hotel**: los de Millenium. - **Email de receptor de notificaciones**: escribe cada dirección y pulsa Intro. Solo reciben los errores técnicos de los cargos por familia que salen en segundo plano. ### 4. En Connect Manager: Conf. de cargos - **Agrupar productos por familia**: manda un cargo por cada familia del ticket, con el código de concepto de esa familia (pestaña Familias). Las familias sin asociar van juntas con el código del centro de venta. Desmarcado: un único cargo por ticket. - **Concepto único**: el concepto deja de listar productos y pasa a ser el nombre del TPV más la serie y número del albarán, por ejemplo «Barra - A/000123». Con esta opción el albarán se crea en Ágora antes de mandar el cargo, para poder poner su número. - **Usar centro de coste como concepto** (solo con Concepto único): usa el nombre del centro de venta en lugar del nombre del TPV. - **Cliente**: el cliente genérico de Ágora para los albaranes. Su nombre fiscal se sustituye por el del titular y la habitación, por ejemplo «Huésped Demo (Nº hab.: 101)». ### 5. En Connect Manager: asociaciones Guarda la integración para que se habiliten las pestañas. - **Centros de venta**: por cada **Centro de venta de Ágora**, en **External id.** el código de concepto de Millenium y en **Nombre externo** una descripción. Si un centro no está asociado, sus cargos van sin código de concepto. - **Familias** (solo con Agrupar productos por familia): por cada **Familia**, el **Id. del servicio** (código de concepto) y un **Nombre externo**. ### 6. En Ágora - Copia del bloque **Enlaces** la **URL botón acción personalizada**. Si empieza por `/venues/`, antepón `https://app.connectmanager.es`. - En **Herramientas → Acciones personalizadas** pulsa **Nuevo**: **Texto** «Cargo habitación», **Tipo** «Url/Aplicación», **Acción** la URL copiada (sin tocar los marcadores entre llaves) y marca **Mostrar Urls en un diálogo de Ágora**. - Coloca la acción en **Herramientas → Configuración de botones** y da su permiso a los perfiles que vayan a cargar. ## Cómo funciona El botón abre la ventana «Consulta de datos» con el ticket abierto. El camarero escribe el número de habitación; Connect Manager pregunta a Millenium y enseña el titular y las fechas. Al pulsar **Cargar**, Connect Manager lee el ticket de Ágora, manda el cargo a Millenium y, si Millenium lo acepta, crea el albarán en Ágora. La ventana responde «Se generó el siguiente cargo» con el número del cargo en Connect Manager. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant PMS as Millenium TPV->>CM: Abre la ventana con el ticket TPV->>CM: Busca la habitación CM->>PMS: Consulta la habitación PMS-->>CM: Titular y fechas CM-->>TPV: Datos de la reserva TPV->>CM: Cargar CM->>TPV: Lee el ticket por la API de Ágora CM->>PMS: Cargo con importe, concepto y código PMS-->>CM: Aceptado o código de error CM->>TPV: Crea el albarán por la API de Ágora CM-->>TPV: Se generó el siguiente cargo ``` **Qué se envía:** la cadena y el hotel, el número de habitación, el importe con IVA (descuentos ya repartidos), el código de concepto si lo hay y el texto del concepto. Con «Concepto único» el orden cambia: primero se crea el albarán y después se manda el cargo. **Cargos por familia:** el primer cargo sale en el momento y el resto, un segundo después, en segundo plano. Si uno de esos falla queda registrado con error (no se ve en el panel) y el TPV ya ha dado el cargo por hecho: revisa en Millenium que estén todos. **Si Millenium no responde o rechaza el cargo:** sin «Concepto único», el albarán no llega a crearse y el ticket sigue abierto en Ágora, así que se puede repetir. Si Millenium aceptó el cargo y lo que falló fue el albarán, al repetir no se vuelve a cargar: solo se crea el albarán. Con «Concepto único», el albarán ya existe y hay que hacer el cargo a mano o anular el albarán. ## Comprobar que funciona - La prueba de conexión del local da «Conexión con éxito». - En Ágora, abre un ticket, pulsa el botón y busca una habitación ocupada: salen número, cliente y fechas «Desde» y «Hasta». - Pulsa **Cargar**: sale «Se generó el siguiente cargo: …» y la ventana se cierra. - En Ágora, el ticket es ahora un albarán a nombre del titular con la habitación. - En Millenium, la habitación tiene el cargo con el importe, el concepto y el código esperados. - En **Operaciones hoteleras → Cargos** aparece el cargo con lo enviado y la respuesta. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «No se ha encontrado reserva para el número de habitación» | Millenium no tiene estancia en esa habitación | Compruébalo en Millenium y el número tecleado. | | «Ocurrió un error: HTTP request returned status code 401…» | Usuario o contraseña de Millenium | Corrígelos. | | «Ocurrió un error: cURL error …» o «…status code 404…» al buscar | URL Api mal escrita o sin la barra final | Pon la URL base de Millenium acabada en /. | | «Ocurrió un error: No se pudo enviar a Millenium: la habitación está libre.» | Millenium devuelve que no hay nadie alojado | Comprueba la habitación en Millenium. | | «Ocurrió un error: No se pudo enviar a Millenium.» | Millenium rechazó el cargo por otro motivo | Mira «Pedido externo (response)» en Operaciones hoteleras → Cargos. | | «Ocurrió un error: AgoraApiHelper getReceiptFromAgora…» o «No existe ningún ticket en Ágora con el identificador: …» | Connect Manager no puede leer el ticket en Ágora | Revisa la conexión con la API de Ágora y que el ticket siga abierto y tenga líneas. | | «Ocurrió un error: AgoraApiHelper sendDeliveryNoteToAgora…» | Ágora no creó el albarán | Revisa el Cliente configurado y la conexión con Ágora. | | «El parámetro room_id es obligatorio…» | Se pulsó Cargar sin buscar la habitación | Busca primero la habitación. | | «Integración pausada» | FOS ha pausado la integración | Contacta con soporte. | ## Preguntas frecuentes ### ¿Cómo conecto Millenium con Ágora? Con Connect Manager: FOS crea la integración con los datos de acceso de Millenium, se asocian los centros de venta y, en Ágora, se añade una acción personalizada con la URL de cargo. ### ¿Por qué la API de Ágora tiene que ser accesible desde fuera? Porque con Millenium es Connect Manager quien lee el ticket y crea el albarán en Ágora desde sus servidores. ### ¿Se anula el cargo en Millenium si anulo el albarán en Ágora? No. La anulación hay que hacerla también en Millenium. ### ¿Qué concepto ve el hotel en la habitación? Por defecto, la lista de productos con unidades e importes. Con «Concepto único», el nombre del TPV o del centro de venta y el número del albarán. ### ¿Qué significa «la habitación está libre»? Que Millenium no tiene a nadie alojado en esa habitación y no acepta el cargo. ## Referencias - [Ficha de la integración con Millenium](https://connectmanager.es/integraciones/millenium) - [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona) - [Integración de Sihot con Ágora](https://connectmanager.es/docs/integracion-sihot-agora): la misma configuración de acción personalizada en Ágora - [Direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) --- # Integración de Noovy con Ágora: cargos a habitación Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-noovy-agora Actualizado: 2026-10-03 La integración de **Noovy con Ágora** permite cargar un ticket del TPV a la reserva de un cliente alojado en Noovy desde una acción personalizada de Ágora: el camarero busca por habitación o por nombre, elige la reserva y Connect Manager crea el albarán en Ágora y envía el consumo a Noovy, en un solo importe o repartido por familias. Este manual es para el técnico que la configura: qué datos pedir, cómo rellenar Connect Manager y Ágora, cómo comprobarla y qué vigilar. ## Qué hace la integración - Busca los clientes alojados por **número de habitación** o por **nombre** y muestra una lista con la habitación, el cliente y el número de reserva, cada uno con su botón **Cargar**. - Crea el albarán en Ágora a nombre del cliente con su número de habitación. - Envía el consumo a la reserva en Noovy de una de estas dos formas: - Sin agrupar: un único importe con el total del ticket y el **ID producto Noovy por defecto**. - Con **Agrupar productos por familia**: un importe por cada familia de Ágora con el producto de Noovy que le hayas asignado; las familias sin asignar se suman al producto por defecto. - Pone en la descripción de cada importe el número del albarán de Ágora. - **Anula el cargo** al cancelar el albarán en Ágora, enviando los mismos importes en negativo, si la integración de documentos de Ágora apunta a la integración (ver el aviso de la configuración). - Renueva sola la sesión con Noovy cuando caduca. ### Qué no hace - **No avisa en el TPV si Noovy rechaza el cargo**: la pantalla dice «Albarán enviado correctamente» aunque el cargo no haya entrado. Hay que comprobarlo en Connect Manager (ver **Comprobar que funciona**). - No descuenta los descuentos a pie de ticket: envía la suma de las líneas, así que si el ticket lleva un descuento global, a Noovy llega el importe sin ese descuento. - No envía propinas, comensales ni el desglose de IVA. - No comprueba el crédito ni el estado de la reserva, ni recoge la firma. - No envía facturas ni hace Z-cierre. - Si no hay **ID producto Noovy por defecto** y no se agrupa por familia, no se envía nada a Noovy. - El cierre de albaranes a los N días depende de una tarea nocturna que en la versión actual del motor está desactivada. - No sincroniza reservas ni disponibilidad. ## Requisitos - **Noovy**: el **Código PMS** del hotel y los productos de Noovy donde se cargarán los consumos. Connect Manager se identifica en Noovy con unas credenciales de Ágora que ya trae configuradas: no hay que pedir usuario ni contraseña al hotel. - **Ágora**: licencia del Módulo de Servicios de Integración, una acción personalizada en el TPV y, para las anulaciones, la integración de documentos con sistemas externos enviando albaranes. - **Conectividad**: el albarán se crea 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 elige productos y opciones y configura Ágora. El hotel facilita el Código PMS y decide los productos. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Noovy | FOS | La que indique FOS | Sí | | Código PMS del hotel | El hotel o Noovy | hotel-demo | Sí | | ID del producto de Noovy por defecto | El hotel, desde Noovy | Identificador del producto «Restaurante» | Sí en la práctica | | Producto de Noovy por familia de Ágora | El hotel, de la lista que trae Noovy | Bebidas → «Bar» | Solo si se agrupa por familia | | Cliente genérico de Ágora para los albaranes | Distribuidor, en Ágora | «CLIENTES HOTEL» | Sí | | URL de API y API key de Ágora del local | Distribuidor | http://servidor:8984 | Sí (en la ficha del local) | | Email para los avisos | Cliente o distribuidor | avisos@hotel-demo.es | Recomendado | ## Configuración paso a paso ### En Noovy - Pide al hotel su **Código PMS** en Noovy. - Que el hotel decida en qué producto de Noovy se cargan los consumos y, si quiere separarlos, qué producto corresponde a cada familia. ### En Connect Manager: alta de la integración (FOS) - Entra en **Administración → Locales**, abre el local y revisa **URL de API**, **API key** y **Zona horaria**. Pulsa **Guardar**. - Pulsa **Integraciones de hoteles → Añadir** y elige el **Proveedor** **Noovy**. - Rellena **URL Api:** y **Código PMS**, y añade el **Email de receptor de notificaciones**. Las credenciales de Noovy no aparecen en el formulario: las pone Connect Manager. - Pulsa **Guardar**. ### En Connect Manager: opciones de los cargos En el bloque **Conf. de cargos**: - **Agrupar productos por familia**: desmarcada, todo el ticket va en un importe con el producto por defecto; marcada, un importe por familia según la pestaña **Productos**. - **ID producto Noovy por defecto**: el identificador del producto de Noovy. Como indica el propio campo, se usa cuando una familia no está asignada o cuando no se agrupa por familia. Rellénalo siempre. - **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 (ver el aviso). - **Cliente**: el cliente genérico de Ágora de los albaranes. El nombre del albarán se sustituye por el del cliente y su habitación. Si vas a agrupar por familia, guarda y entra en la pestaña **Productos**: por cada **Familia** de Ágora, elige su **Producto Noovy** en la lista, que se carga desde Noovy. Copia del bloque **Enlaces** la **URL botón acción personalizada**. > [!WARNING] En Noovy el panel no muestra la URL para enviar facturas desde Ágora, que es la que usa Ágora para avisar de las cancelaciones. Sin ella no se anulan cargos en Noovy. Tiene la misma forma que en el resto de PMS (`…/api/venues/ID-DEL-LOCAL/hotels/noovy/generate-invoice`): pídesela a FOS si el hotel quiere anular desde Ágora. > [!WARNING] El cierre automático de albaranes depende de una tarea programada de Connect Manager que, en la versión actual del motor, está desactivada. ### En Ágora - 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. - Si se van a anular cargos, en la integración de documentos con sistemas externos (**Activar módulos adicionales → Servicios de integración**) pega la URL de documentos que te dé FOS, habilita la integración de documentos y marca el envío de albaranes. ## Cómo funciona Al abrir la acción personalizada, la pantalla lee el ticket desde el TPV. El camarero busca por habitación o por nombre y Connect Manager consulta a Noovy los clientes de ese hotel. La pantalla lista las reservas encontradas; al pulsar **Cargar** en una, el TPV crea el albarán y Connect Manager envía el consumo a Noovy. Después la pantalla muestra «Albarán enviado correctamente» y se cierra. ```mermaid sequenceDiagram participant C as Camarero participant TPV as TPV Ágora participant CM as Connect Manager participant N as Noovy C->>TPV: Pulsa la acción personalizada TPV->>CM: Abre la pantalla y le pasa el ticket C->>CM: Busca por habitación o por nombre CM->>N: clients con el código PMS N-->>CM: Clientes, habitaciones y reservas C->>CM: Pulsa Cargar en una reserva CM->>TPV: Pide crear el albarán desde el TPV TPV-->>CM: Albarán creado CM->>N: add-extras con los importes N-->>CM: Resultado de cada importe CM-->>C: Albarán enviado correctamente ``` Cada importe enviado lleva el número de reserva, el grupo si lo hay, una unidad, el producto de Noovy, la descripción con el número del albarán y el importe en euros. Solo cuentan los productos y las cabeceras de menú; con la agrupación por familia, las líneas a cero se ignoran. Connect Manager guarda la respuesta de Noovy, pero si Noovy rechaza algún importe no lo comunica al TPV: el albarán queda creado en Ágora y el mensaje es el mismo. ### Anulaciones Si Ágora envía las cancelaciones a la URL de documentos de la integración, al cancelar el albarán Connect Manager vuelve a mandar a Noovy los mismos importes en negativo. Si Noovy los 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. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant N as Noovy TPV->>CM: Albarán de cancelación CM->>CM: Busca el cargo por serie y número CM->>N: add-extras con los importes en negativo N-->>CM: Resultado CM-->>TPV: Acepta o rechaza la cancelación ``` ## Comprobar que funciona - Si agrupas por familia, al entrar en **Productos** la lista **Producto Noovy** debe cargar los productos del hotel: eso confirma la URL y el Código PMS. - En Ágora, abre un ticket de prueba sin descuento a pie de ticket y pulsa la acción personalizada. - Busca una habitación ocupada: debe salir la reserva con su cliente y su número. - Pulsa **Cargar**: debe salir «Albarán enviado correctamente» y cerrarse la ventana. - En Connect Manager, en **Operaciones hoteleras → Cargos**, abre el registro: el **Id. de pedido externo** debe tener el número de reserva y en **Pedido externo (response)** no debe haber importes fallidos. Si el Id. está vacío, el cargo no entró en Noovy. - En Noovy, comprueba el consumo en la reserva con la descripción del albarán. - Si configuraste las anulaciones, cancela el albarán de prueba y comprueba el importe en negativo en Noovy. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «Albarán enviado correctamente» pero el consumo no está en Noovy | Noovy rechazó el importe, no hay producto por defecto o el total es cero. La pantalla no lo distingue. | Mira la respuesta en Operaciones hoteleras → Cargos, corrige el producto y haz el cargo directamente en Noovy. | | «No se han encontrado clientes con el criterio especificado» | Noovy no tiene clientes que coincidan con la búsqueda. | Prueba con la habitación o con otra parte del nombre. | | «Debe introducir un criterio de búsqueda» | Se buscó con los campos vacíos. | Rellena habitación o nombre. | | Un texto de error de Noovy, o un mensaje que empieza por «NoovyApiProxy:», al buscar | Noovy devolvió un error o no respondió (URL o Código PMS incorrectos, problema de sesión). | Revisa URL Api y Código PMS. | | El importe en Noovy es mayor que el del ticket | El ticket tenía un descuento a pie de ticket, que no se aplica. | Aplica los descuentos por línea o corrige el importe en Noovy. | | Cancelar el albarán no anula nada en Noovy | Ágora no envía las cancelaciones a la URL de documentos de la integración. | Pide la URL a FOS y configúrala en la integración de documentos de Ágora. | | Aparece en Noovy un importe negativo sin cargo previo | Se canceló el albarán de un cargo que nunca entró en Noovy. | Elimina ese importe en Noovy. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | El TPV no pudo crear el albarán o Connect Manager no pudo guardarlo. | Mira en Ágora si el albarán existe antes de repetir; si no existe, vuelve a intentarlo desde el ticket. | | La pantalla muestra «Integración pausada» | FOS ha pausado el envío de cargos. | Contacta con soporte de FOS. | ## Preguntas frecuentes ### ¿Cómo conecto Noovy con Ágora? FOS da de alta la integración con la URL de Noovy y el Código PMS del hotel. Después se elige el producto por defecto, opcionalmente los productos por familia, y se crea en Ágora la acción personalizada. ### ¿Necesito usuario y contraseña de Noovy? No. Connect Manager usa unas credenciales de Ágora que ya trae configuradas; para cada hotel basta con su Código PMS. ### ¿Se puede buscar en Noovy por el nombre del huésped? Sí. La pantalla tiene dos búsquedas: por número de habitación y por nombre del cliente. ### ¿Cómo sé si un cargo ha llegado a Noovy? En Operaciones hoteleras → Cargos de Connect Manager: si el Id. de pedido externo está relleno y la respuesta no tiene importes fallidos, el cargo entró. El mensaje del TPV no sirve para saberlo. ### ¿Se pueden repartir los consumos por familias en Noovy? Sí, marcando Agrupar productos por familia y asignando en la pestaña Productos un producto de Noovy a cada familia. ## Referencias - [Ficha de Noovy en el catálogo de integraciones](https://connectmanager.es/integraciones/noovy) - [Hotel Hub: cómo funcionan los cargos a habitación desde Ágora](https://connectmanager.es/docs/hotel-hub-como-funciona) --- # Integración de Ofi Hotel con Ágora: cargos a habitación Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-ofi-hotel-agora Actualizado: 2026-10-03 La integración de Ofi Hotel con Ágora permite cargar a la habitación el total de un ticket desde el TPV: el camarero busca al huésped alojado por número de habitación y, al cargar, el ticket se cierra en Ágora como albarán y Connect Manager añade el cargo en Ofi Hotel con el código de cargo configurado. Si la reserva no admite cargos desde el TPV, la ventana lo avisa y no deja seguir. Este manual es para el técnico de FOS o del distribuidor que configura la integración en un local. La visión general de los PMS con Ágora está en [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona). ## Qué hace la integración - Añade a Ágora un botón (acción personalizada) que abre la ventana de cargo dentro del TPV. - Busca en Ofi Hotel al huésped alojado en la habitación y enseña nombre, teléfono, régimen y tipo de tarjeta de fidelización. - Avisa con «La reserva no admite cargos» cuando Ofi Hotel marca la reserva sin crédito en TPV. - Cierra el ticket en Ágora como albarán a nombre del cliente configurado, con la habitación en el nombre fiscal. - Añade en Ofi Hotel un cargo por el total del ticket con IVA, con el código de cargo configurado y la descripción «Bar/Rest/Room Service – » seguida de la serie y número del albarán. ### Qué no hace - No envía el detalle de productos, el IVA ni la propina: solo el total. - No anula en Ofi Hotel el cargo de un albarán anulado en Ágora: hay que anularlo a mano en el PMS. - No envía facturas ni el cierre del día, ni sincroniza reservas o disponibilidad. - No busca por nombre ni por tarjeta: solo por número de habitación. - No lee la respuesta de Ofi Hotel al cargo más allá del código HTTP. ## Requisitos - **Ágora** con **Herramientas → Acciones personalizadas**. La ventana lee el ticket y crea el albarán por la API local del TPV. - **API de Ágora accesible desde Connect Manager** solo para configurar (el selector de Cliente). Abre el puerto a las [IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) o usa Zero Connect. - **Suscripción a la API de integración de reservas de Ofi Hotel**: URL, id. de suscripción, clave (Api Key), código del hotel y código del cargo. - **Quién hace qué.** FOS da de alta el local y la integración con los datos que facilita Ofi Hotel. El distribuidor elige el cliente y configura el botón en Ágora. El cliente valida con una prueba real. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Ofi Hotel, acabada en barra | Ofi Hotel | https://hotel-demo.ejemplo.com/ | Sí | | Id. de la suscripción | Ofi Hotel | 1234 | Sí | | Api Key (clave en base64) | Ofi Hotel | Cadena larga acabada en = | Sí | | Id. del hotel (código del hotel) | Ofi Hotel | 999 | Sí | | Código del cargo | Ofi Hotel o el hotel | REST | Sí | | Cliente genérico de Ágora | Ágora del local | Cargos a habitación | Sí | | URL de API y API key de Ágora | Distribuidor | http://servidor-demo:8984/ | Sí | ## Configuración paso a paso ### 1. En Ofi Hotel - Pide a Ofi Hotel la suscripción a su API de integración de reservas: URL, id. de suscripción, clave y código del hotel. - Pide al hotel el código de cargo con el que quiere ver los consumos del restaurante, y que las reservas que se vayan a cargar admitan cargos desde el TPV. ### 2. En Connect Manager: el local (lo hace FOS) - En **Administración → Locales**, abre el local y rellena **Cliente**, **Nombre**, **URL de API**, **API key**, **Dirección**, **Ciudad** y **Zona horaria**. Pulsa el icono de prueba del campo URL de API (sale con la URL y la API key rellenas): «Conexión con éxito». - **Guardar** → **Integraciones de hoteles** → **Añadir** → proveedor **Ofi Hotel**. ### 3. En Connect Manager: Conf. general - **Pausar el envío de cargos al PMS después de** y **Pausar el envío de cargos al PMS**: solo los ve FOS. Con la integración pausada, el botón del TPV abre el aviso «Integración pausada». - **URL Api**: la de Ofi Hotel, acabada en `/`. Es obligatoria y la barra final importa: Connect Manager firma cada petición con la URL tal cual está escrita y, sin la barra, la firma no coincide. - **Api Key**: la clave de la suscripción, tal cual la entrega Ofi Hotel. - **Id. del hotel**: el código del hotel en Ofi Hotel. - **Email de receptor de notificaciones**: esta integración no envía avisos en segundo plano, pero puedes dejar el correo del cliente. ### 4. En Connect Manager: Conf. de cargos - **Id. de la suscripción**: el identificador de la suscripción. Se usa para firmar las peticiones y va también en su cabecera. - **Código del cargo**: el código con el que Ofi Hotel registra el cargo. - **Cliente**: el cliente genérico de Ágora para los albaranes. Al nombre fiscal se le añade la habitación, por ejemplo «Cargos a habitación (Nº hab.: 101)». ### 5. En Ágora - Copia del bloque **Enlaces** la **URL botón acción personalizada**. Si empieza por `/venues/`, antepón `https://app.connectmanager.es`. - En **Herramientas → Acciones personalizadas** pulsa **Nuevo**: **Texto** «Cargo habitación», **Tipo** «Url/Aplicación», **Acción** la URL copiada (sin tocar los marcadores entre llaves) y marca **Mostrar Urls en un diálogo de Ágora**. - Coloca la acción en **Herramientas → Configuración de botones** y da su permiso a los perfiles que vayan a cargar. ## Cómo funciona El botón abre la ventana con el ticket; la ventana lo lee por la API local de Ágora y lo guarda en Connect Manager. Al buscar la habitación, Connect Manager pide a Ofi Hotel el cliente alojado, firmando la petición con la clave de la suscripción. Si la reserva admite cargos, al pulsar **Cargar** la ventana crea el albarán en Ágora, lo guarda y pide el cargo; Connect Manager lo añade en Ofi Hotel y la ventana dice «Se generó el siguiente cargo» antes de cerrarse. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant PMS as Ofi Hotel TPV->>TPV: Lee el ticket por la API local TPV->>CM: Guarda el ticket TPV->>CM: Busca la habitación CM->>PMS: Cliente alojado en la habitación PMS-->>CM: Nombre, teléfono, régimen y si admite cargos CM-->>TPV: Datos de la reserva TPV->>TPV: Crea el albarán por la API local TPV->>CM: Guarda el albarán y pide el cargo CM->>PMS: Agrega cargo a la habitación PMS-->>CM: Respuesta CM-->>TPV: Se generó el siguiente cargo ``` **Qué se envía:** el código del hotel, el número de habitación, el código del cargo, cantidad 1, el total con IVA y la descripción «Bar/Rest/Room Service – A/000123». El número que enseña la ventana al terminar es el del ticket de Ágora. **Si Ofi Hotel no responde:** el albarán ya está creado en Ágora, la ventana dice «No se ha podido generar el albarán…» y el cargo no se repite solo. Revisa el caso en **Operaciones hoteleras → Cargos**. ## Comprobar que funciona - En Ágora, abre un ticket, pulsa el botón y busca una habitación ocupada: salen cliente, teléfono, régimen y fidelización. - Pulsa **Cargar**: sale «Se generó el siguiente cargo: …» y se imprime el albarán con la habitación. - En Ofi Hotel, la habitación tiene el cargo con el código y la descripción con el número del albarán. - En **Operaciones hoteleras → Cargos** aparece el cargo con lo enviado y la respuesta de Ofi Hotel. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «Ocurrió un error: HTTP request returned status code 401…» al buscar | Api Key o Id. de la suscripción incorrectos, o URL sin la barra final | Revisa los datos con Ofi Hotel y termina la URL en /. | | «Ocurrió un error: cURL error …» | URL vacía o inalcanzable | Corrige la URL; no hay ninguna por defecto. | | «No se han encontrado reservas con el criterio especificado» | No hay huésped alojado en esa habitación para ese código de hotel | Comprueba la habitación y el Id. del hotel. | | «La reserva no admite cargos» | Ofi Hotel tiene la reserva sin crédito en TPV | Que el hotel lo cambie en Ofi Hotel. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Ágora no creó el albarán, o Ofi Hotel rechazó el cargo después de crearlo | Mira si el albarán existe en Ágora y el cargo en Operaciones hoteleras → Cargos. | | La ventana se queda cargando y sale «Request timed out» | La acción no se abre dentro de Ágora | Marca «Mostrar Urls en un diálogo de Ágora». | | «Integración pausada» | FOS ha pausado la integración | Contacta con soporte. | ## Preguntas frecuentes ### ¿Cómo conecto Ofi Hotel con Ágora? Con Connect Manager: FOS crea la integración con los datos de la suscripción de Ofi Hotel, se elige el cliente y, en Ágora, se añade una acción personalizada con la URL de cargo. ### ¿Qué ve el hotel en la habitación? Un cargo por el total del ticket con el código configurado y la descripción con la serie y número del albarán. ### ¿Por qué sale «La reserva no admite cargos»? Porque Ofi Hotel indica que esa reserva no tiene crédito en TPV. Se cambia en Ofi Hotel. ### ¿Se anula el cargo en Ofi Hotel si anulo el albarán en Ágora? No. La anulación hay que hacerla también en Ofi Hotel. ## Referencias - [Ficha de la integración con Ofi Hotel](https://connectmanager.es/integraciones/ofi-hotel) - [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona) - [Integración de Sihot con Ágora](https://connectmanager.es/docs/integracion-sihot-agora): la misma configuración de acción personalizada en Ágora - [Direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) --- # Integración de Prestige con Ágora: cargos a habitación Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-prestige-agora Actualizado: 2026-10-03 La integración de Prestige con Ágora permite cargar a la habitación el importe de un ticket desde el TPV: el camarero busca la habitación, ve el huésped, las fechas, el régimen y el localizador y, al cargar, el ticket se cierra en Ágora como albarán y Connect Manager manda el cargo a Prestige, por su importe sin IVA o repartido por servicios. Este manual es para el técnico de FOS o del distribuidor que configura la integración en un local. La visión general de los PMS con Ágora está en [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona). ## Qué hace la integración - Añade a Ágora un botón (acción personalizada) que abre la ventana de cargo dentro del TPV. - Busca la habitación en Prestige y enseña huésped, entrada, salida, régimen y localizador. - Cierra el ticket en Ágora como albarán a nombre del cliente configurado, con el huésped y la habitación en el nombre fiscal. - Carga a la habitación un único cargo con la base imponible del ticket (sin IVA) en el servicio por defecto, con la serie y número del albarán en las observaciones. - Con «Enviar cargos en diferido», reparte el ticket en un cargo por servicio de Prestige según la familia y el TPV, y lo envía en segundo plano. - Guarda cada cargo en Connect Manager con lo enviado y la respuesta de Prestige, que incluye el motivo cuando lo rechaza (habitación libre, servicio inexistente, segmento de crédito…). ### Qué no hace - No anula en Prestige el cargo de un albarán anulado en Ágora: hay que anularlo a mano en el PMS. - No envía propinas, comensales ni el desglose de IVA, ni facturas. - No sincroniza reservas ni disponibilidad. - No deja cargar tickets con descuento en importe, ni con descuento por línea y a pie de ticket a la vez. - No enseña en el TPV el motivo del rechazo de Prestige: la ventana da un aviso genérico y el detalle queda en Connect Manager. - El cierre diario (Z-cierre) está en el panel, pero la tarea que lo envía no está activada en la versión actual del motor. ## Requisitos - **Ágora** con **Herramientas → Acciones personalizadas**. La ventana lee el ticket y crea el albarán por la API local del TPV. - **API de Ágora accesible desde Connect Manager** solo para configurar: los selectores de Cliente, Familia y TPV del panel la usan. Abre el puerto a las [IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) o usa Zero Connect. - **Servicio web de Prestige** accesible desde Internet. Connect Manager no le manda usuario ni contraseña: si Prestige restringe el acceso por IP, dale las IP de Connect Manager. - **Quién hace qué.** FOS da de alta el local y la integración con la URL que facilita Prestige. El distribuidor revisa la configuración de cargos, asocia familias si hace falta y configura el botón en Ágora. El cliente valida con una prueba real. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL del servicio web de Prestige (sin service.asmx) | Prestige | https://prestige.ejemplo.com/ws/ | Sí | | Servicio de Prestige para los cargos | Desplegable del panel (lista de servicios de Prestige) | Restaurante | Sí | | Servicio por familia y TPV | Hotel | Bebidas en la barra → Bar | Con «Enviar cargos en diferido» | | Cliente genérico de Ágora | Ágora del local | Cargos a habitación | Sí | | Usuario, Password e Id. del hotel | Prestige | usuario-demo, 1 | No: el formulario los pide, pero no se envían | | Factura, Id moneda, Id origen e Id method | Prestige | Códigos numéricos | Solo para el Z-cierre | | URL de API y API key de Ágora | Distribuidor | http://servidor-demo:8984/ | Sí | | Correos para avisos | Cliente o distribuidor | avisos@hotel-demo.com | Con «Enviar cargos en diferido» | ## Configuración paso a paso ### 1. En Prestige - Pide a Prestige la URL de su servicio web para integraciones y, si filtra por IP, que autorice las de Connect Manager. - Confirma con el hotel qué servicios de Prestige se usarán para los cargos. ### 2. En Connect Manager: el local (lo hace FOS) - En **Administración → Locales**, abre el local y rellena **Cliente**, **Nombre**, **URL de API**, **API key**, **Dirección**, **Ciudad** y **Zona horaria**. Pulsa el icono de prueba del campo URL de API (sale con la URL y la API key rellenas): «Conexión con éxito». - **Guardar** → **Integraciones de hoteles** → **Añadir** → proveedor **Prestige**. ### 3. En Connect Manager: Conf. general - **Pausar el envío de cargos al PMS después de** y **Pausar el envío de cargos al PMS**: solo los ve FOS. Con la integración pausada, el botón del TPV abre el aviso «Integración pausada». - **URL Api**: la base del servicio web. Connect Manager añade `service.asmx` detrás. - **Usuario**, **Password** e **Id. del hotel**: rellénalos con lo que dé Prestige, aunque la versión actual no los envía. - **Email de receptor de notificaciones**: escribe cada dirección y pulsa Intro. Ahí llegan los fallos de los cargos en diferido. - Pulsa **Guardar**: la integración se abre en modo edición y aparece el desplegable **Servicio**, que antes de guardar no sale. ### 4. En Connect Manager: Conf. de cargos - **Servicio**: el servicio de Prestige por defecto. Sin «Enviar cargos en diferido», todo el ticket va a este servicio. - **Enviar cargos en diferido**: el ticket se reparte en un cargo por servicio (pestaña Familias) con la base imponible de sus líneas, y los cargos salen en segundo plano. El TPV da el cargo por hecho al momento, sin esperar a Prestige; si Prestige rechaza alguno, llega un correo y queda marcado con error. Desmarcado: un único cargo que se manda en el momento. - **Dejar abierto el albarán**: el albarán se crea en Ágora permitiendo facturarlo después. - **Nº de días para cerrar albaranes** (7 por defecto): lo usa una tarea nocturna, hoy inactiva, que anula en Ágora los albaranes abiertos pasados esos días. No toca Prestige. - **Cliente**: el cliente genérico de Ágora para los albaranes. Su nombre fiscal se sustituye por el del huésped y la habitación. ### 5. En Connect Manager: Familias (con envío en diferido) La pestaña **Familias** solo aparece con «Enviar cargos en diferido» marcado. Por cada **Familia** elige el **Servicio** de Prestige y, si el servicio cambia según dónde se venda, añade la misma familia otra vez con un **TPV** concreto: se usa la asociación del TPV del albarán y, si no la hay, la general. Las familias sin asociar van al servicio por defecto. ### 6. En Connect Manager: Conf. de Z-cierre Con **Z-cierre** marcado aparecen **Factura**, **Id moneda**, **Id origen**, **Id method** y **Hora de generación fich. contable**. Sirven para mandar una vez al día a Prestige un cargo resumen con el total sin IVA de las facturas del día, en el servicio por defecto, con esos códigos. > [!WARNING] La tarea nocturna que envía el Z-cierre no está activada en la versión actual del motor. No configures este bloque contando con él sin confirmarlo antes con FOS. ### 7. En Ágora - Copia del bloque **Enlaces** la **URL botón acción personalizada**. Si empieza por `/venues/`, antepón `https://app.connectmanager.es`. - En **Herramientas → Acciones personalizadas** pulsa **Nuevo**: **Texto** «Cargo habitación», **Tipo** «Url/Aplicación», **Acción** la URL copiada (sin tocar los marcadores entre llaves) y marca **Mostrar Urls en un diálogo de Ágora**. - Coloca la acción en **Herramientas → Configuración de botones** y da su permiso a los perfiles que vayan a cargar. ## Cómo funciona El botón abre la ventana con el ticket; la ventana lo lee por la API local de Ágora y lo guarda en Connect Manager. El camarero busca la habitación y Connect Manager consulta a Prestige el huésped alojado. Al pulsar **Cargar**, la ventana crea el albarán en Ágora, lo guarda y pide el cargo. Sin envío en diferido, Connect Manager manda el cargo a Prestige y espera su respuesta; con envío en diferido, deja los cargos en cola y responde al momento. En los dos casos la ventana dice «Se generó el siguiente cargo» y se cierra. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant PMS as Prestige TPV->>TPV: Lee el ticket por la API local TPV->>CM: Guarda el ticket TPV->>CM: Busca la habitación CM->>PMS: Consulta el huésped alojado PMS-->>CM: Nombre, fechas, régimen y localizador CM-->>TPV: Datos de la reserva TPV->>TPV: Crea el albarán por la API local TPV->>CM: Guarda el albarán y pide el cargo alt Envío inmediato CM->>PMS: Cargo con la base imponible PMS-->>CM: Correcto o código de error else Enviar cargos en diferido CM->>CM: Un cargo por servicio en cola CM->>PMS: Envío en segundo plano end CM-->>TPV: Se generó el siguiente cargo ``` **Qué se envía:** el número de habitación, el servicio, cantidad 1, el importe sin IVA (con los descuentos repartidos) y la observación «Albarán: » seguida de la serie y el número. **Si Prestige rechaza el cargo:** el albarán ya está creado en Ágora. Sin envío en diferido, la ventana dice «No se ha podido generar el albarán…» y el motivo de Prestige queda en **Operaciones hoteleras → Cargos**, en «Pedido externo (response)». Con envío en diferido, el error llega por correo («Enviar cargo diferido de Prestige (Error)») y se ve en la pestaña **Cargos en diferido** del cargo, con estado «Sin enviar», «Enviado» o «Error». En ambos casos el cargo no se repite solo. ## Comprobar que funciona - Tras guardar, el desplegable Servicio muestra los servicios de Prestige. - En Ágora, abre un ticket, pulsa el botón y busca una habitación ocupada: salen cliente, entrada, salida, régimen y localizador. - Pulsa **Cargar**: sale «Se generó el siguiente cargo: …» y se imprime el albarán con el huésped y la habitación. - En Prestige, la habitación tiene el cargo por la base imponible con la observación del albarán. - En **Operaciones hoteleras → Cargos** aparece el cargo; con envío en diferido, su pestaña Cargos en diferido debe pasar a «Enviado». ## Errores frecuentes y solución | Síntoma | Causa | Solución | | El desplegable Servicio sale vacío o da error | URL mal puesta o Prestige no acepta conexiones de Connect Manager | Revisa la URL base y que Prestige autorice las IP de Connect Manager. | | «No se ha podido encontrar reserva para esa habitación» u otro texto de Prestige al buscar | No hay huésped alojado o Prestige devuelve un error | Compruébalo en Prestige. | | «Ocurrió un error: cURL error …» | URL inalcanzable o mal escrita | Corrige la URL; no incluyas service.asmx. | | «No se pueden efectuar cargos con descuentos en efectivo…» o «…con descuentos por línea y a pie de ticket…» | Descuento en importe, o en línea y total a la vez | Deja un único descuento en porcentaje. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Ágora no creó el albarán, falta el Servicio por defecto, o Prestige rechazó el cargo después (2001 habitación no ocupada, 2002 servicio inexistente, 3001 segmento de crédito…) | Mira si el albarán existe en Ágora y la respuesta de Prestige en Operaciones hoteleras → Cargos. | | Correo «Enviar cargo diferido de Prestige (Error)» | Prestige rechazó un cargo enviado en segundo plano | Revisa el motivo en Cargos en diferido y haz el cargo a mano en Prestige. | | La ventana se queda cargando y sale «Request timed out» | La acción no se abre dentro de Ágora | Marca «Mostrar Urls en un diálogo de Ágora». | | «Integración pausada» | FOS ha pausado la integración | Contacta con soporte. | ## Preguntas frecuentes ### ¿Cómo conecto Prestige con Ágora? Con Connect Manager: FOS crea la integración con la URL del servicio web de Prestige, se elige el servicio y, en Ágora, se añade una acción personalizada con la URL de cargo. ### ¿Prestige recibe el importe con IVA o sin IVA? Sin IVA: Connect Manager manda la base imponible del ticket, o de cada servicio con el envío en diferido. ### ¿Se anula el cargo en Prestige si anulo el albarán en Ágora? No. La anulación hay que hacerla también en Prestige. ### ¿Para qué sirve «Enviar cargos en diferido»? Para repartir el ticket entre varios servicios de Prestige por familia y TPV, y para que el TPV no espere la respuesta de Prestige. ### ¿Se manda el cierre de caja a Prestige? El panel tiene el bloque Z-cierre, pero la tarea que lo envía no está activada en la versión actual: confírmalo con FOS. ## Referencias - [Ficha de la integración con Prestige](https://connectmanager.es/integraciones/prestige) - [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona) - [Integración de Sihot con Ágora](https://connectmanager.es/docs/integracion-sihot-agora): la misma configuración de acción personalizada en Ágora - [Direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) --- # Integración de Protel con Ágora: cargos a habitación y facturas Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-protel-agora Actualizado: 2026-10-03 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](https://connectmanager.es/docs/direcciones-ip-connectmanager). - **Á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 | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL del interfaz de Protel | Protel o la informática del hotel | http://protel.hotel-demo.es:5000/ (con la barra final) | Sí | | Id. del hotel en Protel | Protel | 1 | Sí | | Correspondencias en Protel de los Id. de Ágora (TPV, usuarios, familias, IVA, productos y formas de pago) | Protel, con el listado que le pase el distribuidor | TPV 1 de Ágora = punto de venta 1 en Protel | Sí | | Forma de pago de Ágora para el cargo a habitación | Distribuidor, en Ágora | «Cargo habitación» | Solo en el modo con forma de pago | | Cliente genérico de Ágora para los albaranes | Distribuidor, en Ágora | «CLIENTES HOTEL» | Solo en el modo con albaranes | | Segunda búsqueda: tarjeta o apellidos | El hotel | Número de tarjeta | No | | ¿Se puede cargar a reservas bloqueadas? | El hotel | Sí / No | No | | URL de API y API key de Ágora del local | Distribuidor | http://servidor:8984 | Sí (en la ficha del local) | | Email para los avisos | Cliente o distribuidor | avisos@hotel-demo.es | Recomendado | ## 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 - 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. - 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) - Entra en **Administración → Locales**, abre el local y revisa **URL de API**, **API key** y **Zona horaria**. Pulsa **Guardar**. - Pulsa **Integraciones de hoteles → Añadir** y elige el **Proveedor** **Protel**. - 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. - 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 - 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. - 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. - 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. ```mermaid 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. ```mermaid 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 - 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. - **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. - **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. - Cobra otro ticket con tarjeta o efectivo y comprueba que también llega a Protel y que en **Operaciones hoteleras → Facturas** sale como «Aceptado». - 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 | Síntoma | Causa | Solución | | «La reserva está bloqueada y, por tanto, no admite cargos.» | Protel marca la reserva como bloqueada. | Desbloquéala en Protel o activa Permitir cargos bloqueados si el hotel lo acepta. | | Al buscar sale un texto de error de Protel | Protel no encuentra la reserva o rechaza la petición. | Revisa el número tecleado y el Id. del hotel. | | «Configure una URL de la API de Protel válida» | La URL no tiene el formato http://servidor:puerto/. | Corrige la URL, con la barra final. | | «Ocurrió un error: fsockopen(): Unable to connect…» al cargar o al facturar | Connect Manager no consigue abrir la conexión con el servidor y el puerto de la URL. | Revisa que el interfaz de Protel esté en marcha y que el puerto esté abierto a las IP de Connect Manager. | | Los cargos o las facturas tardan y fallan, pero la búsqueda funciona | La URL es https o el puerto no responde a conexiones directas. | Usa la URL http del interfaz y revisa el firewall. | | «Debe seleccionar un número de habitación para poder pagar por Cargo habitación» | Se cobró con Cargo habitación sin elegir reserva en la acción personalizada. | Abre la acción, busca la reserva, pulsa Cargar y vuelve a cobrar. | | «No está configurado un método de pago para Cargo habitación» | Falta el Método de pago de Agora en la integración. | Elígelo y guarda. | | «No tiene un número de reserva asociada.» | Modo con albaranes sin reserva elegida. | Busca la reserva antes de pulsar Cargar. | | «No se encontró una venta asociada a la devolución» | Devolución con Cargo habitación de una factura que no pasó por la integración. | Haz la devolución con otra forma de pago o revisa la factura original. | | «Ocurrió un error no especificado» | Protel contestó con error sin texto. | Revisa la respuesta en Cargos o Facturas y consulta con Protel. | | «Hay que habilitar la opción Habilitar envío de albaranes para poder usar este método» | Se intenta cargar o anular un albarán con Utilizar albaranes desmarcado. | Marca Utilizar albaranes o trabaja con la forma de pago. | | Las facturas no llegan a Protel | Enviar facturas diferidas marcado, o Ágora no envía las facturas a la URL. | Desmarca la casilla y revisa la integración de documentos de Ágora. | | La pantalla muestra «Integración pausada» | FOS ha pausado el envío de cargos. | Contacta con soporte de FOS. | ## 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](https://connectmanager.es/integraciones/protel) - [Hotel Hub: cómo funcionan los cargos a habitación desde Ágora](https://connectmanager.es/docs/hotel-hub-como-funciona) - [Direcciones IP salientes de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) --- # Integración de Redforts con Ágora: cargos a habitación Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-redforts-agora Actualizado: 2026-10-03 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](https://connectmanager.es/docs/zero-connect-instalacion). - **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 | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Ágora (o del ACMS central) | Distribuidor, de la instalación de Ágora | https://hotel-demo.ejemplo.es:8984 | Sí | | API key de Ágora | Distribuidor, desde Ágora | Cadena alfanumérica | Sí | | URL Api de Redforts | Redforts | https://redforts.ejemplo.es/ (solo la base, sin posapi) | Sí, no tiene valor por defecto | | Código de conexión | Redforts (código de la API de TPV del hotel) | Cadena que entrega Redforts | Sí | | Cliente de Ágora para los albaranes | Distribuidor u hotel (cliente genérico creado en Ágora) | HUÉSPEDES HOTEL | Sí, en la práctica | | Correo de notificaciones | Hotel o distribuidor | avisos@hotel-demo.es | No (ningún proceso de Redforts lo usa) | ## Configuración paso a paso ### En Redforts - Pide a Redforts (o al hotel) la URL de la API y el **código de conexión** para el TPV. - 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. - 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 - Entra en `https://app.connectmanager.es` y ve a **Administración → Locales**. Abre el local. - Revisa **URL de API** y **API key** y pulsa el botón de prueba junto a la URL: debe salir Conexión con éxito. - Pulsa **Guardar**. ### En Connect Manager: la integración de hoteles - 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. - 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. - En **Conf. de cargos**, elige el **Cliente** de Ágora para los albaranes. Es la única opción de cargo de Redforts. - Pulsa **Guardar**: sale Se ha guardado la integración de hoteles. Redforts no tiene pestañas de familias ni de formas de pago. - 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 - Si no existe, crea el cliente genérico para los albaranes y comprueba que es el elegido en Cliente. - 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}`… - 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. - 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. ```mermaid 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 - 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. - Abre en Ágora un ticket de prueba con dos productos de familias distintas y pulsa la acción. - Busca una habitación con check-in hecho: aparece su tarjeta con cliente, tarifa y fechas. Prueba también a buscar por apellido. - Pulsa Cargar sin propina: debe salir «Se generó el siguiente cargo: 10000» y cerrarse el diálogo. - En Ágora queda el albarán impreso a nombre del cliente genérico con «(Nº hab.: …)». - En Redforts, la reserva tiene dos líneas con sus familias, productos, impuestos y precios. - En Connect Manager, **Operaciones hoteleras → Cargos** muestra la operación con Pedido externo (request) y Pedido externo (response). - Anula el albarán de prueba en Ágora y quita el cargo en Redforts. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Al guardar: «Ocurrió un error: The auth data field is required.» | El campo Código de conexión está vacío. | Rellena el código que entregó Redforts. | | El buscador de Cliente no devuelve nada | Connect Manager no llega a la API de Ágora. | Revisa URL de API, API key, la prueba de conexión, el puerto 8984 o Zero Connect. | | El TPV muestra «Integración pausada» | FOS ha pausado el envío de cargos. | Contacta con soporte de FOS. | | «No se ha encontrado el ticket: … Cierre esta ventana e intente generar el ticket de nuevo.» o «Request timed out» | La acción no se abre en un diálogo de Ágora o el ticket no existe. | Marca Mostrar Urls en un diálogo de Ágora y lánzala desde un ticket abierto con productos. | | «Han ocurrido los siguientes errores: …» al buscar | Redforts rechazó la consulta (código de conexión o parámetros). | Lee los errores de la lista y revisa el código con Redforts. | | «No se han encontrado reservas con el criterio especificado» | Redforts no tiene reservas con esa habitación o ese nombre. | Revisa cómo se escribe la habitación o el apellido en Redforts. | | Se busca y no aparece ninguna tarjeta | Hay reservas, pero ninguna tiene el check-in hecho. | Haz el check-in en Redforts y vuelve a buscar. | | «Ocurrió un error: HTTP request returned status code …» o «Ocurrió un error: cURL error…» | URL Api incorrecta, código no válido o Redforts no responde. | Revisa la URL (solo la base) y el código de conexión. | | «La propina tiene que ser un número (entero o con coma).» | La propina se escribió con punto o con letras. | No uses la propina con Redforts (ver «Qué no hace»); si la usas, con coma decimal. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Falló el albarán en el TPV o Redforts rechazó el cargo después de crearlo. | Mira en Ágora si el albarán existe y consulta en Redforts si llegó el cargo antes de repetir. | | La propina llega con otro importe a Redforts | Se envía con la cantidad de la última línea del ticket. | Corrígela a mano en Redforts y no uses el campo Propina. | ## 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](https://connectmanager.es/integraciones/redforts) - Visión general de los cargos a habitación: [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona) - Otros PMS: [Guest Pro](https://connectmanager.es/docs/integracion-guestpro-agora), [Hospedium](https://connectmanager.es/docs/integracion-hospedium-agora), [UbikOS](https://connectmanager.es/docs/integracion-ubikos-agora) y [Sihot](https://connectmanager.es/docs/integracion-sihot-agora) - [Direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) - [Zero Connect: conectar Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion) --- # Integración de RoomRaccoon con Ágora Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-roomraccoon-agora Actualizado: 2026-10-03 Manual de uso: Cargo RoomRaccoon desde el POS Objetivo Este manual explica, paso a paso, cómo cargar consumiciones del POS a una habitación de RoomRaccoon. **1. Creación del ticket en el POS** - Desde el **POS**, selecciona los productos (bebidas/comidas) que el cliente consuma. - Verifica que los artículos aparecen correctamente en el **listado del ticket** (cantidades, precios y total). - Confirma el **total del ticket** antes de continuar. **2. Acceso a la opción “Otros”** - En la barra inferior del POS, pulsa **Otros**. - Se abrirá el menú de acciones avanzadas. **3. Cargo a RoomRaccoon** - Dentro del menú **Otros**, selecciona **Cargo Roomraccoon**. - Se abrirá la pantalla de búsqueda de habitación. **4. Selección de la habitación** - Introduce el **número de habitación** (por ejemplo, 14) usando el teclado numérico. - Pulsa **Enter**. - Verifica que el sistema muestra: - Número de habitación - Cliente asociado - Pulsa **Cargar** para enviar el cargo. - Tras cargar el importe, el sistema genera un **albará.** **6. Verificación en RoomRaccoon – Reserva** - Accede a **RoomRaccoon**. - Entra en **Reservations > Calendar**. - Localiza la **habitación** y la **reserva** correspondiente. - Abre la reserva. - En la sección **Add-ons**, verifica que aparecen los cargos del POS: - Producto - Fecha - Importe Referencia visual: reserva con add-ons cargados desde el POS. **7. Verificación en Reportes – POS Revenue** - En RoomRaccoon, ve a **Reports**. - Selecciona la pestaña **Revenue**. - Ajusta el rango de fechas. - Accede a **POS Revenue**. - Verifica que el importe del cargo aparece reflejado en la fecha correcta. Nota: Aquí se muestran todos los cargos realizados en una habitación incluso si existe una devolución del albaran **8. Verificación en Reportes – External Revenue** - Dentro de **Reports > Revenue**, selecciona **External Revenue**. - Revisa el mismo rango de fechas. - Confirma que el total incluye los cargos realizados desde el POS. Nota: Aquí se muestran todos los cargos y devoluciones que no tienen una asociación de habitación y que son totalmente externos (La consulta y el total de este saldo se carga 1 vez por día cuando se cierra la Jornada de Trabajo) --- # Integración de Shiji con Ágora: cargos a habitación Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-shiji-agora Actualizado: 2026-10-03 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 | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de los servicios de Shiji | Shiji | https://shiji.hotel-demo.es/htng/ | Sí | | Usuario y contraseña | Shiji | usuario-demo | Sí | | Id. de la cadena (ChainCode) | Shiji | DEMO | Sí | | Id. del hotel (HotelCode) | Shiji | 12345 | Sí | | Id. del turno por defecto y turnos con su franja horaria | Shiji (códigos de turno) | Comida 1, de 13:00 a 16:30 | Recomendado | | Cuenta de ingresos para las facturas | Shiji | POS | Sí, si se envían facturas | | Código de Shiji de cada forma de pago de Ágora | Shiji | Efectivo → CASH | Sí, si se envían facturas | | Centros de ingresos de Shiji con el Id. del centro de venta de Ágora | Shiji, con el listado del distribuidor | Centro de venta 2 de Ágora = centro 2 | Sí | | Códigos de ingreso de Shiji con el Id. de familia (o de formato) de Ágora | Shiji, con el listado del distribuidor | Familia 7 de Ágora = código 7 | Sí | | Cliente genérico de Ágora para los albaranes | Distribuidor, en Ágora | «CLIENTES HOTEL» | Sí | | URL de API y API key de Ágora del local | Distribuidor | http://servidor:8984 | Sí (en la ficha del local) | | Email para los avisos | Cliente o distribuidor | avisos@hotel-demo.es | Recomendado | ## Configuración paso a paso ### En Shiji - Pide a Shiji la URL de sus servicios, el usuario, la contraseña, el código de cadena y el código de hotel. - 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) - Entra en **Administración → Locales**, abre el local y revisa **URL de API**, **API key** y **Zona horaria**. Pulsa **Guardar**. - Pulsa **Integraciones de hoteles → Añadir** y elige el **Proveedor** **Shiji**. - Rellena **URL Api:**, **Usuario**, **Password**, **Id. de la cadena** e **Id. del hotel**, y añade el **Email de receptor de notificaciones**. - 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: - **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. - **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 - 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. - 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. ```mermaid 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. ```mermaid 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 - En Ágora, abre un ticket de prueba en un centro de venta ya codificado en Shiji y pulsa la acción personalizada. - Busca una habitación ocupada: deben salir el huésped, el estado y sus fechas. - Pulsa **Cargar**: debe salir «Se generó el siguiente cargo:» con un identificador y cerrarse la ventana. - 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. - En Connect Manager, en **Operaciones hoteleras → Cargos**, el **Id. de pedido externo** debe estar relleno. - Cobra otro ticket con tarjeta y emite la factura: debe cerrarse sin error en Ágora y aparecer en Shiji contra la cuenta de ingresos. - Cancela el albarán de prueba y comprueba el cargo en negativo en Shiji. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «No se ha encontrado reserva para el número de habitación: - No record» | Shiji no tiene ninguna reserva alojada en esa habitación. | Comprueba la habitación y el estado de la reserva en Shiji. | | «La reserva no admite cargos» | Shiji marca la reserva como sin cargos permitidos. | Que recepción lo revise en Shiji. | | «Ocurrió un error:» seguido de un texto de Shiji al cargar | Shiji rechazó el cargo (código de ingreso, centro o turno inexistente, credenciales…). | Revisa que los Id. de Ágora existan como códigos en Shiji y las credenciales. | | «Ocurrió un error: No se pudo enviar a Shiji.» | Shiji no respondió o la respuesta no se pudo leer. | Revisa la URL y la conectividad con Shiji. El albarán ya está en Ágora: no lo repitas sin comprobar Shiji. | | Ágora no deja cerrar una factura: «El método de pago X no está asignado a ningún método de pago de Shiji. Por favor, asígnelo para poder continuar» | La forma de pago no está en la pestaña Métodos de pago. | Asígnale su código de Shiji y vuelve a emitir la factura. | | Ágora no deja cerrar una factura: «Ocurrió un error no especificado.» | Shiji no devolvió éxito al recibir la factura. | Mira la respuesta en Operaciones hoteleras → Facturas y revisa la Cuenta de ingresos y los códigos. | | El turno que llega a Shiji no es el esperado | La hora del albarán no cae en ningún turno, o el turno cruza la medianoche. | Revisa las franjas de la pestaña Turnos y el Id. del turno por defecto. | | Facturas duplicadas en Shiji | Z-cierre activo además del envío en tiempo real. | Desmarca Z-cierre. | | La pantalla muestra «Integración pausada» | FOS ha pausado el envío de cargos. | Contacta con soporte de FOS. | ## 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](https://connectmanager.es/integraciones/shiji) - [Hotel Hub: cómo funcionan los cargos a habitación desde Ágora](https://connectmanager.es/docs/hotel-hub-como-funciona) - [Web oficial de Shiji](https://www.shijigroup.com) --- # Integración de Sihot con Ágora: cargos a habitación y Z-cierre Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-sihot-agora Actualizado: 2026-10-03 La integración de **Sihot** (SIHOT) con **Ágora** carga en la cuenta del huésped lo que consume en el restaurante o el bar del hotel y envía a Sihot el Z-cierre con las ventas del día a clientes no alojados. También imprime la firma del huésped en el albarán y anula en Sihot el cargo de un albarán anulado en Ágora. Todo pasa por Connect Manager, que guarda el registro de cada operación. Este manual es para el técnico de FOS o del distribuidor que la configura: qué datos pedir, dónde meterlos, cómo funciona, 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 la habitación en Sihot por número y enseña los Datos de la reserva: Nº de hab., un desplegable Cliente con los huéspedes de la habitación, Checkin, Checkout, Regimen y Lím. Créd. Si el límite de crédito es menor que el ticket, el botón Cargar se desactiva. - Avisa al abrir si el ticket lleva descuentos que no admite: por importe, o por línea y a pie de ticket a la vez. - Si activas Solicitar firma, recoge la firma del huésped y la **imprime en el albarán** de Ágora. - Crea el **albarán en Ágora** desde el propio TPV, a nombre del huésped elegido con su habitación (`Nombre Apellido (Nº hab.: 101)`) sobre el cliente configurado, y después envía el cargo a la cuenta de ese huésped: **línea a línea** (centro de venta, familia, producto, formato, cantidad, precio, IVA, albarán, caja y usuario) o, con Concepto único bien configurado, en una sola línea. Puede añadir el número de comensales. - **Anula el cargo**: al anular en Ágora un albarán de la integración, envía a Sihot el abono a la misma cuenta. - Envía el **Z-cierre**: las facturas de Ágora del día (ventas a no alojados), agrupadas, con sus formas de pago, a la cuenta de una habitación de Sihot. - Guarda en Connect Manager cada cargo y cada cierre, con lo enviado y la respuesta de Sihot. ### Qué no hace - **No envía las facturas de Ágora a Sihot.** Si Ágora las manda a la URL de documentos, Connect Manager las acepta sin enviarlas. Las ventas a no alojados solo llegan agrupadas en el Z-cierre. - No busca por nombre del huésped ni por tarjeta: solo por número de habitación. - No envía propinas ni manda la firma a Sihot: la firma queda en Connect Manager y se imprime en el albarán. - El envío automático del Z-cierre a la Hora de generación fich. contable y la cancelación de albaranes abiertos tras Nº de días para cerrar albaranes dependen de tareas programadas del motor que hoy no están activas. El Z-cierre se lanza a mano desde el panel. - No sincroniza reservas, disponibilidad ni tarifas. ## Requisitos - **Connect Manager**: el local dado de alta en `app.connectmanager.es`. La **URL de API** y la **API key** de Ágora van en los datos del local, no en la integración. 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, un **cliente genérico** para los albaranes y acceso a la configuración del servicio para activar la integración de documentos (firma y anulaciones). - **Conectividad**: el cargo lo hace el TPV a través del diálogo, con su API local. Connect Manager sí necesita llegar a la API de Ágora (puerto 8984, publicada o con [Zero Connect](https://connectmanager.es/docs/zero-connect-instalacion)) para las listas del panel y para el Z-cierre, que lee las facturas desde fuera. Los «buscadores» vacíos casi siempre son falta de conexión con esa API. - **Sihot**: la URL de su interfaz, un usuario y contraseña de integración y el identificador del hotel; para el Z-cierre, una habitación ocupada que haga de cuenta de las ventas externas y las formas de pago de Sihot. Reparto de tareas: **FOS** da de alta el local y la integración; el **distribuidor** rellena los campos, hace las asociaciones y configura Ágora; el **hotel o Sihot** facilita credenciales, identificadores y la habitación del Z-cierre. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Ágora (o del ACMS central) y API key | Distribuidor, de la instalación de Ágora | https://hotel-demo.ejemplo.es:8984 | Sí (en los datos del local) | | URL Api de Sihot | Sihot o el hotel | https://sihot.ejemplo.es/… | Sí, no tiene valor por defecto | | Usuario y Password de integración | Sihot | Credenciales de la interfaz | Sí | | Id. del hotel | Sihot | 1 | Sí | | Cliente de Ágora para los albaranes | Distribuidor u hotel (cliente genérico en Ágora) | HUÉSPEDES HOTEL | Sí, en la práctica | | Id. de Sihot por familia de Ágora | Sihot u hotel | Bebidas → 20 | No (sin él va el id. de Ágora) | | Número de caja de Sihot por local, TPV o centro de venta | Sihot u hotel | Restaurante → 5 | No (sin él va el id. de Ágora) | | Concepto único: Middlecat, Articlecat y Articleno (id. y descripción) y tipo de IVA | Sihot u hotel | 10 / Restaurante | Solo con concepto único | | Z-cierre: habitación que hace de cuenta | Hotel (debe estar ocupada en Sihot) | 999 | Solo con Z-cierre | | Z-cierre: forma de pago de Sihot por cada forma de pago de Ágora | Hotel; la lista sale de Sihot | Efectivo → Cash | Sí, con Z-cierre | | Correos para avisos de error | Hotel o distribuidor | avisos@hotel-demo.es | No | ## Configuración paso a paso ### En Sihot - Pide al hotel o a Sihot la URL de la interfaz, el usuario, la contraseña y el identificador del hotel. - Decide con el hotel cómo se identifican las cajas en Sihot (por local, por TPV o por centro de venta de Ágora) y pide sus números. - Si se usa el Z-cierre: la habitación que hará de cuenta de las ventas a no alojados, que tiene que estar ocupada, y las formas de pago de Sihot. - Si se quiere Concepto único: los identificadores y descripciones de Middlecat, Articlecat y Articleno que usará Sihot. ### En Connect Manager: datos del local - Entra en `https://app.connectmanager.es` y ve a **Administración → Locales**. Abre el local. - Revisa **URL de API** y **API key** de Ágora y pulsa el botón de prueba junto a la URL: debe salir Conexión con éxito. - Pulsa **Guardar**. ### En Connect Manager: la integración de hoteles - En la columna de la derecha, entra en **Integraciones → Integraciones de hoteles**. Abre la de Sihot o, si eres administrador, pulsa Añadir y elige el **Proveedor** Sihot. - En **Conf. general** rellena **URL Api:**, **Usuario**, **Password**, **Id. del hotel** y, si quieres avisos, **Email de receptor de notificaciones**. Ahí llegan los errores del Z-cierre; los fallos de un cargo no se avisan por correo. - Para el Z-cierre, en **Conf. de Z-cierre** marca **Z-cierre** y rellena **Núm. de habitación de Z-cierre** y **Hora de generación fich. contable**. Cada vez que guardas, Connect Manager pide a Sihot la cuenta de esa habitación y la usa en los cierres: si no está ocupada, no la obtiene y, si nunca se obtuvo, el cierre fallará. - En **Conf. de cargos** ajusta las opciones de la tabla y elige el **Cliente**. - Pulsa **Guardar**: sale Se ha guardado la integración de hoteles y se activan las pestañas de asociaciones. - En **Familias**, por cada familia con identificador propio en Sihot: **Familia** (de Ágora) e **Id. del servicio**. - La segunda pestaña se llama **Local**, **TPV** o **Centro de venta** según Agrupar cargos por.... Por cada entidad: la de Ágora, **Tipo de facturación** (Interna para los cargos a habitación, Externa para el Z-cierre; si necesitas las dos, crea dos filas), **External id.** (el número de caja de Sihot) y **Nombre externo**. - En **Métodos de pago**, por cada forma de pago de Ágora: **Método de pago de Agora** y **Método de pago Sihot** (la lista viene de Sihot). Con Z-cierre, asócialas todas. - En **Enlaces**, copia la **URL botón acción personalizada** y, si aparece, la **URL para enviar facturas desde Ágora**: solo se muestra con Dejar abierto el albarán o Solicitar firma marcadas. | Opción | Qué hace | Valor recomendado | | Solicitar firma | Muestra un recuadro para la firma (con Borrar); se imprime en el albarán si está configurada la URL de documentos en Ágora. | Según pida el hotel. | | Agrupar cargos por... | Local, TPV o Centro de venta: qué entidad de Ágora se envía como caja a Sihot en los cargos y por cuál se agrupa el Z-cierre. Cambia la segunda pestaña. | Local (por defecto), salvo que Sihot tenga una caja por TPV o por centro. | | Concepto único | Envía todo el ticket en una línea con el total y el Tipo de IVA elegido (10, 21, 4 o 0 %). Solo agrupa si están rellenos los seis campos Middlecat id., Middlecat desc., Articlecat id., Articlecat desc., Articleno id. y Articleno desc.; si falta alguno, va línea a línea. | Solo si el hotel lo pide: todo el ticket va con ese IVA aunque mezcle tipos. | | Enviar nº de comensales | Añade los comensales del ticket al cargo y la suma del día al Z-cierre. | Según pida el hotel. | | Dejar abierto el albarán | Crea el albarán abierto en Ágora, lo que permite anularlo después desde el TPV; la anulación llega a Sihot por la URL de documentos. | Marcada si el hotel quiere anular cargos desde Ágora. | | Nº de días para cerrar albaranes | Días tras los que una tarea del motor cancelaría los albaranes abiertos. Hoy esa tarea no está activa: no tiene efecto. | 7 (por defecto). | | Cliente | Cliente de Ágora del albarán; el documento sale con el nombre del huésped y su habitación. | Un cliente genérico de cargos a habitación. | **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 - Si no existe, crea el cliente genérico para los albaranes y comprueba que es el elegido en Cliente. - Ve a **Herramientas → Acciones personalizadas** y pulsa + Nuevo: Texto «Cargo habitación», Tipo Url/Aplicación y, en Acción, la URL botón acción personalizada tal cual, con sus marcadores `{user_id}`, `{pos_id}`, `{ticket_global_id}`… - Marca **Mostrar Urls en un diálogo de Ágora**: la pantalla lee el ticket y crea el albarán a través de ese diálogo. - En **Herramientas → Configuración de Botones**, coloca la acción en un botón del perfil del local y da el permiso de la acción a los perfiles que vayan a cargar. - Para la firma y las anulaciones: en la configuración del servicio de Ágora, entra en **Activar módulos adicionales → Servicios de integración**, pega la URL para enviar facturas desde Ágora y marca Habilitar integración de documentos y Enviar albaranes. Las URL tienen esta forma, precedidas del dominio que muestre el panel: `/venues/123/hotels/sihot/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}` para la acción y `/api/venues/123/hotels/sihot/generate-invoice` para los documentos. ## Cómo funciona Al pulsar la acción, el diálogo carga la pantalla de Connect Manager, que pide al TPV el ticket abierto. El camarero escribe la habitación; Connect Manager se identifica en Sihot (guarda el token hasta que caduca) y trae los huéspedes de esa habitación. Elige el huésped en Cliente, el huésped firma si se pide y pulsa Cargar. El orden es: primero se sube la firma, después el TPV crea el albarán y, por último, Connect Manager envía el cargo a la cuenta del huésped en Sihot. Si Sihot lo acepta, sale «Se generó el siguiente cargo:» con el número interno del registro y el diálogo se cierra a los dos segundos. ```mermaid sequenceDiagram participant C as Camarero participant AG as TPV Ágora participant CM as Connect Manager participant SH as Sihot 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 por la API local C->>CM: Escribe el nº de habitación CM->>SH: Consulta la habitación SH-->>CM: Huéspedes, fechas, régimen y crédito C->>CM: Elige huésped, firma y pulsa Cargar CM->>AG: Crea el albarán por la API local opt Con la integración de documentos activa AG->>CM: Envía el albarán a la URL de documentos CM-->>AG: Acepta y devuelve la firma para imprimir end CM->>SH: Cargo a la cuenta del huésped SH-->>CM: Cargo aceptado CM-->>C: Se generó el siguiente cargo ``` Cada línea del cargo lleva el centro de venta, la familia (con el Id. del servicio asociado o el de Ágora), el producto, el formato, la cantidad, el precio unitario y total con los descuentos repartidos, el IVA, el número de albarán (`SERIE/000123`), la caja (según Agrupar cargos por..., con su asociación Interna) y el usuario de Ágora. Los platos de menú a 0 € no se envían. Como el albarán se crea antes, si Sihot rechaza el cargo el albarán ya existe en Ágora y la pantalla dice «No se ha podido generar el albarán…»; el motivo de Sihot queda en Operaciones hoteleras → Cargos. ### Anulación de un cargo Con la integración de documentos activa en Ágora, al anular un albarán que salió de la integración Ágora envía el documento de anulación a la URL de documentos. Connect Manager localiza el cargo por la serie y el número del albarán y envía a Sihot el abono a la misma cuenta. Si Sihot lo rechaza, Connect Manager responde a Ágora con el rechazo y el motivo. Los albaranes que no salieron de la integración se aceptan sin tocar Sihot. ### El Z-cierre Se lanza desde **Inicio**, en el recuadro Generar cierre Z del hotel (Sihot) (Local, Fecha y Click para generar), o desde **Operaciones hoteleras → Cierres de caja**, seleccionando un cierre y pulsando Exportar. Connect Manager pide a Ágora las facturas de ese día de negocio, las agrupa por local, TPV o centro de venta (con su asociación Externa), suma las líneas por formato (o en un concepto único) y envía a la cuenta de la habitación del Z-cierre las líneas, el rango de facturas, los pagos por forma de pago de Sihot y, si está activado, los comensales. ```mermaid flowchart TD A[Inicio o Cierres de caja] --> B{Cierre de ese día ya enviado} B -->|sí| X[No se vuelve a enviar] B -->|no| C[Lee de Ágora las facturas del día] C --> D{Todas las formas de pago asociadas} D -->|no| E[Error de mapeo, aviso por correo] D -->|sí| F[Envía el cierre a la cuenta del Z-cierre] F --> G{Respuesta de Sihot} G -->|correcta| H[Estado Enviado] G -->|error| I[Estado Error con el mensaje] ``` El resultado queda en Cierres de caja: Enviado, Error (con el mensaje de Sihot en Error en la respuesta externa) o No hay datos. Si falla antes de enviar (una forma de pago sin asociar, la cuenta del Z-cierre sin obtener, Ágora sin respuesta), el estado no cambia (Creado la primera vez) y el motivo llega por correo a las direcciones de notificaciones. Un cierre enviado no se repite. El aviso del recuadro de Inicio es siempre el mismo, así que el resultado se mira en Cierres de caja. ## Comprobar que funciona - 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; la lista de Método de pago Sihot carga (credenciales correctas). - Abre en Ágora un ticket de prueba sin descuentos y pulsa la acción. Busca una habitación ocupada: salen sus huéspedes y los datos de la reserva. - Pulsa Cargar (y firma si está activado): debe salir «Se generó el siguiente cargo:» y cerrarse el diálogo. - En Ágora queda el albarán impreso con «huésped (Nº hab.: …)» y, si se pidió, la firma bajo `FIRMA:`. - En Sihot, la cuenta del huésped tiene las líneas con la caja esperada. - Si usas anulaciones, anula el albarán en Ágora: en Sihot debe aparecer el abono. - Si usas Z-cierre, genéralo desde Inicio para un día con ventas y comprueba en Cierres de caja que queda Enviado y en Sihot la cuenta de la habitación del Z-cierre. - En **Operaciones hoteleras → Cargos** están las operaciones con Pedido externo (request) y Pedido externo (response). ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Los buscadores de Cliente, familias o formas de pago de Ágora no devuelven nada | Connect Manager no llega a la API de Ágora. | Revisa URL de API y API key del local, la prueba de conexión, el puerto 8984 o Zero Connect. | | «Ocurrió un error: No se ha podido obtener un token de Autenticación.» | URL, usuario, contraseña o Id. del hotel de Sihot incorrectos. | Revísalos con Sihot. | | «La habitación no está ocupada», «La habitación no existe» o «No se ha podido encontrar reserva para esa habitación» | Sihot no devuelve cuenta para ese número de habitación. | Comprueba la habitación y la reserva en Sihot. | | «No se pueden efectuar cargos con descuentos en efectivo…» o «No se pueden efectuar cargos con descuentos por línea y a pie de ticket…» | Descuento por importe, o descuentos en una línea y en el total a la vez. | No pulses Cargar: cierra el diálogo, deja un único descuento en porcentaje y vuelve a abrir la acción. Si se carga igualmente, se crea el albarán sin cargo («No existe un ticket asociado…»). | | Cargar en gris | El límite de crédito del huésped es menor que el ticket. | Revisa el crédito en Sihot o elige otro huésped. | | «El parámetro customer_name es obligatorio. Realice la búsqueda para poder realizar el cargo.» | Se pulsó Cargar sin buscar la habitación. | Busca primero la habitación. | | «No se ha encontrado el ticket: …» o «Request timed out» | La acción no se abre en un diálogo de Ágora o el ticket no existe. | Marca Mostrar Urls en un diálogo de Ágora y lánzala desde un ticket abierto con productos. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Falló el albarán en el TPV o Sihot rechazó el cargo después de crearlo. | Mira en Ágora si el albarán existe y en Cargos el mensaje de Sihot antes de repetir. | | La firma no sale en el albarán | Falta la URL de documentos en Ágora o Enviar albaranes está desmarcado. | Configura Servicios de integración en Ágora. | | Se anula el albarán y el cargo sigue en Sihot | Falta la URL de documentos en Ágora o el albarán no salió de la integración. | Configura la integración de documentos y quita ese cargo a mano en Sihot. | | Correo con «Error de mapeo: el método de pago con id. N no está asociado a ningún método de pago de Sihot.» | Una forma de pago de las facturas del día no está en Métodos de pago. | Asóciala y relanza el cierre con Exportar. | | El cierre no cambia de estado (sigue en Creado) y llega un correo de error | Falló antes de enviar: forma de pago sin asociar, cuenta del Z-cierre sin obtener (habitación no ocupada al guardar) o Ágora sin respuesta. | Corrige la causa (y, si es la habitación, vuelve a guardar la integración con ella ocupada) y relanza. | | Cierre en estado Error | Sihot rechazó el cierre. | Lee Error en la respuesta externa en el detalle y corrige. | ## Preguntas frecuentes ### ¿Cómo conecto Sihot con Ágora? FOS da de alta la integración de hoteles con el proveedor Sihot; tú pones la URL, el usuario, la contraseña y el Id. del hotel, eliges el cliente, haces las asociaciones y creas en Ágora una acción personalizada con la URL del panel, mostrada en un diálogo. ### ¿Se envían las facturas de Ágora a Sihot? No una a una. Las ventas a no alojados llegan agrupadas en el Z-cierre, a la cuenta de la habitación configurada. ### ¿Cómo se anula un cargo enviado a Sihot? Anulando el albarán en Ágora, con la integración de documentos configurada: Connect Manager envía el abono a la misma cuenta de Sihot. ### ¿Dónde queda la firma del huésped? Se guarda en Connect Manager y se imprime en el albarán de Ágora; no se envía a Sihot. ### ¿Se puede buscar al huésped por nombre? No: se busca por número de habitación y luego se elige el huésped en el desplegable Cliente. ## Referencias - Ficha del catálogo: [Sihot](https://connectmanager.es/integraciones/sihot) - Visión general de los cargos a habitación: [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona) - Otros PMS: [Guest Pro](https://connectmanager.es/docs/integracion-guestpro-agora), [Hospedium](https://connectmanager.es/docs/integracion-hospedium-agora), [UbikOS](https://connectmanager.es/docs/integracion-ubikos-agora) y [Redforts](https://connectmanager.es/docs/integracion-redforts-agora) - [Zero Connect: conectar Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion) - [Direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) --- # Integración de UbikOS con Ágora: cargos a habitación y cierre Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-ubikos-agora Actualizado: 2026-10-03 La integración de **UbikOS** (Ubikos) con **Ágora** carga en la reserva del huésped lo que consume en el restaurante o el bar del hotel, línea a línea y con el servicio de UbikOS que corresponda a cada familia, y permite enviar a UbikOS el cierre del día con las facturas del TPV y sus formas de pago. El camarero busca la habitación desde el TPV y pulsa Cargar; Connect Manager hace el resto y guarda el registro. Este manual es para el técnico de FOS o del distribuidor que la configura: qué datos pedir, dónde meterlos, cómo funciona, 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. - **Búsqueda normal**, por número de habitación exacto: enseña los Datos de la reserva (Nº de hab., Cliente, Checkin, Checkout, Regimen y Lím. Créd.) y avisa «La reserva no admite cargos» si UbikOS no los permite. - **Con Mostrar todas las habitaciones**: lista al abrirse todas las habitaciones con reserva y deja buscar por habitación o por nombre del cliente. Cada tarjeta muestra habitación, cliente, tarifa, fechas y crédito, y Cargar sale desactivado si la reserva no admite cargos o su crédito es menor que el total del ticket. - Avisa al abrir si el ticket lleva descuentos que UbikOS no admite: por importe, o por línea y a pie de ticket a la vez. - Crea el **albarán en Ágora** desde el propio TPV, con el nombre del huésped y la habitación (`Nombre Apellido (Nº hab.: 101)`) sobre el cliente configurado, y lo imprime. - Envía el cargo a la reserva **línea a línea**: cantidad, precio unitario, IVA, porcentaje de descuento (el de la línea o el general del ticket), descripción y el **servicio de UbikOS** de la familia (o el servicio por defecto), con el número de albarán, el identificador del ticket y el centro de venta de Ágora. - Puede omitir los platos de menú sin precio y, con un informe personalizado instalado en Ágora, añadir al cargo el cliente del ticket y su código. - Envía el **cierre del día**: las facturas de Ágora de la jornada, con líneas, cliente y formas de pago, a una cuenta diversa de UbikOS. Se lanza desde la pantalla de Inicio del panel. - Guarda en Connect Manager cada cargo (ticket, albarán, envío y respuesta de UbikOS) y cada cierre. ### Qué no hace - No pide la firma del huésped ni envía propinas. - **Anulaciones:** el motor tiene preparada la orden que borra en UbikOS el cargo de un albarán anulado, pero se dispara desde la integración de documentos de Ágora y el panel no da esa URL para UbikOS. Tal como se configura desde el panel, anular el albarán no toca UbikOS; si el hotel lo necesita, consúltalo con FOS. - El envío automático del cierre a la Hora de generación fich. contable y la cancelación automática de albaranes abiertos tras Nº de días para cerrar albaranes dependen de tareas programadas del motor que hoy no están activas. El cierre se lanza a mano desde el panel. - En la búsqueda normal la habitación debe escribirse exactamente como en UbikOS. - 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, un **cliente genérico** para los albaranes y, si se usa Buscar datos de reservas, acceso al servidor para instalar un informe personalizado. - **Conectividad**: el cargo lo hace el TPV a través del diálogo, con su API local. Connect Manager sí necesita llegar a la API de Ágora (puerto 8984, publicada o con [Zero Connect](https://connectmanager.es/docs/zero-connect-instalacion)) para las listas del panel (clientes, familias y formas de pago) y para el cierre, que lee las facturas de Ágora desde fuera. - **UbikOS**: la Api Key, el identificador del hotel y los identificadores de servicios, formas de pago y cuenta diversa. Reparto de tareas: **FOS** da de alta el local y la integración; el **distribuidor** rellena los campos, asocia familias y formas de pago y configura Ágora; el **hotel o UbikOS** facilita la Api Key y los identificadores. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Ágora (o del ACMS central) | Distribuidor, de la instalación de Ágora | https://hotel-demo.ejemplo.es:8984 | Sí | | API key de Ágora | Distribuidor, desde Ágora | Cadena alfanumérica | Sí | | Api Key de UbikOS | UbikOS | Cadena que entrega UbikOS | Sí | | Id. del hotel | UbikOS | 123 | Sí | | URL Api | UbikOS, solo si indica otra | Vacía = https://api.ubikos.es/ | No | | Cliente de Ágora para los albaranes | Distribuidor u hotel (cliente genérico en Ágora) | HUÉSPEDES HOTEL | Sí, en la práctica | | Id. del servicio por defecto y, si se quiere, servicio por familia | UbikOS | 10; Bebidas → 11 | El de por defecto, recomendado | | Cierre: cuenta diversa | UbikOS | 900 | Solo con cierre | | Cierre: forma de pago por defecto y la de UbikOS por cada una de Ágora | UbikOS | Efectivo → 1 | Solo con cierre | | Correos para avisos de error | Hotel o distribuidor | avisos@hotel-demo.es | No | ## Configuración paso a paso ### En UbikOS - Pide a UbikOS (o al hotel) la **Api Key** y el **identificador del hotel**. - Pide los **identificadores de servicio** de los cargos: uno por defecto y, si se quiere separar, uno por grupo de familias. - Si se va a enviar el cierre, el identificador de la **cuenta diversa** y los de las **formas de pago**. ### En Connect Manager: datos del local - Entra en `https://app.connectmanager.es` y ve a **Administración → Locales**. Abre el local. - Revisa **URL de API** y **API key** y pulsa el botón de prueba junto a la URL: debe salir Conexión con éxito. - Pulsa **Guardar**. ### En Connect Manager: la integración de hoteles - En la columna de la derecha, entra en **Integraciones → Integraciones de hoteles**. Abre la de UbikOS o, si eres administrador, pulsa Añadir y elige el **Proveedor** UbikOS. - En **Conf. general** rellena **URL Api:** (vacía para la de UbikOS), **Api Key:**, **Id. del hotel** y, si quieres avisos, **Email de receptor de notificaciones**, donde llegan los errores del cierre. - En **Conf. de cargos** ajusta las opciones de la tabla, elige el **Cliente** y pon el **Id. del servicio** por defecto. - Para el cierre: en **Conf. de Z-cierre** marca **Z-cierre** y rellena **Cuenta diversa**, **Método de pago por defecto** y **Hora de generación fich. contable**. - Pulsa **Guardar**: sale Se ha guardado la integración de hoteles y se activan las pestañas **Familias** y **Métodos de pago**. - En **Familias**, pulsa Añadir por cada familia con servicio propio: **Familia** (de Ágora) e **Id. del servicio** (de UbikOS). - En **Métodos de pago** (solo para el cierre), por cada forma de pago de Ágora: **Método de pago de Agora** y **External id.**, la de UbikOS. Las que no asocies van con el Método de pago por defecto. - En **Enlaces**, copia la **URL botón acción personalizada**. | Opción | Qué hace | Valor recomendado | | Dejar abierto el albarán | Crea el albarán abierto en Ágora, para poder facturarlo o anularlo después. | Desmarcada, salvo que el hotel lo pida. | | Nº de días para cerrar albaranes | Con el albarán abierto, días tras los que una tarea del motor cancela en Ágora los que sigan abiertos. Esa tarea hoy no está programada. | 7 (por defecto). | | Cliente | Cliente de Ágora del albarán; el documento sale con el nombre del huésped y su habitación. | Un cliente genérico de cargos a habitación. | | Id. del servicio | Servicio de UbikOS para las líneas cuya familia no está asociada. | Rellénalo siempre. | | Ocultar artículos del menú con precio cero | No envía los platos de un menú que van a 0 €. | Marcada si el hotel no quiere ver esas líneas. | | Buscar datos de reservas | Al abrir la pantalla ejecuta en Ágora el informe Customer_Reservation_For_Ticket y añade al cargo el cliente del ticket y su código. Muestra la tarjeta Informes personalizados para descargarlo. | Solo si el hotel asigna clientes a los tickets y quiere verlos en UbikOS. | | Mostrar todas las habitaciones | Cambia la pantalla a la lista de habitaciones con búsqueda por nombre y bloqueo por crédito. | Según prefiera el hotel. | **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 - Si no existe, crea el cliente genérico para los albaranes y comprueba que es el elegido en Cliente. - 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}`… - Marca **Mostrar Urls en un diálogo de Ágora**: la pantalla lee el ticket, ejecuta el informe y crea el albarán a través de ese diálogo. - 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 que vayan a cargar. - Solo con Buscar datos de reservas: descarga el informe desde Informes personalizados (Informe de reserva de cliente), cópialo en `[Carpeta de instalación de Ágora]\custom-queries` del servidor (o del ACMS central) y da el permiso de esa consulta al perfil del usuario cuyo token usa el local. > [!WARNING] Copia el informe tal cual se descarga. Un XML de consulta mal formado en `custom-queries` (por ejemplo, sin el nodo `Columns`) impide que arranque el servicio de Ágora del cliente hasta que se retira. La URL de la acción tiene esta forma, precedida del dominio que muestre el panel: `/venues/123/hotels/ubikos/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}`. ## Cómo funciona Al pulsar la acción, el diálogo carga la pantalla de Connect Manager, que pide al TPV el ticket abierto (y, si está activado, ejecuta el informe de reserva). Si el ticket lleva descuentos que UbikOS no admite, avisa y no guarda el ticket: hay que cerrar el diálogo y corregirlo, porque el botón no se bloquea y, si se carga igualmente, se crea el albarán pero el cargo no sale. El camarero busca la habitación y Connect Manager pide a UbikOS las habitaciones con reserva. Al pulsar Cargar, el TPV crea el albarán, Connect Manager lo guarda y envía el cargo a la reserva. Si UbikOS lo acepta, sale «Se generó el siguiente cargo:» con el número de ticket de UbikOS y el diálogo se cierra a los dos segundos. ```mermaid sequenceDiagram participant C as Camarero participant AG as TPV Ágora participant CM as Connect Manager participant UB as UbikOS 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 por la API local y revisa descuentos C->>CM: Escribe el nº de habitación CM->>UB: Pide las habitaciones con reserva UB-->>CM: Reserva, régimen y crédito C->>CM: Pulsa Cargar CM->>AG: Crea el albarán por la API local AG-->>CM: Albarán con serie y número CM->>UB: Cargo a la reserva línea a línea UB-->>CM: Número de ticket de UbikOS CM-->>C: Se generó el siguiente cargo ``` La consulta va a `…/pos/revo/{Id. del hotel}/bookingrooms` y el cargo a `…/pos/revo/{Id. del hotel}/bookingcharge/{reserva}`, con la Api Key. El albarán se crea **antes** del cargo: si UbikOS lo rechaza, el albarán ya existe en Ágora y la pantalla dice «No se ha podido generar el albarán…». La respuesta de UbikOS queda guardada en Cargos también cuando falla. ### El cierre del día Se lanza desde **Inicio**, en el recuadro Generar cierre Z del hotel (Ubikos): eliges Local y Fecha y pulsas Click para generar. Connect Manager pide a Ágora las facturas de ese día de negocio y envía cada una a la cuenta diversa de UbikOS (`…/invoicecharge/{cuenta diversa}`) con su número, día de negocio, centro de venta, cliente, líneas con los servicios de las familias y formas de pago. El resultado queda en **Operaciones hoteleras → Cierres de caja**: Enviado, Error (si UbikOS rechaza alguna factura) o No hay datos. ```mermaid flowchart TD A[Inicio: Generar cierre Z del hotel] --> B{Cierre de ese día ya enviado} B -->|sí| X[No se vuelve a enviar] B -->|no| C[Lee de Ágora las facturas del día] C --> D[Envía cada factura a la cuenta diversa de UbikOS] D --> E{Alguna factura con error} E -->|no| F[Estado Enviado] E -->|sí| G[Estado Error] ``` Un cierre ya enviado no se repite, ni desde Inicio ni con Exportar en Cierres de caja, que sirve para relanzar los que quedaron en error o sin datos. El aviso de Inicio es siempre el mismo («La petición para generar el cierre se ha enviado…»), así que el resultado se mira en Cierres de caja. Si falla la lectura de Ágora, se avisa por correo. > [!NOTE] Las facturas del día se piden sin filtrar por local: si la URL de API del local es la de un ACMS central con varios locales, el cierre incluye las de todos. ## Comprobar que funciona - La prueba de la URL de API del local da Conexión con éxito y los buscadores de Cliente y de familias listan datos de Ágora. - Abre en Ágora un ticket de prueba sin descuentos y pulsa la acción: se abre el diálogo de búsqueda. - Busca una habitación ocupada: salen los datos de la reserva (o su tarjeta, con Mostrar todas las habitaciones). - Pulsa Cargar: debe salir «Se generó el siguiente cargo:» con un número y cerrarse el diálogo. - En Ágora queda el albarán impreso con «huésped (Nº hab.: …)» y en UbikOS la reserva tiene una línea por producto con el servicio esperado. - En **Operaciones hoteleras → Cargos** aparece la operación con lo enviado y la respuesta. - Si usas el cierre, genera desde Inicio el de un día con ventas y comprueba en Cierres de caja que queda Enviado y en UbikOS que las facturas están en la cuenta diversa. - Anula el albarán de prueba en Ágora y quita el cargo a mano en UbikOS. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Al guardar: «Ocurrió un error: The auth data field is required.» | El campo Api Key está vacío. | Rellena la Api Key de UbikOS. | | Los buscadores de Cliente, familias o formas de pago no devuelven nada | Connect Manager no llega a la API de Ágora. | Revisa URL de API, API key, la prueba de conexión, el puerto 8984 o Zero Connect. | | El TPV muestra «Integración pausada» | FOS ha pausado el envío de cargos. | Contacta con soporte de FOS. | | «No se pueden efectuar cargos con descuentos en efectivo…» o «No se pueden efectuar cargos con descuentos por línea y a pie de ticket…» | El ticket tiene un descuento por importe, o descuentos en una línea y en el total a la vez. | No pulses Cargar: cierra el diálogo, deja un único descuento en porcentaje y vuelve a abrir la acción. | | El albarán se crea en Ágora pero el cargo no llega a UbikOS | Se pulsó Cargar sin que la pantalla hubiera guardado el ticket (por ejemplo, tras el aviso de descuentos): Connect Manager responde «No existe un ticket asociado. Por favor, cierre la ventana e inténtelo de nuevo.» | Devuelve ese albarán en Ágora, corrige el ticket y repite el cargo. | | «No se han encontrado reservas con el criterio especificado» | La habitación no está escrita como en UbikOS o no tiene reserva. | Escríbela exacta o usa Mostrar todas las habitaciones. | | «La reserva no admite cargos» o Cargar en gris | UbikOS no permite cargos en esa reserva o el crédito no cubre el ticket. | Revisa la reserva en UbikOS. | | «No se ha encontrado el ticket: … Cierre esta ventana e intente generar el ticket de nuevo.» o «Request timed out» | La acción no se abre en un diálogo de Ágora o el ticket no existe. | Marca Mostrar Urls en un diálogo de Ágora y lánzala desde un ticket abierto con productos. | | «Ocurrió un error: HTTP request returned status code …» | Api Key, Id. del hotel o URL Api incorrectos, o UbikOS rechazó la petición. | Revisa los datos con UbikOS; la respuesta está en Pedido externo (response). | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Falló el albarán en el TPV o UbikOS rechazó el cargo después de crearlo. | Mira en Ágora si el albarán existe y en Cargos la respuesta antes de repetir. | | Error al abrir la pantalla y el cliente del ticket no llega a UbikOS | Buscar datos de reservas está marcada pero el informe no está instalado o falta su permiso. | Instala el informe y da el permiso, o desmarca la opción. | | Cierre en estado Error | UbikOS rechazó alguna factura o no se pudo leer Ágora. | Mira Respuesta externa en el detalle del cierre, corrige cuenta diversa o formas de pago y relánzalo con Exportar. | | Al generar el cierre: «No tienes esta integración contratada…» | El local elegido no tiene integración de UbikOS. | Elige el local correcto. | ## Preguntas frecuentes ### ¿Cómo conecto UbikOS con Ágora? FOS da de alta la integración de hoteles con el proveedor UbikOS; tú pones Api Key, Id. del hotel, cliente y servicio por defecto, asocias familias y formas de pago y creas en Ágora una acción personalizada con la URL del panel, mostrada en un diálogo. ### ¿Se puede buscar al huésped por nombre? Sí, con Mostrar todas las habitaciones: la pantalla lista las habitaciones con reserva y deja buscar por habitación o por nombre del cliente. ### ¿Cómo envío a UbikOS las ventas del día? Activa el Z-cierre con la cuenta diversa y las formas de pago, y lánzalo desde Inicio con Generar cierre Z del hotel (Ubikos). El resultado se ve en Cierres de caja. ### ¿Se anula el cargo en UbikOS si anulo el albarán? Con la configuración que da el panel, no: el cargo hay que quitarlo en UbikOS. El motor tiene la anulación preparada, pero necesita una URL de documentos de Ágora que el panel no muestra para UbikOS. ### ¿Por qué sale un aviso al cargar un ticket con descuento? Porque UbikOS solo recibe descuentos en porcentaje y en un único nivel, por línea o a pie de ticket, nunca por importe. Si sale el aviso, no pulses Cargar: cierra el diálogo, corrige el descuento y vuelve a abrir la acción. ## Referencias - Ficha del catálogo: [UbikOS](https://connectmanager.es/integraciones/ubikos) - Visión general de los cargos a habitación: [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona) - Otros PMS: [Guest Pro](https://connectmanager.es/docs/integracion-guestpro-agora), [Hospedium](https://connectmanager.es/docs/integracion-hospedium-agora), [Redforts](https://connectmanager.es/docs/integracion-redforts-agora) y [Sihot](https://connectmanager.es/docs/integracion-sihot-agora) - [Zero Connect: conectar Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion) - [Direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) --- # Integración de Ulyses con Ágora: cargos a habitación y facturas Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-ulyses-agora Actualizado: 2026-10-03 La integración de Ulyses con Ágora permite cargar a la habitación los consumos del restaurante o la cafetería sin salir del TPV: el camarero busca la habitación, Connect Manager consulta los folios en Ulyses (el PMS de Tesipro) y el ticket se cierra en Ágora como albarán y se apunta en el folio del huésped. Además envía a Ulyses las facturas que emite Ágora y anula el cargo cuando se anula el albarán. Este manual es para el técnico de FOS o del distribuidor que deja la integración funcionando en un local. Cómo encajan en general los PMS con Ágora está en [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona). ## Qué hace la integración - Añade a Ágora un botón (acción personalizada) que abre la ventana de cargo dentro del TPV. - Busca por número de habitación los folios de Ulyses y enseña huésped, entrada, salida, régimen y crédito. Si hay varios folios, deja elegir y preselecciona el que está en fechas. - Puede ocultar los folios fuera de fechas y bloquear el cargo si el folio no tiene crédito suficiente. - Cierra el ticket en Ágora como albarán a nombre del cliente configurado, con el nombre del folio y la habitación en el nombre fiscal, y lo imprime. - Apunta el cargo en el folio con el detalle de líneas, los comensales y la serie y número del albarán; si se pide, reparte el importe entre comida, bebida y otros. - Elige el servicio de Ulyses por centro de venta, por franja horaria o por familia, y manda un apunte por servicio si el ticket los mezcla. - Al anular en Ágora el albarán de un cargo, manda a Ulyses un apunte de anulación con las mismas líneas y las unidades en negativo. - Envía a Ulyses las facturas que emite Ágora a un folio de facturación (las rectificativas, a uno de devolución), con un cobro por forma de pago, en el momento o cinco minutos después. - Guarda cada cargo y cada factura con lo enviado y lo respondido, y avisa por correo de los fallos de los envíos en segundo plano. ### Qué no hace - No busca por nombre del huésped, tarjeta ni localizador: solo por número de habitación o, con una variante, por código de folio. - No envía propinas ni el desglose de IVA, ni sincroniza reservas, disponibilidad o tarifas. - No deja cargar tickets con descuento en importe, ni con descuento por línea y a pie de ticket a la vez. - No reintenta sola un envío en segundo plano que falla: avisa por correo y el reenvío lo hace FOS. - No cierra por sí sola los albaranes abiertos. «Nº de días para cerrar albaranes» depende de una tarea nocturna del motor que en la versión actual no está activada: confírmalo con FOS antes de contar con ella. ## Requisitos - **Ágora** con **Herramientas → Acciones personalizadas** y, para anulaciones y facturas, el módulo **Servicios de integración**. - **Conectividad con Ágora.** La ventana lee el ticket y crea el albarán a través de la API local del TPV, así que para cobrar no hace falta abrir Ágora a Internet. Para configurar, sí: los selectores del panel (Cliente, Familia, Centro de venta, Método de pago) leen Ágora desde Connect Manager con la URL de API y la API key del local, que tienen que ser accesibles desde fuera (puerto abierto a las [IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) o publicado con Zero Connect). - **Acceso a la API de Ulyses**: URL, usuario, contraseña, id. de cadena e id. de hotel. - **Quién hace qué.** El cliente pide a Ulyses el acceso de integración y Ulyses manda los datos a FOS. FOS da de alta el local y la integración y rellena esos datos. El distribuidor revisa la configuración de cargos, hace las asociaciones, configura Ágora y prueba con el cliente. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Ulyses | Ulyses, por correo a FOS | https://pms.ejemplo.com/api/ | Sí | | Usuario y contraseña de integración | Ulyses | usuario-demo | Sí | | Id. de la cadena e Id. del hotel | Ulyses | 12 y 345 | Sí | | Servicio de Ulyses para los cargos | Desplegable del panel (lista de Ulyses); lo confirma el hotel | Restaurante | Sí | | Folio de facturación y de devolución | Desplegable del panel (folios de punto de venta) | TPV Restaurante | Si se envían facturas | | Cliente genérico de Ágora | Ágora del local (se crea si no existe) | Cargos a habitación | Sí | | Equivalencia de formas de pago | Distribuidor con el hotel | Tarjeta → VISA | Si se envían facturas | | Servicio por centro de venta y franjas | Hotel | Desayunos de 07:00 a 11:00 | No | | Reparto comida / bebida / otros por familia | Contabilidad del hotel | Vinos → Bebida | Con «Contabilizar por separado» | | Correos para avisos | Cliente o distribuidor | avisos@hotel-demo.com | Recomendado | | URL de API y API key de Ágora | Distribuidor | http://servidor-demo:8984/ | Sí | ## Configuración paso a paso ### 1. En Ulyses - El cliente solicita a Ulyses el acceso de integración con Connect Manager; Ulyses envía a FOS la URL, el usuario, la contraseña y los ids. de cadena y hotel. - Comprueba con el hotel que existen en Ulyses los servicios, los folios de punto de venta y las formas de pago que se van a usar: el panel los carga de Ulyses, no se escriben a mano. ### 2. En Connect Manager: el local (lo hace FOS) - En **Administración → Locales**, abre el local y rellena **Cliente**, **Nombre**, **URL de API** y **API key** de Ágora, **Dirección**, **Ciudad** y **Zona horaria**. Con la zona horaria se comprueban las fechas de la reserva y se fecha el albarán. - Pulsa el icono de prueba del campo URL de API (sale con la URL y la API key rellenas): debe salir «Conexión con éxito». - **Guardar** → **Integraciones de hoteles** → **Añadir** → proveedor **Ulyses**. ### 3. En Connect Manager: Conf. general - **Proveedor**: Ulyses. No se puede cambiar después de guardar. - **Pausar el envío de cargos al PMS después de** y **Pausar el envío de cargos al PMS**: solo los ve FOS. Con la integración pausada (o desde el día siguiente a esa fecha), el botón del TPV abre el aviso «Integración pausada» en vez de la ventana de cargo. - **URL Api**, **Usuario**, **Password**, **Id. de la cadena** e **Id. del hotel**: los de Ulyses. La URL es obligatoria: no hay ninguna por defecto. - **Email de receptor de notificaciones**: escribe cada dirección y pulsa Intro. - Pulsa **Guardar**: la integración se abre en modo edición y aparecen los desplegables de Ulyses y las pestañas de asociaciones, que antes de guardar no salen. ### 4. En Connect Manager: Conf. de cargos - **Comprobar fechas de reserva**: al buscar solo salen los folios cuya estancia incluye hoy (de la llegada a la salida, con la zona horaria del local). Desmarcado salen todos los que devuelva Ulyses, también reservas pasadas o futuras. Recomendado: marcado. - **Dejar abierto el albarán**: el albarán se crea en Ágora permitiendo facturarlo después. Es lo que permite anular el cargo más tarde desde Ágora y que la anulación llegue a Ulyses. Recomendado: marcado. - **Nº de días para cerrar albaranes** (7 por defecto): la tarea nocturna que lo usa anula en Ágora los albaranes de cargo que siguen abiertos pasados esos días, sin tocar Ulyses, y solo si «Dejar abierto el albarán» está marcado. Hoy esa tarea no está activa. - **Cliente**: el cliente genérico de Ágora al que se emiten los albaranes. Su nombre fiscal se sustituye por el del folio y la habitación, por ejemplo «Huésped Demo (Nº hab.: 101)». - **Servicio**: el servicio de Ulyses por defecto para los cargos. - **Folio de facturación** y **Folio de devolución**: donde se apuntan las facturas y las rectificativas que llegan de Ágora. No intervienen en los cargos a habitación. - **Enviar facturas en diferido**: Ágora recibe la factura como aceptada al momento y el envío a Ulyses sale cinco minutos después, en segundo plano. Así una caída de Ulyses no bloquea el cobro en el TPV. Recomendado: marcado. - **Contabilizar por separado**: añade a cada apunte los importes de comida, bebida y otros. Cada línea va a lo que diga su familia en la pestaña Familias o, si no está asociada, a **Contabilizar por defecto como** (Comida, Bebida u Otras), que aparece al marcarla. - **Comprobar si hay crédito disponible**: el botón Cargar se bloquea si el folio no tiene crédito, si es menor que el total del ticket o si Ulyses no devuelve un importe de crédito. ### 5. En Connect Manager: asociaciones - **Centros de venta** (opcional): por cada **Centro de venta de Ágora**, su **Servicio**; un **Servicio alternativo** con su **Hora de inicio del servicio alternativo** y su **Hora de finalización del servicio alternativo** (dentro de esa franja se usa el alternativo); y un **Folio de facturación** y **Folio de devolución** propios para sus facturas. - **Familias** (opcional): por cada **Familia**, **Contabilizar por** Comida, Bebida u Otras; para repartir, un porcentaje y un **Contabilizar por (2ª)** con el suyo, que deben sumar 100. Con un **Servicio** propio, sus líneas van en un apunte aparte. - **Métodos de pago**: cada **Método de pago de Agora** con su **Método de pago Ulyses**. Si se envían facturas, asócialos todos: una factura con una forma de pago sin asociar se rechaza. ### 6. En Ágora - Copia del bloque **Enlaces** la **URL botón acción personalizada** con su botón de copiar. Si empieza por `/venues/`, antepón la dirección del panel (`https://app.connectmanager.es`). - En **Herramientas → Acciones personalizadas** pulsa **Nuevo**: **Texto** «Cargo habitación», **Tipo** «Url/Aplicación», **Acción** la URL copiada, sin tocar los marcadores entre llaves que Ágora rellena solo (`{user_id}`, `{pos_id}`, `{ticket_global_id}`…), y marca **Mostrar Urls en un diálogo de Ágora**. - Coloca la acción en **Herramientas → Configuración de botones** y da el permiso que genera a los perfiles que vayan a cargar. - Para anulaciones y facturas, en **Herramientas → Activar módulos adicionales → Servicios de integración** pega la **URL para enviar facturas desde Ágora** y activa **Habilitar integración de documentos** y **Enviar albaranes**. > [!WARNING] Con la integración de documentos activa, todas las facturas que emite Ágora se envían a Ulyses. Asocia antes las formas de pago y elige los folios, o Ágora no dejará cerrar esas ventas. > [!TIP] Para cargar a folios que no son de habitación (grupos, eventos), crea una segunda acción con la misma URL y `&search-by-folio=1` al final: la ventana busca por «Cód. de folio», con la casilla «Búsqueda exacta». Su campo «Propina» no se envía a Ulyses. ## Cómo funciona Al pulsar el botón, Ágora abre la ventana con el usuario, el TPV y el identificador del ticket. La ventana pide el ticket a la API local de Ágora y lo guarda en Connect Manager. El camarero escribe la habitación y Connect Manager trae sus folios de Ulyses. Al pulsar **Cargar**, la ventana crea primero el albarán en Ágora, lo guarda y pide el cargo; Connect Manager apunta el ticket en el folio elegido y responde «Se generó el siguiente cargo» con el número de Ulyses. La ventana se cierra a los dos segundos. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant PMS as Ulyses TPV->>CM: Abre la ventana con el ticket TPV->>TPV: Lee el ticket por la API local TPV->>CM: Guarda el ticket TPV->>CM: Busca la habitación CM->>PMS: Pide los folios de la habitación PMS-->>CM: Huésped, fechas, régimen y crédito CM-->>TPV: Datos de la reserva TPV->>TPV: Crea el albarán por la API local TPV->>CM: Guarda el albarán y pide el cargo CM->>PMS: Apunte en el folio PMS-->>CM: Número del apunte CM-->>TPV: Se generó el siguiente cargo ``` **Qué se envía:** el servicio, la serie y el número del albarán, los comensales, el total con IVA y, por línea, el nombre del formato, las unidades y el precio unitario ya descontado (las unidades no enteras van como una unidad con el importe total). Con «Contabilizar por separado» se añaden comida, bebida y otros. Si hay varios servicios, el primer apunte sale en el momento y el resto un segundo después, en segundo plano; si alguno falla llega un correo «Error en aplicación» con «Enviar cargo adicional de Ulyses (Error)». **Si Ulyses no responde:** la búsqueda da error en la ventana. Si falla el cargo, el albarán ya está creado en Ágora, la ventana dice «No se ha podido generar el albarán…» y el cargo no se repite solo: revisa el caso en **Operaciones hoteleras → Cargos**. ### Anulaciones Al anular en Ágora un albarán de cargo, Ágora lo comunica a la URL de facturas. Connect Manager lo reconoce por su serie y número, rehace el apunte con las mismas líneas y las unidades en negativo y lo manda al mismo folio. Si Ulyses no contesta, Ágora recibe un rechazo y la anulación no se completa. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant PMS as Ulyses TPV->>CM: Albarán anulado por la URL de facturas CM->>PMS: Apunte con las unidades en negativo PMS-->>CM: Respuesta CM-->>TPV: Aceptado o rechazado ``` ### Facturas Cada factura que emite Ágora llega a la misma URL. Connect Manager comprueba que sus formas de pago estén asociadas y que haya folio, y la apunta en el folio de facturación (el de devolución si es rectificativa; el del centro de venta si lo tiene) con las líneas agrupadas por servicio. Después manda un cobro por forma de pago, con importe, fecha de cobro y día de negocio. En diferido, Ágora recibe la aceptación al instante y el envío sale a los cinco minutos; si falla, llega el correo «Enviar factura diferida de Ulyses (Error)». En **Operaciones hoteleras → Facturas** salen como «Aceptado» cuando Ulyses las ha recibido, y sin estado mientras esperan el envío diferido. ## Comprobar que funciona - En la integración guardada, los desplegables Servicio y Folio muestran datos de Ulyses. - En Ágora, abre un ticket con un par de productos y pulsa el botón. Busca una habitación con huésped en casa: deben salir folio, cliente, entrada, salida, régimen y crédito. - Pulsa **Cargar**: sale «Se generó el siguiente cargo: …», la ventana se cierra y se imprime el albarán con el nombre y la habitación. - En Ulyses, el folio tiene el apunte con las líneas y la serie y número del albarán; en **Operaciones hoteleras → Cargos** aparece el cargo con su Id. de pedido externo. - Anula el albarán de prueba en Ágora y comprueba en Ulyses el apunte de anulación. - Emite una factura de una venta normal y comprueba el apunte y el cobro en el folio de facturación (a los cinco minutos si está en diferido). ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Los desplegables de Ulyses salen vacíos, o al buscar sale «Ocurrió un error: HTTP request returned status code 401…» | URL Api, usuario, contraseña o ids. de cadena y hotel incorrectos | Revísalos con Ulyses; la URL es la base de la API. | | Los selectores de Cliente, Familia, Centro de venta o Método de pago no cargan | Connect Manager no llega a la API de Ágora | Prueba la conexión en la ficha del local; abre el puerto a las IP de Connect Manager o usa Zero Connect. | | «No se han encontrado reservas con el criterio especificado» | La habitación no tiene folio, o está fuera de fechas con «Comprobar fechas de reserva» | Compruébalo en Ulyses. | | El botón Cargar está gris | «Comprobar si hay crédito disponible» activo y el folio sin crédito suficiente o sin importe de crédito | Que el hotel lo resuelva en Ulyses, o desactiva la opción. | | «No se pueden efectuar cargos con descuentos en efectivo…» o «…con descuentos por línea y a pie de ticket…» | Descuento en importe, o en línea y total a la vez | Deja un único descuento en porcentaje. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Ágora no creó el albarán, o Ulyses rechazó el cargo después de crearlo | Mira si el albarán existe en Ágora y si el cargo figura en Operaciones hoteleras → Cargos; «Pedido externo (response)» guarda la respuesta de Ulyses. | | La ventana se queda cargando y sale «Request timed out» | La acción no se abre dentro de Ágora | Marca «Mostrar Urls en un diálogo de Ágora». | | «Integración pausada» | FOS ha pausado la integración o ha vencido la fecha de pausa | Contacta con soporte. | | Factura rechazada: «El método de pago … no está asignado a ningún método de pago de Lean…» | Forma de pago sin asociar (el texto dice «Lean», pero es Ulyses) | Asóciala en Métodos de pago. | | Factura rechazada: «Configure un folio para poder crear facturas» | Sin folio de facturación | Elige el folio en Conf. de cargos o en el centro de venta. | | Al anular el albarán no llega la anulación a Ulyses | Falta la URL de facturas o «Enviar albaranes» en Ágora | Configúralos en Servicios de integración. | > [!WARNING] Si el cargo falló después de crear el albarán, no anules ese albarán sin revisar antes el folio: la anulación se manda a Ulyses aunque el cargo original no llegara. ## Preguntas frecuentes ### ¿Cómo conecto Ulyses con Ágora? Con Connect Manager: FOS da de alta la integración con los datos de Ulyses, se hacen las asociaciones y en Ágora se crea una acción personalizada con la URL de cargo y, para anulaciones y facturas, la URL de facturas en Servicios de integración. ### ¿Qué tiene que ver Tesipro con Ulyses? Ulyses es el PMS de Tesipro. En el panel sale como «Ulyses»; en las URL de la integración aparece como `tesipro`. ### ¿Si anulo el albarán en Ágora se anula el cargo en Ulyses? Sí, si la URL de facturas está configurada con «Enviar albaranes»: Connect Manager manda al folio un apunte de anulación con las mismas líneas y las unidades en negativo. ### ¿Se pueden enviar a Ulyses las ventas de clientes no alojados? Sí, como facturas: van al folio de facturación con un cobro por forma de pago. ### ¿Qué pasa si Ulyses está caído? No se puede buscar ni cargar. Las facturas en diferido se aceptan en Ágora y se intentan enviar a los cinco minutos; si fallan, llega un aviso por correo. ## Referencias - [Ficha de la integración con Ulyses](https://connectmanager.es/integraciones/ulyses) - [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona) - [Integración de Sihot con Ágora](https://connectmanager.es/docs/integracion-sihot-agora): la misma configuración de acción personalizada y URL de facturas en Ágora - [Direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) - [Glosario de Connect Manager](https://connectmanager.es/docs/glosario) --- # Integración de Winhotel con Ágora: cargos a habitación Portal: Hotel Hub · PMS URL: https://connectmanager.es/docs/integracion-winhotel-agora Actualizado: 2026-10-03 La integración de Winhotel con Ágora permite cargar a la habitación el total de un ticket desde el TPV: el camarero busca la habitación, elige a qué titular con crédito se carga y Connect Manager manda el cargo a Winhotel mientras el ticket se cierra en Ágora como albarán. La ventana enseña además el límite de crédito, las fechas y las tarifas de la reserva. Este manual es para el técnico de FOS o del distribuidor que configura la integración en un local. La visión general de los PMS con Ágora está en [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona). ## Qué hace la integración - Añade a Ágora un botón (acción personalizada) que abre la ventana de cargo dentro del TPV. - Busca por número de habitación los titulares con crédito en Winhotel y enseña el límite de crédito del que se elija. - Enseña la entrada y la salida de la reserva vigente hoy y, con el botón de tarifas, sus tipos de tarifa. - Deja elegir a qué titular se carga cuando hay varios. - Cierra el ticket en Ágora como albarán a nombre del cliente configurado, con el titular y la habitación en el nombre fiscal. - Carga en Winhotel el total del ticket con IVA, con el producto de Winhotel configurado y la serie y número del albarán como documento de origen. ### Qué no hace - No envía el detalle de productos ni la propina: solo el total. - No anula en Winhotel el cargo de un albarán anulado en Ágora: hay que anularlo a mano en el PMS. - No envía facturas ni sincroniza reservas o disponibilidad. - No impide cargar por encima del límite de crédito: lo enseña, pero no bloquea. - No lee la respuesta de Winhotel más allá del código HTTP: si Winhotel contesta sin error técnico, el cargo se da por hecho. ## Requisitos - **Ágora** con **Herramientas → Acciones personalizadas**. La ventana lee el ticket y crea el albarán por la API local del TPV. - **API de Ágora accesible desde Connect Manager** solo para configurar (el selector de Cliente). Abre el puerto a las [IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) o usa Zero Connect. - **Acceso a la API de consultas de Winhotel**: usuario, contraseña y los dos códigos de hotel (source y target). - **Quién hace qué.** FOS da de alta el local y la integración con los datos que facilita Winhotel. El distribuidor elige el producto y el cliente y configura el botón en Ágora. El cliente valida con una prueba real. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | URL de la API de Winhotel | Winhotel | Vacía para usar la pública de Winhotel | No | | Usuario y contraseña | Winhotel | usuario-demo | Sí | | Hotel source code y Hotel target code | Winhotel | 0001 y 0002 | Sí | | Producto de Winhotel para los cargos | Desplegable del panel (lista de Winhotel); lo confirma el hotel | Restaurante | Sí | | Cliente genérico de Ágora | Ágora del local | Cargos a habitación | Sí | | URL de API y API key de Ágora | Distribuidor | http://servidor-demo:8984/ | Sí | ## Configuración paso a paso ### 1. En Winhotel - Pide a Winhotel el acceso a su API de consultas para Ágora: usuario, contraseña, Hotel source code, Hotel target code y, si no es la pública, la URL. - Confirma con el hotel qué producto de Winhotel recibirá los cargos del restaurante. ### 2. En Connect Manager: el local (lo hace FOS) - En **Administración → Locales**, abre el local y rellena **Cliente**, **Nombre**, **URL de API**, **API key**, **Dirección**, **Ciudad** y **Zona horaria**. Pulsa el icono de prueba del campo URL de API (sale con la URL y la API key rellenas): «Conexión con éxito». - **Guardar** → **Integraciones de hoteles** → **Añadir** → proveedor **Winhotel**. ### 3. En Connect Manager: Conf. general - **Pausar el envío de cargos al PMS después de** y **Pausar el envío de cargos al PMS**: solo los ve FOS. Con la integración pausada, el botón del TPV abre el aviso «Integración pausada». - **URL Api**: déjala vacía para usar la API pública de Winhotel, o pon la que te indiquen. - **Usuario** y **Password**: los de Winhotel. - **Hotel source code** y **Hotel target code**: los dos códigos del mapa de hotel que te dé Winhotel. Van en todas las consultas y en los cargos. - **Email de receptor de notificaciones**: esta integración no envía avisos en segundo plano, pero puedes dejar el correo del cliente. - Pulsa **Guardar**: la integración se abre en modo edición y aparece el desplegable **Producto**, que antes de guardar no sale. ### 4. En Connect Manager: Conf. de cargos - **Cliente**: el cliente genérico de Ágora para los albaranes. Su nombre fiscal se sustituye por el del titular y la habitación, por ejemplo «Huésped Demo (Nº hab.: 101)». - **Producto**: el producto de Winhotel al que van los cargos. Es obligatorio: sin él no se puede cargar. ### 5. En Ágora - Copia del bloque **Enlaces** la **URL botón acción personalizada**. Si empieza por `/venues/`, antepón `https://app.connectmanager.es`. - En **Herramientas → Acciones personalizadas** pulsa **Nuevo**: **Texto** «Cargo habitación», **Tipo** «Url/Aplicación», **Acción** la URL copiada (sin tocar los marcadores entre llaves) y marca **Mostrar Urls en un diálogo de Ágora**. - Coloca la acción en **Herramientas → Configuración de botones** y da su permiso a los perfiles que vayan a cargar. ## Cómo funciona El botón abre la ventana con el ticket; la ventana lo lee por la API local de Ágora y lo guarda en Connect Manager. Al buscar la habitación, Connect Manager pide a Winhotel los titulares con crédito y la reserva vigente hoy. Al pulsar **Cargar**, la ventana crea el albarán en Ágora, lo guarda y pide el cargo; Connect Manager lo inserta en Winhotel como cargo externo y la ventana dice «Se generó el siguiente cargo» antes de cerrarse. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant PMS as Winhotel TPV->>TPV: Lee el ticket por la API local TPV->>CM: Guarda el ticket TPV->>CM: Busca la habitación CM->>PMS: Titulares con crédito de la habitación CM->>PMS: Reserva vigente hoy PMS-->>CM: Titulares, límites, fechas y tarifas CM-->>TPV: Datos de la reserva TPV->>TPV: Crea el albarán por la API local TPV->>CM: Guarda el albarán y pide el cargo CM->>PMS: Cargo externo con el total PMS-->>CM: Respuesta CM-->>TPV: Se generó el siguiente cargo ``` **Qué se envía:** el titular elegido (identificador y nombre), el número de habitación, la serie y número del albarán, la fecha del albarán, el total con IVA y el código del producto. Todas las llamadas llevan el usuario, la contraseña y los dos códigos de hotel. El número que enseña la ventana al terminar es siempre el mismo (10000): no es un identificador de Winhotel. **Si Winhotel no responde:** el albarán ya está creado en Ágora, la ventana dice «No se ha podido generar el albarán…» y el cargo no se repite solo. Revisa el caso en **Operaciones hoteleras → Cargos**. ## Comprobar que funciona - Tras guardar, el desplegable Producto muestra los productos de Winhotel: credenciales y códigos correctos. - En Ágora, abre un ticket, pulsa el botón y busca una habitación ocupada: salen los titulares en el desplegable Cliente, el crédito, el checkin y el checkout. - Pulsa **Cargar**: sale «Se generó el siguiente cargo: 10000» y se imprime el albarán con el titular y la habitación. - En Winhotel, el titular tiene el cargo con el total y el número del albarán. - En **Operaciones hoteleras → Cargos**, «Pedido externo (response)» guarda lo que contestó Winhotel: revísalo en la primera prueba. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | El desplegable Producto sale vacío o da error | Usuario, contraseña o códigos de hotel incorrectos, o URL mal puesta | Revísalos con Winhotel; deja la URL vacía si usas la pública. | | «No se han encontrado reservas con el criterio especificado» | La habitación no tiene titulares con crédito en Winhotel | Compruébalo en Winhotel. | | Al buscar sale otro texto de error | Mensaje devuelto por Winhotel (credenciales, códigos…) | Resuélvelo con Winhotel según el texto. | | Al buscar sale un error «TypeError…» | Winhotel devuelve titulares pero ninguna reserva vigente hoy para esa habitación | Revisa las fechas de la reserva en Winhotel. | | «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Ágora no creó el albarán, falta el Producto, o Winhotel falló después de crear el albarán | Mira si el albarán existe en Ágora y el cargo en Operaciones hoteleras → Cargos; revisa el Producto. | | La ventana dice que el cargo se generó, pero no está en Winhotel | Winhotel rechazó el cargo sin error técnico y la integración no lo detecta | Mira «Pedido externo (response)» en Operaciones hoteleras → Cargos y haz el cargo a mano. | | La ventana se queda cargando y sale «Request timed out» | La acción no se abre dentro de Ágora | Marca «Mostrar Urls en un diálogo de Ágora». | | «Integración pausada» | FOS ha pausado la integración | Contacta con soporte. | ## Preguntas frecuentes ### ¿Cómo conecto Winhotel con Ágora? Con Connect Manager: FOS crea la integración con el acceso a la API de Winhotel, se elige el producto y el cliente y, en Ágora, se añade una acción personalizada con la URL de cargo. ### ¿Qué titular recibe el cargo si la habitación tiene varios? El que elija el camarero en el desplegable Cliente; por defecto, el primero que devuelve Winhotel. ### ¿Se manda el detalle de lo consumido? No. Winhotel recibe el total con IVA y el número del albarán; el detalle queda en el albarán de Ágora. ### ¿Se anula el cargo en Winhotel si anulo el albarán en Ágora? No. La anulación hay que hacerla también en Winhotel. ### ¿Bloquea el cargo si se supera el crédito? No: la ventana enseña el límite de crédito del titular, pero deja cargar. ## Referencias - [Ficha de la integración con Winhotel](https://connectmanager.es/integraciones/winhotel) - [Hotel Hub: cómo funciona](https://connectmanager.es/docs/hotel-hub-como-funciona) - [Integración de Sihot con Ágora](https://connectmanager.es/docs/integracion-sihot-agora): la misma configuración de acción personalizada en Ágora - [Direcciones IP de Connect Manager](https://connectmanager.es/docs/direcciones-ip-connectmanager) --- # Fidelización: conectar el club con Ágora Portal: Fidelización · Primeros pasos URL: https://connectmanager.es/docs/fidelizacion-conectar-con-agora Actualizado: 2026-10-03 La integración de **Fidelización de Connect Manager con Ágora** conecta el club de fidelización de un grupo (monedero de saldo, sellos o puntos, cupones y niveles) con el TPV Ágora de cada local: en caja se identifica al socio, se ven su saldo y sus recompensas, se paga con saldo y, al cerrar la factura, se acumula lo que corresponda y se imprime un resumen al pie del ticket. Este manual es para el técnico que deja el club funcionando en el TPV: qué se configura en Connect Manager, qué en Ágora, cómo funciona y cómo comprobarlo. ## Qué hace la integración - **Identifica al socio en caja** por su código de socio (el QR o código de barras de su tarjeta del móvil o de su área privada), por su teléfono, con o sin prefijo, o por un código adicional de su ficha (por ejemplo, una tarjeta física). Solo encuentra socios activos de un grupo al que pertenezca el local. - **Enseña en Ágora un saludo con el saldo y las recompensas**: los cupones vigentes del socio para ese local y, si el local canjea el saldo como descuento, el monedero en tramos fijos (1, 2, 5, 10, 15, 20 y 40 € de serie) más «todo el saldo». - **Cobra con saldo** de una de dos maneras, a elegir por local: como forma de pago, desde una ventana del monedero que se abre en el TPV (acción personalizada) e inyecta el pago en el ticket; o como descuento, con la fidelización nativa de Ágora. - **Acumula al cerrar la factura** según el modelo del club: cashback en euros (porcentaje del local, con reglas por producto o familia y el multiplicador del nivel), sellos por visita o puntos por euro, con un cupón de recompensa al completar la tarjeta. Suma la visita y el gasto, recalcula el nivel y, si el club lo tiene activado, pide una reseña de Google. - **Imprime al pie del ticket** un bloque «WALLET» con el socio, los cupones aplicados, el saldo gastado, lo acumulado y el saldo restante. - **Deshace la venta al devolverla entera**: devuelve el saldo gastado, retira el cashback (aunque deje el saldo en negativo), libera cupones, quita sellos o puntos y descuenta la visita y el gasto. - **No duplica nada** si Ágora reenvía la misma factura, y **devuelve el saldo** en el acto si Ágora rechaza un pago hecho desde la ventana del monedero. - **Convive con otro programa de fidelización** en el mismo Ágora: lo que no es un socio del club se le pregunta al otro programa. - **Actualiza la tarjeta del móvil** del socio (Apple o Google Wallet) al registrar la venta. - Opcional: **emite en Ágora la factura de anticipo** de cada recarga de saldo, y el abono proporcional al gastarlo, a través del ACMS. ### Qué no hace - **No acumula en albaranes**: según la guía del integrador de Ágora, solo se notifican las facturas. - **No revierte sola una devolución parcial** ni la de un albarán: el ticket imprime «Devolucion registrada. Fidelizacion: revision manual.» y el saldo se ajusta a mano en la ficha del socio. Ninguna pantalla lista estas devoluciones pendientes. - **Una factura con varios socios** (varios albaranes) solo se procesa para el primero. - **Un cambio de forma de pago** de una factura ya emitida no se notifica, así que no se recalcula nada. - **En modo «Solo wallet»** la ventana descuenta saldo, pero no hay acumulación ni cupones en caja. - **No da de alta socios desde el TPV**: se dan de alta en el panel, en el portal de registro del club o por importación. - **Sin Api-Token**, la ventana del monedero pide el importe a mano y no inyecta el pago: hay que cobrarlo en Ágora con la forma de pago del saldo. - **La fidelización del TPV no pasa por el ACMS**: cada local lleva sus propias direcciones. ## Requisitos - **Ágora** con el módulo de Servicios de integración activo; su Api-Token solo hace falta para cobrar como forma de pago. El formato de las facturas se comprobó con Ágora 8.9.3; desde Ágora 9.0.2 el TPV exige además credenciales de integrador, que son de Connect Manager y ya están en el servidor. - **Salida a Internet**: el servidor de Ágora y el navegador del TPV tienen que llegar por HTTPS a `https://hub.connectmanager.es`. **No hace falta abrir puertos, ni exponer la API de Ágora, ni Zero Connect**: la ventana del monedero habla con la API local a través del propio TPV. - **El club creado** para el grupo en **Configuración → Portal público de clientes** y el local asignado a ese grupo. - **Una forma de pago propia para el saldo** en Ágora (modo forma de pago). - **Socios dados de alta**, con su código de socio (formato `CM26-XXXXXXXX`). - **Permisos en el panel de Fidelización**: «Fidelización: Configurar integración por local» (locales), «Fidelización: Activar por grupo» (club) y, si se usan, «Fidelización: Facturas de anticipo». **Quién hace qué.** **FOS** crea el club, incorpora el local al grupo, cambia el modo de canje en `/admin` y mantiene las credenciales de integrador. **El distribuidor** configura Ágora y la ficha del local en el panel de Fidelización. **El cliente** decide el modelo, el porcentaje de cashback, los tramos y los cupones. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Club y grupo | FOS, en Configuración → Portal público de clientes | Grupo Demo | Sí | | Local asignado al grupo | FOS o el técnico, en Configuración → Locales | Restaurante Demo Centro | Sí | | Modo de canje del saldo | Cliente y técnico | Forma de pago o Descuento | Sí | | Id de la forma de pago del saldo | Ágora: exportación de maestros (PaymentMethods) o la ficha de la forma de pago | Número entero, p. ej. 12 | Solo forma de pago | | Api-Token de Servicios de integración | Ágora | Cadena alfanumérica | Solo forma de pago | | Modelo del club | Cliente | Cashback, sellos, puntos o sin plan | Sí | | Porcentaje de cashback del local | Cliente | 5 (= 5 %) | En cashback (de serie es 0) | | Id de los TPV autorizados | Ágora | 1, 2 | No (vacío = todos) | | Tramos del monedero | Cliente | 2, 5, 10 | No | | Códigos de descuentos o promociones de Ágora para cupones | Ágora: «Descuento en Ticket» o promoción «Sólo clientes y tickets seleccionados» | HBD | Solo con esos cupones | | URLs del otro programa de fidelización | Proveedor del otro programa | https://otro-programa.example/api/socios/{memberId} | No | | URL y Api-Token del ACMS, e Ids del emisor | ACMS del grupo | https://acms-del-grupo.example | Solo facturas de anticipo | ## Configuración paso a paso ### 1. En Connect Manager: el club y el local - En **Configuración → Portal público de clientes**, abre el club (si no existe, lo da de alta FOS) y, en su subpágina **Fidelización**, elige el «Modelo» en «Modelo de fidelización»: Cashback (monedero €), Sellos por visita, Puntos por gasto o Sin plan (no acumula nada). Con sellos o puntos, rellena la meta, los sellos por visita o los puntos por euro y el «Cupón de recompensa al completar». - Elige el grupo en el selector de la cabecera: la lista de locales se filtra por él. - En **Configuración → Locales**, si el local no está en el grupo, usa **Asignar grupos** (menú «Más opciones» de la fila). «Incorporar local» y «Crear local nuevo» solo los ve FOS. - Pulsa **Configurar** y rellena: - «Fidelización activa»: enciéndelo. Apagado, la ventana del monedero y las URLs de Ágora contestan que el local no está activo. - «ID de forma de pago en Ágora» y «Token de API de Ágora» (modo forma de pago). - «Porcentaje de acumulación de cashback (%)»: 5 = 5 %. De serie es 0, que no acumula. - «Lista blanca de IDs de TPV (Cajas)»: los TPV que pueden abrir la ventana del monedero; vacío = todos. - «Importes de descuento del monedero (€)»: los tramos (solo en modo descuento). - «Ancho del ticket (columnas)»: 48 o 42. - «Reglas de cashback por categoría / producto (opcional)»: cada línea acumula según la primera regla que coincida («Coincidir por» nombre de producto o categoría / familia; «Efecto» % fijo, × del base o Excluir (0 %)). Las de familia solo funcionan si la factura de Ágora trae la familia en sus líneas. - «Otro programa: URL de validación de participantes» y «Otro programa: URL de envío de facturas» (paso 7). - «Google Place ID / enlace (reseñas)»: ver [Reseñas de Google](https://connectmanager.es/docs/fidelizacion-resenas-de-google). - Guarda y abre **Ver enlaces de integración** (menú «Más opciones»): ahí están las tres URLs del local. > [!WARNING] El campo de la forma de pago enseña «Ej.: FIDELITY_CM», pero la ventana del monedero solo entiende un número: con un texto descuenta el saldo y no inyecta el pago en el ticket. Pon siempre el Id numérico. ### 2. En Connect Manager: el modo de canje (solo si el local va a descontar) De serie todos los locales cobran el saldo como forma de pago. Para cambiarlo: - Entra en **/admin → Locales**, abre el local y ve a la pestaña **Ecosistema Conectado**. - Edita la fila «Fidelización ConnectManager» (si no existe: **Añadir Integración**, «Servicio / Proveedor» Fidelización ConnectManager (Loyalty)). - En «Cómo se canjea el saldo del cliente» elige Como descuento — Ágora pide los premios al servicio de fidelización y lo aplica al ticket y guarda. En este modo no hacen falta forma de pago ni Api-Token. Si no tienes acceso a `/admin`, pídeselo a FOS. > [!NOTE] Un solo modo por local: en modo descuento el servidor rechaza el cobro desde la ventana del monedero, para no cobrar el saldo dos veces. ### 3. En Ágora: forma de pago y Api-Token (modo forma de pago) - Crea una forma de pago para el saldo (por ejemplo, «Monedero club») para que el arqueo la separe del resto, y apunta su Id. - Localiza el Api-Token de Servicios de integración y el usuario al que pertenece: su perfil necesita los permisos del paso 4. ### 4. En Ágora: las consultas personalizadas Son dos ficheros XML que facilita FOS y que se copian en la carpeta `custom-queries` de la instalación de Ágora de cada local; Ágora los instala solo. - `cm-loyalty-attach.xml` («CM Asociar socio fidelización»): al cobrar con saldo, asocia el socio al ticket para que Ágora notifique esa factura y se acumule sobre lo pagado de otra forma. Da el permiso «Consulta: CM Asociar socio fidelización» al perfil del usuario del Api-Token. - `cm-loyalty-read.xml` («CM Leer socio del ticket»), recomendable: si el cajero ya identificó al socio en la fidelización de Ágora, la ventana del monedero lo carga sola. Permiso «Consulta: CM Leer socio del ticket». Si faltan, el cobro funciona igual; sin la primera, una compra pagada con saldo solo acumula si el socio también se identificó en la fidelización de Ágora. ### 5. En Ágora: la acción personalizada - En **Herramientas → Acciones personalizadas** crea una acción y pega la «URL para Acción Personalizada (IFrame)» tal cual, con sus marcadores; Ágora los rellena al abrirla. Tiene esta forma: `https://hub.connectmanager.es/loyalty/embed/TOKEN-DEL-LOCAL?user_id={user_id}&pos_id={pos_id}&ticket_id={ticket_id}&ticket_global_id={ticket_global_id}&introduced_value={introduced_value}`. - Marca la opción de mostrar la URL en un diálogo de Ágora y añade el permiso que crea la acción a los perfiles de los usuarios que vayan a cobrar con saldo. - Si el local solo quiere gastar saldo, sin acumular ni cupones, enciende antes en «Ver enlaces de integración» el interruptor «Solo wallet — gastar saldo sin los detalles de la factura»: la URL pasa a llevar `wallet_only=1` y no hace falta el paso 6. En modo descuento la ventana es opcional: consulta saldo y movimientos, pero no cobra. ### 6. En Ágora: las URLs de fidelización - En **Servicios de integración → Fidelización**, copia la «URL para Validación de Participantes» en el campo de validación de participantes. Deja `{member_id}` tal cual: Ágora pone ahí el código leído. Forma: `https://hub.connectmanager.es/api/loyalty/TOKEN-DEL-LOCAL/member/{member_id}`. - Copia la «URL para Envío de Facturas» en el campo de envío de facturas. Forma: `https://hub.connectmanager.es/api/loyalty/TOKEN-DEL-LOCAL/invoices`. La URL de validación resuelve también los QR de cupón (códigos que empiezan por `CPNT`). Los cupones de tipo «Descuento predefinido en Ágora» o «Promoción predefinida en Ágora» necesitan que el código exista ya en Ágora; si no, Ágora ignora la recompensa. > [!WARNING] Cada local tiene sus propias URLs: el token identifica al local. Si el grupo replica la configuración desde Ágora Central (ACMS), comprueba que cada local se queda con las suyas. Tras «Rotar token», vuelve a pegar las tres en Ágora. ### 7. Opcional: otro programa de fidelización en el mismo Ágora Ágora solo admite una URL de validación y una de facturas. En Ágora van las de Connect Manager y, en **Configurar**, las del otro programa: en la de validación, si la dirección lleva `{memberId}` o `{member_id}` ahí se pone el código y, si no, se añade al final; a la de facturas se le reenvía la factura entera y su respuesta es la que ve Ágora. Solo funciona si los códigos de los dos programas no se solapan. El otro servidor tiene 5 segundos para contestar; si no contesta, Ágora recibe el «no encontrado» de Connect Manager. ### 8. Opcional: facturas de anticipo del monedero (ACMS) En **Configuración → Facturas de anticipo** se rellenan «Activación» («Activar facturación de anticipos», «Facturar recargas manuales», «Facturar recargas recurrentes»), «Conexión con el ACMS de Ágora» («URL del ACMS», «Api-Token» y **Probar conexión**), «Emisor de las facturas» (Ids de almacén/local, TPV, usuario, forma de pago y, si se usan, centro de venta y tarifa) y «Producto de anticipo y series» (producto, IVA, «Serie anticipos» y «Serie abonos», p. ej. `WANT` y `WABO`, con sus contadores). Cada recarga facturable genera una factura de anticipo simplificada (hasta 2.999 €; por encima, solo si el socio tiene datos de facturación) y cada consumo de ese saldo, su abono proporcional. Cashback, regalos e importaciones no se facturan, y un fallo de facturación no bloquea el saldo: se reintenta. ## Cómo funciona ### Modo descuento El cajero identifica al socio en la fidelización del ticket de Ágora. Ágora llama a la URL de validación con el código; Connect Manager busca al socio en los grupos del local y contesta con un saludo («Hola …, tu saldo disponible es de …») y las recompensas: un descuento por cada tramo que cubra el saldo («Descontar 5 € del monedero»), «Descontar hasta … (todo tu saldo)» y los cupones. El cajero elige. Al emitir la factura, Ágora la envía entera a la URL de facturas: Connect Manager descuenta lo que Ágora restó de verdad en la línea (nunca más que el premio elegido), canjea los cupones, acumula sobre lo pagado y contesta «accepted» con el texto a imprimir. Si algo no cuadra (saldo insuficiente, cupón agotado) contesta «rejected» con el motivo y, según la guía de Ágora, la factura no se cierra hasta corregirlo. ```mermaid sequenceDiagram participant C as Cajero participant TPV as TPV Ágora participant CM as Connect Manager C->>TPV: Identifica al socio con QR, código o teléfono TPV->>CM: GET validación de participante con el código CM-->>TPV: Saludo con saldo, tramos y cupones C->>TPV: Elige el premio y cobra el resto TPV->>CM: POST factura emitida con el premio CM->>CM: Descuenta saldo, canjea cupón y acumula CM-->>TPV: accepted y texto para el ticket TPV-->>C: Imprime el bloque WALLET ``` ### Modo forma de pago El cajero abre la acción personalizada desde el ticket. La ventana comprueba el token y la lista blanca, y abre una sesión de un solo uso de 5 minutos. Carga el socio que ya tenga el ticket o lo identifica con lector, cámara, NFC, código o teléfono, y enseña su saldo, si es «Válido aquí» y sus últimos movimientos. Con Api-Token lee el total del ticket y no deja cobrar más de ese total ni más saldo del disponible. Al cobrar, Connect Manager descuenta el saldo; la ventana asocia el socio al ticket, inyecta el pago con la forma de pago configurada (el ticket se cierra) y se cierra sola. Si Ágora rechaza el pago, el saldo se devuelve en el acto, una sola vez y con la caducidad que tenía. Al emitirse la factura, Ágora la envía a la URL de facturas y se acumula sobre la parte no pagada con saldo. ```mermaid sequenceDiagram participant C as Cajero participant V as Ventana monedero participant CM as Connect Manager participant TPV as TPV Ágora C->>V: Abre la acción personalizada V->>CM: Pide el saldo del socio V->>TPV: Lee el total del ticket C->>V: Pulsa cobrar V->>CM: Descuenta el saldo V->>TPV: Asocia el socio e inyecta el pago alt Ágora rechaza el pago V->>CM: Revierte el cobro CM-->>V: Saldo devuelto end TPV->>CM: POST factura emitida CM-->>TPV: accepted y texto para el ticket ``` ### Devoluciones Una devolución se procesa aunque el ticket de devolución no lleve el socio: se busca la venta original por su identificador (o por su número) y se actúa sobre el socio de esa venta. Se revierte entera si Ágora indica que es de ticket, de factura, por reapertura o por conversión a factura nominativa, o si no indica el origen pero devuelve exactamente lo que costó la venta. Si es parcial, de albaranes o no aparece la venta original, queda en revisión manual. Una devolución ya revertida no se repite. ```mermaid flowchart TD A[Llega una devolución] --> B{Total o importe igual a la venta} B -->|No| R[Revisión manual en el ticket] B -->|Sí| C{Venta original encontrada} C -->|No| R C -->|Sí| D{Ya revertida} D -->|Sí| E[Devolucion ya procesada] D -->|No| F[Reabona saldo, retira cashback y libera cupones y sellos] F --> G[Imprime DEVOLUCION - WALLET] ``` ### Lo que se acumula y se imprime El cashback es neto × porcentaje del local × multiplicador del nivel (con reglas, el porcentaje es la media ponderada de las líneas). En modo descuento el neto es el importe de la factura, que Ágora ya manda sin el descuento del monedero; en modo forma de pago, el importe menos lo cobrado con saldo. Los sellos son los de «Sellos por visita (ticket)» por factura y los puntos, neto × «Puntos por € gastado»; al llegar a la meta se asigna el cupón de recompensa. Con «Sin plan» no se crea ningún movimiento. El texto que se imprime tiene esta forma, a 48 o 42 columnas: ``` ================================================ WALLET ================================================ Cliente: Socio de ejemplo Cupon aplicado: Café de bienvenida Saldo redimido -5,00 EUR Acumulado hoy +0,75 EUR Saldo disponible 20,75 EUR ================================================ ``` Si Ágora reenvía una factura ya aceptada, recibe la misma respuesta; una rechazada se vuelve a procesar. Las URLs de Ágora admiten 300 peticiones por minuto y por IP, y la ventana del monedero, 60. ## Comprobar que funciona - En **Configuración → Locales**, el local aparece con «Fidelización activa». - Abre en un navegador la URL de validación con el código de un socio de prueba en lugar de `{member_id}`: debe devolver un JSON con `MemberId`, `DisplayText` y `Rewards`. Con un código inventado, `{"error":"Cliente no encontrado."}`. - Dale saldo al socio desde su ficha (**Administración → Clientes** → «Añadir saldo»; si hay facturas de anticipo, desmarca «Emitir factura de anticipo en Ágora»). - Modo descuento: identifica al socio en un ticket, aplica «Descontar 2 € del monedero» y factura. Se imprime el bloque WALLET y en el «Historial de saldo» del socio aparece «Consumo de saldo en ticket #…» con origen «Ágora TPV». - Modo forma de pago: abre la acción personalizada, identifica al socio, comprueba que sale el total y cobra. El ticket se cierra con la forma de pago del saldo y en la ficha aparece «Pago TPV (Ticket: …)». - Devuelve el ticket entero: se imprime «DEVOLUCION - WALLET» y el saldo vuelve. - Asigna un cupón al socio y comprueba que sale en las recompensas de Ágora. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «Este local no tiene la fidelización activada.» en la ventana, o «Configuración de local no válida o deshabilitada.» en las URLs | «Fidelización activa» apagado, o URL con un token anterior a «Rotar token». | Enciéndelo o vuelve a copiar las URLs. | | «Este TPV no está autorizado para el monedero.» | El TPV no está en la lista blanca. | Añádelo o vacía la lista. | | La ventana pide el importe a mano | Falta Api-Token o forma de pago, o Ágora rechazó leer el ticket por permisos. | Rellena los dos campos y revisa el perfil del usuario del token. | | «Este local canjea el saldo como descuento desde la fidelización de Ágora. No se puede cobrar desde esta ventana.» | Local en modo descuento. | Usa los premios de Ágora o cambia el modo. | | «Ágora rechazó el cobro: … La operación ha sido CANCELADA y el saldo devuelto al cliente.» | Forma de pago inexistente, ticket ya cerrado o permisos. | Revisa el Id de la forma de pago y los permisos; el saldo ya está devuelto. | | El motivo es «El integrador 'anonymous' no dispone de acceso al API 'add-payments'» | Ágora 9.0.2 o superior sin credenciales de integrador. | Avisa a FOS. | | Se descuenta el saldo pero el ticket no recibe el pago | Forma de pago escrita como texto, no como Id numérico. | Pon el Id numérico y corrige el saldo con «Ajuste manual» en el «Historial de saldo». | | «Error grave: No se pudo registrar en el ticket de Ágora ni revertir el saldo automáticamente.» | Ágora rechazó el pago y la reversión no llegó. | Corrige a mano el movimiento cuyo número (TXN) indica. | | «Timeout al conectar con Ágora (15s).» | El TPV no contestó a la ventana. | Reintenta; si se repite, revisa el TPV. | | Ágora no reconoce al socio («Cliente no encontrado.») | Código mal leído, socio inactivo o de otro club, o URL sin {member_id}. | Revisa la ficha del socio y la URL. | | «El cliente no está autorizado para usar el club en este local.» | El local no está en el grupo del socio. | Usa «Asignar grupos». | | La factura no se cierra: «Saldo insuficiente. Disponible: … €» o un aviso de cupón («Cupón ya canjeado el máximo de veces por este cliente.», «El cupón ha caducado.», «Este cupón no vale en este local.») | El saldo o el cupón cambiaron entre la identificación y el cierre. | Quita el premio y aplica otro. | | Un cupón de descuento o promoción de Ágora no se aplica | El código no existe en Ágora con ese tipo. | Créalo en Ágora con el código exacto. | | No acumula nada | Porcentaje en 0, modelo «Sin plan», ticket cerrado como albarán, socio no asociado o local en «Solo wallet». | Revisa porcentaje y modelo, factura el ticket e instala «CM Asociar socio fidelización». | ## Preguntas frecuentes ### ¿Cómo conecto el club de fidelización de Connect Manager con Ágora? Configura el local en **Configuración → Locales → Configurar**, abre «Ver enlaces de integración» y pega en Ágora la URL de la acción personalizada (cobrar con saldo) y las de validación de participantes y envío de facturas (acumular y aplicar premios). ### ¿Es mejor cobrar el saldo como forma de pago o como descuento? Como forma de pago, el saldo sale en el arqueo como un cobro más y se puede gastar cualquier importe. Como descuento no hacen falta Api-Token ni acción personalizada, y el saldo se aplica por tramos o entero. Solo uno por local. ### ¿Hay que abrir puertos o instalar Zero Connect para la fidelización? No. Ágora llama a Connect Manager por HTTPS y la ventana del monedero habla con la API local a través del TPV. Basta con salida a Internet hacia `hub.connectmanager.es`. ### ¿Puedo usar el club de Connect Manager y otro programa de fidelización en el mismo Ágora? Sí: en Ágora van las URLs de Connect Manager y en la ficha del local las del otro programa, que recibe lo que no es nuestro. Los códigos de los dos no pueden solaparse. ### ¿Qué pasa con el saldo si se devuelve un ticket pagado con el monedero? Si la devolución es total, el saldo vuelve solo y se retira el cashback de esa venta. Si es parcial, el ticket avisa de revisión manual y se ajusta en la ficha del socio. ## Referencias - [Apple Wallet: la tarjeta del club en el iPhone](https://connectmanager.es/docs/fidelizacion-apple-wallet) - [Google Wallet: la tarjeta del club en Android](https://connectmanager.es/docs/fidelizacion-google-wallet) - [WhatsApp y Bird: mensajes y campañas del club](https://connectmanager.es/docs/fidelizacion-whatsapp-bird) - [Reseñas de Google](https://connectmanager.es/docs/fidelizacion-resenas-de-google) - [Pagos con Redsys](https://connectmanager.es/docs/pagos-redsys) (cobros online del club: tarjetas regalo, cuotas y entradas) - [Proveedores de envío de correo](https://connectmanager.es/docs/correo-proveedores-de-envio) - [Programa de fidelización de Connect Manager](https://connectmanager.es/programa-de-fidelizacion) - Guía del Integrador de Ágora, apartado «Integración con Sistemas de Fidelización» (la facilita Ágora). --- # Apple Wallet: la tarjeta del socio en el iPhone Portal: Fidelización · Tarjeta en el móvil URL: https://connectmanager.es/docs/fidelizacion-apple-wallet Actualizado: 2026-10-03 La integración de **Apple Wallet** del club de fidelización de Connect Manager pone la tarjeta de socio en la app Cartera del iPhone, con su saldo al día y el código que se escanea en el TPV Ágora para identificarle. Este manual es para el técnico: qué tiene que haber en el servidor, qué se configura en cada club, cómo se genera y se actualiza el pase y cómo diagnosticarlo cuando no llega o no cambia. ## Qué hace la integración - **Emite a cada socio su tarjeta del club** con su nombre, su saldo, su código de socio y un código escaneable (QR, PDF417 o Código 128) cuyo valor es el código de socio: el mismo que Ágora valida en la fidelización. - **La mantiene al día sola**: cada movimiento de saldo, cambio de nivel o de membresía y cada cambio de diseño del club reescribe el pase y avisa al iPhone, que se descarga la versión nueva. El campo del saldo lleva el aviso «Tu saldo ahora es …» en la pantalla de bloqueo. - **Muestra los avisos de las campañas** del canal «Tarjeta del móvil» en la pantalla de bloqueo y los deja 30 días en el reverso. - **Personaliza la tarjeta por club**: logo cuadrado y logo apaisado, colores de fondo, texto y etiquetas, qué dato va en cada una de las cuatro posiciones del frontal, formato del código y, si el club tiene niveles, el color del nivel de cada socio como fondo. - **Rellena el reverso** con «CÓMO FUNCIONA» (un texto según el modelo del club), la membresía y el nivel del socio, «INVITA A UN AMIGO» con su código y «Invitar por WhatsApp», hasta 8 enlaces de interés, «PEDIR A DOMICILIO» si el club lo elige, «TU ÁREA PRIVADA» («Ver mi perfil») y «ACTUALIZAR TARJETA» («Actualizar ahora»). - **Da acceso al área privada desde el pase**, si el club lo enciende: el enlace del reverso es personal, entra sin pedir el correo y solo deja mirar. En ese caso el pase no se puede compartir desde Cartera. - **Avisa cerca de los locales**: hasta 10 locales del club con su ubicación; el iPhone saca la tarjeta en la pantalla de bloqueo con el nombre público del local. - **Anula la tarjeta** si el socio pierde el móvil: pasa a «Tarjeta anulada», sin código ni saldo, y deja de actualizarse. - **Emite también las entradas** de la agenda del club como pase de evento. - **Funciona en el Apple Watch**: con Código 128 el pase lleva además el mismo código en QR, porque el reloj no pinta códigos de barras 1D. ### Qué no hace - **No usa cuentas de Apple del cliente.** Todos los clubes firman sus pases con el certificado de Connect Manager; no se puede emitir con el identificador de pase (Pass Type ID) de un cliente. - **No actualiza una entrada de evento** ya añadida a Cartera si el evento cambia o se cancela. - **No repite un aviso con el mismo texto**: iOS solo avisa cuando el valor cambia, así que una campaña con el mismo texto que la anterior no suena. - **Los enlaces para añadir la tarjeta caducan**: 1 hora en la pantalla final del portal de registro, 1 día en el área privada y 14 días en los correos y en WhatsApp. - **No cambia los pases al instante al tocar el diseño**: se reescriben en segundo plano, socio a socio, y tardan unos minutos. ## Requisitos - **En el servidor de Connect Manager** (lo mantiene FOS): el certificado de tipo Pass Type ID en formato .p12, vigente, con su contraseña; el Pass Type ID y el Team ID que coinciden con ese certificado; el secreto del servicio web, de al menos 16 caracteres; y una dirección pública https para el servicio web de los pases. Todo se revisa con `php artisan loyalty:check-apple-cert`. - **La cola de trabajos funcionando**: las actualizaciones de los pases van encoladas. - **El club creado** en **Configuración → Portal público de clientes**, con su «Título de la aplicación» (sale como organización y nombre del club en el pase) y su logo. - **La integración con el TPV funcionando** (ver [Fidelización: conectar el club con Ágora](https://connectmanager.es/docs/fidelizacion-conectar-con-agora)), para que el código de la tarjeta sirva en caja. - **Un lector en el TPV que lea el formato elegido**: QR y PDF417 necesitan un lector 2D o cámara; un lector láser 1D solo lee Código 128. - **Socios con iPhone** y la app Cartera. - **Permisos en el panel**: «Fidelización: Activar por grupo» para editar Monederos y «Fidelización: Emitir wallet passes» para «Enviar wallet». **Quién hace qué.** **FOS** mantiene el certificado y el servidor. **El técnico** configura el diseño en Monederos, elige el formato del código según el lector del local y hace las pruebas. **El cliente** aporta logos, colores, textos y enlaces. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Logotipo cuadrado de los pases | Cliente | Imagen 1:1, mínimo 660 × 660 px, máximo 2 MB | Recomendado (si no, el del portal) | | Logotipo apaisado para Apple | Cliente | PNG con fondo transparente, 480 × 150 px | Recomendado | | Colores de fondo, texto y etiquetas | Cliente | Hexadecimal de 6 cifras, p. ej. #0f172a | No (fondo: color del portal; texto blanco; etiquetas gris claro) | | Etiqueta del saldo | Cliente | «Saldo» | No («Saldo Acumulado») | | Dato de cada posición del frontal | Técnico y cliente | Cabecera: Saldo · Principal: Nombre del cliente · Secundario: Código de socio · Auxiliar: Nombre del club | Sí (esos son los de serie) | | Formato del código | Técnico, según el lector del TPV | QR, PDF417 o Código 128 | Sí (QR de serie) | | Enlaces de interés | Cliente | https://…, tel:… o mailto:…, hasta 8 | No | | Ubicación de cada local | Delivery propio → Configuración → Locales → Ubicación y contacto | Latitud y longitud | Solo para avisos por cercanía | | Certificado, Pass Type ID, Team ID y secreto del servicio web | FOS (cuenta de Apple de Connect Manager) | — | Ya en el servidor | ## Configuración paso a paso ### 1. En el servidor de Connect Manager (FOS) - Ejecuta `php artisan loyalty:check-apple-cert`. Enseña la organización, el Pass Type ID, el Team ID y las fechas de validez del certificado, y debe decir «El certificado está VIGENTE ahora mismo.» y que el Pass Type ID y el Team ID coinciden con la configuración. - En el mismo informe, el apartado del servicio web debe indicar que el pase llevará la dirección del servicio y un secreto correcto. Un pase con dirección de servicio y sin secreto lo rechaza iOS. - Si el certificado ha caducado, FOS lo renueva en su cuenta de Apple Developer, lo sube al servidor con su contraseña y vuelve a desplegar. ### 2. En Connect Manager: el diseño de la tarjeta Ve a **Configuración → Portal público de clientes**, abre el club y entra en la subpágina **Monederos**. El mismo formulario está en **Delivery propio → Tienda → Pases**: los dos guardan la misma tarjeta. - «Logotipo de los pases»: sube el «Logotipo para Apple/Google Wallet» (cuadrado, del que sale el icono) y el «Logotipo apaisado para Apple Wallet» (Apple lo pinta en una banda de 160 × 50 puntos y un logo cuadrado queda diminuto). Para quitar el apaisado, «Quitar el logotipo apaisado (Apple usará el de arriba)». - En «Personalizador de tarjetas», en «Selecciona el monedero a personalizar», elige Apple Wallet (iOS). El selector solo cambia lo que se ve: lo tocado en la otra plataforma también se guarda. - «Etiqueta del saldo (Apple y Google)»: la misma para las dos tarjetas. - «Apariencia y colores»: «Color de fondo de tarjeta», «Color de texto primario» y «Color de etiquetas», siempre en hexadecimal de seis cifras. - «Distribución de campos»: elige el dato de «Campo de cabecera (arriba a la derecha)», «Campo principal (gran tamaño)», «Campo secundario (bajo el principal, a la izquierda)» y «Campo auxiliar (misma fila, a la derecha)» entre Nombre del cliente, Saldo, Código de socio, Nombre del club, Nivel de fidelización, Membresía de socio (nivel del club) y Ocultar / ninguno. Un dato solo puede estar en una posición. Después elige el «Formato de código de barras»: Código QR (recomendado), PDF417 (código 2D clásico) o Código 128 (código de barras 1D). - «Detalles del pase»: «Enlaces de interés» (cada uno con «Título», «Qué es» —Un enlace o Un texto— y su «Dirección» o «Texto»), «Código de invitación del socio» (necesita el programa de referidos y el portal de registro encendidos), «Entrar al área privada desde el pase», «Botón del pase de Google» (en Apple salen los dos en el reverso), «Avisar cerca de los locales» (indica cuántos locales tienen la ubicación puesta) y «Color del nivel en la tarjeta» (solo aparece si el club tiene niveles activos con color). - Comprueba el resultado en «Vista previa del monedero» y guarda. Si ya hay pases emitidos, sale el aviso «Actualizando los pases ya emitidos»: recibirán el diseño nuevo en unos minutos. > [!NOTE] Cambiar el logotipo o el «Título de la aplicación» en la subpágina **Apariencia** también reescribe los pases de Apple ya emitidos. ### 3. Entregar la tarjeta a los socios - **En su área privada** del portal del club, con el botón de Apple Wallet. - **Por correo**: la bienvenida y el «Envío del wallet para descarga» (**Comunicaciones** del club) llevan el botón «Añadir mi tarjeta al móvil». **Por WhatsApp**, ver [WhatsApp y Bird](https://connectmanager.es/docs/fidelizacion-whatsapp-bird). - **A mano**, desde la ficha del socio con **Enviar wallet** (necesita el permiso «Fidelización: Emitir wallet passes»). - **Al terminar el alta** en el portal de registro del club. - **En «Mi cuenta»** de la tienda online propia del grupo. Los enlaces de los correos llevan a una página que, en un iPhone, abre directamente el pase de Apple; en Android lleva al de Google y en un ordenador enseña los dos botones. ### 4. En Ágora No hay nada específico: el código del pase es el código de socio y se lee en la fidelización de Ágora como cualquier otro. Basta con tener puesta la URL de validación de participantes y elegir un formato que el lector del local lea. ## Cómo funciona ### Alta del pase en el iPhone El socio abre un enlace firmado. Connect Manager compone el pase con el contenido completo del club (colores, campos, código y reverso), lo firma con el certificado de Connect Manager y lo guarda. El número de serie es el código de socio y cada pase lleva su propio token, calculado a partir de ese número, para hablar con el servicio web. Al añadirlo, el iPhone se registra en el servicio web de pases de Connect Manager (las rutas `/passkit/v1/…`), que apunta ese dispositivo para avisarle de los cambios. ```mermaid sequenceDiagram participant I as iPhone participant CM as Connect Manager I->>CM: Abre el enlace firmado CM->>CM: Compone y firma el pase CM-->>I: Pase con el código de socio I->>I: El socio lo añade a Cartera I->>CM: Registra el dispositivo con el token del pase CM-->>I: Registro guardado ``` ### Actualizaciones Cuando cambia algo del socio (una factura en Ágora, una recarga, un cambio de nivel) o del club (el diseño), se encola una sincronización de ese socio. El trabajo reconstruye el pase entero —así un campo que se oculta desaparece también de los pases ya emitidos—, lo guarda y avisa a APNs, el servicio de notificaciones de Apple, para cada iPhone registrado. El iPhone pide entonces la versión nueva al servicio web y, si el saldo ha cambiado, enseña «Tu saldo ahora es …». Si la sincronización falla se reintenta hasta 3 veces, cada 30 segundos, y los cambios seguidos del mismo socio se agrupan en una sola. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant APNs as Apple APNs participant I as iPhone TPV->>CM: Factura con socio CM->>CM: Encola la actualización del pase CM->>APNs: Aviso de pase cambiado APNs->>I: Aviso de actualización I->>CM: Pide la última versión del pase CM-->>I: Pase nuevo con el saldo I->>I: Muestra Tu saldo ahora es ``` ### Avisos de campaña Una campaña con el canal «Tarjeta del móvil» (**Administración → Campañas**) guarda el aviso en el socio (se conservan los 5 últimos), reescribe el pase con el aviso en el reverso y lo envía como cualquier actualización: al cambiar el texto, iOS lo enseña en la pantalla de bloqueo. El aviso se queda 30 días y solo llega a quien tiene la tarjeta añadida. Las campañas de este canal se envían a un ritmo de 5 socios por segundo. ### Seguridad - El token de cada pase solo sirve para ese pase: con un pase propio no se puede descargar el de otro socio. Los pases emitidos antes de este cambio, que llevan el secreto común antiguo, se rechazan y hay que volver a enviarlos. - Los enlaces para añadir la tarjeta van firmados y caducan; uno caducado lleva al acceso del portal del club con un aviso. - «Actualizar ahora» lleva su propia firma, no necesita sesión y admite 10 pulsaciones por minuto. ## Comprobar que funciona - FOS: `php artisan loyalty:check-apple-cert` dice que el certificado está vigente y que coincide con la configuración. - Guarda Monederos y revisa la vista previa. - Con un socio de prueba con correo, pulsa **Enviar wallet**, abre el correo en un iPhone y añade la tarjeta. - En la ficha del socio, pestaña «Wallet (Apple / Google)», aparece el pase de Apple Wallet con su fecha de emisión. - Escanea la tarjeta en Ágora: el socio se identifica. - Añade 1 € de saldo desde la ficha: en unos segundos la tarjeta cambia y sale «Tu saldo ahora es …». - FOS puede comprobar los dispositivos registrados con `php artisan loyalty:apple-push-test CM26-XXXXXXXX --dry` y, sin `--dry`, mandar un aviso real y ver la respuesta de Apple. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | El iPhone no deja añadir la tarjeta | Certificado caducado o que no coincide con el Pass Type ID o el Team ID, o servicio web sin secreto. | FOS: loyalty:check-apple-cert y renovar o corregir. | | «Apple Wallet no configurado. Contacte al administrador.» | No hay certificado en el servidor. | Avisa a FOS. | | «Error al generar la firma del pase de Apple Wallet.» | Falló la firma (certificado o contraseña) o la preparación de las imágenes. | FOS revisa el registro del servidor. | | El enlace lleva al acceso del portal con «El enlace para añadir tu tarjeta al móvil ha caducado. Inicia sesión y vuelve a generarlo desde tu área.» | Enlace caducado. | Vuelve a enviar la tarjeta o que el socio la descargue desde su área privada. | | La tarjeta no se actualiza | El iPhone no está registrado, la cola está parada o falló el aviso a Apple. | «Resincronizar saldo» en la pestaña «Wallet (Apple / Google)» de la ficha (fuerza el aviso aunque no haya cambios); el socio puede pulsar «Actualizar ahora» en el reverso. FOS: loyalty:apple-push-test. | | El lector del TPV no lee la tarjeta | Lector láser 1D con código QR o PDF417. | Elige Código 128 en «Formato de código de barras»: los pases ya emitidos se reescriben. | | El logo sale diminuto | Solo hay logotipo cuadrado. | Sube el «Logotipo apaisado para Apple Wallet». | | «Tiene que ser un color hex, por ejemplo #926f2d.» | Color en otro formato. | Escríbelo como #rrggbb. | | «Ese dato ya está en otra posición de la tarjeta.» | El mismo dato en dos posiciones. | Cambia una de ellas o ponla en «Ocultar / ninguno». | | En el registro: «Pase de Apple con el token global antiguo: hay que reemitirlo.» | Pase emitido antes del token por pase. | Vuelve a enviar la tarjeta al socio para que la sustituya. | | Un aviso de campaña no sonó | Mismo texto que el aviso anterior, o el socio no tiene la tarjeta de Apple. | Cambia el texto del aviso. | ## Preguntas frecuentes ### ¿El restaurante necesita una cuenta de desarrollador de Apple para tener su tarjeta en Apple Wallet? No. Los pases se firman con el certificado de Connect Manager; en cada club solo se configura el diseño: logos, colores, campos y enlaces. ### ¿Cómo se actualiza el saldo de la tarjeta de Apple Wallet después de pagar en Ágora? Al registrar la factura, Connect Manager reescribe el pase y avisa al iPhone a través de Apple; el iPhone descarga la versión nueva en segundos y muestra «Tu saldo ahora es …». ### ¿Qué formato de código elijo para que el TPV Ágora lea la tarjeta del iPhone? QR si el lector del local es 2D o con cámara; Código 128 si es un láser 1D. Con Código 128 el Apple Watch enseña el mismo código en QR. ### ¿Qué hago si un socio pierde el iPhone? En su ficha, pestaña «Wallet (Apple / Google)», pulsa «Anular pases»: la tarjeta queda anulada, deja de actualizarse y el enlace personal de su área privada deja de valer. Después envíale la tarjeta de nuevo con «Enviar wallet». ### ¿Se pueden mandar notificaciones a la tarjeta de Apple Wallet? Sí: con una campaña del canal «Tarjeta del móvil» el aviso sale en la pantalla de bloqueo y queda 30 días en el reverso. Además, cada cambio de saldo avisa solo. ## Referencias - [Ficha de Apple Wallet en el catálogo](https://connectmanager.es/integraciones/apple-wallet) - [Fidelización: conectar el club con Ágora](https://connectmanager.es/docs/fidelizacion-conectar-con-agora) - [Google Wallet: la tarjeta del club en Android](https://connectmanager.es/docs/fidelizacion-google-wallet) - [WhatsApp y Bird: mensajes y campañas del club](https://connectmanager.es/docs/fidelizacion-whatsapp-bird) - [Apple Wallet para desarrolladores](https://developer.apple.com/wallet/) - [Documentación de Apple sobre pases de Wallet](https://developer.apple.com/documentation/walletpasses) --- # Google Wallet: la tarjeta del socio en Android Portal: Fidelización · Tarjeta en el móvil URL: https://connectmanager.es/docs/fidelizacion-google-wallet Actualizado: 2026-10-03 La integración de **Google Wallet** del club de fidelización de Connect Manager pone la tarjeta de socio en la app Google Wallet de los móviles Android, con el saldo al día, avisos en la propia tarjeta y el código que se escanea en el TPV Ágora para identificar al socio. Este manual explica al técnico cómo se organiza en Google (emisor, clase y objeto), qué se configura en cada club, cómo se actualiza y qué límites pone Google. ## Qué hace la integración - **Emite la tarjeta del club en Google Wallet**: arriba el nombre del club y su logo, como título el «Nombre del programa», el saldo con su etiqueta y el código de socio en QR, PDF417 o Código 128 (o en texto, si se elige no poner código de barras). En los detalles: el nombre y el código del socio (Google los enseña siempre), hasta dos datos más, su membresía y su nivel. - **Guarda la marca del club en una «clase» de Google**, una por club: nombre del programa, color de fondo, logo, imagen de portada, enlaces de interés y ubicaciones de los locales. Al guardar Monederos o Apariencia se sube a Google y se ve en todas las tarjetas del club, también en las ya guardadas. - **Guarda los datos de cada socio en su «objeto»**: saldo, nombre, código, botón, datos de los detalles y franja del nivel. Se actualizan con cada movimiento y Google avisa al socio cuando cambia el saldo. - **Enseña el nivel con su color**: Google no deja cambiar el fondo de una tarjeta suelta, así que el nivel va en una franja con su color y su nombre (1032 × 336 px) en el lugar de la portada. - **Manda los avisos de las campañas** del canal «Tarjeta del móvil» como mensajes con notificación, que se quedan 30 días en los detalles de la tarjeta. - **Pone un botón en el frontal**: «Ver mi perfil» (el área privada del socio) o «Pedir a domicilio» (la tienda online propia del grupo, si está publicada). - **Añade enlaces en los detalles**: «Tu área privada», «Invitar por WhatsApp», los enlaces de interés del club y «Actualizar mi tarjeta». - **Avisa cerca de los locales**: hasta 10 locales con su ubicación; Google avisa al socio al pasar cerca si lo tiene activado en su móvil. - **Anula la tarjeta** (móvil perdido o socio de baja): pasa a inactiva. - **Emite las entradas** de la agenda del club, con una clase propia por evento que se actualiza al editar el evento. ### Qué no hace - **Más de 3 avisos con notificación al día por tarjeta.** A partir del tercero Google contesta con error de cuota y el aviso se guarda en los detalles, pero sin notificación. Según los límites de Google, el aviso de cambio de saldo cuenta para el mismo tope. - **Un color de fondo distinto por socio**: el color es del club; el nivel va como franja. - **Saber si el socio guarda o borra la tarjeta**: Google no lo comunica. Solo se sabe cuándo abrió el enlace para añadirla, y eso es lo que enseña su ficha. - **Guardar más de 5 avisos por socio** (Google admite 10 por tarjeta; se dejan los 5 últimos). - **Usar la cuenta de Google del cliente**: todas las tarjetas salen de la cuenta de emisor de Connect Manager. - **Imágenes en direcciones privadas**: Google descarga logos y portadas desde sus servidores, así que tienen que estar en una dirección pública https. - **Llevar a todos los socios los cambios que viven en su tarjeta** (datos de los detalles, código, botón): se reenvían solo a los socios que han abierto el enlace de Google. La marca de la clase sí llega a todos. ## Requisitos - **En el servidor de Connect Manager** (lo mantiene FOS): el Issuer ID de la cuenta de emisor de Connect Manager en Google Wallet y la clave JSON de su cuenta de servicio, subida en base64. Se revisa con `php artisan loyalty:google-wallet-check`. - **Una dirección pública https** del hub, desde la que Google pueda descargar el logo, la portada y las franjas de nivel. - **La cola de trabajos funcionando**: las actualizaciones van encoladas. - **El club creado** en **Configuración → Portal público de clientes**, con su «Título de la aplicación» (sale como nombre del emisor encima del título) y su logo. - **La integración con el TPV funcionando** (ver [Fidelización: conectar el club con Ágora](https://connectmanager.es/docs/fidelizacion-conectar-con-agora)) y un lector que lea el formato elegido: QR y PDF417 necesitan lector 2D o cámara; un láser 1D solo lee Código 128. - **Socios con Android** y Google Wallet; para recibir los avisos, las notificaciones de Wallet activadas en el móvil. - **Permisos en el panel**: «Fidelización: Activar por grupo» para editar Monederos y «Fidelización: Emitir wallet passes» para «Enviar wallet». **Quién hace qué.** **FOS** mantiene la cuenta de emisor y la cuenta de servicio. **El técnico** configura el diseño en Monederos, elige el formato del código y hace las pruebas. **El cliente** aporta nombre del programa, colores, logos, portada y enlaces. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Nombre del programa | Cliente | «Club Demo»; Google recomienda 20 caracteres como mucho | No (hereda el título de la aplicación) | | Color de fondo | Cliente | Hexadecimal de 6 cifras, p. ej. #926f2d | No (color principal del portal) | | Logotipo cuadrado | Cliente | 1:1, mínimo 660 × 660 px, con margen alrededor (Google lo recorta en círculo), máximo 2 MB | Recomendado (si no, el del portal) | | Imagen de portada | Cliente | Apaisada, 1032 × 336 px (3:1), máximo 2 MB | No | | Etiqueta del saldo | Cliente | «Saldo»; Google recomienda 9 caracteres como mucho | No («Saldo Acumulado») | | Dos datos para los detalles | Técnico y cliente | Nombre del club, Saldo… | No | | Formato del código | Técnico, según el lector del TPV | QR, PDF417, Código 128 o sin código | Sí (QR de serie) | | Botón del frontal | Cliente | Ver mi perfil o Pedir a domicilio | Sí (Ver mi perfil de serie) | | Enlaces de interés | Cliente | https://…, tel:… o mailto:…; Google recomienda 4 por tarjeta | No | | Ubicación de cada local | Delivery propio → Configuración → Locales → Ubicación y contacto | Latitud y longitud | Solo para avisos por cercanía | | Issuer ID y cuenta de servicio | FOS | — | Ya en el servidor | ## Configuración paso a paso ### 1. En el servidor de Connect Manager (FOS) - Ejecuta `php artisan loyalty:google-wallet-check`. Comprueba el Issuer ID, que la clave se lee como JSON con su `client_email` y su `private_key`, y pide un token a Google. Tiene que terminar con «Token OAuth obtenido … Google Wallet autentica correctamente.». - Si sale `invalid_grant`, la clave de la cuenta de servicio se ha rotado o borrado en Google Cloud: FOS genera una nueva y la sube en base64. ### 2. En Connect Manager: el diseño de la tarjeta Ve a **Configuración → Portal público de clientes**, abre el club y entra en **Monederos** (o en **Delivery propio → Tienda → Pases**, que edita la misma tarjeta). - «Logotipo de los pases»: sube el «Logotipo para Apple/Google Wallet», cuadrado y con margen alrededor de la marca. - En «Selecciona el monedero a personalizar» elige Google Wallet (Android). Lo tocado en Apple también se guarda. - «Etiqueta del saldo (Apple y Google)». - «Apariencia y colores»: «Color de fondo de tarjeta» (el color del texto lo elige Google, blanco o negro, según el fondo), «Nombre del programa» e «Imagen de portada» (se recorta al centro a 3:1). Para quitarla, «Quitar la imagen de portada». - «Detalles y escáner»: «Dato en los detalles (1)» y «Dato en los detalles (2)» (el nombre y el código ya salen siempre, y el nivel y la membresía también si el socio los tiene) y «Formato de código escaneable»: Código QR (recomendado), PDF417 (código 2D), Código 128 (código de barras 1D) o Sin código de barras (se muestra el código de socio en texto). - «Detalles del pase»: «Enlaces de interés», «Código de invitación del socio», «Entrar al área privada desde el pase», «Botón del pase de Google» (Ver mi perfil o Pedir a domicilio; la segunda solo se puede elegir con la tienda online publicada), «Avisar cerca de los locales» y «Color del nivel en la tarjeta». - Guarda. Deben salir «Tarjeta de Google Wallet actualizada» (la marca, los enlaces del club y las ubicaciones llegan a todas las tarjetas en unos minutos) y, si hay socios con la tarjeta, «Actualizando los pases ya emitidos». > [!NOTE] Guardar la subpágina **Apariencia** también vuelve a subir la clase, porque la tarjeta hereda de ahí el color principal y el logo cuando no hay uno propio. Y cambiar la ubicación de un local en Delivery propio actualiza las ubicaciones de la clase. ### 3. Entregar la tarjeta a los socios Los mismos caminos que en Apple: el botón de Google Wallet del área privada, la bienvenida y el «Envío del wallet para descarga» por correo, WhatsApp (ver [WhatsApp y Bird](https://connectmanager.es/docs/fidelizacion-whatsapp-bird)), **Enviar wallet** desde la ficha del socio, la pantalla final del portal de registro y «Mi cuenta» de la tienda online. En un móvil Android, la página del enlace lleva directamente a guardar la tarjeta en Google. ### 4. En Ágora Nada específico: el código de la tarjeta es el código de socio, que Ágora valida con la URL de validación de participantes. ## Cómo funciona ### Emisor, clase y objeto Todas las tarjetas salen de la cuenta de emisor de Connect Manager. Cada club tiene una clase, `loyalty_class_` más la dirección web (slug) del grupo, con su marca; y cada socio un objeto, `customer_` más su número interno, con sus datos. La clase se actualiza para todo el club de una vez; el objeto, socio a socio. ### Alta de la tarjeta El socio abre un enlace firmado. Connect Manager apunta que ese socio ha pedido la tarjeta de Google, compone un JWT con la clase del club y el objeto del socio, lo firma con la cuenta de servicio y lo manda al enlace de guardar de Google. Al pulsar «Guardar», Google crea el objeto. Google solo lee la clase del enlace si todavía no existe; si ya existía, se queda con la suya, y por eso la marca se sube aparte al guardar Monederos. ```mermaid sequenceDiagram participant M as Móvil Android participant CM as Connect Manager participant G as Google Wallet M->>CM: Abre el enlace firmado CM->>CM: Apunta la petición y firma un JWT con clase y objeto CM-->>M: Redirige al enlace de guardar de Google M->>G: El socio pulsa Guardar G->>G: Crea el objeto del socio ``` ### Actualizaciones Cuando cambia algo del socio se encola una sincronización. El trabajo actualiza su objeto en la API de Google Wallet: estado activo, nombre, saldo, botón, datos de los detalles, enlaces, código y franja del nivel, pidiendo a Google que avise si cambia el saldo. Si el socio abrió el enlace pero no llegó a guardar la tarjeta, Google contesta 404 y se ignora. Un error de credenciales o de Google queda en el registro y el trabajo se reintenta hasta 3 veces, cada 30 segundos. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant G as API Google Wallet participant M as Móvil Android TPV->>CM: Factura con socio CM->>CM: Encola la actualización CM->>G: Actualiza el objeto del socio con el saldo alt El socio no guardó la tarjeta G-->>CM: 404, se ignora else Tarjeta guardada G->>M: Actualiza la tarjeta y avisa del saldo end ``` ### Avisos de campaña Una campaña del canal «Tarjeta del móvil» (**Administración → Campañas**) llega a los socios que han pedido la tarjeta de Google. Para cada uno se dejan en la tarjeta solo los últimos avisos guardados y se añade el nuevo como mensaje con notificación, visible 30 días. Si Google responde que se ha superado la cuota de avisos, se vuelve a mandar como mensaje sin notificación: queda en los detalles. Este canal se envía a 5 socios por segundo. ### La marca del club Al guardar Monederos o Apariencia, Connect Manager crea o actualiza la clase del club en Google. Las direcciones de las imágenes llevan una versión, porque Google las guarda en caché por dirección: así un logo nuevo se descarga de verdad. Si la dirección del logo no es pública (un entorno de pruebas), la actualización no se envía y queda anotado en el registro. ## Comprobar que funciona - FOS: `php artisan loyalty:google-wallet-check` obtiene el token sin errores. - Guarda Monederos: sale «Tarjeta de Google Wallet actualizada». - Con un socio de prueba, pulsa **Enviar wallet**, abre el correo en un Android y guarda la tarjeta. - En la ficha del socio, pestaña «Wallet (Apple / Google)», aparece «Google Wallet: enlace del pase abierto el …». - Escanea la tarjeta en Ágora: el socio se identifica. - Añade 1 € de saldo: la tarjeta cambia y, con las notificaciones de Wallet activadas, el móvil avisa. - Cambia el color de fondo, guarda y comprueba que la tarjeta lo refleja en unos minutos. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «Google Wallet pendiente de configuración de credenciales.» | No hay cuenta de servicio en el servidor. | Avisa a FOS. | | Al guardar Monederos: «No se pudo actualizar la tarjeta en Google Wallet» con «La configuración se guardó, pero Google no aceptó el cambio de la tarjeta. Vuelve a guardar en unos minutos o revisa los registros.» | Google rechazó la clase: imagen inaccesible, un dato inválido o credenciales. | Vuelve a guardar en unos minutos; si se repite, FOS revisa el registro. | | En el registro: «Sync de la clase de Google omitido (grupo …): la URL del logo no es pública. Revisa APP_URL.» | Se guardó desde un entorno sin dirección pública. | Guarda desde el panel de producción. | | loyalty:google-wallet-check devuelve invalid_grant | Clave de la cuenta de servicio rotada o borrada. | FOS genera una clave nueva y la sube en base64. | | Las tarjetas siguen con un logo o un color antiguos | La clase se creó con otra marca y Google no la cambia desde el enlace de alta. | Guarda Monederos para subir la marca actual. | | Un aviso de campaña no hizo sonar el móvil | Tope de 3 avisos al día por tarjeta, notificaciones de Wallet apagadas o tarjeta no guardada. | El aviso queda en los detalles; para los siguientes, deja pasar 24 horas. | | «Pedir a domicilio» no se puede elegir, o sale «El club no tiene la tienda de Delivery publicada.» | La tienda online propia no está publicada. | Publícala o deja «Ver mi perfil». | | «Ese dato ya está en el otro hueco de los detalles.» | El mismo dato en los dos huecos. | Cambia uno de los dos. | | La ficha dice «Sin passes emitidos» aunque el socio tiene la tarjeta de Google | Google no comunica los guardados. | Es normal: mira si aparece «Google Wallet: enlace del pase abierto el …». | | El logo sale pixelado o cortado | Logo pequeño o sin margen. | Súbelo cuadrado, de 660 px o más y con margen. | ## Preguntas frecuentes ### ¿El restaurante necesita su propia cuenta de Google Wallet? No. Todas las tarjetas salen de la cuenta de emisor de Connect Manager; cada club tiene su clase con su marca. ### ¿Cómo cambio el color de la tarjeta de Google Wallet? Con «Color de fondo de tarjeta» en Monederos, para todo el club. Si el club tiene niveles con color, cada socio ve además una franja con el color y el nombre de su nivel. ### ¿Se actualiza el saldo de Google Wallet al pagar en Ágora? Sí. Al registrarse la factura se actualiza el objeto del socio y Google le avisa del nuevo saldo, si tiene las notificaciones de Wallet activadas. ### ¿Por qué un socio con Android no recibe la notificación de una campaña? Google permite 3 avisos con notificación al día por tarjeta; los siguientes se guardan sin avisar. También puede tener las notificaciones de Wallet apagadas o no haber guardado la tarjeta. ### ¿Puedo poner un botón para pedir a domicilio en la tarjeta de Google Wallet? Sí, eligiendo «Pedir a domicilio» en «Botón del pase de Google», si el grupo tiene su tienda online publicada. El área privada pasa entonces a los enlaces de los detalles. ### ¿Qué pasa con las tarjetas ya guardadas si cambio el logo? Al guardar se sube la clase del club y todas las tarjetas, nuevas y guardadas, muestran el logo nuevo en unos minutos. ## Referencias - [Ficha de Google Wallet en el catálogo](https://connectmanager.es/integraciones/google-wallet) - [Fidelización: conectar el club con Ágora](https://connectmanager.es/docs/fidelizacion-conectar-con-agora) - [Apple Wallet: la tarjeta del club en el iPhone](https://connectmanager.es/docs/fidelizacion-apple-wallet) - [WhatsApp y Bird: mensajes y campañas del club](https://connectmanager.es/docs/fidelizacion-whatsapp-bird) - [Documentación de Google Wallet para desarrolladores](https://developers.google.com/wallet) - [Tarjetas de fidelización en Google Wallet](https://developers.google.com/wallet/retail/loyalty-cards) --- # WhatsApp con Bird: mensajes y campañas del club Portal: Fidelización · Comunicación URL: https://connectmanager.es/docs/fidelizacion-whatsapp-bird Actualizado: 2026-10-03 La integración de **WhatsApp a través de Bird** permite al club de fidelización de Connect Manager mandar por WhatsApp la tarjeta del móvil, el enlace de acceso al área del socio y campañas, y enviar campañas por SMS, con la cuenta de Bird de Connect Manager o con la del propio club. No es una conexión con Ágora en sí, pero los socios a los que llega son los mismos que se identifican en el TPV Ágora. Este manual es para el técnico que la configura: qué pedir, dónde ponerlo, cómo funciona y qué hacer cuando un mensaje no llega. ## Qué hace la integración - **Envía la tarjeta del móvil por WhatsApp** con la plantilla «wallet», que lleva los enlaces para añadirla a Apple Wallet y a Google Wallet: al dar de alta al socio desde el panel, si el envío automático está encendido, o a mano desde su ficha con «Enviar wallet». - **Deja entrar al área del socio con el teléfono**: si el socio escribe su teléfono en el acceso del portal en vez del correo, recibe el enlace de acceso por WhatsApp con la plantilla «login». El enlace vale 15 minutos y una sola vez. - **Envía campañas por WhatsApp** a los socios que han dado permiso para ese canal, con la plantilla «notificación»: el texto de la campaña entero va en su único parámetro. - **Envía campañas por SMS**, en texto libre, por el canal de SMS de Bird. - **Elige la cuenta por canal**: «Servicio propio», que es la cuenta de Bird de Connect Manager y su número, o «Bird (cuenta del portal)», la del propio club con su número y sus plantillas. - **Permite probar una campaña de WhatsApp** mandándola a un teléfono por el mismo camino que el envío real, con valores de ejemplo. - **Respeta el consentimiento por canal** (correo, SMS y WhatsApp, con fecha e histórico): las campañas de WhatsApp solo salen hacia quien tiene «Sí» en WhatsApp, y se vuelve a comprobar justo antes de enviar. - **Adjunta un cupón a la campaña** y sustituye las variables `{customer_name}`, `{balance}`, `{code}` y las del cupón (`{coupon_name}`, `{coupon_benefit}`, `{coupon_code}`, `{coupon_url}`). - **Deja rastro**: el estado de cada destinatario en los resultados de la campaña y, en la ficha del socio, la pestaña «Comunicaciones» con los envíos de acceso y de tarjeta. - **Controla el ritmo**: las campañas de SMS y WhatsApp salen a 8 mensajes por segundo para que Bird no las corte. ### Qué no hace - **Mensajes libres por WhatsApp**: solo plantillas aprobadas por Meta en Bird. - **Saber si el mensaje se entregó o se leyó**: solo consta que Bird lo aceptó. - **Comprobar el consentimiento de SMS**: las campañas por SMS van a todos los socios del segmento con teléfono. - **Reintentar los mensajes de campaña**: cada uno se intenta una vez, para no mandarlo dos veces. Los de acceso y de tarjeta sí se reintentan. - **Conservar los saltos de línea en WhatsApp**: Meta no los admite en un parámetro de plantilla, así que los párrafos se juntan con « · ». - **Comunicaciones automáticas por SMS**: el SMS solo se usa en campañas. - **Recibir respuestas** de los socios: no hay bandeja de entrada. - El botón **«Invitar por WhatsApp»** de la tarjeta del móvil no pasa por Bird: abre el WhatsApp del propio socio con el mensaje escrito. > [!WARNING] El desplegable de proveedor de WhatsApp ofrece también «WhatsApp Web (gateway no oficial · Evolution/WAHA)». No forma parte de esta integración: enlaza un número por QR sin la API oficial, va contra las condiciones de Meta y puede acabar con el número bloqueado. Usa siempre Bird. ## Requisitos - **Una cuenta de Bird con un canal de WhatsApp Business** (número verificado) y las plantillas aprobadas por Meta. Con «Servicio propio» son las de Connect Manager y las mantiene FOS; con la cuenta del club, el cliente da de alta su número y sus plantillas en su Bird. - **Un canal de SMS en Bird**, si se van a enviar campañas por SMS. - **La cola de trabajos funcionando**: todos los envíos van encolados. - **El club creado** en **Configuración → Portal público de clientes**. - **Socios con teléfono**. Sin prefijo se entienden como españoles (+34); los de otros países tienen que llevar su prefijo. - **Consentimiento de WhatsApp** de los socios a los que se quiera mandar campañas. - **Permisos en el panel**: «Fidelización: Activar por grupo» para la configuración del club y «Fidelización: Marketing» para las campañas. **Quién hace qué.** **FOS** mantiene la cuenta de Bird de Connect Manager y sus plantillas. **El cliente**, si quiere su propio número, contrata Bird, conecta su número de WhatsApp y aprueba las plantillas. **El técnico** pega las credenciales, enciende las comunicaciones y hace las pruebas. ## Datos que necesitamos Solo hacen falta si se usa la cuenta de Bird del club; con «Servicio propio» no se pide nada. Los campos que se dejen vacíos se toman de la cuenta de Connect Manager. | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Workspace ID | Cliente, en su cuenta de Bird | 00000000-0000-0000-0000-000000000000 | Sí | | Access Key | Cliente, en su cuenta de Bird (clave de acceso a la API) | Cadena secreta | Sí | | Channel ID del canal de WhatsApp | Cliente, en Bird (canal conectado a su número) | 00000000-0000-0000-0000-000000000000 | Sí | | Plantilla login: Project ID y Versión | Cliente, en Bird | Identificadores de la plantilla y de su versión | Para el acceso con teléfono | | Plantilla wallet: Project ID y Versión | Cliente, en Bird | Identificadores de la plantilla y de su versión | Para enviar la tarjeta | | Plantilla notificación: Project ID y Versión | Cliente, en Bird | Identificadores de la plantilla y de su versión | Para las campañas | | Workspace ID, Access Key y Channel ID del canal de SMS | Cliente, en Bird | Como los de WhatsApp | Para campañas por SMS | Parámetros que tienen que tener las plantillas, con estos nombres exactos y en español: | Plantilla | Parámetros | Qué lleva | | login | url, Portal | El enlace de acceso y el nombre del club | | wallet | url_apple, url_google | Los enlaces para añadir la tarjeta | | notificación | message | El texto completo de la campaña | ## Configuración paso a paso ### 1. En Bird (solo con la cuenta del club) - Conecta el número de WhatsApp Business del club y anota el Channel ID del canal y el Workspace ID. - Crea las plantillas «login», «wallet» y «notificación» en español con los parámetros de la tabla. En las URL, la plantilla tiene que poner `https://` delante del parámetro: Connect Manager manda las direcciones sin `https://`. - Espera a que Meta las apruebe y anota el Project ID y la versión de cada una. - Crea una Access Key con permiso para enviar mensajes. - Si va a haber campañas por SMS, da de alta el canal de SMS. ### 2. En Connect Manager: el proveedor de cada canal Ve a **Configuración → Portal público de clientes**, abre el club y entra en la subpágina **Fidelización**, sección «Servicios de comunicación (proveedores)»: - En «WhatsApp» elige Servicio propio (Bird de la plataforma) o Bird (cuenta del portal). Con la cuenta del club aparecen «WhatsApp · Workspace ID», «WhatsApp · Access Key», «WhatsApp · Channel ID», «WhatsApp · Plantilla login · Project ID», «WhatsApp · Plantilla login · Versión», «WhatsApp · Plantilla wallet · Project ID», «WhatsApp · Plantilla wallet · Versión», «WhatsApp · Plantilla notificación · Project ID» y «WhatsApp · Plantilla notificación · Versión». - En «SMS» elige Servicio propio (Bird de la plataforma) o Bird (cuenta del portal); con la del club, «SMS · Workspace ID», «SMS · Access Key» y «SMS · Channel ID». - Guarda. En la misma sección se elige el proveedor del correo, que también puede ser Bird; ver [Proveedores de envío de correo](https://connectmanager.es/docs/correo-proveedores-de-envio). ### 3. En Connect Manager: el acceso con teléfono y el envío de la tarjeta - En la subpágina **Comunicaciones** del club, elige el «Canal» WhatsApp. - En «Acceso por WhatsApp (login con teléfono)», deja «Comunicación activada». - En «Envío del wallet para descarga», revisa «Comunicación activada», «Enviar automáticamente al registrarse» y «Enviar también por WhatsApp» (los tres vienen encendidos de serie). El envío automático es para las altas hechas en **Administración → Clientes**; con la bienvenida activada, en esas altas solo sale el WhatsApp, porque el correo de bienvenida ya lleva el botón de la tarjeta. - En la subpágina **Apariencia**, enciende «Permitir acceso con el teléfono (WhatsApp)». Debajo, «Estado del canal de WhatsApp» tiene que decir «Configurado.»: entonces el acceso pide «correo o teléfono». Con «Sin configurar.», sigue pidiendo solo el correo. ### 4. En Connect Manager: el consentimiento de WhatsApp - En la ficha del socio (**Administración → Clientes**), el bloque «Consentimiento comercial» tiene un desplegable por canal (Email, SMS y WhatsApp) con «Sí», «No» o «Sin contestar», y la fecha del último cambio. - En la tienda online propia, el socio lo da al pagar (una casilla para los tres canales) o desde «Mi cuenta», canal a canal. - En el portal de registro solo se recoge el permiso comercial general, que corresponde al correo: no da permiso de WhatsApp. ### 5. Crear una campaña por WhatsApp o SMS - Ve a **Administración → Campañas** y crea una campaña. - Elige el «Canal» WhatsApp o SMS y el «Segmento (audiencia)». La estimación dice cuántos destinatarios hay «con teléfono y permiso de WhatsApp» o «con teléfono». Si el club no tiene WhatsApp listo, avisa ahí mismo. - Escribe el texto (un SMS admite unos 160 caracteres), adjunta un cupón si hace falta y, si quieres, «Programar para» una fecha. - Desde el listado, en la fila de la campaña, usa «Enviar prueba» (te pide un teléfono) y después «Enviar ahora». El botón «Plantillas» del listado guarda textos de campaña para reutilizarlos; no son las plantillas de WhatsApp. ## Cómo funciona ### Campaña por WhatsApp Al lanzar la campaña se comprueba que el club tiene la plantilla de notificación lista y que el cupón adjunto, si lo hay, sigue vigente; si no, no se lanza. Se reserva el envío para que no salga dos veces aunque coincidan la programación y un clic, se cuentan los destinatarios y se encola un trabajo por socio, escalonado a 8 por segundo. Cada trabajo vuelve a mirar el permiso de WhatsApp, normaliza el teléfono a formato internacional, junta los párrafos en una línea y llama a la API de mensajes de Bird con la plantilla y el texto. Bird lo entrega a Meta, que lo hace llegar al móvil. El destinatario queda como enviado, fallido o suprimido, con el motivo en «Detalle». ```mermaid sequenceDiagram participant P as Panel participant CM as Connect Manager participant B as Bird participant S as Móvil del socio P->>CM: Enviar ahora CM->>CM: Comprueba plantilla y cupón y encola un envío por socio CM->>CM: Revisa el permiso de WhatsApp y el teléfono CM->>B: POST mensaje con plantilla de notificación B->>S: WhatsApp con el texto de la campaña B-->>CM: Aceptado CM->>CM: Destinatario marcado como enviado ``` Lo que se manda a Bird es el destinatario (el teléfono en formato internacional) y la plantilla (su Project ID, su versión, el idioma `es` y los parámetros, cada uno con su nombre y su valor), a `https://api.bird.com/workspaces/{workspace}/channels/{canal}/messages` con la Access Key en la cabecera de autorización. Si Bird no contesta en 8 segundos o responde con error, ese destinatario queda como fallido. ### Acceso con el teléfono El socio escribe su teléfono en el acceso del portal. Connect Manager comprueba que el club ofrece el acceso por WhatsApp, normaliza el número y busca al socio activo del club con ese teléfono; si hay dos fichas con el mismo número, no entra en ninguna. Genera un enlace de un solo uso válido 15 minutos y encola el envío con la plantilla «login». Por seguridad, la pantalla contesta lo mismo exista o no el teléfono, y cada teléfono puede pedir 3 enlaces cada 15 minutos. ```mermaid sequenceDiagram participant S as Socio participant CM as Connect Manager participant B as Bird S->>CM: Escribe su teléfono en el acceso CM->>CM: Busca al socio y genera el enlace de 15 minutos CM->>B: Plantilla login con el enlace y el nombre del club B->>S: WhatsApp con el enlace de acceso S->>CM: Abre el enlace CM-->>S: Entra en su área privada ``` ### Envío de la tarjeta Al dar de alta un socio desde el panel, si el envío automático está activado, o al pulsar «Enviar wallet» en su ficha, se manda la plantilla «wallet» con los enlaces firmados para Apple y Google, válidos 14 días. Si una de las dos plataformas no está configurada, en su lugar va el enlace de la página que elige la tarjeta según el móvil. ### Reintentos - Acceso y tarjeta: hasta 3 intentos, cada 30 segundos. - Campañas: un solo intento por destinatario. - Tiempo máximo de espera a Bird: 8 segundos en WhatsApp y 10 en SMS. ## Comprobar que funciona - En **Apariencia**, «Estado del canal de WhatsApp» dice «Configurado.». - Abre el acceso del portal del club, escribe el teléfono de un socio de prueba y comprueba que llega el WhatsApp y que el enlace entra. En su ficha, pestaña «Comunicaciones», aparece «Acceso al portal» por WhatsApp. - En la ficha, «Enviar wallet» por WhatsApp: llega el mensaje con los enlaces de la tarjeta. - Pon a «Sí» el consentimiento de WhatsApp del socio de prueba, crea una campaña de WhatsApp y usa «Enviar prueba» con tu teléfono. - Lanza la campaña a un segmento pequeño y revisa en «Resultados» el estado de cada destinatario. - Para SMS, lo mismo con una campaña de canal SMS. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «El club no tiene WhatsApp listo para campañas: falta la plantilla de notificación de Bird o la conexión de WhatsApp Web (Configuración → Comunicaciones).» | Falta el Project ID o la versión de la plantilla de notificación. | Rellénalos en la sección «Servicios de comunicación (proveedores)» de la subpágina Fidelización del club (el aviso cita otra ruta). | | «El proveedor de WhatsApp no ha aceptado el mensaje. Revisa la plantilla o la conexión.» | Bird rechazó el envío: plantilla sin aprobar, parámetro con otro nombre, Access Key o canal erróneos. | Revisa la plantilla y las credenciales en Bird. | | «Ese teléfono no es válido. Ponlo con el prefijo del país si no es español.» | Teléfono de prueba mal escrito o extranjero sin prefijo. | Escríbelo con prefijo, p. ej. +34 600 000 000. | | La estimación de una campaña de WhatsApp sale a 0 o muy baja | Pocos socios tienen «Sí» en el consentimiento de WhatsApp. | Recoge el permiso (tienda online o ficha del socio); sin él no se puede enviar. | | Destinatarios con «Sin permiso para WhatsApp.» | Retiraron el permiso entre el lanzamiento y el envío. | Correcto: quedan como suprimidos. | | Destinatarios con «Sin teléfono válido.» | Teléfono vacío o que no se puede convertir a formato internacional. | Corrige el teléfono en la ficha. | | El acceso del portal solo pide el correo | «Permitir acceso con el teléfono (WhatsApp)» apagado, comunicación desactivada o canal «Sin configurar.». | Revisa los tres puntos del paso 3. | | El socio no recibe el enlace de acceso | Teléfono en dos fichas del club, socio inactivo, más de 3 peticiones en 15 minutos o plantilla rechazada. | Revisa la ficha y el estado en su pestaña «Comunicaciones». | | El enlace del WhatsApp llega sin https:// o no se puede abrir | La plantilla no pone https:// delante del parámetro de URL. | Corrige la plantilla en Bird. | | «Enviar wallet» no ofrece WhatsApp | El socio no tiene teléfono, o no está configurada la plantilla wallet de la cuenta de Connect Manager (es la que mira ese botón). | Añade el teléfono o avisa a FOS. | | «No se pudo enviar» con «Revisa que el cliente tenga teléfono y que Bird (plantilla wallet) esté configurado.» | Teléfono no válido o plantilla wallet sin configurar. | Corrige el teléfono o la plantilla. | | Una campaña de SMS no sale; en el registro, «Bird SMS no configurado: no se envía.» | Falta el canal de SMS. | Configura el canal de SMS en la sección de proveedores (o pide a FOS el de la plataforma). | ## Preguntas frecuentes ### ¿Cómo envío campañas de WhatsApp a los socios del club de fidelización? Con la plantilla de notificación de Bird configurada, crea una campaña de canal WhatsApp en **Administración → Campañas**. Solo llega a los socios con teléfono y «Sí» en el consentimiento de WhatsApp. ### ¿Puedo enviar los WhatsApp desde el número del restaurante? Sí: elige «Bird (cuenta del portal)» y pon las credenciales y plantillas de la cuenta de Bird del club, conectada a su número. Con «Servicio propio» salen desde el número de Connect Manager. ### ¿Por qué mi campaña de WhatsApp llega a tan pocos socios? Porque Meta exige permiso expreso para WhatsApp y solo cuentan los socios con «Sí» en ese canal. El permiso general del portal de registro es del correo. ### ¿Se pueden mandar WhatsApp sin plantilla? No con Bird: solo plantillas aprobadas por Meta. El texto de la campaña va dentro del parámetro de la plantilla de notificación. ### ¿Sabe Connect Manager si el socio ha leído el WhatsApp? No. Solo registra si Bird aceptó el mensaje; no recibe entregas ni lecturas. ## Referencias - [Ficha de WhatsApp en el catálogo](https://connectmanager.es/integraciones/whatsapp) - [Ficha de Bird en el catálogo](https://connectmanager.es/integraciones/bird) - [Fidelización: conectar el club con Ágora](https://connectmanager.es/docs/fidelizacion-conectar-con-agora) - [Apple Wallet: la tarjeta del club en el iPhone](https://connectmanager.es/docs/fidelizacion-apple-wallet) - [Google Wallet: la tarjeta del club en Android](https://connectmanager.es/docs/fidelizacion-google-wallet) - [Proveedores de envío de correo](https://connectmanager.es/docs/correo-proveedores-de-envio) - [Documentación de Bird](https://docs.bird.com) - [Política de WhatsApp Business](https://business.whatsapp.com/policy) --- # Reseñas de Google: pedirlas después de cada visita Portal: Fidelización · Reseñas URL: https://connectmanager.es/docs/fidelizacion-resenas-de-google Actualizado: 2026-10-03 La integración de **Reseñas de Google** del club de fidelización de Connect Manager trae cada día al panel las reseñas de Google de cada local y, cuando un socio paga en el TPV Ágora, le pide una reseña con un enlace directo a la ficha del local, con un filtro opcional que recoge en privado las valoraciones bajas. Este manual es para el técnico que lo deja configurado: qué identificador de Google hace falta, dónde se pone, cómo funciona por dentro y cómo comprobarlo. ## Qué hace la integración - **Importa las reseñas de Google de cada local** todos los días a las 05:30 (hora de Madrid), a través de Outscraper: nota, texto, autor, fecha, respuesta del dueño y enlace a la reseña. La importación es incremental: solo pide lo publicado desde la última reseña que ya tiene, menos un día de margen, y no duplica nada. - **Importa a demanda** desde la lista de locales: «Sincronizar reseñas» (lo nuevo) e «Importar histórico» (reseñas antiguas, con un tope que se elige). - **Pide una reseña tras la visita**: al cerrar en Ágora una factura con socio, si el club lo tiene activado, a partir de un número mínimo de visitas y sin repetir antes de unos días. Le llega por correo con un botón «Dejar mi reseña». - **Filtra antes de mandar a Google**, si se activa: el enlace lleva primero a una página propia donde el socio puntúa con estrellas. A partir del umbral elegido (3, 4 o 5 estrellas) se le lleva a escribir la reseña en Google; por debajo, su comentario se queda en privado en «Opiniones privadas». - **Genera enlaces y QR por local** para poner en las mesas, con el mismo filtro; lo que entra por ahí sale como anónimo. - **Propone una respuesta** a cada reseña con IA (o con una plantilla según la nota, si no hay IA configurada), para copiarla y pegarla en Google. - **Enseña la nota media de Google** y el número de reseñas en la portada de la tienda online propia del grupo. - **Da acceso de solo lectura** a las reseñas del grupo para otros sistemas (por ejemplo, Power BI) con una clave de API. ### Qué no hace - **No publica las respuestas en Google**: el borrador se copia y se pega en la ficha de Google. - **No deja cambiar el texto del correo de petición** desde el panel: sale siempre el texto de serie. - **No pide reseña por notificación**: aunque la comunicación tiene un canal de notificación, el portal no llega a suscribir el navegador, así que la petición solo llega por correo. Un socio sin correo no la recibe. - **No recupera solo lo que no entró en la primera carga**: la importación diaria avanza hacia delante. Para lo antiguo está «Importar histórico». - **No pide reseñas de ventas sin socio**: solo de facturas que llegan a Connect Manager por la fidelización de Ágora. - **No manda a Google a quien puntúa alto si el local no tiene identificador de Google**: le da las gracias y ya. ## Requisitos - **La clave de Outscraper en el servidor** (cuenta de Connect Manager, la mantiene FOS). Sin ella no se importa nada y los botones de importar no aparecen. Outscraper cobra por reseña descargada. - **El identificador de Google de cada local**: el Place ID (`ChIJ…`), el CID o un enlace de Google Maps. - **La integración con el TPV funcionando**, con la URL de envío de facturas puesta en Ágora (ver [Fidelización: conectar el club con Ágora](https://connectmanager.es/docs/fidelizacion-conectar-con-agora)): la petición de reseña sale al registrar la factura. - **Socios con correo** y el proveedor de correo del club funcionando (ver [Proveedores de envío de correo](https://connectmanager.es/docs/correo-proveedores-de-envio)). - **Para los borradores con IA**, un proveedor de IA configurado en el servidor (si no, se usa la plantilla). - **Permisos en el panel**: «Fidelización: Configurar integración por local» para los locales y «Fidelización: Reputación» para «Reseñas de Google» y «Opiniones privadas». **Quién hace qué.** **FOS** mantiene la clave de Outscraper y la de IA. **El técnico** pone el identificador de cada local, lanza la primera importación y activa la petición. **El cliente** decide si pide reseñas, a partir de qué visita, cada cuánto y si usa el filtro. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Place ID de cada local | Buscador de Place ID de Google, o el enlace del local en Google Maps | ChIJ… (mejor), un CID numérico o el enlace | Sí | | Visita a partir de la que se pide | Cliente | 1 = desde la primera | No (1) | | Días sin volver a pedir | Cliente | 90 | No (90) | | Usar el filtro y su umbral | Cliente | 3, 4 o 5 estrellas | No (si se usa, 4 de serie) | | Tope de la carga histórica | Cliente y FOS (por el coste) | 200; 0 = todas | Solo al importar el histórico | | Enlace de reseña de cada local para la tienda online | Ficha del negocio en Google | https://g.page/r/…/review | Solo con tienda online propia | ## Configuración paso a paso ### 1. En Google: el identificador del local - Busca el local con el buscador de Place ID de Google y copia el identificador que empieza por `ChIJ`, o copia el enlace del local en Google Maps. - Para la petición de reseña conviene el Place ID: con él el enlace abre directamente el cuadro de «escribir reseña». Con un CID se abre la ficha del negocio y el socio tiene que pulsar él «Escribir reseña». ### 2. En Connect Manager: el local - Elige el grupo en el selector de la cabecera y ve a **Configuración → Locales**. - Pulsa **Configurar** en el local y pega el identificador en «Google Place ID / enlace (reseñas)». Acepta el Place ID, el CID o un enlace de Google Maps o de las reseñas: al guardar se extrae el identificador. - Guarda. En la lista, la columna «Reseñas» del local pasa a marcada («Google Place ID configurado · importación de reseñas activa»). - Para traer las reseñas antiguas, en «Más opciones» pulsa **Importar histórico** y pon «Máx. reseñas a importar» (se recomienda empezar con 200–500; 0 = todas, y se cobran todas). Tarda unos minutos. - A partir de ahí la importación es diaria. **Sincronizar reseñas** trae lo nuevo en el momento. ### 3. En Connect Manager: la petición tras la visita Ve a **Configuración → Portal público de clientes**, abre el club y entra en **Fidelización**, sección «Reseñas (petición tras la visita)»: - «Pedir reseña automáticamente tras la visita»: enciéndelo. - «Pedir a partir de la visita nº»: 1 = desde la primera; súbelo para pedir solo a clientes recurrentes. - «No volver a pedir antes de (días)»: el periodo mínimo entre dos peticiones al mismo socio. - «Filtrar antes de pedir reseña pública (gating)» y «Estrellas mínimas para mandar a Google»: 3 ★ o más, 4 ★ o más o Solo 5 ★. - Guarda. La petición solo sale en los locales que tienen identificador de Google. ### 4. Los QR de las mesas - Elige el grupo en el selector de la cabecera. - Ve a **Reputación → Opiniones privadas** y pulsa **Enlaces para QR**. - Para cada local salen su enlace y su QR, con un PNG grande para imprimir. Los enlaces van firmados y no caducan, así que el QR impreso sigue valiendo. ### 5. Lo que se ve en el panel - **Reputación → Reseñas de Google**: fecha, local, valoración, autor, reseña, si está respondida y fuente, con filtros por valoración, respuesta y local. Acciones: «Ver en Google», «Ver completa» y «Sugerir respuesta». - **Reputación → Opiniones privadas**: fecha, local, cliente (o anónimo), valoración, si se mandó a Google y comentario. - Si el cliente no lo tiene contratado, se puede quitar del menú en la subpágina **Fidelización** del club, «Módulos visibles en el menú» («Reseñas de Google» y «Opiniones privadas»). Solo afecta al menú. ### 6. Opcional: acceso desde Power BI u otro sistema En **Configuración → Integraciones** crea una clave para el grupo y abre «Ver credenciales»: muestra la URL, la clave, un ejemplo de cURL y la consulta para Power BI. Los puntos de acceso, de solo lectura y limitados al grupo de la clave, son `GET /api/loyalty/reviews` (con `per_page`, `locale_id`, `min_rating` y `since`), `GET /api/loyalty/reviews/summary` y `GET /api/loyalty/locales`, con la clave en la cabecera `X-API-KEY`. Admiten 120 peticiones por minuto. ### 7. Opcional: la tienda online propia La portada de la tienda enseña sola la nota media de Google del grupo cuando hay reseñas importadas. Para pedir la reseña al entregar un pedido, cada local tiene su campo en **Delivery propio → Configuración → Locales → Ubicación y contacto**, sección «Reseñas», «Enlace para dejar una reseña en Google» (tiene que empezar por `https://`). ## Cómo funciona ### Importación diaria A las 05:30 una tarea recorre los locales con identificador de Google. Para cada uno pide a Outscraper las reseñas más recientes desde la fecha de corte (la última reseña guardada menos un día). Si Outscraper responde que la tarea va en segundo plano, se le pregunta cada 15 segundos hasta que termina. Cada reseña se guarda o se actualiza por su identificador, así que reimportar no duplica y recoge las respuestas del dueño de las reseñas que vuelven a entrar. Si un local falla, se anota y se sigue con el siguiente. ```mermaid sequenceDiagram participant T as Tarea diaria participant CM as Connect Manager participant O as Outscraper participant G as Google Maps T->>CM: Locales con identificador de Google CM->>O: Reseñas del local desde la fecha de corte O->>G: Lee las reseñas públicas O-->>CM: Reseñas o tarea en segundo plano CM->>O: Consulta el resultado cada 15 segundos CM->>CM: Guarda o actualiza cada reseña ``` ### Petición de reseña tras la visita Cuando Ágora envía a Connect Manager la factura de un socio y se acepta, se suma la visita y se mira si toca pedir reseña: el local tiene identificador de Google, el club tiene la petición encendida, el socio llega al mínimo de visitas y no se le ha pedido dentro del plazo (esta comprobación se reserva de forma que dos tickets a la vez no mandan dos correos). Si toca, se encola el correo con el enlace: el de la página de filtro, firmado y válido 30 días, si el filtro está activo, o el directo de Google si no. Un fallo aquí nunca impide aceptar la factura. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant S as Socio participant G as Google TPV->>CM: Factura con socio CM->>CM: Comprueba visitas, plazo e identificador del local CM->>S: Correo con el enlace de reseña S->>CM: Puntúa con estrellas en la página de filtro alt Nota igual o superior al umbral CM-->>S: Le lleva a escribir la reseña S->>G: Publica la reseña else Nota inferior CM->>CM: Guarda la opinión privada CM-->>S: Página de agradecimiento end ``` ### El filtro y los QR Cada valoración queda registrada en «Opiniones privadas», con la marca de si se mandó a Google; el comentario solo se guarda cuando no se manda. Si el mismo socio vuelve a valorar el mismo local, se corrige su valoración en vez de sumar otra. En los QR de mesa no hay socio: la valoración entra como anónima y el mismo navegador corrige la suya si vuelve a enviar. ### Coste y reintentos - La importación diaria pide como mucho 50 reseñas por local; «Sincronizar reseñas», 200. Outscraper solo cobra las que superan la fecha de corte. - La importación desde el panel va en segundo plano: 2 intentos, con 3 minutos de margen (10 en el histórico). - El correo de petición se reintenta hasta 3 veces si el proveedor de correo falla. ## Comprobar que funciona - El local tiene marcada la columna «Reseñas» en **Configuración → Locales**. - Pulsa «Sincronizar reseñas» y, en unos minutos, mira **Reputación → Reseñas de Google** filtrando por el local. - Con un socio de prueba que tenga correo, pon «Pedir a partir de la visita nº» en 1 y cierra en Ágora una factura con ese socio en un local con identificador de Google. Debe llegarle el correo y, en su ficha, pestaña «Comunicaciones», aparecer «Petición de reseña». - Con el filtro activo, abre el enlace y puntúa con 2 estrellas: la opinión aparece en «Opiniones privadas». Vuelve a abrirlo y puntúa con 5: se abre Google para escribir la reseña. - Escanea uno de los QR de mesa y comprueba que la opinión entra como anónima. - En una reseña, pulsa «Sugerir respuesta» y revisa el borrador. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | No aparecen «Sincronizar reseñas» ni «Importar histórico» | El local no tiene identificador de Google o falta la clave de Outscraper en el servidor. | Pon el identificador; si sigue sin salir, avisa a FOS. | | Se sincroniza pero no llega ninguna reseña | Outscraper no encuentra el local con ese identificador. | Pega el Place ID ChIJ… o el enlace de Google Maps del local. El fallo queda en el registro como «Outscraper reviews: HTTP …». | | Faltan reseñas antiguas | La importación diaria solo trae lo nuevo. | Usa «Importar histórico» con un tope. | | Las respuestas del dueño a reseñas antiguas no se actualizan | La importación incremental no vuelve a pedir reseñas viejas. | FOS puede lanzar php artisan loyalty:sync-reviews --full para el local. | | Al socio no le llega la petición de reseña | Petición apagada, visitas por debajo del mínimo, plazo sin cumplir, local sin identificador de Google, socio sin correo o factura sin socio. | Revisa la sección «Reseñas (petición tras la visita)», el local y la ficha del socio. | | El enlace abre la ficha del negocio en vez de «escribir reseña» | El local tiene un CID en lugar del Place ID. | Cambia el identificador por el Place ID ChIJ…. | | El socio puntúa alto y no se abre Google | El local no tiene identificador de Google. | Añádelo; mientras tanto solo se le dan las gracias. | | El enlace del correo da error de firma | Han pasado más de 30 días desde el envío. | Es lo esperado: el enlace caduca. | | «Enlaces para QR» está desactivado («Selecciona un grupo activo primero») | No hay grupo elegido en la cabecera. | Elige el grupo. | | El borrador dice «Borrador sugerido (sin IA configurada). Edítalo a tu gusto.» | No hay proveedor de IA en el servidor, o falló. | Se usa la plantilla por nota; para IA, avisa a FOS. | | La API responde «API key requerida (cabecera X-API-KEY).», «API key inválida o desactivada.» o «La API key no tiene permiso para este recurso.» | Sin clave, clave regenerada o desactivada, o sin permiso de lectura de reseñas. | Revisa la clave en Configuración → Integraciones. | ## Preguntas frecuentes ### ¿Cómo conecto las reseñas de Google de mi restaurante con Connect Manager? Pega el Place ID o el enlace de Google Maps del local en **Configuración → Locales → Configurar**, «Google Place ID / enlace (reseñas)». Desde ese momento las reseñas se importan cada día. ### ¿Cómo pido reseñas de Google a los clientes que pagan en Ágora? Activa «Pedir reseña automáticamente tras la visita» en la subpágina **Fidelización** del club. Al cerrar en Ágora una factura con socio, se le manda un correo con el enlace a la reseña del local. ### ¿Se pueden contestar las reseñas de Google desde el panel? No se publican desde el panel: «Sugerir respuesta» prepara un borrador, con IA si está configurada, que se copia y se pega en Google. ### ¿Qué hace el filtro de reseñas (gating)? Antes de mandar al socio a Google le pide una nota con estrellas en una página propia. Si llega al umbral, va a Google; si no, su opinión se guarda en privado en «Opiniones privadas». ### ¿Cuánto tarda en aparecer en el panel una reseña nueva de Google? Como mucho hasta la importación de las 05:30 del día siguiente; con «Sincronizar reseñas» aparece en unos minutos. ### ¿Dónde encuentro el Place ID de mi local? En el buscador de Place ID de Google (enlace abajo). También vale pegar el enlace del local en Google Maps: Connect Manager extrae el identificador al guardar. ## Referencias - [Ficha de Reseñas de Google en el catálogo](https://connectmanager.es/integraciones/resenas-de-google) - [Fidelización: conectar el club con Ágora](https://connectmanager.es/docs/fidelizacion-conectar-con-agora) - [Proveedores de envío de correo](https://connectmanager.es/docs/correo-proveedores-de-envio) - [Place ID de Google y buscador de Place ID](https://developers.google.com/maps/documentation/places/web-service/place-id) - [Outscraper](https://outscraper.com) --- # Plataformas de reparto: cómo se pide el rider desde Ágora Portal: Plataformas de reparto · Primeros pasos URL: https://connectmanager.es/docs/plataformas-de-reparto-como-funciona Actualizado: 2026-10-03 Connect Manager conecta Ágora con plataformas de reparto para que, cuando entra un pedido a domicilio, el repartidor (rider) se pida desde el propio TPV, sin abrir la aplicación de la flota. Hoy se pueden configurar tres flotas: Glovo On-Demand (en la web, Glovo Local), Catcher y Shipday. Este manual explica, para el técnico que tiene que elegir y montar la flota de un local, cómo llega la petición desde Ágora, qué hace cada flota, dónde se sigue cada reparto, cómo se cancela y quién lo factura. ## Qué flotas hay y qué hace cada una > [!NOTE] Uber Direct figura en el catálogo de integraciones, pero todavía no tiene integración que configurar en Connect Manager. Si un cliente la pide, consúltalo con FOS. Las tres flotas disponibles reciben el pedido de Ágora por la misma vía, al asignar un repartidor, pero no se configuran en el mismo sitio ni hacen lo mismo después. Glovo On-Demand vive en Connect Manager App (app.connectmanager.es); Catcher y Shipday, en el hub de Connect Manager (hub.connectmanager.es). | Función | Glovo On-Demand (Glovo Local) | Catcher | Shipday | | Dónde se configura | Connect Manager App, integraciones de reparto del local | Hub, panel /admin, Ecosistema Conectado del local | Hub, panel /admin, Ecosistema Conectado del local | | Pedir el rider al asignar el repartidor en Ágora | Sí | Sí | Sí | | Pedir el rider al crear el pedido, sin asignar | No | Sí, con el interruptor «Pedir rider al crear el pedido» | No | | Saber antes de pedir si la flota puede hacerlo | Sí: Glovo valida zona, horario y ciudad, y Ágora recibe el motivo | No. La vía automática descarta las direcciones fuera del radio configurado | No | | Cancelar al cancelar el reparto en Ágora | Sí, mientras Glovo lo permita | Sí | Sí: borra el pedido en Shipday | | Cancelar desde un panel | Sí: Cancelar petición en Recogidas de pedidos | Sí: Cancelar rider en la pantalla de repartos del TPV | No: el botón de Histórico Riders falla | | Seguimiento del reparto | Recogidas de pedidos (app.connectmanager.es): estado, posición y entrega estimada | Pantalla de repartos dentro del TPV e Histórico Riders | Histórico Riders: estado, repartidor, teléfono y enlace de seguimiento | | Aparece en Histórico Riders | No | Sí | Sí | | Evita pedir dos riders para el mismo pedido | No | Solo en la vía al crear el pedido | No | ## Las dos vías por las que Ágora pide el rider Ágora tiene dos mecanismos que pueden avisar a Connect Manager de un pedido a domicilio. La diferencia entre ellos decide si el personal tiene que hacer algo en el TPV para que salga el rider. ### Al asignar el repartidor: integración con plataformas de reparto Es la integración estándar de Ágora con plataformas de reparto, documentada en la guía del integrador desde la versión 7.1.0. Se configura en cada usuario de Ágora marcado como repartidor, con dos URLs: una para solicitar el reparto y otra para cancelarlo. Cuando el personal asigna ese repartidor a un pedido a domicilio, Ágora envía a la URL de solicitud el número de pedido, la dirección de entrega con coordenadas, la hora de recogida (hora local del establecimiento), el nombre y el teléfono del cliente, las notas, el importe y las líneas. Connect Manager traslada el pedido a la flota y contesta a Ágora en el momento: «aceptado», o «rechazado» con el motivo. Si después hay que cancelar un reparto que todavía no se ha recogido, Ágora llama a la URL de cancelación con el número de pedido. La usan las tres flotas. Su límite: si nadie asigna el repartidor, no se pide nada. El diagrama resume esta vía: Ágora llama a Connect Manager al asignar el repartidor, Connect Manager crea el reparto en la flota y devuelve a Ágora la respuesta; después la flota avisa de cada cambio de estado y, si Ágora cancela antes de la recogida, Connect Manager anula el reparto. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager participant F as Flota TPV->>CM: request-pickup al asignar el repartidor CM->>F: crea el reparto F-->>CM: aceptado o motivo del rechazo CM-->>TPV: accepted o rejected con el motivo F-->>CM: avisos de estado y repartidor TPV->>CM: cancel-pickup si se cancela antes de la recogida CM->>F: anula el reparto ``` ### Al crear el pedido: integración de documentos (solo Catcher) Ágora puede avisar además a un sistema externo cada vez que crea un documento de venta. Es la integración con sistemas externos al crear documentos: se activa en el módulo de servicios de integración de Ágora, eligiendo a qué documentos afecta (pedidos, albaranes o facturas; los pedidos, desde Ágora 8.1.0). Como es del sistema y no de un usuario, salta sola al crear el pedido, también con los pedidos importados. Solo Catcher la aprovecha: con el interruptor «Pedir rider al crear el pedido (sin asignar repartidor)» de su configuración, Connect Manager contesta a Ágora al instante y pide el rider en segundo plano, con los minutos de preparación y el radio máximo que configures. El detalle está en el [manual de Catcher](https://connectmanager.es/docs/integracion-catcher-agora). > [!WARNING] Esta integración de Ágora es un validador: si el sistema externo contesta «rechazado», el pedido no se crea en el TPV. Por eso Connect Manager la acepta siempre, aunque Catcher esté caído o falten datos, y los pedidos que no puede enviar quedan anotados en Histórico Riders con el motivo. En resumen, el pedido a domicilio sale de Ágora por una de las dos vías. Al asignar el repartidor, va a la URL de la flota de ese repartidor, sea Glovo On-Demand, Catcher o Shipday. Al crear el pedido, solo llega a Catcher, y solo si el local tiene activada la vía automática. ```mermaid flowchart LR P[Pedido a domicilio en Ágora] --> A{Qué lo dispara} A -->|Se asigna el repartidor| U[URLs del usuario-repartidor] A -->|Se crea el pedido| D[Integración de documentos] U --> G[Glovo On-Demand por Connect Manager App] U --> C[Catcher por el hub] U --> S[Shipday por el hub] D -->|Solo con la vía automática activada| C ``` ## Una flota por local Cada flota se configura por local, con las credenciales de la cuenta del local en esa flota y su dirección de recogida. Lo normal es que un local trabaje con una sola flota, y conviene saber por qué: - Ágora guarda las URLs en cada usuario-repartidor, así que un local puede tener dos repartidores apuntando a flotas distintas (por ejemplo, «GLOVO» y «SHIPDAY») y elegir al asignar: cada petición va solo a la flota del repartidor asignado. Funciona, pero el personal tiene que saber cuál asignar en cada caso. - En el hub, no des de alta dos veces la misma flota en el mismo local: al recibir el pedido, Connect Manager usa la primera integración activa que encuentra. - Con la vía automática de Catcher, todos los pedidos a domicilio del local se piden a Catcher al crearse. Si además se asigna un repartidor de otra flota, saldrán dos riders. - Por el mismo motivo, no asignes el usuario-repartidor de Catcher a un pedido que ya pidió rider por la vía automática: la vía clásica no comprueba si el pedido ya tiene rider, y Catcher no descarta los pedidos repetidos. ## Dónde se configura y quién hace qué | Flota | Dónde se crea la integración | Qué se pega en Ágora | Qué hay que poner en la flota | | Glovo On-Demand | app.connectmanager.es: Administración → Locales → local → Integraciones de reparto → Añadir | URL de petición de recogida y URL de cancel. de recogida, en el usuario-repartidor | Nada: los avisos de estado se dan de alta solos al guardar | | Catcher | Hub, panel /admin: Seguridad → Locales → local → Ecosistema Conectado → Añadir Integración | URLs de solicitud y de cancelación (botón Endpoints Ágora) en el usuario-repartidor; para la vía automática, la URL de aviso al crear pedido en la integración de documentos; para la pantalla de repartos, una acción personalizada | La URL de avisos de estado, que Catcher configura en su panel | | Shipday | Igual que Catcher | URL de Solicitud de Viaje (Request) y URL de Cancelación de Viaje (Cancel) (botón Endpoints Ágora) en el usuario-repartidor | La URL Webhook Global, en la configuración de webhooks de Shipday | - **FOS** da de alta el local y la integración. En Connect Manager App, el botón **Añadir** de las integraciones de reparto solo lo ven los administradores; en el hub, el panel /admin pide el permiso «Entorno: Acceder a Configuración». - **El distribuidor** crea en Ágora el usuario-repartidor de cada flota y pega las URLs; con Catcher, si procede, configura la integración de documentos y la acción personalizada; y hace la prueba de punta a punta. - **El cliente** contrata con la flota, facilita las credenciales y la dirección de recogida, y prepara su cuenta en la flota (repartidores en Shipday, URL de avisos). ## Requisitos comunes - **Ágora 7.1.0 o posterior**; 8.1.0 o posterior si se usa la vía automática de Catcher, que necesita la integración de documentos con pedidos. - **Salida a internet por HTTPS desde Ágora**. Todas las llamadas las inicia Ágora y estas integraciones no consultan la API de Ágora, así que no hace falta Zero Connect ni abrir puertos. - **Cuenta del local en la flota** con sus credenciales de API. - **Un usuario de Ágora marcado como repartidor** por cada flota que se use al asignar. - **Pedidos a domicilio con la dirección completa**, el nombre y el teléfono del cliente. ## Seguimiento de los repartos No hay una única pantalla para las tres flotas: depende de dónde vive la integración. ### Histórico Riders (Catcher y Shipday) - **Dónde**: panel /app del hub, menú **Delivery Hub → Riders**; la página se titula «Histórico Riders». Hace falta el permiso «Acceder a riders» y cada usuario ve solo sus locales. - **Qué muestra**: una tarjeta por solicitud, de la más reciente a la más antigua, 40 por página con **Anterior** y **Siguiente**. Se refresca sola cada 10 segundos. Cada tarjeta lleva el cliente, el ID del registro, el local, el número de pedido de Ágora, el estado en el canal, el total y la fecha. La etiqueta «Ágora: Enviado» es fija: no indica el estado del pedido en Ágora. - **Filtros**: **Desde**, **Hasta**, **Canal** (Shipday o Catcher), **Estado Petición**, **Local** y un buscador por local, cliente o número de pedido. En el móvil están tras el botón «Filtros y búsqueda». - **Detalle** (clic en la tarjeta): canal destino, número de pedido de Ágora, restaurante, total y fecha del registro; **Repartidor asignado**, **Teléfono** y **Seguimiento en Vivo** («Ver mapa GPS») cuando la flota los ha comunicado; los artículos del pedido; y tres bloques plegados con botón **Copiar**: **PAYLOAD ENTRADA (ÁGORA)**, **PAYLOAD ENVIADO** y **RESPUESTA EXTERNA (API)**. Es lo primero que hay que mirar ante un fallo. > [!WARNING] Los botones **Actualizar** y **Cancelar Viaje** del detalle no funcionan hoy: buscan las credenciales de la flota en un sitio donde no están. Con Shipday responden «No hay API Key para este local.» y «Clave de API de Shipday no configurada para este local.»; con Catcher, «La integración de Catcher no existe o está desactivada.». Para Catcher usa la pantalla de repartos del TPV; para Shipday, cancela desde Ágora o desde el panel de Shipday. ### Recogidas de pedidos (Glovo On-Demand) En app.connectmanager.es, el menú **Recogidas de pedidos** tiene las vistas **Peticiones en curso** e **Historial de pedidos**. Cada petición muestra el número de pedido de Ágora, el número de seguimiento de Glovo (**Id. Externo**), el estado, el cliente, el local y la entrega estimada; **Ver detalle** abre el mapa con la posición del repartidor, sus datos y el historial de estados. Se actualiza sola. Más en el [manual de Glovo On-Demand](https://connectmanager.es/docs/integracion-glovo-on-demand-agora). ### Pantalla de repartos en el TPV (Catcher) Catcher tiene además una pantalla que se abre dentro de Ágora como acción personalizada, con los repartos de hoy, de 7 días o de 30 días, su estado, el repartidor y su posición, y botones para actualizar, ver la ficha y cancelar el rider. Se instala desde el botón **Pantalla de repartos** de la integración: está en el [manual de Catcher](https://connectmanager.es/docs/integracion-catcher-agora). ## Estados de un reparto - **Glovo On-Demand**: los de Glovo, en Recogidas de pedidos: Creado, Agendado, Activado, Aceptado, En proceso de recogida, Recogido, En proceso de entrega, Entregado, Cancelado, Devuelto, En proceso de devolución y Rechazado. Si Glovo no valida la petición, el estado es el motivo (por ejemplo, «Fuera de las zonas de trabajo», que en realidad significa fuera de horario). - **Catcher**: los ocho de Catcher en la pantalla del TPV (Esperando a agruparse, Buscando repartidor, Repartidor asignado, Va al local, Esperando en el local, En reparto, Entregado y Cancelado). En Histórico Riders se resumen en Aceptado (buscando o con repartidor asignado), Active (de camino al local o al cliente), Entregado y Cancelled. - **Shipday**: Aceptado cuando Shipday crea el pedido y, desde ahí, el estado que mande Shipday en sus avisos, con su nombre original. - **Comunes en Histórico Riders**: Pendiente (se está enviando), Rechazado (la flota no lo aceptó o la vía automática lo descartó; el motivo está en el detalle) y Fallido (error de comunicación o interno). > [!TIP] Los repartos anulados desde Ágora o desde la pantalla de Catcher quedan como «Cancelled» y no salen con el filtro **Cancelado** de Histórico Riders, que busca otra palabra. Para encontrarlos, busca por número de pedido. ## Cancelaciones Cancelar el reparto y cancelar el pedido son cosas distintas, y cada flota se cancela desde sitios diferentes. - **Desde Ágora**: cuando se cancela el reparto de un pedido que todavía no se ha recogido, Ágora llama a la URL de cancelación del repartidor asignado. Glovo On-Demand lo anula si Glovo aún lo permite; Shipday borra el pedido en Shipday; Catcher anula el viaje. Con la vía automática de Catcher, además, anular o borrar el pedido en Ágora cancela el rider. - **Desde un panel**: Glovo On-Demand con **Cancelar petición** en Recogidas de pedidos; Catcher con **Cancelar rider** en la pantalla del TPV (solo pedidos del día). Shipday no tiene hoy un botón que funcione: usa Ágora o el panel de Shipday. - Cancelar desde un panel anula el repartidor, no el pedido: en Ágora el pedido sigue abierto y hay que resolverlo allí. - Si el reparto nunca llegó a crearse en la flota (rechazado o fallido), no hay nada que anular: Catcher y Shipday contestan a Ágora «No se encontró pedido o falta ID interno.». ## Quién paga cada reparto Connect Manager no calcula ni cobra el precio de los repartos, y ninguna de las tres integraciones lo consulta antes de pedir. Cada petición sale con las credenciales de la cuenta del local en la flota, así que cada reparto lo factura la flota al titular de esa cuenta, según su contrato. Por eso importan tanto los duplicados: un rider pedido dos veces puede facturarse dos veces (con Catcher está comprobado que no descarta los pedidos repetidos). ## Comprobar que funciona - La integración del local está creada y activa en su sitio: app.connectmanager.es para Glovo On-Demand, Ecosistema Conectado del hub para Catcher y Shipday. - En Ágora existe el usuario-repartidor de la flota, con la URL de solicitud y la de cancelación, cada una en su campo. - En Catcher y en Shipday está puesta la URL de avisos; en Glovo On-Demand se dan de alta solos al guardar. - Crea en Ágora un pedido a domicilio real con dirección completa, nombre y teléfono, y asigna el repartidor: Ágora debe aceptar. - Comprueba que aparece donde toca (Recogidas de pedidos para Glovo On-Demand, Histórico Riders para Catcher y Shipday) y en el panel de la flota. - Espera al primer cambio de estado y a que salga el repartidor. - Cancela el reparto en Ágora antes de la recogida y comprueba que la flota lo anula. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Ágora rechaza la asignación con un motivo de la flota | La flota no puede hacer el envío: zona, horario o algún dato del pedido | Leer el motivo y consultar la tabla de errores del manual de esa flota | | Ágora da error al asignar y no aparece nada en ningún panel | URL mal pegada (de otro local, de otra flota o con los campos cruzados), o Ágora sin salida a internet | Copiar de nuevo las URLs desde la integración del local y pegar cada una en su campo | | Se configuró todo y nunca se pide ningún rider | Nadie asigna el repartidor en Ágora, o el repartidor asignado no tiene las URLs | Asignar el usuario-repartidor correcto; con Catcher, valorar la vía automática | | La solicitud aparece pero el estado no cambia nunca | No llegan los avisos de la flota: falta la URL de avisos en Catcher o en Shipday, o falló el alta automática en Glovo On-Demand | Poner la URL de avisos; en Glovo On-Demand, volver a guardar la integración | | Dos riders para el mismo pedido | Se asignó el repartidor dos veces, o se combinó la vía automática de Catcher con una asignación | Cancelar el sobrante en la flota; no reasignar pedidos que ya tienen reparto | | «No hay API Key para este local.», «Clave de API de Shipday no configurada para este local.» o «La integración de Catcher no existe o está desactivada.» en Histórico Riders | Los botones Actualizar y Cancelar Viaje fallan hoy | Cancelar desde Ágora, desde la pantalla de repartos (Catcher) o desde el panel de la flota | | Un reparto de Glovo On-Demand no aparece en Histórico Riders | Glovo On-Demand no registra ahí sus envíos | Buscarlo en Recogidas de pedidos de app.connectmanager.es | ## Preguntas frecuentes ### ¿Qué flotas de reparto se pueden conectar con Ágora? Uber Direct figura en el catálogo, pero todavía no se puede configurar. Las que funcionan hoy son Glovo On-Demand (Glovo Local), Catcher y Shipday, cada una con su propio manual. ### ¿Se puede pedir el rider automáticamente al crear el pedido en Ágora? Solo con Catcher, activando «Pedir rider al crear el pedido» y pegando su URL en la integración de documentos de Ágora. Con Glovo On-Demand y Shipday el rider se pide al asignar el usuario-repartidor. ### ¿Puede un local trabajar con dos flotas a la vez? Sí, con un usuario-repartidor por flota en Ágora, y el personal elige al asignar. No lo combines con la vía automática de Catcher, porque todos los pedidos a domicilio ya salen por Catcher al crearse. ### ¿Dónde veo el estado de los repartos? Catcher y Shipday, en Histórico Riders (panel /app del hub, **Delivery Hub → Riders**); Catcher también en su pantalla dentro del TPV; Glovo On-Demand, en Recogidas de pedidos de app.connectmanager.es. ### ¿Quién factura los repartos? La flota, al titular de la cuenta con la que se piden, según su contrato. Connect Manager no calcula ni cobra el precio de cada reparto. ### ¿Hace falta Zero Connect o abrir la API de Ágora para pedir riders? No. Todas las llamadas las inicia Ágora hacia Connect Manager; basta con que el equipo tenga salida a internet por HTTPS. ## Referencias - [Integración de Glovo On-Demand (Glovo Local) con Ágora](https://connectmanager.es/docs/integracion-glovo-on-demand-agora) - [Integración de reparto con Catcher](https://connectmanager.es/docs/integracion-catcher-agora) - [Integración de Shipday con Ágora](https://connectmanager.es/docs/integracion-shipday-agora) - Fichas del catálogo: [Glovo On-Demand](https://connectmanager.es/integraciones/glovo-on-demand), [Catcher](https://connectmanager.es/integraciones/catcher) y [Shipday](https://connectmanager.es/integraciones/shipday) - Guía del Integrador de Ágora, capítulos «Integración con Plataformas de Reparto» e «Integración con Sistemas Externos al crear documentos». --- # Integración de reparto con Catcher Portal: Plataformas de reparto · Flotas URL: https://connectmanager.es/docs/integracion-catcher-agora Actualizado: 2026-08-23 ## Integración de reparto con Catcher Catcher es una plataforma de repartidores. Esta integración conecta el TPV Ágora de un local con Catcher para que, cuando entra un pedido a domicilio, salga un rider a recogerlo sin que nadie tenga que entrar en otra aplicación. Todo el intercambio pasa por Connect Manager, que además guarda el registro de cada solicitud: qué se pidió, qué contestó Catcher y cómo acabó el reparto. Este manual cubre la puesta en marcha completa: qué datos hay que pedirle a Catcher, cómo se configura el local, dónde se pegan las URLs dentro de Ágora, cómo funciona la pantalla de repartos del TPV y qué hacer cuando algo no sale. ## Antes de empezar: qué datos necesitas Los tres primeros los facilita **Catcher**; sin ellos no se puede configurar nada. Los dos últimos son del local y los pones tú. - **App ID** — identificador de la cuenta de tu empresa en Catcher. - **App Secret** — la contraseña que acompaña al App ID. - **Location ID** — identificador del local concreto en Catcher. Ojo: es uno por local, no uno por empresa. Es el error más habitual al dar de alta el segundo restaurante. - **Latitud y longitud del local** — el punto de recogida. Catcher las exige para calcular la ruta del repartidor. Para sacar las coordenadas, busca el local en Google Maps, haz clic derecho sobre el punto exacto de la puerta y copia los dos números que aparecen arriba del menú. El primero es la latitud y el segundo la longitud. ### Modo pruebas La integración tiene un interruptor de **modo pruebas** (sandbox). Al activarlo no hace falta rellenar ninguna credencial: se usan automáticamente las de prueba de Catcher y las peticiones van a su entorno de pruebas, donde no se envía ningún repartidor de verdad. Es la forma recomendada de comprobar que todo encaja antes de activar el local. ## Las dos formas de pedir el rider Ágora puede avisarnos de un pedido por dos caminos distintos, y la diferencia entre ellos decide cuánto trabajo manual tiene el personal del local. Se pueden tener los dos activos a la vez. ### Opción A al asignar un repartidor (la clásica) Ágora avisa cuando alguien **asigna manualmente** un repartidor al pedido dentro del TPV. Es la vía que Ágora tiene pensada para plataformas de reparto y se configura por usuario-repartidor. **Cuándo usarla:** cuando el local quiere decidir pedido a pedido si lo lleva un rider externo o alguien de la casa. **Su límite:** si nadie asigna, no se pide nada. ### Opción B al crear el pedido (automática) Ágora avisa en el momento en que se **crea el pedido**, sin que nadie tenga que asignar a nadie. Cuelga de la integración de creación de documentos con sistemas externos, que es del sistema y no de un usuario concreto. **Cuándo usarla:** cuando todos los domicilios los lleva Catcher y no se quiere ningún paso manual. Es la opción que eligen la mayoría de los locales. Con esta vía, la solicitud sale **en segundo plano**: Ágora recibe la confirmación al instante y el pedido se crea en la caja aunque Catcher esté lento o caído. Si el envío falla, el pedido queda registrado como fallido y se puede reintentar desde la pantalla de repartos, pero la caja nunca se bloquea. ## Configurar el local en Connect Manager - Entra en **Locales** y abre la ficha del restaurante. - Ve a la pestaña **Integraciones** y pulsa Crear. - Elige el proveedor **Catcher**. - Rellena los campos y guarda. ### Qué significa cada campo - **Modo pruebas** — envía todo al entorno de pruebas de Catcher con credenciales de prueba. Al activarlo desaparecen los campos de credenciales, porque no hacen falta. - **App ID, App Secret, Location ID** — los que te dio Catcher. - **Latitud y longitud de recogida** — las del local. - **Pedir rider al crear el pedido** — activa la Opción B. Si lo dejas apagado, los avisos de creación de pedido se reciben pero no se pide ningún repartidor. - **Minutos hasta la recogida** — cuánto tarda la cocina. Es la hora que se le dice a Catcher para que el rider llegue cuando el pedido esté listo, no antes. Con 0, se pide para ya. - **Retrasar la solicitud (minutos)** — espera antes de pedir el rider. Distinto del anterior: aquí no se manda nada a Catcher hasta que pasa ese tiempo. Sirve para dar margen a cancelar un pedido recién metido sin que ya haya salido un repartidor. - **Radio máximo de reparto (km)** — si la dirección del cliente cae más lejos del local que esta distancia, la solicitud no se envía y queda registrada con el motivo. Es una red de seguridad contra direcciones ambiguas: «Calle Mayor 5» existe en media España, y sin este control el reparto podría salir hacia otra provincia. Por defecto son 30 km. ## Pegar las URLs en Ágora En la fila de Catcher de la ficha del local hay un botón **Endpoints Ágora** que muestra las URLs de ese local concreto. Cada una va en un sitio distinto de la configuración de Ágora, y confundirlas es la causa más frecuente de que «no llegue nada». - **URL de solicitud de viaje** y **URL de cancelación** — van en los ajustes de Integración Reparto de Ágora. Son las de la Opción A. - **URL de aviso al crear pedido** — va en la integración de creación de documentos con sistemas externos, que está en otro apartado de Ágora. Es la de la Opción B, y además hay que activar el interruptor «Pedir rider al crear el pedido». ### La URL de avisos de estado (importante) Hay una URL más, que **no** va en Ágora: hay que dársela a Catcher para que ellos la configuren en su panel. Es por donde Catcher nos cuenta que ha asignado repartidor, que va de camino o que ha entregado. Sin ella, la integración sigue funcionando los pedidos se envían igual pero la pantalla de repartos se queda sin actulizaciones y hay que pulsar Actualizar pedido a pedido. La encontrarás en el botón **Pantalla de repartos** de la ficha del local. ## La pantalla de repartos en el TPV Es una pantalla pensada para abrirse **dentro del propio TPV**, para que el personal gestione los repartos sin salir de Ágora ni entrar en el panel de Catcher. ### Cómo se instala - En la ficha del local, fila de Catcher, pulsa **Pantalla de repartos**. - Copia la URL de la acción personalizada. La primera vez que abras esa ventana se genera sola; a partir de ahí es siempre la misma. - En Ágora, crea una **acción personalizada** del TPV y pega esa URL tal cual, incluido el `?pos_id={pos_id}` del final: Ágora lo rellena solo. La URL lleva un código propio de ese local. El local no viaja en la dirección: se deduce del código. Si alguna vez hay que revocar el acceso, se cambia ese código sin tocar las credenciales de Catcher. ### Qué se ve La pantalla lista los repartos del local, del más reciente al más antiguo, con tres ventanas: **Hoy**, **7 días** y **30 días**. Se refresca sola cada 30 segundos. De cada pedido se muestra el número, el cliente, la dirección, el importe, el estado y —cuando Catcher ya lo ha comunicado— el repartidor asignado con su teléfono, el tipo de vehículo y un enlace para ver en el mapa dónde está en ese momento. ### Los botones - **Actualizar** — pregunta a Catcher el estado actual y dónde está el rider. Desaparece cuando el pedido ya está entregado o cancelado, porque no puede cambiar. Funciona también con pedidos de días anteriores. - **Ver ficha** — abre el detalle completo: código de recogida, horas de recepción, recogida y entrega, entrega prevista, distancia, coste del reparto y comentarios del repartidor si los dejó. - **Cancelar rider** — anula el reparto en Catcher. **Solo aparece en los pedidos de hoy**, porque Catcher no permite cancelar lo de días anteriores ni lo ya entregado. Importante: cancela el repartidor, no el pedido; el pedido sigue abierto en Ágora y hay que resolverlo allí. - **Volver a pedir rider** — solo aparece si el envío falló y el pedido nunca llegó a crearse en Catcher. Ver el aviso más abajo. ## Estados de un reparto Son los que usa Catcher, en el orden en que ocurren: - **Esperando a agruparse** — el pedido espera a juntarse con otro, si el local lo tiene configurado así. - **Buscando repartidor** — publicado, todavía sin nadie que lo acepte. - **Repartidor asignado** — alguien lo ha cogido. - **Va al local** — el rider está de camino a recoger. - **Esperando en el local** — ha llegado y espera el pedido. - **En reparto** — va hacia el cliente. - **Entregado** — terminado. - **Cancelado** — anulado. Además pueden verse estados que son nuestros, no de Catcher, y que describen en qué quedó el envío: **Enviando…**, **Enviado, sin noticias** (mandado hoy, Catcher aún no ha dicho nada), **Estado sin comprobar** (de días atrás y nadie lo ha consultado; pulsa Actualizar), **Rechazado por Catcher** y **No se pudo enviar**. ## Cuando algo falla ### «No se encontraron las coordenadas de la dirección» Catcher exige latitud y longitud del destino, y el pedido de Ágora solo trae calle, población y código postal. Connect Manager las busca automáticamente, pero una dirección mal escrita puede no encontrarse. Revisa la dirección del cliente en Ágora y vuelve a pedir el rider. ### «Coordenadas descartadas por estar demasiado lejos» La dirección se localizó, pero cae fuera del radio configurado. O el cliente está realmente lejos y entonces hay que ampliar el radio o la dirección es ambigua y se ha localizado en otra población. ### El envío da error de tiempo agotado Catcher tardó más de la cuenta en responder. El pedido queda como fallido y se puede reintentar con Volver a pedir rider, pero antes lee el aviso siguiente. ### ⚠ Cuidado con reintentar **Catcher no descarta los pedidos repetidos.** Si el primer envío llegó a su sistema aunque nos diera error, volver a pedirlo crea un segundo reparto: saldrán dos repartidores y se facturarán los dos. Por eso el reintento nunca es automático y el botón solo aparece cuando el pedido no llegó a crearse. Ante la duda, comprueba antes en el panel de Catcher si el pedido ya está. ### El pedido llega a Catcher como «Cliente Ágora» Significa que el pedido no tenía cliente asignado en el TPV, o que el cliente no tiene nombre fiscal relleno. El nombre que se envía sale de la ficha del cliente en Ágora. ## Preguntas frecuentes ### ¿Puedo usar las dos formas de pedir el rider a la vez? Sí, conviven sin estorbarse. Y aunque las dos se disparasen para el mismo pedido, solo se pide un repartidor: antes de enviar se comprueba si ese pedido ya tiene reparto solicitado. ### ¿Se pide rider para los pedidos de barra o de recoger? No. Si el pedido no lleva dirección de entrega, se entiende que no es un domicilio y no se solicita nada. ### ¿Por qué el repartidor no ve el teléfono del cliente? Cuando el aviso llega por la vía automática (Opción B), el pedido que manda Ágora no incluye ningún teléfono del cliente, así que no hay nada que enviar. Es una limitación del formato de Ágora, no de Catcher. ### ¿Puedo cancelar un reparto de ayer? No. Catcher solo permite cancelar repartos del día en curso y que no estén ya entregados o cancelados. Por eso el botón no aparece en los pedidos anteriores. ### Cancelo el rider, ¿se cancela también el pedido en Ágora? No. Se anula únicamente el repartidor. El pedido sigue abierto en el TPV y hay que cerrarlo o anularlo allí. ### ¿Los repartos aparecen en algún otro sitio del panel? Sí. En Delivery Hub → Riders está el histórico completo de todos los canales, con filtros por fecha, local y estado. La pantalla del TPV es la versión pensada para el turno en curso. ### ¿Cuánto tarda en salir el rider desde que entra el pedido? La solicitud se manda en cuestión de segundos, salvo que hayas configurado un retraso. A partir de ahí, el tiempo hasta que un repartidor la acepta depende de Catcher y de la demanda que haya en ese momento. --- # Integración de Glovo On-Demand (Glovo Local) con Ágora Portal: Plataformas de reparto · Flotas URL: https://connectmanager.es/docs/integracion-glovo-on-demand-agora Actualizado: 2026-10-03 Glovo On-Demand (en la web, **Glovo Local**) es el servicio de Glovo para usar sus repartidores en los pedidos a domicilio del propio restaurante. Con esta integración de Connect Manager, al asignar en Ágora el repartidor de Glovo a un pedido se pide el envío a Glovo, Ágora recibe al momento si Glovo lo acepta o por qué no, y el reparto se sigue en el panel de Connect Manager App. Este manual es para el técnico que la configura en un local. ## Qué hace la integración - Pide un repartidor a Glovo cuando en Ágora se asigna a un pedido a domicilio el usuario-repartidor que tiene las URLs de Connect Manager. - Antes de crear el envío, pregunta a Glovo si puede hacerlo. Si no puede, Ágora recibe el motivo: fuera de horario, dirección de entrega o de recogida fuera de zona, direcciones en ciudades distintas, ciudad cerrada o bloqueada por alta demanda, u hora de recogida no válida. - Envía a Glovo la entrega (dirección, notas, cliente y teléfono, contenido e importe) y la recogida (dirección del local y hora). Si la hora de recogida que manda Ágora ya ha pasado, la pide para dentro de un minuto. - Cancela el envío en Glovo cuando Ágora cancela el reparto o cuando se pulsa **Cancelar petición** en el panel, mientras Glovo lo permita. - Al guardar la integración, da de alta en Glovo los avisos de cambio de estado y de posición del repartidor. No hay que pegar ninguna URL en Glovo. - Muestra en **Recogidas de pedidos** (app.connectmanager.es) cada envío con su estado, el repartidor y su teléfono, su posición en el mapa, la hora estimada de entrega y el historial de estados. La lista se actualiza sola. ### Qué no hace - No muestra el estado del reparto en el TPV ni en **Histórico Riders** del hub: se sigue en Recogidas de pedidos. - No pide el repartidor al crear el pedido, solo al asignar el usuario-repartidor. La vía automática es exclusiva de Catcher. - No consulta el precio del envío, no deja elegir repartidor y solo funciona en España (las direcciones van siempre con el país «Spain»). - No gestiona cobros: no envía forma de pago ni importe a cobrar. El total viaja solo como valor declarado del paquete. - No evita duplicados. Si Ágora vuelve a pedir el reparto de un pedido que ya lo tenía (por ejemplo, al asignar otra vez el repartidor), se pide otro envío a Glovo y el anterior no se cancela. - No envía el campo **Detalles de la dirección**: en la recogida, Glovo recibe «Nombre del local: » y el nombre del local en Connect Manager. - No pregunta a Glovo por el estado a petición: el panel solo cambia cuando llegan los avisos de Glovo. - Cancelar desde el panel anula el repartidor, no el pedido: en Ágora el pedido sigue igual. > [!WARNING] En el hub (hub.connectmanager.es, sección **Ecosistema Conectado** del local) aparece un proveedor «Glovo (On Demand)» con campos como «ID de Tienda» y «Aceptar automáticamente». No está conectado a nada: guardar ahí una configuración no pide ningún repartidor. Glovo On-Demand se configura en app.connectmanager.es, como se explica abajo. ## Requisitos - **Ágora 7.1.0 o posterior**: la integración con plataformas de reparto aparece en la guía del integrador de Ágora desde esa versión. - **Un usuario de Ágora configurado como repartidor** que represente a Glovo (por ejemplo, «GLOVO»). - **Contrato de Glovo On-Demand** para el local, con credenciales de API: Client id y Client secret. Las da Glovo. - **Conectividad**: Ágora tiene que poder salir a internet por HTTPS hacia app.connectmanager.es. Todas las llamadas las inicia Ágora y la integración no consulta la API de Ágora, así que no hace falta Zero Connect ni abrir puertos. - **El local dado de alta en Connect Manager App** (app.connectmanager.es). - **Quién hace qué**: FOS da de alta el local y la integración (el botón **Añadir** solo lo ven los administradores); el distribuidor configura el usuario-repartidor en Ágora y hace la prueba; el cliente contrata con Glovo y facilita credenciales y dirección de recogida. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Client id. | Glovo, al dar de alta el servicio On-Demand | glovo-client-12345 | Sí | | Client secret | Glovo, junto al Client id | Cadena secreta: trátala como una contraseña | Sí | | Dirección de recogida: calle, número, código postal y ciudad | Cliente: la puerta por la que sale el pedido | Calle Mayor · 5 · 28013 · Madrid | Sí, los cuatro. Si falta uno, no se envía ni la dirección ni la hora de recogida | | Latitud y longitud de la recogida | Se rellenan solas al buscar la dirección en el mapa de la configuración | 40.4168000 / -3.7038000 | Muy recomendable | | URL del entorno de pruebas de Glovo | Glovo, si da credenciales de pruebas | URL https que indique Glovo | No | | Usuario-repartidor en Ágora | Cliente o distribuidor | GLOVO | Sí | ## Configuración paso a paso ### En Glovo - El cliente contrata Glovo On-Demand para el local y pide a Glovo las credenciales de API (Client id y Client secret). - Confirma con Glovo que la dirección del local está dentro de su zona de servicio y en qué horario opera. Si no lo está, todas las peticiones volverán rechazadas en la validación. ### En Connect Manager App (lo hace FOS) - Entra en `https://app.connectmanager.es` y ve a **Administración → Locales**. Abre el local, revisa sus datos y pulsa **Guardar** si has cambiado algo. - En el panel **Integraciones** de la derecha, pulsa **Integraciones de reparto**. - Pulsa **Añadir**. - **Proveedor**: elige Glovo On Demand. Después de guardar ya no se puede cambiar. - **URL Api:** al crear la integración se guarda siempre `https://api.glovoapp.com/` (producción), escribas lo que escribas. Para usar un entorno de pruebas de Glovo, cámbiala después editando la integración: vale para la autenticación y para los envíos. - **Client id.** y **Client secret**: los que ha dado Glovo. - Bloque **Dirección de recogida**: escribe la dirección del local en **Buscar**. El mapa la localiza, pone la marca y rellena **Nombre de la calle**, **Nº de la calle**, **Código postal**, **Ciudad**, **Latitud** y **Longitud**. Revisa cada campo y corrígelo a mano si hace falta. - **Detalles de la dirección** se guarda pero no viaja a Glovo; lo que recibe es el nombre del local en Connect Manager, así que comprueba que el repartidor lo pueda reconocer. - Pulsa **Guardar**. Sale el aviso «Se ha guardado la integración de reparto». Unos segundos después, Connect Manager da de alta en Glovo los avisos de estado y de posición. - La pantalla pasa a modo edición y muestra la **URL de petición de recogida** y la **URL de cancel. de recogida**, cada una con su botón de copiar (aviso «Enlace copiado al portapapeles»). Las dos URLs llevan el número del local en Connect Manager App y tienen esta forma (aquí, con el local de ejemplo 123): ``` https://app.connectmanager.es/api/venues/123/deliveries/glovo-on-demand/request-pickup https://app.connectmanager.es/api/venues/123/deliveries/glovo-on-demand/cancel-pickup ``` > [!TIP] Si la pantalla muestra las URLs sin dominio (empiezan por `/api/venues/`), añade delante `https://app.connectmanager.es` antes de pegarlas en Ágora. ### En Ágora (distribuidor) - Crea o elige un usuario configurado como repartidor que represente a Glovo, por ejemplo «GLOVO». Es el que el personal asignará a los pedidos que tenga que llevar Glovo. - En la ficha de ese usuario, en sus ajustes de **Integración Reparto**, pega la **URL de petición de recogida** como URL de solicitud de reparto y la **URL de cancel. de recogida** como URL de cancelación. Son dos campos distintos: no las cruces. - Explica al personal que, para pedir un Glovo, basta con asignar ese repartidor al pedido a domicilio, y que si Glovo no puede hacer el envío Ágora recibe el motivo. ## Cómo funciona ### Pedir el repartidor Al asignar el repartidor «GLOVO», Ágora envía a la URL de petición el pedido: número, dirección de entrega con coordenadas, hora de recogida, nombre y teléfono del cliente, notas, importe y líneas. Connect Manager guarda la petición (una por número de pedido y local) y pide a Glovo un token con el Client id y el Client secret, que reutiliza hasta unos minutos antes de que caduque. Después pregunta a Glovo si el envío es posible con esas direcciones y esa hora. Si Glovo dice que no, guarda el código del motivo como estado y responde a Ágora «rechazado» con el motivo en español. Si dice que sí, crea el envío: Glovo devuelve su número de seguimiento (en el panel, **Id. Externo**) y el estado inicial, y Ágora recibe «aceptado». Cada llamada a Glovo se intenta hasta tres veces, con medio segundo entre intentos, si falla. Si sigue fallando, Ágora recibe «rechazado» con el error y nada se reintenta más tarde: hay que volver a asignar el repartidor. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Connect Manager App participant G as Glovo TPV->>CM: request-pickup con el pedido CM->>G: token con Client id y Client secret CM->>G: validación de direcciones y hora alt Glovo no puede G-->>CM: código del motivo CM-->>TPV: rejected con el motivo else Glovo puede CM->>G: crear envío G-->>CM: número de seguimiento y estado CM-->>TPV: accepted end ``` Así se traduce el pedido de Ágora al envío de Glovo: | Dato de Ágora o de la configuración | Qué recibe Glovo | | Calle, código postal y población de entrega | Dirección de entrega en texto: «calle, CP, población, Spain» | | Latitud y longitud de entrega | Coordenadas de entrega, solo si Ágora las manda | | Notas del pedido | Detalles de la dirección de entrega | | Nombre y teléfono del cliente | Contacto del envío | | Importe del pedido | Valor del paquete (tipo de contenido: comida) | | Líneas del pedido | Descripción: «Producto: cantidad; Producto: cantidad» | | Número de pedido | Referencia del paquete y código de recogida | | Hora de recogida | Hora de recogida en UTC; si ya ha pasado, ahora más un minuto | | Calle, número, CP y ciudad de la configuración | Dirección de recogida, solo si están los cuatro | | Latitud y longitud de la configuración | Coordenadas de recogida | | Nombre del local en Connect Manager | Detalles de la recogida: «Nombre del local: …» | ### Avisos de Glovo y seguimiento Al guardar la integración, Connect Manager da de alta en Glovo dos avisos que apuntan a Connect Manager: cambio de estado y posición del repartidor, con hasta cinco reintentos por parte de Glovo. Cuando llega un aviso, Connect Manager comprueba la clave que Glovo devuelve en la cabecera (si no coincide, lo rechaza con «El token proporcionado no es válido.»), busca el envío por su número de seguimiento y guarda estado, repartidor y posición. Después consulta a Glovo el detalle completo del envío para actualizar el estado, la hora estimada de entrega y si todavía se puede cancelar. El panel se refresca al momento. Si el alta de los avisos falla, FOS recibe un aviso interno («Crear webhook (Error)») y el estado de los envíos de ese local no cambiará en el panel. Volver a pulsar **Guardar** en la integración reintenta el alta. ```mermaid sequenceDiagram participant G as Glovo participant CM as Connect Manager App participant P as Panel Recogidas G->>CM: aviso de estado o de posición CM->>G: consulta el detalle del envío G-->>CM: estado, entrega estimada y si es cancelable CM-->>P: actualiza la petición al momento ``` ### Cancelar Cuando en Ágora se cancela el reparto de un pedido que aún no se ha recogido, Ágora llama a la URL de cancelación con el número de pedido. Connect Manager busca la petición de ese local y, si Glovo todavía la marca como cancelable, pide a Glovo que la anule, vuelve a leer el estado y responde «aceptado». Si Glovo ya no lo permite, responde «Ocurrió un error: El pedido P-123 no se puede cancelar.»; si el pedido nunca se pidió por esta integración, «Ocurrió un error: El pedido P-123 no está dado de alta en el sistema.». El botón **Cancelar petición** del panel hace la misma llamada y solo aparece mientras el envío es cancelable; si va bien, avisa con «Se ha enviado la cancelación del pedido al proveedor.». ### Estados que verás en el panel En **Recogidas de pedidos** (con sus vistas **Peticiones en curso** e **Historial de pedidos**) cada envío lleva el estado de Glovo: **Creado**, **Agendado**, **Activado**, **Aceptado** (repartidor asignado), **En proceso de recogida**, **Recogido**, **En proceso de entrega**, **Entregado**, **Cancelado**, **Devuelto**, **En proceso de devolución** y **Rechazado**. Las peticiones que Glovo no validó se quedan en **Peticiones en curso** con el motivo como estado: **Error en la hora de recogida**, **Fuera de las zonas de trabajo** (que en realidad significa fuera de horario), **Dirección de recogida fuera de la zona de trabajo**, **Dirección de entrega fuera de la zona de trabajo**, **Las direcciones no están en la misma ciudad**, **Ciudad bloqueada** o **Ciudad cerrada**. Cada fila tiene **Ver detalle** (mapa, datos de recogida, de entrega y del repartidor, e historial de estados) y, si se puede, **Cancelar petición**. El menú lo ven los administradores y los usuarios de cliente o distribuidor cuyos locales tienen una integración de reparto. ## Comprobar que funciona - En la integración guardada se ven la **URL de petición de recogida** y la **URL de cancel. de recogida**, y en Ágora están pegadas en el usuario «GLOVO», cada una en su campo. - Pregunta a FOS si ha llegado algún aviso «Crear webhook (Error)» de ese local. Si ha llegado, vuelve a guardar la integración antes de seguir. - Crea en Ágora un pedido a domicilio real, con una dirección cercana dentro de la zona de Glovo y en su horario, con nombre y teléfono del cliente. - Asigna el repartidor «GLOVO». Ágora debe aceptar la asignación; si la rechaza, el motivo te dice qué falla (tabla de abajo). - En app.connectmanager.es, abre **Recogidas de pedidos → Peticiones en curso**: el pedido aparece con su **Nº de pedido de Agora**, su **Id. Externo** de Glovo y su estado. - Espera a que Glovo asigne repartidor: el estado debe avanzar solo y en **Ver detalle** deben aparecer el repartidor, su posición y la entrega estimada. Si el estado no se mueve, los avisos no están dados de alta. - Prueba la cancelación con un pedido que todavía no se haya recogido, desde Ágora o con **Cancelar petición**: el estado pasa a **Cancelado**. Es un repartidor real, así que hazlo enseguida. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Ágora rechaza con «Ocurrió una Exception: Fuera de horas de trabajo» | Glovo no opera en esa ciudad a esa hora | Pedir dentro del horario de Glovo o llevarlo con un repartidor propio | | «Ocurrió una Exception: Dirección de entrega fuera del área de trabajo» | El cliente está fuera de la zona de Glovo, o la dirección del pedido está mal escrita | Revisar la dirección del cliente en Ágora; si es correcta, no se puede repartir con Glovo | | «Ocurrió una Exception: Dirección de recogida fuera del área de trabajo» | La dirección o las coordenadas de recogida de la configuración están mal, o el local está fuera de zona | Revisar calle, número, CP, ciudad, latitud y longitud de la integración | | «Ocurrió una Exception: Las direcciones no están en la misma ciudad» | Glovo solo reparte dentro de la misma ciudad | Revisar la población del pedido; si es otra ciudad, no se puede repartir con Glovo | | «Ocurrió una Exception: Los pedidos están bloqueados en esta ciudad debido a la alta demanda. Por favor, prueba en 5 minutos» o «Ocurrió una Exception: El servicio en esta ciudad está actualmente cerrado» | Glovo ha bloqueado la ciudad por saturación o no da servicio en ese momento | Volver a asignar el repartidor pasados unos minutos o repartir por otra vía | | «Ocurrió una Exception: Hora de recogida no válida» | Glovo no acepta la hora de recogida pedida | Revisar la hora de entrega del pedido en Ágora y volver a asignar | | «Ocurrió una Exception: Error no especificado» | Glovo devolvió un código de validación que Connect Manager no traduce | Mirar el estado de la petición en el panel: guarda el código tal cual lo mandó Glovo | | «Ocurrió una Exception: » seguido de otro texto de Glovo | Glovo no acepta algún dato del envío (dirección, teléfono, hora) | Corregir el dato en el pedido de Ágora o en la configuración y volver a asignar | | «Ocurrió una Exception: Undefined property: stdClass::$status» | Glovo validó el envío pero rechazó crearlo, y Connect Manager no consigue mostrar su motivo | Volver a asignar el repartidor; si se repite, pedir a FOS que revise el registro de esa petición | | «Ocurrió una Exception: HTTP request returned status code 401…» | Client id o Client secret erróneos, o URL Api: de otro entorno distinto al de las credenciales | Revisar las credenciales con Glovo y la URL Api; corregir y guardar | | Ágora da error al asignar y no aparece nada en el panel | URL mal copiada: número de local de otro local, o local sin integración Glovo On Demand | Volver a copiar las URLs desde la integración de ese local | | «Ocurrió un error: El pedido P-123 no se puede cancelar.» | Glovo ya no permite cancelar ese envío | Resolverlo directamente con Glovo | | «Ocurrió un error: El pedido P-123 no está dado de alta en el sistema.» | Ese pedido no se pidió por esta integración o la URL de cancelación es de otro local | Comprobar la URL de cancelación del usuario «GLOVO» | | El estado se queda en el inicial y no aparece el repartidor | Los avisos de Glovo no se dieron de alta (FOS recibe «Crear webhook (Error)») | Volver a guardar la integración; si Glovo responde que ya existen, avisar a FOS | | Glovo no tiene la dirección ni la hora de recogida del local | Falta alguno de los cuatro campos de la dirección de recogida: entonces no se envían ni la dirección ni la hora | Rellenar calle, número, CP y ciudad y guardar | | Dos envíos de Glovo para el mismo pedido | Se asignó el repartidor dos veces y Connect Manager pidió dos envíos | Cancelar el sobrante con Glovo; no reasignar un pedido que ya tiene envío | ## Preguntas frecuentes ### ¿Cómo conecto Glovo On-Demand (Glovo Local) con Ágora? FOS da de alta la integración en app.connectmanager.es, en las integraciones de reparto del local, con el Client id, el Client secret y la dirección de recogida. Después se pegan la URL de petición y la de cancelación en un usuario-repartidor de Ágora, y basta con asignar ese repartidor al pedido. ### ¿Glovo On-Demand es lo mismo que recibir pedidos de Glovo en Ágora? No. Recibir en Ágora los pedidos que entran por la app de Glovo es la integración de Glovo como plataforma de pedidos ([manual de Glovo](https://connectmanager.es/docs/integracion-glovomarketplace-agora)). Glovo On-Demand sirve para pedir un repartidor de Glovo para tus propios pedidos a domicilio. ### ¿Se pide el repartidor de Glovo automáticamente al crear el pedido? No. Solo cuando se asigna en Ágora el usuario-repartidor de Glovo. La petición automática al crear el pedido solo existe para Catcher. ### ¿Dónde veo por dónde va el repartidor de Glovo? En app.connectmanager.es, en **Recogidas de pedidos**: posición en el mapa, entrega estimada y datos del repartidor. No se ve en el TPV ni en Histórico Riders del hub. ### ¿Puedo cancelar un Glovo que ya he pedido? Sí, desde Ágora o con **Cancelar petición** en el panel, mientras Glovo lo marque como cancelable. Cancelar el repartidor no anula el pedido en Ágora. ### ¿Funciona fuera de España? No. Las direcciones se envían siempre con el país «Spain». ## Referencias - [Ficha de Glovo On-Demand en el catálogo de integraciones](https://connectmanager.es/integraciones/glovo-on-demand) - [Plataformas de reparto: cómo se pide el rider desde Ágora](https://connectmanager.es/docs/plataformas-de-reparto-como-funciona) - [Integración de reparto con Catcher](https://connectmanager.es/docs/integracion-catcher-agora) - [Integración de Shipday con Ágora](https://connectmanager.es/docs/integracion-shipday-agora) - [Integración de pedidos de Glovo](https://connectmanager.es/docs/integracion-glovomarketplace-agora) - Guía del Integrador de Ágora, capítulo «Integración con Plataformas de Reparto». La documentación de la API On-Demand la facilita Glovo con el alta del servicio. --- # Integración de Shipday con Ágora: repartos desde el TPV Portal: Plataformas de reparto · Flotas URL: https://connectmanager.es/docs/integracion-shipday-agora Actualizado: 2026-10-03 Shipday es una plataforma de gestión de repartos: recibe los pedidos y los asigna a los repartidores o servicios de reparto que el restaurante tenga configurados en su cuenta. Con esta integración de Connect Manager, al asignar en Ágora el repartidor de Shipday a un pedido a domicilio se crea el pedido en Shipday, al cancelar el reparto en Ágora se anula, y el estado, el repartidor y el enlace de seguimiento se ven en Histórico Riders. Este manual es para el técnico que la configura en un local. ## Qué hace la integración - Crea el pedido en Shipday cuando en Ágora se asigna a un pedido a domicilio el usuario-repartidor que tiene las URLs de Connect Manager. - Envía a Shipday el número de pedido, el nombre y el teléfono del cliente, la dirección de entrega (con coordenadas si Ágora las manda), el nombre y la dirección del local, la hora de recogida, las notas como instrucciones de entrega, el importe total y los productos con su cantidad e importe. - Responde a Ágora al momento: «aceptado» si Shipday crea el pedido, o «rechazado» con el motivo que devuelve Shipday. - Anula el pedido en Shipday cuando Ágora cancela el reparto. - Recibe los avisos de Shipday en una URL única para todos los locales y guarda el estado del viaje, el nombre y el teléfono del repartidor y el enlace de seguimiento. - Guarda cada solicitud en **Histórico Riders** (panel /app del hub) con lo que llegó de Ágora, lo que se envió a Shipday y su respuesta. ### Qué no hace - No crea el pedido en Shipday al crearlo en Ágora: solo al asignar el usuario-repartidor. La vía automática al crear el pedido es exclusiva de Catcher. - No muestra el estado del reparto en el TPV: se sigue en Histórico Riders. - No elige repartidor ni consulta el precio del envío: quién reparte y cuánto cuesta se decide en Shipday, según la cuenta del cliente. - No envía la forma de pago del pedido. - No evita duplicados: cada solicitud que llega de Ágora crea un pedido nuevo en Shipday, aunque el número de pedido ya existiera. - Los botones **Actualizar** y **Cancelar Viaje** del detalle de Histórico Riders no funcionan hoy con Shipday: responden «No hay API Key para este local.» y «Clave de API de Shipday no configurada para este local.». Para anular, cancela el reparto desde Ágora o borra el pedido en el panel de Shipday. - Una vez creada, la integración no tiene botón de editar ni de borrar en la ficha del local: para cambiar la API Key, el nombre o la dirección, o para desactivarla, hay que pedírselo a FOS. ## Requisitos - **Ágora 7.1.0 o posterior**: la integración con plataformas de reparto aparece en la guía del integrador de Ágora desde esa versión. - **Un usuario de Ágora configurado como repartidor** que represente a Shipday (por ejemplo, «SHIPDAY»). - **Cuenta de Shipday** con su API Key y con los repartidores o servicios de reparto ya configurados en Shipday. Eso lo prepara el cliente en Shipday; Connect Manager no da de alta repartidores. - **Conectividad**: Ágora tiene que poder salir a internet por HTTPS hacia el hub de Connect Manager. Todas las llamadas las inicia Ágora y la integración no consulta la API de Ágora, así que no hace falta Zero Connect ni abrir puertos. - **El local dado de alta en el hub** (hub.connectmanager.es). - **Quién hace qué**: FOS crea la integración en el panel /admin del hub (hace falta el permiso «Entorno: Acceder a Configuración»). El distribuidor configura el usuario-repartidor en Ágora, pega las URLs y hace la prueba. El cliente facilita la API Key y pega la URL de avisos en su panel de Shipday (o da acceso para hacerlo). ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Shipday API Key | Cliente, en su cuenta de Shipday: My Account → API Key | Cadena larga de letras y números: trátala como una contraseña | Sí | | Nombre del Establecimiento Emisor | Cliente: el nombre con el que el repartidor reconoce el local | Restaurante Demo Centro | Sí | | Dirección de Origen Física | Cliente: dirección postal completa donde se recoge el pedido | Calle Mayor 5, 28013 Madrid | Sí | | Acceso al panel de Shipday | Cliente, para pegar la URL de avisos | — | Sí, para ver estados y repartidor | | Usuario-repartidor en Ágora | Cliente o distribuidor | SHIPDAY | Sí | ## Configuración paso a paso ### En Shipday - El cliente copia la API Key de su cuenta (**My Account → API Key**). - Comprueba con el cliente que en Shipday ya tiene dados de alta los repartidores o el servicio de reparto que va a usar: Connect Manager solo crea el pedido. ### En el hub de Connect Manager (lo hace FOS) - Entra en el panel /admin del hub y ve a **Seguridad → Locales**. Abre el local. - Baja hasta la sección **Ecosistema Conectado** y pulsa **Añadir Integración**. - **Servicio / Proveedor**: elige Shipday (Delivery). - **Estado Operativo**: déjalo activado. Si está apagado, Connect Manager rechaza las peticiones de ese local. - En el bloque **Shipday**, rellena **Shipday API Key**, **Nombre del Establecimiento Emisor** y **Dirección de Origen Física**. Ágora no manda el nombre ni la dirección del local, por eso se piden aquí: es lo que Shipday usa como punto de recogida. - Revisa los tres datos y pulsa **Crear**. Después no se pueden editar desde esta pantalla. - En la fila de Shipday, pulsa **Endpoints Ágora**. Se abre la ventana «Configuración Webhook - Ágora POS» con tres URLs de solo lectura: **URL de Solicitud de Viaje (Request)**, **URL de Cancelación de Viaje (Cancel)** y **URL Webhook Global (Pegar en el panel del proveedor)**. Las dos primeras llevan el número del local en el hub y terminan así (aquí, con el local de ejemplo 45): ``` …/api/incoming/agora/45/shipday/request-pickup …/api/incoming/agora/45/shipday/cancel-pickup ``` > [!NOTE] No des de alta dos integraciones de Shipday en el mismo local: al recibir un pedido, Connect Manager usa la primera activa que encuentra. ### En Ágora (distribuidor) - Crea o elige un usuario configurado como repartidor que represente a Shipday, por ejemplo «SHIPDAY». Es el que el personal asignará a los pedidos que tenga que llevar Shipday. - En la ficha de ese usuario, en sus ajustes de **Integración Reparto**, pega la **URL de Solicitud de Viaje (Request)** como URL de solicitud de reparto y la **URL de Cancelación de Viaje (Cancel)** como URL de cancelación. Son dos campos distintos: no las cruces. - Explica al personal que, para mandar un pedido a Shipday, basta con asignar ese repartidor al pedido a domicilio. ### De vuelta en Shipday - En la configuración de webhooks del panel de Shipday, añade la **URL Webhook Global**. Es la misma para todos los locales: Connect Manager reconoce cada aviso por el número de pedido de Shipday. - Sin este paso los pedidos se crean igual, pero Histórico Riders se queda en «Aceptado» y nunca muestra el repartidor ni el enlace de seguimiento. ## Cómo funciona ### Crear el pedido en Shipday Al asignar el repartidor «SHIPDAY», Ágora envía a la URL de solicitud el pedido: número, dirección de entrega con coordenadas, hora de recogida, nombre y teléfono del cliente, notas, importe y líneas. Connect Manager comprueba que el local tiene una integración de Shipday activa con API Key, anota la solicitud en Histórico Riders como «Pendiente» y crea el pedido en Shipday con la API Key en la cabecera. Si Shipday lo acepta, guarda su número de pedido, marca la solicitud como «Aceptado» y responde a Ágora «aceptado». Si Shipday lo rechaza, la marca como «Rechazado» y responde a Ágora con «Shipday: » y el texto de Shipday. Si Shipday no contesta o hay un error interno, la marca como «Fallido» y Ágora recibe «Error interno procesando el webhook de Ágora.». No hay reintentos: para volver a intentarlo, hay que volver a asignar el repartidor. ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Hub Connect Manager participant S as Shipday TPV->>CM: request-pickup con el pedido CM->>CM: anota la solicitud como Pendiente CM->>S: crea el pedido con la API Key alt Shipday lo acepta S-->>CM: número de pedido de Shipday CM-->>TPV: accepted else Shipday lo rechaza o no contesta S-->>CM: error CM-->>TPV: rejected con el motivo end S->>CM: avisos de estado del viaje CM->>CM: guarda estado, repartidor y seguimiento ``` Así se traduce el pedido de Ágora al pedido de Shipday: | Dato de Ágora o de la configuración | Qué recibe Shipday | | Número de pedido | Número de pedido | | Nombre del cliente | Nombre del cliente («Cliente Ágora» si no viene) | | Teléfono del cliente | Teléfono del cliente | | Calle, población, provincia y código postal | Dirección del cliente en una línea: «calle, población, provincia CP» | | Latitud y longitud de entrega | Coordenadas de entrega, solo si Ágora las manda | | Hora de recogida | Hora de recogida prevista, tal como la manda Ágora (hora local) | | Notas del pedido | Instrucciones de entrega | | Importe del pedido | Coste total del pedido | | Líneas del pedido | Productos con nombre, cantidad e importe (el importe es el total de la línea) | | Nombre del Establecimiento Emisor | Nombre del restaurante | | Dirección de Origen Física | Dirección del restaurante (recogida) | ### Avisos de Shipday Cada vez que el viaje cambia, Shipday llama a la URL Webhook Global. Connect Manager busca la solicitud por el número de pedido de Shipday y guarda el estado (con el nombre que usa Shipday, en minúsculas), el nombre y el teléfono del repartidor y el enlace de seguimiento. El aviso completo queda en el detalle de Histórico Riders, en el bloque **RESPUESTA EXTERNA (API)**. Si el aviso no trae número de pedido o ese número no corresponde a ninguna solicitud, se descarta. ### Cancelar Cuando en Ágora se cancela el reparto de un pedido que aún no se ha recogido, Ágora llama a la URL de cancelación con el número de pedido. Connect Manager busca la última solicitud de ese pedido en el local y borra el pedido en Shipday. Si Shipday lo borra, o responde que ya no existe, marca la solicitud como «Cancelled» y responde «aceptado». Si la solicitud no llegó a crearse en Shipday (no tiene número de Shipday), responde «No se encontró pedido o falta ID interno.». ```mermaid sequenceDiagram participant TPV as TPV Ágora participant CM as Hub Connect Manager participant S as Shipday TPV->>CM: cancel-pickup con el número de pedido CM->>CM: busca la última solicitud del pedido CM->>S: borra el pedido en Shipday S-->>CM: borrado o ya no existe CM-->>TPV: accepted ``` ### Estados en Histórico Riders - **Pendiente**: la solicitud ha llegado y se está enviando a Shipday. - **Aceptado**: Shipday ha creado el pedido. Se queda así hasta que llegue el primer aviso de Shipday. - **Rechazado**: Shipday no aceptó el pedido; el motivo está en el detalle. - **Fallido**: error de comunicación o interno; el mensaje está en el detalle. - El estado que mande Shipday en sus avisos, con su nombre original. - **Cancelled**: anulado desde Ágora. Ojo: el filtro **Cancelado** de la pantalla no lo encuentra, porque busca otra palabra. ## Comprobar que funciona - Abre la **URL de Solicitud de Viaje (Request)** en un navegador: debe aparecer una página «Connect Manager API» que dice que es un endpoint privado para recibir webhooks. Eso confirma que la URL está bien escrita y es accesible; Ágora la llamará por POST. - Comprueba que las dos URLs están en el usuario «SHIPDAY» de Ágora, cada una en su campo, y que la URL Webhook Global está pegada en Shipday. - Crea en Ágora un pedido a domicilio real con dirección, nombre y teléfono del cliente, y asígnale el repartidor «SHIPDAY». Ágora debe aceptar la asignación. - En el panel de Shipday debe aparecer el pedido con el mismo número que en Ágora. - En el panel /app del hub, abre **Delivery Hub → Riders**, filtra por **Canal** Shipday y busca el número de pedido: debe salir como «Aceptado». La lista se refresca sola cada 10 segundos. - Asigna un repartidor en Shipday: en el detalle de Histórico Riders deben aparecer **Repartidor asignado**, **Teléfono** y **Seguimiento en Vivo**. Si no aparecen, revisa la URL de avisos en Shipday. - Cancela el reparto en Ágora: el pedido desaparece de Shipday y la solicitud pasa a «Cancelled». ## Errores frecuentes y solución | Síntoma | Causa | Solución | | Ágora rechaza con «La integración de Shipday no existe o está desactivada para este Local.» | La URL es de otro local, la integración no se creó o se creó con Estado Operativo apagado | Copiar de nuevo las URLs desde Endpoints Ágora del local correcto; si está desactivada, pedir a FOS que la active | | «Shipday: API Key inválida o acceso denegado (HTTP 401). Revise la clave en el panel.» o «Shipday: » seguido de un error de autorización | API Key errónea o revocada en Shipday | Pedir al cliente la API Key vigente y a FOS que la cambie (no hay botón de editar) | | «Shipday: » seguido de otro texto | Shipday no acepta algún dato del pedido | Leer el texto: es el motivo que da Shipday. El envío completo está en PAYLOAD ENVIADO del detalle | | «API Key de Shipday no configurada en Filament.» | La integración se guardó sin API Key | Pedir a FOS que la complete | | «Error interno procesando el webhook de Ágora.» | Número de local inexistente en la URL, o Shipday no contestó a tiempo | Revisar la URL; si la solicitud figura como «Fallido», el mensaje del detalle dice qué pasó. Volver a asignar el repartidor | | Al cancelar: «No se encontró pedido o falta ID interno.» | Ese pedido no se creó en Shipday (rechazado o fallido) o se pidió por otro local | No hay nada que anular en Shipday; revisar la solicitud en Histórico Riders | | Al cancelar: «Integración Shipday inactiva.» o «API Key Shipday no configurada.» | Integración desactivada o sin API Key | Pedir a FOS que la revise; mientras, borrar el pedido en Shipday | | Al cancelar: «Shipday rechazó cancelación HTTP 4xx» | Shipday no permite borrar ese pedido | Gestionarlo en el panel de Shipday | | Histórico Riders se queda en «Aceptado» y no sale el repartidor | La URL Webhook Global no está pegada en Shipday | Añadirla en la configuración de webhooks de Shipday | | «Clave de API de Shipday no configurada para este local.» o «No hay API Key para este local.» al pulsar Cancelar Viaje o Actualizar | Esos botones buscan la API Key donde no está; fallan siempre con Shipday | Cancelar desde Ágora o desde el panel de Shipday | | Dos pedidos en Shipday para el mismo pedido de Ágora | Se asignó el repartidor dos veces: cada solicitud crea un pedido | Borrar el sobrante en Shipday; no reasignar un pedido que ya está en Shipday | ## Preguntas frecuentes ### ¿Cómo conecto Shipday con Ágora? FOS crea la integración de Shipday en la ficha del local del hub con la API Key, el nombre y la dirección del local. Después se pegan la URL de solicitud y la de cancelación en un usuario-repartidor de Ágora y la URL Webhook Global en Shipday. Para mandar un pedido, se asigna ese repartidor. ### ¿Shipday reparte con mis propios repartidores? Depende de cómo esté configurada la cuenta de Shipday del cliente: Connect Manager solo crea el pedido en Shipday, y la asignación a un repartidor de plantilla o a un servicio de reparto se hace en Shipday. ### ¿Se crea el pedido en Shipday al crearlo en Ágora? No. Se crea al asignar en Ágora el usuario-repartidor de Shipday. ### ¿Dónde veo el estado del reparto y quién lo lleva? En el panel /app del hub, en **Delivery Hub → Riders**: estado, repartidor, teléfono y enlace de seguimiento, siempre que la URL Webhook Global esté puesta en Shipday. ### ¿Puedo cancelar un reparto de Shipday desde el panel? Hoy no: el botón **Cancelar Viaje** de Histórico Riders falla con Shipday. Cancela el reparto desde Ágora, que borra el pedido en Shipday, o bórralo en el panel de Shipday. ### ¿Cómo cambio la API Key de Shipday de un local? Pídeselo a FOS: la integración de Shipday no tiene botón de editar en la ficha del local. ## Referencias - [Ficha de Shipday en el catálogo de integraciones](https://connectmanager.es/integraciones/shipday) - [Plataformas de reparto: cómo se pide el rider desde Ágora](https://connectmanager.es/docs/plataformas-de-reparto-como-funciona) - [Integración de reparto con Catcher](https://connectmanager.es/docs/integracion-catcher-agora) - [Integración de Glovo On-Demand (Glovo Local) con Ágora](https://connectmanager.es/docs/integracion-glovo-on-demand-agora) - Documentación oficial de la API de Shipday: [docs.shipday.com](https://docs.shipday.com/) - Guía del Integrador de Ágora, capítulo «Integración con Plataformas de Reparto». --- # Riders (repartidores) Portal: Plataformas de reparto · Panel URL: https://connectmanager.es/docs/manual-riders Actualizado: 2026-06-17 ## Riders (repartidores) Este apartado te muestra el histórico completo de todas las entregas que tus restaurantes han enviado a través de canales de delivery como Shipday y Catcher. Aquí puedes revisar el estado de cada pedido, los datos del repartidor asignado, el mapa de seguimiento en vivo, y acciones como sincronizar o cancelar entregas cuando es necesario. ### Cómo usarlo - **Accede a la página**: en el menú lateral, ve a Delivery Hub y selecciona Riders. - **Aplica filtros** (opcional): - Desde / Hasta: filtra pedidos por rango de fechas. - Canal: muestra solo entregas de Shipday o Catcher. - Estado Petición: filtra por estado (Aceptado, Completado, Entregado, Cancelado, etc.). - Local: selecciona un restaurante específico. - Búsqueda: escribe el nombre del cliente, número de pedido de Ágora o local para encontrar un pedido rápidamente. - **Revisa la lista de entregas**: cada fila muestra el cliente, número de pedido, local, estado en el canal, total y fecha. En pantalla móvil hay un botón Filtros y búsqueda que abre los filtros en una ventana flotante. - **Abre los detalles**: toca o haz clic en cualquier tarjeta de pedido. Se abrirá un panel lateral con toda la información: - Canal de destino (Shipday, Catcher, etc.). - Número de pedido y restaurante. - Repartidor asignado y teléfono (si está disponible). - Link de mapa GPS con seguimiento en vivo. - Lista de artículos del pedido con cantidades y precios. - Payload de entrada (datos que Ágora envió), payload enviado y respuesta de la API externa (para revisar detalles técnicos si hay problemas). - **Sincroniza o cancela (cuando sea posible)**: - Actualizar: fuerza una sincronización con los servidores de Shipday o Catcher para obtener el estado más reciente del pedido. - Cancelar Viaje: cancela la entrega en el proveedor. No aparece si el pedido ya está entregado, cancelado o no tiene ID externo (pedidos muy antiguos). - **Navega entre páginas**: al final de la lista hay botones Anterior y Siguiente para desplazarte por los registros (40 por página). ### Consejos - Si un pedido muestra estado Pendiente o parece antiguo, usa Actualizar para sincronizarlo con el canal. A veces los datos se cargan con retraso. - El teléfono del repartidor es un link que abre `tel:`, así que en móvil puedes llamar directamente. - Los payloads JSON se pueden copiar al portapapeles con el botón Copiar en la parte inferior del panel de detalles. Útil si necesitas compartir la información con soporte técnico. - Si un pedido es muy antiguo (sin ID en Shipday o Catcher), aparecerá un botón gris No Cancelable (Antiguo). En estos casos, la entrega ya no se puede modificar desde el panel. --- # Delivery propio: conectar la tienda online con Ágora Portal: Delivery propio · Primeros pasos URL: https://connectmanager.es/docs/delivery-propio-conectar-con-agora Actualizado: 2026-10-03 El **delivery propio** de Connect Manager es la tienda online de pedidos de un grupo de restaurantes —reparto a domicilio, recogida en tienda y pedido en mesa— conectada con **Ágora**: copia la carta digital del TPV, cobra con la pasarela de cada local y mete cada pedido en la caja del local como un pedido de Ágora. Este manual es para el técnico que pone en marcha la tienda de un cliente: qué hay que preparar en Ágora, qué se configura en el panel `/delivery-propio`, cómo viaja un pedido de la cesta al TPV y qué hacer cuando no entra. ## Qué hace la integración - **Copia la carta digital de Ágora**: categorías y su orden, artículos con el orden que tienen en Ágora, precios de la tarifa de la carta, nombre y descripción públicos, fotos, grupos de añadidos y modificadores (también los de precio cero), menús con sus platos y suplementos, alérgenos y etiquetas. La tienda sirve esa copia: no pregunta a Ágora en cada visita. - **Vuelve a traer la carta** a mano o cada 1, 6, 12 o 24 horas, según elijas. - **Una carta por canal** si hace falta: reparto, recogida y mesa pueden vender cartas digitales distintas; si un canal no tiene la suya, usa la del local. - **Lee los maestros de Ágora acotados a cada local** para que se elijan de una lista y no se tecleen: TPV, usuario, formas de pago, tarifas, centros de venta, series de pedido y formatos de venta (para los portes). - **Importa la configuración de pedidos que el local ya tiene en Ágora** como punto de partida: TPV, usuario, forma de pago, tarifa, centro de venta, comensales, pago a la entrega, minutos de preparación, días de antelación, franjas horarias y áreas de reparto con su polígono, pedido mínimo y porte. Lo que se haya cambiado a mano en los campos de cada servicio se respeta; las franjas y áreas que vinieron de Ágora se sustituyen en cada nueva importación y las creadas en el panel no se tocan. - **Decide qué local atiende cada dirección** con las áreas dibujadas en el mapa: si varias se pisan, el local abierto más cercano. Ver [Google Maps en el delivery propio](https://connectmanager.es/docs/delivery-propio-google-maps). - **Cobra** con el Redsys de cada local (tarjeta y, si el banco los tiene activos, Bizum y Apple Pay o Google Pay), con pago a la entrega, al recoger o al camarero, o con el saldo del club de fidelización. Ver [Redsys](https://connectmanager.es/docs/pagos-redsys). - **Mete el pedido en el TPV del local** por la API del integrador de Ágora como pedido de tipo `Delivery`, `TakeAway` o `Table`, con su serie y número propios, el cliente dedicado a los pedidos web, la dirección, el teléfono, las notas, las líneas (los menús como cabecera más platos), el porte, el descuento y el pago. - **Reintenta solo** cuando Ágora no acepta el pedido, **avisa por correo** de los pedidos cobrados que no han entrado e **imprime el pedido** en la impresora del local cuando se agotan los reintentos, para prepararlo a mano. - **Repasa cada 5 minutos** lo que se ha quedado a medias entre el banco, la cola y el TPV. - **Avisa al cliente por correo** cuando su pedido entra en la cocina y cuando el local lo marca como listo o en camino. - Da a cada pedido un **número corto de recogida** (del 1 al 99, por local y día) que viaja al TPV en la ubicación del pedido. - Permite **agotar productos** por local desde el panel (hoy o de forma permanente) sin tocar la carta de Ágora. ### Qué no hace - No consulta a Ágora en tiempo real: un precio o un plato cambiado en Ágora no llega a la tienda hasta la siguiente importación de la carta. - No edita la carta. Precios, nombres y categorías mandan en Ágora; en el panel solo se añaden cosas propias de la tienda (descripción, foto, vídeo y promoción de un plato). - No muestra los grupos de opciones de segundo nivel que no cuelgan de un plato de menú (el importador los cuenta en su aviso). - No decide la comanda de cocina: en los pedidos de reparto y para llevar, que la comanda se imprima o no depende de cómo esté configurado Ágora para ese tipo de pedido. - No se entera de lo que pasa con el pedido dentro del TPV una vez ha entrado. «Listo» o «En camino» lo marca el local en el panel. - No añade líneas a la cuenta abierta de una mesa: en el pedido en mesa cada ronda se pide y se paga aparte. - Cancelar un pedido en el panel no devuelve el dinero de la tarjeta: la devolución se hace en el TPV virtual del banco. - El número de recogida da la vuelta después del 99: con más de 99 pedidos en un día en el mismo local, se repite. ## Requisitos - **Ágora** con la licencia del **Módulo de Servicios de Integración** activa (la API del integrador, puerto 8984 por defecto) en el ACMS central y en el Ágora de cada local donde se meten los pedidos. El `Api-Token` se define al activar el módulo en **Herramientas → Activar Módulos Adicionales**. - **Conectividad**: Connect Manager está en la nube, así que el ACMS y el servicio de integración de cada local tienen que ser accesibles desde internet (puerto publicado o túnel de [Zero Connect](https://connectmanager.es/docs/zero-connect-instalacion)). Si el certificado es autofirmado, se puede desactivar la verificación del certificado en el panel. - **Las dos consultas personalizadas** de Connect Manager instaladas en el ACMS central: `CM Delivery configuración` y `CM Delivery catálogo`, con su permiso dado al perfil del usuario dueño del Api-Token. Se descargan desde el propio panel. - **Una carta digital** creada en Ágora para cada local (y, si se quiere, una por canal). - En el Ágora de cada local: una **serie de pedidos adicional** (no la serie activa), un **cliente dedicado** a los pedidos web, una **forma de pago** para los cobros online y, si se cobra envío, un **formato de venta para los portes**. - **En Connect Manager**: el grupo y sus locales dados de alta (lo hace FOS) y un usuario con acceso al panel Delivery propio y el permiso `Delivery: Configurar locales`. Quien solo atiende pedidos necesita `Delivery: Gestionar pedidos`. - **Para cobrar con tarjeta**: un TPV virtual de Redsys por local (lo contrata el cliente con su banco). - **Quién hace qué**: FOS da de alta el grupo y los locales en Connect Manager, asigna los permisos y mantiene los servicios de la plataforma (colas, claves de Google, correo de la plataforma). El distribuidor prepara Ágora (licencia, API, consultas, carta, serie, cliente y formas de pago) y configura la tienda y los locales en el panel. El cliente aporta los datos del banco, los horarios, las zonas y los precios de envío. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Dirección del ACMS | Distribuidor o informático del cliente: URL por la que se llega al servicio de integración del central desde internet | https://central-demo.example.com:8984 | Sí | | Api-Token del ACMS | Ágora central → Herramientas → Activar Módulos Adicionales | Cadena secreta: no la mandes por correo sin cifrar | Sí | | Consultas CM Delivery configuración y CM Delivery catálogo | Panel → Conexión ACMS → botones «Informe de configuracion» e «Informe de cartas» | Ficheros .xml | Sí | | Carta digital de cada local o canal | Ágora (Carta digital) | Se elige de una lista | Sí | | Dirección del servicio de Ágora de cada local | Distribuidor: URL del servicio de integración del TPV del local, accesible desde internet | https://local-demo.example.com:8984 | Sí | | Api-Token de cada local | Ágora del local → Herramientas → Activar Módulos Adicionales | Cadena secreta | Sí | | TPV, usuario, forma de pago, tarifa y centro de venta por servicio | Ágora del local (se eligen de listas en el panel) | «Caja 1», «WEB», «Tarjeta web» | Sí | | Serie de pedidos y último número usado | Ágora: serie adicional del local, distinta de la activa | PW · último nº 120 | Sí | | Cliente para los pedidos web | Ágora: número de una ficha de cliente creada solo para esto | 1234 · «PEDIDOS WEB» | Sí | | Formato de venta de los portes | Ágora: formato de venta del producto «Gastos de envío» | Se busca por nombre en el mapa de áreas | Si se cobra envío | | Forma de pago del saldo del club | Ágora: forma de pago para pedidos pagados con saldo | «Saldo club» | Solo para pagar con saldo | | Dirección exacta del local | Cliente | Calle Mayor 1, 28013 Madrid | Sí, para reparto | | Horarios, cierres y días de antelación | Cliente | Lunes a domingo 13:00–16:00 y 20:00–23:30 | Sí | | Zonas de reparto, pedido mínimo y coste de envío | Cliente | Zona 1: mínimo 15 €, envío 2,50 € | Sí, para reparto | | Datos del TPV virtual (FUC, terminal, clave SHA-256) | Banco del cliente | Ver Redsys | Para cobrar con tarjeta | | Correos que reciben los avisos de pedidos sin entrar | Cliente | encargado@restaurante-demo.es | Recomendado | | Nombre de la impresora para pedidos con error | Ágora del local | «COCINA» | No (vacío: la impresora por defecto) | ## Configuración paso a paso ### En Ágora (ACMS central) - Comprueba que la licencia del Módulo de Servicios de Integración está activa y anota el `Api-Token` en **Herramientas → Activar Módulos Adicionales**. - Descarga las dos consultas desde el panel (**Configuración → Tienda pública → Conexión ACMS**, botones «Informe de configuracion» e «Informe de cartas») y cópialas en la carpeta `custom-queries` de la instalación de Ágora del **ACMS central**. - Da los permisos `Consulta: CM Delivery configuración` y `Consulta: CM Delivery catálogo` al perfil del usuario cuyo Api-Token vas a usar. Sin el permiso, la consulta no devuelve nada. - Si actualizas Connect Manager y te piden una versión nueva de la consulta, vuelve a copiarla entera: el identificador no cambia, el contenido sí. - Revisa que cada local tenga su carta digital creada y con fotos. ### En Ágora (cada local) - Crea una **serie de pedidos adicional** para los pedidos web (una por canal si lo quieres separar). Ágora no deja importar pedidos con la serie activa del local. - Crea un **cliente dedicado**, por ejemplo «PEDIDOS WEB», y anota su número. No uses el cliente genérico de las ventas de mostrador: Ágora guarda con cada pedido el nombre, la dirección y el teléfono del comprador y va reescribiendo con ellos la ficha de ese cliente. - Crea o revisa la **forma de pago** de los cobros online (por ejemplo «Tarjeta web») y, si se va a pagar con saldo del club, otra para el saldo. - Si se cobra envío, crea un producto «Gastos de envío» con su formato de venta. - Revisa cómo trata Ágora los pedidos de reparto y para llevar (impresión de comanda, preparación): Connect Manager no lo fuerza. - Comprueba que el servicio de integración del local responde desde fuera (puerto 8984 publicado o túnel de Zero Connect). ### En Connect Manager: conexión con el ACMS - Entra en `/delivery-propio` y elige el grupo en el selector de la cabecera. - Ve a **Configuración → Tienda pública → Conexión ACMS** y rellena: - **Dirección del ACMS**: la URL del central. - **Api-Token**: se guarda cifrado y no se vuelve a enseñar. Un campo vacío al guardar significa «no lo cambies». - **Verificar el certificado**: déjalo encendido salvo que el ACMS use un certificado autofirmado. - **Revisar la carta**: «Solo a mano», «Cada hora», «Cada 6 horas», «Cada 12 horas» o «Una vez al día». Si el cliente toca la carta a menudo, «Cada 6 horas» es un buen punto de partida. La revisión automática solo corre con la tienda abierta. - Pulsa **Guardar** y después **Probar ACMS**. Debe decir «Todo listo» con el número de cartas encontradas. Hasta que la prueba no sale bien no aparecen los botones «Importar cartas» e «Importar de Ágora». ### En Connect Manager: cada local - Ve a **Configuración → Locales** y pulsa **Traer locales del grupo**. Llegan apagados y sin tocar nada de lo que ya estuviera configurado. - Abre el local. En **Ubicación y contacto**: el **Nombre público** (el que ve el cliente en la carta, en los correos y en el cargo de la tarjeta, cortado a 25 caracteres), los **Servicios** (Reparto a domicilio, Recogida en tienda, Pedido en mesa; con los tres apagados el local no sale en la web), la **Dirección** con **Buscar en Google** para fijar latitud y longitud, el contacto, las redes, el enlace de reseñas y los **Días futuros que se pueden reservar**. - En **Identidad y conexión**: - **Local en Ágora** y **Carta digital**: se eligen de las listas del ACMS. - **Dirección del servicio** y **Api-Token**: los del Ágora del local, por donde entra el pedido en su caja. - **Verificar el certificado** y **Impresora para pedidos con error** (nombre de la impresora en Ágora; vacío, la de por defecto). Guarda y pulsa **Probar inyección**: prueba lo guardado, no lo escrito en pantalla. - Opcional pero recomendable: vuelve a **Conexión ACMS** y pulsa **Importar de Ágora**. Trae servicios, franjas horarias y áreas de reparto de los locales que ya tienen elegido su local de Ágora, y te dice qué campos ha respetado por estar cambiados a mano. No trae la serie ni el cliente de los pedidos web. - En **Pasarela de pago**, los datos de Redsys del local (ver [Redsys](https://connectmanager.es/docs/pagos-redsys)). - En **Reparto**, **Recogida** y **En mesa** (solo los servicios que use el local): - **Carta digital**: vacía, la del local; elige otra solo si ese canal vende cosas distintas. Si la carta elegida no está traída, se trae sola. - **TPV**, **Usuario**, **Forma de pago**, **Tarifa** y **Centro de venta**: las listas solo enseñan los maestros de ese local en Ágora. Si no sale el que buscas, revisa en Ágora que esté disponible para los grupos de TPV del local. Un centro de venta equivocado no da error al guardar: el pedido sale por la cocina equivocada. - **Forma de pago del saldo del club**: vacía, la tienda no ofrece pagar con saldo. - **Cliente para los pedidos web** (número de Ágora) y **Nombre del cliente**. - **Serie de pedidos**: solo salen las series adicionales del local. Al elegirla se rellena **Próximo número de pedido** con lo que diga Ágora; compruébalo en el TPV antes de guardar. El contador es del local y la serie: reparto y recogida lo comparten si usan la misma. - **Reintentos si no entra en Ágora**: 5 por defecto (de 0 a 20). - **Preguntar el número de comensales**, **Minutos de preparación** (30 por defecto; es la primera hora que se ofrece al cliente) y **Permitir pago a la entrega** / **al recoger** / **pagar al camarero**. - En mesa: **Mesas, una por línea**, con el nombre exacto de la ubicación en Ágora. Debajo salen los enlaces de cada mesa para hacer los códigos QR. Si la pantalla dice que no se puede configurar, lee el motivo: falta el ACMS, el local de Ágora o la sección «Maestros» de la consulta. Arréglalo y pulsa **Volver a comprobar**. - Completa **Horarios** (franjas por día; si la hora de fin es menor que la de inicio, la franja cruza la medianoche), **Cierres** y **Áreas de reparto** (ver [Google Maps](https://connectmanager.es/docs/delivery-propio-google-maps)). ### En Connect Manager: carta y publicación - Trae las cartas con **Importar cartas** (Conexión ACMS) o con **Volver a traer** en **Operación → Cartas**. Va en segundo plano y avisa en la campana del panel al terminar. - En **Operación → Cartas** elige la carta y revisa artículos, precios, fotos (filtro «Con foto») y opciones. «Borrar cartas sin usar» quita las que no tiene asignadas ningún local ni canal. - En **Configuración → Tienda pública → Correo**, rellena **Avisar a** con los correos que deben enterarse de un pedido cobrado que no entra en el TPV. El proveedor de correo se explica en [Correo electrónico](https://connectmanager.es/docs/correo-proveedores-de-envio). - En **Configuración → Tienda pública → General**: la **Dirección** pública (queda como `https://hub.connectmanager.es/pedidos/restaurante-demo`), el **Nombre para el cliente** y, cuando todo esté probado, **Tienda abierta**. La lista «Locales» de esa pantalla dice qué le falta a cada uno; publica cuando todos digan «Listo». ## Cómo funciona ### La carta: de Ágora a la tienda Al pulsar «Importar cartas», o cuando toca la revisión programada (cada hora se mira qué tiendas abiertas tienen que refrescar), Connect Manager encola una importación por tienda. La importación pide al ACMS, con la consulta `CM Delivery catálogo`, solo las cartas asignadas a algún local o canal; baja las fotos que falten, las reduce y las guarda en su almacén, y actualiza su copia de la carta sin borrarla y recrearla, para que una cesta a medio llenar no se quede apuntando a artículos que ya no existen. Si Ágora devuelve una carta vacía, se aborta para no dejar la tienda sin nada que vender. Un fallo en una carta no cancela las demás, y el resultado se avisa en la campana del panel. Desde ese momento la tienda lee la copia: no pregunta a Ágora en cada visita. ```mermaid sequenceDiagram participant P as Panel participant Q as Cola participant A as ACMS Ágora participant F as Almacén de fotos participant B as Copia de la carta participant T as Tienda online P->>Q: Importar cartas o revisión programada Q->>A: Consulta CM Delivery catálogo por secciones A-->>Q: Categorías, artículos, opciones, menús y alérgenos Q->>A: Pide las fotos que faltan Q->>F: Guarda las fotos reducidas Q->>B: Actualiza la copia sin borrarla Q-->>P: Aviso en la campana con el resultado T->>B: Lee la copia al pintar la carta ``` ### El pedido: de la cesta al TPV El cliente elige local y servicio, llena la cesta y va a pagar. Al pulsar «Pagar», Connect Manager vuelve a leer precios, opciones, horario, zona, pedido mínimo, agotados y promociones (no se fía de lo que tenía pintado la pantalla) y comprueba que el servicio del local tenga el mapeo de Ágora completo y la pasarela configurada. Si algo falla, no se cobra. Si todo cuadra, crea el pedido «Sin pagar» y lleva al cliente a la página de Redsys. La confirmación del banco llega por una notificación firmada servidor a servidor, que es la única que da el pedido por cobrado; el regreso del navegador no decide nada. Con el pedido cobrado se le asigna el número de recogida y se encola el envío al TPV, que reserva serie y número una sola vez y manda el documento al Ágora del local. Cuando Ágora lo acepta, el pedido pasa a «En el TPV» y el cliente recibe el correo de pedido confirmado. ```mermaid sequenceDiagram participant C as Cliente participant T as Tienda online participant R as Redsys participant Q as Cola participant A as Ágora del local C->>T: Pulsa Pagar T->>T: Revalida carta, horario, zona y precios T->>T: Crea el pedido Sin pagar T->>R: Formulario firmado con el importe C->>R: Paga con tarjeta, Bizum o cartera R->>T: Notificación firmada servidor a servidor T->>T: Pedido cobrado y número de recogida T->>Q: Encola el envío al TPV Q->>A: POST /api/import/ con serie y número reservados A-->>Q: Aceptado Q->>C: Correo de pedido confirmado R-->>C: Vuelve a la pantalla de gracias ``` ### Pago a la entrega y con saldo del club Con pago a la entrega, al recoger o al camarero, el pedido no pasa por el banco: nace confirmado («Cobrado, sin enviar» en el panel, pero sin fecha de cobro) y se manda directamente al TPV **sin ningún pago**; el local lo cobra en la caja y elige allí la forma de pago. En el panel, el total de esos pedidos lleva debajo «a la entrega». Con saldo del club, el saldo se descuenta en el mismo momento de crear el pedido (si ya no llega, no se crea nada) y el pedido entra en Ágora cobrado con la **Forma de pago del saldo del club**. Si el grupo tiene [club de fidelización](https://connectmanager.es/docs/fidelizacion-conectar-con-agora), el pedido acumula con las reglas del local cuando se confirma; lo hace Connect Manager, porque en el TPV el pedido entra con el cliente de los pedidos web y no con el del socio. ### Qué se manda a Ágora - **Serie, número y GlobalId** reservados antes del primer intento y repetidos en cada reintento: Ágora reconoce el pedido por serie y número, así que reenviar uno que ya entró no lo duplica. - **Tipo** `Delivery`, `TakeAway` o `Table`, estado pendiente y fecha de entrega (la programada o ahora más los minutos de preparación). - **Referencia** del pedido (por ejemplo `P-ABC123`) en el número de documento del cliente. - **Cliente**: siempre el número configurado, con el nombre, la dirección y el teléfono del comprador. - **Dirección de entrega**, TPV, local, usuario y centro de venta; en la ubicación va la mesa (pedido en mesa) o el número de recogida. - **Notas**: las del cliente, su nombre y las indicaciones de la dirección (piso, puerta). - **Líneas**: cada plato con su formato de venta, IVA y tarifa; los añadidos dentro de su línea; los menús como cabecera con el precio del menú y un plato por grupo con su suplemento; y el porte como una línea más con el formato elegido. - **Descuento** en euros en el pie del documento (cupón de campaña más promociones de plato). - **Pago** con la forma de pago configurada, el importe que firmó el banco y la referencia de Redsys en sus notas; vacío en el pago a la entrega. Antes de mandarlo se comprueba que las líneas menos el descuento sumen exactamente el total cobrado; si no cuadra, el pedido no se manda y queda como incidencia. Los tipos de IVA se leen del propio Ágora del local. ### Reintentos, aviso e impresión Si Ágora no acepta el pedido (TPV apagado, sin conexión, un maestro que no existe), el pedido pasa a «No ha entrado en el TPV» con el error de Ágora guardado. En ese primer fallo se envía **un único correo** al local, a las direcciones de «Avisar a» y a la guardia de FOS. A los pocos segundos se reintenta solo, con la misma serie y el mismo número, tantas veces como diga «Reintentos si no entra en Ágora». Si sigue sin entrar al agotarlos, se imprime el pedido con su error en la impresora del local para que la cocina lo prepare a mano. Si Ágora responde que el pedido «ya existe», se da por bueno. ```mermaid flowchart TD E[Envío al TPV] --> D{Ágora lo acepta} D -- Sí --> OK[En el TPV y correo al cliente] D -- No --> X[No ha entrado en el TPV] X --> M[Correo de aviso, una sola vez por pedido] X --> W[Espera unos segundos] W --> R{Quedan reintentos} R -- Sí --> E R -- No --> I[Ticket con el error en la impresora del local] ``` ### El repaso de cada 5 minutos Cada 5 minutos Connect Manager repasa los pedidos: si el banco cobró y el pedido seguía «Sin pagar» (por ejemplo, porque se cortó un proceso en mitad), lo marca cobrado y lo manda al TPV; vuelve a encolar los pedidos cobrados que llevan más de 5 minutos sin enviarse; marca como caducados los intentos de pago que se fueron al banco hace más de 20 minutos sin volver (el pedido se queda «Sin pagar» y el cliente puede reintentar con la misma cesta), y manda el aviso de los pedidos fallidos que no lo recibieron. Todo es repetible sin duplicar comandas ni avisos. ### Los avisos - **Al cliente**: «Pedido confirmado» cuando entra en el TPV (no al cobrar) y «Listo» o «En camino» cuando el local lo marca en el panel. El seguimiento da el pedido por entregado hora y media después. - **Al local**: el correo de pedido sin entrar en el TPV y, si se agotan los reintentos, el ticket impreso. - **En el panel**: la entrada «Pedidos» del menú lleva un contador con los pedidos cobrados sin enviar y los que no han entrado, y la lista se refresca cada 30 segundos. ## Comprobar que funciona - En **Conexión ACMS**, «Probar ACMS» dice «Todo listo». - En **Configuración → Locales**, la columna «Ágora» del local dice «Conectado» tras «Probar inyección», y «En el mapa» está marcada. - En **Operación → Cartas** se ve la carta con sus precios y fotos. - En **Tienda pública → General**, el local sale como «Listo». - Con la pasarela del local en **Pruebas**, abre la tienda (botón «Abrir la tienda»), busca una dirección dentro de una zona, haz un pedido pequeño y págalo con la tarjeta de prueba de Redsys. - En **Operación → Pedidos** el pedido debe pasar a «En el TPV»; pulsando el estado ves la serie y el número con los que entró. - Busca ese pedido en el TPV del local y revisa local, centro de venta, líneas, porte, cliente, notas e importe. - Comprueba que llega el correo de pedido confirmado y marca el pedido como «Listo» o «En camino» para ver el segundo correo. - Prueba también una recogida y, si se ofrece, un pago a la entrega. - Cuando todo cuadre, cambia la pasarela a **Producción** y abre la tienda. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «No se ha podido conectar con el ACMS» | URL o token mal, ACMS apagado o no accesible desde internet | Revisa la dirección, el token y el puerto; prueba la URL desde fuera de la red del cliente | | «Conectado, pero el informe no contesta» | La consulta CM Delivery configuración no está copiada en custom-queries del ACMS o su perfil no tiene permiso | Copia el fichero en el central y da el permiso al perfil del usuario del Api-Token | | «El informe instalado es de una versión anterior» | Falta la sección «Maestros» de la consulta | Descarga de nuevo el informe de configuración y vuelve a copiarlo | | La pantalla de Reparto o Recogida no deja configurar | ACMS sin probar, local sin emparejar en «Identidad y conexión» o consulta sin la sección Maestros | Arregla lo que indica el aviso y pulsa «Volver a comprobar» | | «Ningún local tiene carta asignada» | No se ha elegido carta digital en ningún local | Elige la carta en «Identidad y conexión» y vuelve a importar | | La tienda dice «La carta de este local todavía no está publicada» | La carta asignada no se ha importado | Pulsa «Volver a traer» en Operación → Cartas | | Un precio cambiado en Ágora no se ve en la tienda | La tienda vende con la copia de la carta | Vuelve a traer la carta o pon «Revisar la carta» cada pocas horas | | El cliente ve «Este local no está aceptando pedidos ahora mismo» | Mapeo de Ágora incompleto en ese servicio, o la zona cobra envío y no tiene producto de portes | Completa el servicio (la lista de «General» dice qué falta) y elige el producto de portes en el mapa de áreas | | «Este local no puede cobrar ahora mismo» | Pasarela apagada o sin FUC o clave | Revisa Pasarela de pago | | Pedido en «No ha entrado en el TPV» con «Equipo apagado o sin conexión (túnel no disponible)» o «Sin conexión con el TPV (túnel no encontrado)» | Equipo del local apagado o túnel de Zero Connect caído | Enciende el equipo o revisa Zero Connect y pulsa «Reenviar» | | Error «La serie no se encuentra dada de alta» | Serie inexistente o es la activa del local | Usa una serie adicional del local y reenvía | | Errores como «Tarifa no existe», «Centro de venta no existe» o «Usuario no dado de alta» | Maestro borrado en Ágora o que ya no pertenece a ese local | Corrige el campo en el servicio y reenvía | | «No se conoce el tipo de IVA … Vuelve a probar la conexión del local para releer los maestros de Ágora» | Un artículo usa un IVA que el Ágora del local no tiene, o Connect Manager no pudo leer los IVA del local (por ejemplo, porque el TPV estaba apagado) y guarda esa lectura hasta 6 horas | Revisa los IVA en Ágora. Si el TPV estuvo apagado, pide a FOS que refresque la lista de IVA del local: «Probar inyección» no la renueva. Después pulsa «Reenviar» | | «El documento no cuadra: las lineas suman …» | Las líneas menos el descuento no dan el total cobrado | No se manda a propósito: mételo a mano en el TPV, márcalo con «Metido a mano» y avisa a FOS | | Pedido «No ha entrado en el TPV» con «El banco ha cobrado X € de un total de Y €.» | El banco cobró menos que el total: el pedido no se manda a la cocina | Revisa el cobro en Redsys antes de prepararlo | | Pedidos que se quedan «Sin pagar» | Tarjeta denegada o el cliente abandonó la página del banco | Es normal: el filtro de la lista los oculta y el cliente puede volver a pagar | | Pedidos que el panel da por «En el TPV» y no están en la caja, o números repetidos en la serie | «Próximo número de pedido» por debajo del último número de esa serie en Ágora: Ágora contesta que el pedido «ya existe» y Connect Manager lo da por entrado | Pon en el servicio el siguiente al último número que tenga Ágora en esa serie y revisa a mano los pedidos afectados | | Nunca llega el aviso de pedido sin entrar | «Avisar a» vacío o correo del local sin rellenar, o problema con el proveedor de correo | Rellena «Avisar a» y revisa el correo | ## Preguntas frecuentes ### ¿Cómo conecto la tienda online del delivery propio con Ágora? Instala las dos consultas de Connect Manager en el ACMS, pon la dirección y el Api-Token del ACMS en Tienda pública → Conexión ACMS, empareja cada local con su local de Ágora y su carta, pon la dirección y el token del Ágora del local para meter los pedidos y completa el mapeo de Reparto y Recogida (TPV, usuario, forma de pago, tarifa, centro de venta, serie y cliente). ### ¿Necesito un ACMS central para usar el delivery propio? El panel lee los maestros y las cartas de la «Dirección del ACMS» del grupo, y mete cada pedido por la dirección de Ágora de su local. Si el cliente no tiene central, consulta con FOS qué servidor usar como ACMS antes de configurarlo. ### ¿Por qué no puedo usar el cliente genérico de Ágora para los pedidos web? Porque Ágora guarda con cada pedido el nombre, la dirección y el teléfono del comprador y va reescribiendo con ellos la ficha del cliente usado. Con un cliente dedicado solo se reescribe esa ficha; con el genérico, la de las ventas de mostrador. ### ¿Qué pasa si el TPV del local está apagado cuando entra un pedido? El pedido ya está cobrado: queda como «No ha entrado en el TPV», se avisa por correo, se reintenta solo y, si no entra, se imprime en el local al agotar los reintentos. Cuando el TPV vuelve, «Reenviar» lo mete sin duplicarlo. ### ¿Se duplica el pedido si lo reenvío? No. Cada pedido conserva siempre la misma serie y el mismo número, y Ágora reconoce el pedido por esa pareja: si ya había entrado, lo actualiza en vez de crear otro. ### ¿Cada cuánto se actualiza la carta de la tienda? Cuando pulsas «Importar cartas» o «Volver a traer», y además cada 1, 6, 12 o 24 horas si lo eliges en «Revisar la carta». La revisión automática solo funciona con la tienda abierta. ## Referencias - [Google Maps en el delivery propio: direcciones y zonas de reparto](https://connectmanager.es/docs/delivery-propio-google-maps) - [Redsys: pasarela de pago de la tienda y de Fidelización](https://connectmanager.es/docs/pagos-redsys) - [Correo electrónico: proveedores de envío](https://connectmanager.es/docs/correo-proveedores-de-envio) - [Medición del delivery propio: GA4, Tag Manager y Meta Pixel](https://connectmanager.es/docs/delivery-propio-medicion) - [Google Gemini y Veo en el delivery propio](https://connectmanager.es/docs/delivery-propio-ia) - [Fidelización: conectar el club con Ágora](https://connectmanager.es/docs/fidelizacion-conectar-con-agora) - [Zero Connect: conectar Ágora sin abrir puertos](https://connectmanager.es/docs/zero-connect-instalacion) - [Catálogo de integraciones de Connect Manager](https://connectmanager.es/integraciones) --- # Google Maps en Delivery propio: direcciones y zonas de reparto Portal: Delivery propio · Integraciones URL: https://connectmanager.es/docs/delivery-propio-google-maps Actualizado: 2026-10-03 **Google Maps** está detrás de todas las direcciones del delivery propio de Connect Manager, la tienda online conectada con **Ágora**: propone la calle mientras el cliente escribe, convierte la dirección en coordenadas para saber si cae dentro de una zona de reparto, sitúa cada local en el mapa y dibuja las zonas en el panel. Este manual es para el técnico que ubica los locales y dibuja las zonas de reparto con sus mínimos y portes: qué servicios de Google se usan, qué claves hacen falta y quién las pone, y cómo decide la tienda qué local lleva cada pedido. ## Qué hace la integración - **Propone direcciones mientras el cliente escribe** (a partir de 3 caracteres), en la portada de la tienda, en el paso de pago y en «Mi cuenta». Solo propone direcciones de España (calle, portal), hasta cinco. - **Saca el punto exacto de la dirección elegida** y, de la misma respuesta, la calle, el número, la ciudad, la provincia y el código postal. Esos datos viajan al pedido de Ágora cada uno en su casilla. - **Busca una dirección escrita a mano** con el botón de la portada, y **pone nombre a la ubicación del móvil** cuando el cliente pulsa «usar mi ubicación». - **Sitúa cada local en el mapa** con el botón «Buscar en Google» de su ficha; las coordenadas se pueden corregir a mano. - **Dibuja las zonas de reparto en un mapa del panel**, todas a la vez para ver dónde se pisan, con vértices que se pueden arrastrar. - Cada zona tiene **pedido mínimo, coste de envío, tramos de envío por importe**, **envío gratis desde** un importe y el **producto de portes** de Ágora con el que se cobra. - **Decide qué local reparte**: el que tiene una zona activa que contiene la dirección; si hay varios, el abierto más cercano. - **Enseña al cliente lo que cuesta el envío** antes de entrar en la carta y, en el pago, cuánto le falta para el siguiente tramo («Añade X € y el envío te cuesta Y €»). - **Ordena los locales de recogida** por cercanía a la dirección del cliente. - En el seguimiento de un pedido a domicilio, **pinta un mapa** con el local y la dirección de entrega unidos por una línea punteada. - **Importa de Ágora las áreas de reparto** que el local ya tenga dibujadas allí, con su polígono, mínimo, porte y formato de portes. ### Qué no hace - No calcula rutas ni tiempos por carretera: el reparto se decide con zonas dibujadas, y la distancia en línea recta solo sirve para ordenar locales. - No sigue al repartidor: la línea del seguimiento va del local a la dirección, no es una ruta. - No crea zonas por radio ni por código postal: se dibujan a mano o se importan de Ágora. - No propone direcciones fuera de España ni nombres de negocios. - No usa claves de Google del cliente: las claves son de la plataforma y las configura FOS. - En el paso de pago la dirección de reparto se elige de la lista que propone Google: si el autocompletado no funciona, el cliente no puede completar un pedido a domicilio. ## Requisitos - **Claves de Google en el servidor de Connect Manager** (las pone FOS, son comunes a todos los clientes): - Una **clave de servidor** con Geocoding API y Places API (New): sugerencias, punto exacto, búsqueda escrita, «usar mi ubicación» y «Buscar en Google» del panel. - Una **clave de navegador** con Maps JavaScript API: el mapa de áreas del panel y el mapa del seguimiento del pedido. - El delivery propio conectado con Ágora (ver [Delivery propio: conectar la tienda online con Ágora](https://connectmanager.es/docs/delivery-propio-conectar-con-agora)): el producto de portes se elige de los formatos de venta del ACMS. - En Ágora, un producto de gastos de envío con su formato de venta si alguna zona cobra envío. - Un usuario con el permiso `Delivery: Configurar locales`. - **Quién hace qué**: FOS mantiene las claves y el proyecto de Google; el distribuidor ubica los locales, dibuja las zonas y elige el producto de portes; el cliente decide zonas, mínimos y precios de envío. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Dirección exacta de cada local | Cliente | Calle Mayor 1, 28013 Madrid | Sí, para repartir | | Coordenadas de la puerta por la que sale el reparto | Cliente o técnico: en Google Maps, clic derecho sobre el punto | 40.4168 · -3.7038 | Solo si Google no acierta | | Contorno de cada zona de reparto | Cliente: plano o calles que hacen de límite | «Hasta la M-30 y el río» | Sí, para repartir | | Pedido mínimo por zona | Cliente | 15,00 € | No (0 = sin mínimo) | | Coste de envío de partida | Cliente | 2,50 € | No (0 = gratis) | | Tramos de envío | Cliente | Desde 25 € el envío cuesta 1,50 € | No | | Envío gratis desde | Cliente | 40,00 € | No | | Producto de portes | Ágora: formato de venta del producto de envío | «Gastos de envío» | Sí, si la zona cobra envío | | Clave de servidor de Google | FOS (no se pide al cliente) | Variable del servidor GEOCODING_GOOGLE_KEY | Sí | | Clave de navegador de Google | FOS (no se pide al cliente) | Variable del servidor GOOGLE_MAPS_BROWSER_KEY | Sí, para dibujar y para el mapa del seguimiento | ## Configuración paso a paso ### En Google Cloud (lo hace FOS) - En el proyecto de Google de la plataforma, activa **Geocoding API**, **Places API (New)** y **Maps JavaScript API**. - **Clave de servidor**: limita sus APIs a Geocoding y Places (New) y guárdala en el servidor como `GEOCODING_GOOGLE_KEY`. Nunca se publica en ninguna página. - **Clave de navegador**: restríngela por referente HTTP a los dominios del panel y de la tienda, con Maps JavaScript API como única API, y guárdala como `GOOGLE_MAPS_BROWSER_KEY`. Esta sí viaja en el código de las páginas, por eso va aparte y restringida. > [!NOTE] Las sugerencias de calle se piden desde el servidor y no desde el navegador a propósito: con la clave del navegador, Places contestaba `API_KEY_SERVICE_BLOCKED` por sus restricciones. Si un día dejan de salir sugerencias, en el registro del servidor se distingue `API_KEY_SERVICE_BLOCKED` (restricciones de la clave) de `SERVICE_DISABLED` (API sin activar en el proyecto). ### En Ágora - Si alguna zona va a cobrar envío, crea el producto de gastos de envío con su formato de venta. Es lo que se elige como «Producto de los portes». - Si el local ya tiene las áreas de reparto dibujadas en su configuración de pedidos de Ágora, puedes traerlas en lugar de dibujarlas (paso «Importar de Ágora» más abajo). ### En Connect Manager: situar el local - Ve a **Configuración → Locales**, abre el local y entra en **Ubicación y contacto**. - Escribe la **Dirección** con número de portal y ciudad y pulsa **Buscar en Google**. Si la encuentra, rellena **Latitud** y **Longitud**. - Si el punto no es el bueno (la salida de la cocina está en otra calle, una plaza peatonal), corrige las coordenadas a mano. - Pulsa **Guardar**. En el listado de locales, la columna «En el mapa» queda marcada. > [!WARNING] Sin punto en el mapa el local puede repartir, pero cuando dos zonas se pisan va siempre el último en el orden: no se puede calcular qué local está más cerca. ### En Connect Manager: dibujar las zonas - En el mismo local, entra en **Áreas de reparto**. El mapa sale centrado en el local. - Pulsa **Añadir zona** y ponle nombre. - Con la zona en modo **Dibujando**, pulsa en el mapa para ir marcando el contorno y ciérralo pulsando el primer punto o con doble clic. Con la zona ya dibujada puedes arrastrar sus vértices; para editar otra, pulsa su botón «Dibujar» o pulsa sobre ella en el mapa. - Rellena los importes de la zona: - **Mínimo (€)**: pedido mínimo de comida, sin contar descuentos. - **Envío (€)**: el coste de partida. - **Gratis desde (€)**: vacío es «Nunca». - **Tramos del envío**: con «+ Añadir tramo», «Desde X € el envío cuesta Y €». Por debajo del primer tramo se cobra el «Envío» de partida. - **Producto de los portes**: escribe para buscar entre los formatos de venta de Ágora. - Deja marcada **Activa** (desmarcada, la zona existe pero no cubre a nadie). - Pulsa **Guardar áreas**. Guarda todas las zonas del local de una vez; si una zona cobra envío y no tiene producto de portes, no deja guardar. > [!TIP] Si haces anillos (1 km, 2 km, 3 km con mínimo y porte crecientes), crea primero el más pequeño. Dentro de un mismo local, cuando una dirección cae en varias zonas manda la primera en el orden, y las dibujadas en el panel van por orden de creación. ### En Connect Manager: traer las zonas de Ágora (opcional) - Con el local emparejado con su local de Ágora (pantalla «Identidad y conexión»), ve a **Configuración → Tienda pública → Conexión ACMS** y pulsa **Importar de Ágora**. - Se crean las zonas con el polígono, el pedido mínimo, el coste de envío y el formato de portes de Ágora, en el orden que tienen allí. - Revisa cada zona en el mapa y añade tramos o envío gratis si hacen falta. > [!WARNING] Al volver a importar de Ágora, las zonas que vinieron de Ágora se sustituyen enteras por lo que haya allí, aunque las hayas retocado en el panel. Las zonas creadas en el panel no se tocan. ## Cómo funciona ### De lo que escribe el cliente a la zona de reparto Mientras el cliente escribe su dirección, la tienda pide sugerencias a Places desde el servidor de Connect Manager (no desde el navegador), con un identificador de sesión para que Google cuente toda la búsqueda como una sola. Cuando el cliente elige una sugerencia, se pide el detalle de ese sitio: coordenadas, calle, número, ciudad, provincia y código postal. Con las coordenadas se busca qué zonas activas contienen el punto y se decide el local; la tienda responde si llega, si llega pero ahora está cerrado (y si se puede programar) o si no reparte en esa dirección, junto con el pedido mínimo y el coste de envío de la zona. El pedido se resuelve con las coordenadas y no con el texto: dos portales de la misma calle pueden caer en zonas distintas. ```mermaid sequenceDiagram participant C as Cliente participant T as Tienda online participant G as Google Places participant Z as Zonas de reparto C->>T: Escribe la dirección T->>G: Autocompletado con sesión G-->>T: Hasta 5 direcciones de España C->>T: Elige una T->>G: Detalle del sitio G-->>T: Coordenadas, calle, número, ciudad y CP T->>Z: Qué zonas activas contienen el punto Z-->>T: Local, mínimo y coste de envío T-->>C: Llegamos, cerrado ahora o fuera de zona ``` ### Qué local reparte Para cada local con reparto encendido se mira si alguna de sus zonas activas contiene el punto; dentro de un local se queda con la primera que lo contiene. Si hay varios locales candidatos, se ordenan por distancia en línea recta desde la dirección y gana el más cercano **que esté abierto** en ese momento; si el más cercano libra ese día, reparte el siguiente. Si todos los que cubren la dirección están cerrados, la tienda enseña el horario del más cercano. Un local sin coordenadas va el último. Para la recogida no hay zonas: se enseñan todos los locales que recogen, ordenados por distancia. ```mermaid flowchart TD P[Punto de la dirección] --> L{Algún local tiene una zona activa que lo contiene} L -- No --> F[Fuera de zona] L -- Sí --> O[Candidatos ordenados por distancia en línea recta] O --> A{Hay alguno abierto} A -- Sí --> R[Reparte el abierto más cercano con su zona] A -- No --> C[Cerrado, se enseña cuándo abre el más cercano] ``` ### Cuánto cuesta el envío El envío se calcula contra el importe de la comida **sin descuentos**, igual que el pedido mínimo: si ese importe llega al «Gratis desde», el envío es gratis; si no, se cobra el coste del último tramo alcanzado y, por debajo del primero, el «Envío» de partida. En el paso de pago se avisa del siguiente escalón que abarata el envío. El porte entra en Ágora como una línea más con el formato de venta elegido y el IVA de la comida. ### Los mapas El mapa de áreas del panel y el del seguimiento del pedido se cargan en el navegador con la clave de navegador. El del seguimiento solo sale en pedidos a domicilio cuyo local tiene coordenadas y cuya dirección tiene punto, y no es una ruta: es una línea punteada del local a la dirección. ### Caché y límites - Una dirección encontrada se recuerda 180 días (las que no se encuentran, 6 horas); una ubicación del móvil ya traducida, 30 días; una sugerencia, 5 minutos. - Para no gastar cuota con abusos, cada conexión puede pedir 60 sugerencias por minuto y usar «mi ubicación» 20 veces cada 10 minutos. - Las búsquedas van en español y sesgadas a España. ## Comprobar que funciona - «Buscar en Google» encuentra la dirección del local y la columna «En el mapa» queda marcada. - En «Áreas de reparto» se ve el mapa; tras dibujar y pulsar «Guardar áreas» el aviso dice «Todas tienen su zona dibujada». - Abre la tienda, escribe una dirección que sepas que está dentro: deben salir sugerencias y, al elegirla, el local, el mínimo y el coste de envío. - Prueba una dirección justo fuera de la zona: no debe ofrecer reparto. Prueba también una en la zona de solape entre dos locales. - En el paso de pago, añade comida hasta cruzar un tramo y comprueba que el envío cambia. - Haz un pedido de prueba a domicilio y revisa en Ágora la línea de portes y la dirección (calle, población y código postal en sus casillas). - Abre el seguimiento del pedido y comprueba que sale el mapa. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | «Falta la clave de Google» con «Sin GEOCODING_GOOGLE_KEY hay que poner la latitud y la longitud a mano» | Falta la clave de servidor | Avisa a FOS; mientras tanto escribe las coordenadas a mano | | «No se ha encontrado esa dirección» al pulsar «Buscar en Google» | Dirección incompleta o ambigua | Añade número de portal y ciudad, o escribe las coordenadas | | En «Áreas de reparto»: «Falta la clave de Google Maps» | Falta la clave de navegador | Avisa a FOS. Se pueden editar los importes, pero no dibujar | | «No se pudo cargar Google Maps. Revisa que la clave sea de navegador y que el dominio este permitido.» | Clave de navegador mal restringida o API sin activar | FOS debe permitir el dominio del panel y activar Maps JavaScript API | | «Falta el producto de los portes» | La zona cobra envío o algún tramo y no tiene formato de portes | Elige el producto en «Producto de los portes» y vuelve a guardar | | «Áreas guardadas» con «Ojo: N sin dibujar» | Zonas con menos de tres puntos | Dibuja su contorno; sin él no cubren ninguna dirección | | La tienda no propone ninguna calle al escribir | Clave de servidor ausente, sin Places API (New) o con sus restricciones bloqueándola | Avisa a FOS; en el registro se ve si es API_KEY_SERVICE_BLOCKED o SERVICE_DISABLED | | «Elige la dirección de la lista que propone el buscador.» en el pago | El cliente escribió la dirección sin elegir una sugerencia | Tiene que elegirla de la lista; si no sale ninguna, ver la fila anterior | | «Este local no reparte en esa dirección.» | El punto no cae en ninguna zona activa de ese local | Revisa el dibujo y que la zona esté marcada como activa | | «El pedido mínimo de esa zona son … Te faltan …» | Mínimo de la zona no alcanzado (se mide sin descuentos) | Es lo esperado; ajusta el mínimo si no es el que quiere el cliente | | Reparte un local que no es el más cercano | El cercano está cerrado, no tiene coordenadas o su zona no cubre ese punto | Revisa horarios, «En el mapa» y el dibujo de las zonas | | Se cobra un porte que no corresponde en una casa cerca del local | Anillos creados en mal orden: manda la primera zona que contiene la dirección | Borra y vuelve a crear las zonas empezando por la más pequeña | | Tras «Importar de Ágora» desaparecen retoques del mapa | Las zonas importadas de Ágora se sustituyen al reimportar | Haz los cambios en Ágora o crea las zonas en el panel | | «Demasiados intentos desde esta conexión. Escribe tu dirección.» | Límite de «usar mi ubicación» de una misma conexión | Escribir la dirección a mano; el límite se libera solo | ## Preguntas frecuentes ### ¿Tengo que pedirle al cliente una clave de Google Maps? No. Las claves son de la plataforma y las configura FOS en el servidor de Connect Manager; sirven para todas las tiendas. ### ¿Cómo se calcula el coste de envío del delivery propio? Por la zona en la que cae la dirección: el envío de partida, el tramo alcanzado según el importe de la comida sin descuentos o gratis desde el importe que pongas. No se calcula por kilómetros. ### ¿Qué pasa si dos zonas de locales distintos se pisan? Reparte el local abierto más cercano a la dirección en línea recta. Si el más cercano está cerrado, reparte el siguiente que esté abierto. ### ¿Puedo traer las zonas de reparto que ya tengo en Ágora? Sí, con «Importar de Ágora» en Tienda pública → Conexión ACMS. Trae el polígono, el pedido mínimo, el coste y el formato de portes de cada área. Si luego las retocas en el panel, una nueva importación las vuelve a dejar como están en Ágora. ### ¿Por qué la dirección llega a Ágora con la calle, la población y el código postal separados? Porque se toman de la respuesta de Google al elegir la sugerencia y cada dato va a su casilla del pedido de Ágora, en lugar de meter la línea entera en la calle. ## Referencias - [Ficha de Google Maps en el catálogo de integraciones](https://connectmanager.es/integraciones/google-maps) - [Delivery propio: conectar la tienda online con Ágora](https://connectmanager.es/docs/delivery-propio-conectar-con-agora) - [Geocoding API (documentación de Google)](https://developers.google.com/maps/documentation/geocoding/overview) - [Places API (documentación de Google)](https://developers.google.com/maps/documentation/places/web-service/overview) - [Maps JavaScript API (documentación de Google)](https://developers.google.com/maps/documentation/javascript/overview) - [Buenas prácticas de seguridad de las claves de Google Maps](https://developers.google.com/maps/api-security-best-practices) --- # Seguimiento en Delivery propio: GA4, Tag Manager y Meta Pixel Portal: Delivery propio · Integraciones URL: https://connectmanager.es/docs/delivery-propio-medicion Actualizado: 2026-10-03 La tienda online del delivery propio de Connect Manager, conectada con **Ágora**, puede enviar sus visitas y sus ventas a la cuenta de **Google Analytics 4** del cliente, a su contenedor de **Google Tag Manager** y a su **píxel de Meta**, con los pasos de la compra (plato visto, añadido a la cesta, inicio del pago y compra con su importe) y solo para quien acepta las cookies. Este manual es para el técnico o la agencia que lo configura: qué identificadores hacen falta, dónde se ponen, qué eventos llegan y cómo comprobarlo. ## Qué hace la integración - **Carga la etiqueta oficial** de Google Analytics 4, de Google Tag Manager o del píxel de Meta a partir de su identificador. No se pega código: se escribe el identificador y la tienda monta el fragmento de cada plataforma. - **Mide las páginas vistas**: la vista de página automática de GA4, el arranque del contenedor de Tag Manager y el `PageView` de Meta. - **Mide el embudo de compra** con los eventos de comercio de GA4: `view_item_list`, `view_item`, `add_to_cart`, `begin_checkout` y `purchase`, traducidos para Meta a `ViewContent`, `AddToCart`, `InitiateCheckout` y `Purchase`. - **La compra lleva la referencia del pedido**, el total, el envío, el código de campaña y los platos, identificados por su formato de venta de Ágora para poder cruzarlo con las ventas del TPV. - **Cuenta cada compra una sola vez** por navegador, aunque se recargue la pantalla de gracias o se vuelva a ella desde el correo. En Meta, la compra lleva un identificador de evento para que se pueda deduplicar. - **Solo se carga con las cookies aceptadas**: el aviso de cookies de la tienda da o quita el permiso, con «Rechazar» y «Aceptar» igual de visibles. ### Qué no hace - No mide la compra de tarjetas regalo ni las páginas de contacto, reservas y textos legales: allí no se carga la medición. - No envía conversiones desde el servidor (API de conversiones de Meta ni Measurement Protocol de GA4): todo sale del navegador del cliente. - No usa el modo de consentimiento de Google: si el visitante no acepta, no se carga nada (tampoco señales anónimas). - No admite HTML ni código propio, ni píxeles de otras plataformas (por ejemplo TikTok). - Con Google Analytics 4 y Tag Manager configurados a la vez, los eventos de comercio van solo a GA4: Tag Manager no los recibe. - No envía datos personales del cliente (nombre, correo, teléfono o dirección). ## Requisitos - La tienda del delivery propio configurada y publicada (ver [Delivery propio: conectar la tienda online con Ágora](https://connectmanager.es/docs/delivery-propio-conectar-con-agora)). - Una cuenta del cliente en Google Analytics 4, Google Tag Manager o Meta (Business Manager con el píxel creado). Al menos una de las tres. - Un usuario de Connect Manager con el permiso `Delivery: Configurar locales` para entrar en **Configuración → Tienda pública**. - Recomendado: la política de privacidad del cliente puesta en **Tienda pública → Legal**, porque el enlace «Más información» del aviso de cookies lleva a ella. - **Quién hace qué**: el cliente o su agencia crean las cuentas y facilitan los identificadores; el distribuidor los pone en el panel y prueba; las etiquetas dentro de Tag Manager las monta quien gestione el contenedor. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | ID de medición de Google Analytics 4 | Cliente o agencia: GA4 → Administrar → Flujos de datos → flujo web | G- seguido de 4 a 20 letras o números, p. ej. G-AB12CD34EF | No (al menos uno de los tres) | | ID del contenedor de Google Tag Manager | Cliente o agencia: Tag Manager → contenedor web | GTM- seguido de 4 a 20 letras o números, p. ej. GTM-AB12CD3 | No | | ID del píxel de Meta | Cliente o agencia: Administrador de eventos de Meta | De 8 a 20 dígitos, p. ej. 123456789012345 | No | | Política de privacidad | Cliente: enlace a su web o texto en Tienda pública → Legal | https://restaurante-demo.es/privacidad | Recomendado | | Dominio de la tienda | Panel: Tienda pública → General | https://hub.connectmanager.es/pedidos/restaurante-demo | Para crear el flujo de datos | ## Configuración paso a paso ### En Google Analytics 4, Tag Manager o Meta - **GA4**: crea (o usa) un flujo de datos web para el dominio donde se abre la tienda y copia su ID de medición. - **Tag Manager**: en el contenedor web, crea las etiquetas que quieras. Si vas a mandar el comercio a GA4 desde Tag Manager, crea activadores de evento personalizado con los nombres `view_item_list`, `view_item`, `add_to_cart`, `begin_checkout` y `purchase`, y que la etiqueta de evento de GA4 lea los datos de comercio de la capa de datos (llegan en el objeto `ecommerce`). Publica el contenedor. - **Meta**: en el Administrador de eventos, copia el identificador del píxel. > [!TIP] Elige un camino para Google Analytics: o pones el ID de GA4 en el panel, o montas GA4 dentro de Tag Manager y dejas vacío el campo de GA4. Con las dos cosas a la vez, Tag Manager no recibe los eventos de comercio y, si además tiene su propia etiqueta de GA4, las páginas vistas se cuentan dos veces. ### En Connect Manager - Entra en `/delivery-propio`, elige el grupo en el selector de la cabecera y ve a **Configuración → Tienda pública → Seguimiento**. - Rellena los campos que correspondan: **Google Analytics 4**, **Google Tag Manager** y **Píxel de Meta**. Si el formato no es válido, no deja guardar. - Pulsa **Guardar**. Se aplica al momento en todas las páginas medidas de la tienda. - En **Tienda pública → Legal**, comprueba que la política de privacidad está puesta (enlace o texto). ## Cómo funciona ### El consentimiento de cookies La primera vez que alguien entra en la tienda ve el aviso de cookies con «Rechazar» y «Aceptar». La decisión se guarda en una cookie propia de la tienda, `cm_cookies`, con el valor `todas` o `necesarias`, durante 180 días. Mientras no haya aceptado, la página no carga ni Google Analytics, ni Tag Manager, ni el píxel de Meta. Al pulsar «Aceptar» la página se recarga y entonces se pintan las etiquetas; al pulsar «Rechazar» no se carga nada. La sesión, la cesta y el enlace de acceso funcionan igual en los dos casos, porque son necesarios para pedir. Los enlaces de campaña de la tienda (`?c=`) también respetan la decisión: sin permiso, el código de la campaña se guarda solo en la sesión y pasa a sus cookies si el cliente acepta después. ```mermaid sequenceDiagram participant C as Cliente participant T as Tienda online participant G as GA4 o Tag Manager participant M as Meta C->>T: Primera visita T-->>C: Aviso de cookies, sin etiquetas C->>T: Aceptar T->>T: Cookie cm_cookies todas y recarga T->>G: Etiqueta y vista de página T->>M: Píxel y PageView C->>T: Abre un plato y lo añade T->>G: view_item y add_to_cart T->>M: ViewContent y AddToCart C->>T: Paga y vuelve a la pantalla de gracias T->>G: purchase con la referencia del pedido T->>M: Purchase con identificador de evento ``` ### Qué eventos se envían | Momento | GA4 o Tag Manager | Meta | | Cada página medida | Vista de página automática de GA4 o arranque del contenedor | PageView | | Al abrir la carta de un local (una vez por visita) | view_item_list con los primeros 30 platos y su categoría | No se envía | | Al abrir la ficha de un plato | view_item | ViewContent | | Al añadir a la cesta | add_to_cart con el precio por unidad con opciones y la cantidad | AddToCart | | Al llegar al paso de pago (una vez) | begin_checkout con el total (envío y descuentos incluidos) y el cupón | InitiateCheckout | | En la pantalla de gracias tras pagar (una vez por navegador) | purchase con transaction_id, total, envío, cupón y platos | Purchase con identificador compra- más la referencia | ### Qué datos viajan - **Platos**: `item_id` es el formato de venta de Ágora (no cambia al reimportar la carta y casa con las ventas del TPV), `item_name`, `price`, `quantity` y, en la carta y la ficha, `item_category`. - **Importes**: `value` en euros (`currency` = `EUR`). En la compra, `value` es el total del pedido, `shipping` el envío (que no va entre los platos) y `coupon` el código de la campaña con la que entró el pedido. - **Referencia**: `transaction_id` es la referencia del pedido (por ejemplo `P-ABC123`), la misma que ve el cliente y que llega a Ágora. - **Meta** recibe lo mismo con sus nombres: `content_ids`, `contents`, `num_items`, `value` y `currency`, más `content_name` cuando hay un solo plato. ### GA4, Tag Manager o los dos Los eventos se reparten en el navegador: si está cargada la etiqueta de GA4, van directos a GA4; si no, se meten en la capa de datos de Tag Manager como `{ event: nombre, ecommerce: datos }`, precedidos de un `{ ecommerce: null }` que limpia el evento anterior. Nunca van a los dos, para que GA4 no cuente doble. Meta recibe los suyos aparte, sea cual sea el camino de Google. ### Dónde se mide La medición se carga en la portada de la tienda, la carta de cada local, el paso de pago, la pantalla de gracias y seguimiento, y «Mi cuenta». No se carga en las tarjetas regalo, el contacto, las reservas ni los textos legales, y la página del banco es de Redsys. La compra solo se mide cuando el cliente vuelve a la pantalla de gracias con las cookies aceptadas: si paga y cierra la pestaña en la página del banco, el pedido entra en la cocina igual, pero la compra no llega a Analytics ni a Meta. ## Comprobar que funciona - Guarda los identificadores y abre la tienda en una ventana privada: debe salir el aviso de cookies y, en la pestaña de red del navegador, no debe cargarse nada de Google ni de Meta. - Pulsa «Aceptar»: la página se recarga. Con DebugView o Tiempo real de GA4, la vista previa de Tag Manager o la extensión Meta Pixel Helper, comprueba la vista de página. - Abre la carta de un local (`view_item_list`), abre un plato (`view_item` / `ViewContent`), añádelo (`add_to_cart` / `AddToCart`) y ve a pagar (`begin_checkout` / `InitiateCheckout`). - Con la pasarela del local en pruebas, completa un pedido y vuelve a la pantalla de gracias: debe llegar `purchase` / `Purchase` con la referencia del pedido como `transaction_id`. - Recarga la pantalla de gracias: no debe llegar una segunda compra. - En otra ventana privada pulsa «Rechazar» y repite: no debe cargarse ninguna etiqueta. ## Errores frecuentes y solución | Síntoma | Causa | Solución | | El campo no deja guardar | Formato no válido | GA4 empieza por G-, Tag Manager por GTM- y el píxel de Meta son solo dígitos (de 8 a 20) | | No llega nada a ninguna herramienta | Cookies no aceptadas, bloqueador de anuncios o identificador equivocado | Prueba en ventana privada sin extensiones, acepta las cookies y revisa el identificador | | Tag Manager no recibe add_to_cart ni purchase | También está puesto el ID de GA4 en el panel: los eventos van directos a GA4 | Deja vacío el campo de GA4 y monta GA4 dentro de Tag Manager | | Las páginas vistas salen dobles en GA4 | ID de GA4 en el panel y otra etiqueta de GA4 dentro de Tag Manager | Quita una de las dos | | Hay menos compras en Analytics que pedidos en el panel | Clientes que rechazan las cookies o que no vuelven del banco a la pantalla de gracias | Es esperado: el panel de pedidos es la fuente de verdad de las ventas | | Las compras aparecen como procedentes del banco | El cliente vuelve de la página de pago de Redsys a la tienda | En GA4, añade el dominio de Redsys a la lista de referencias no deseadas del flujo de datos | | No se ven las compras de tarjetas regalo | Esas páginas no cargan la medición | No está disponible | | Meta da menos conversiones de las esperadas | Solo se mide desde el navegador (sin API de conversiones) | No está disponible; revisa también los bloqueadores | ## Preguntas frecuentes ### ¿Cómo pongo Google Analytics 4 en la tienda online del delivery propio de Ágora? Copia el ID de medición de tu flujo de datos web (empieza por `G-`) y pégalo en Configuración → Tienda pública → Seguimiento, campo «Google Analytics 4». Al guardar, la tienda carga la etiqueta para quien acepta las cookies y envía los eventos de comercio. ### ¿Puedo pegar mi propio código de seguimiento o el píxel de TikTok? No. Por seguridad solo se admiten los identificadores de Google Analytics 4, Google Tag Manager y Meta; la tienda monta el código oficial de cada uno. Si necesitas otras etiquetas, ponlas dentro de tu contenedor de Tag Manager. ### ¿Se mide a los clientes que rechazan las cookies? No. Sin aceptar no se carga ninguna etiqueta de Google ni de Meta, y la tienda no usa el modo de consentimiento de Google. ### ¿Qué identificador de producto llega a Analytics y a Meta? El formato de venta de Ágora de cada plato. Así puedes cruzar los informes con las ventas del TPV y no cambia aunque se vuelva a importar la carta. ### ¿Por qué no coinciden las compras de Analytics con los pedidos? Porque la compra se mide en el navegador, en la pantalla de gracias y con cookies aceptadas. Quien rechaza las cookies o no vuelve del banco no se cuenta, aunque su pedido entre en Ágora. ### ¿Se envían a Google o a Meta los datos del cliente? No. Viajan los platos, los importes, el envío, el código de campaña y la referencia del pedido; no el nombre, el correo, el teléfono ni la dirección. ## Referencias - [Ficha de Google Analytics 4 en el catálogo](https://connectmanager.es/integraciones/google-analytics), [Google Tag Manager](https://connectmanager.es/integraciones/google-tag-manager) y [Meta Pixel](https://connectmanager.es/integraciones/meta-pixel) - [Delivery propio: conectar la tienda online con Ágora](https://connectmanager.es/docs/delivery-propio-conectar-con-agora) - [Eventos de comercio de GA4 (documentación de Google)](https://developers.google.com/analytics/devguides/collection/ga4/ecommerce) - [Ayuda de Google Tag Manager](https://support.google.com/tagmanager) - [Meta Pixel (documentación de Meta)](https://developers.facebook.com/docs/meta-pixel/) --- # IA en Delivery propio: descripciones con Gemini y vídeos con Veo Portal: Delivery propio · Integraciones URL: https://connectmanager.es/docs/delivery-propio-ia Actualizado: 2026-10-03 **Google Gemini** y **Google Veo** son la inteligencia artificial del delivery propio de Connect Manager, la tienda online conectada con **Ágora**: Gemini escribe la descripción de un plato a partir de su foto y atiende el asistente «¿Qué te apetece?» de la carta, y Veo genera un vídeo corto del plato para enseñarlo en lugar de la foto. Este manual es para el técnico que lo pone en marcha y lo revisa: qué hace cada botón, qué hace falta, cómo se cambia el prompt de los vídeos y dónde se ve el uso y el coste en «Uso de IA». ## Qué hace la integración - **Describe un plato con IA**: desde la ficha del plato, Gemini mira la foto que ve el cliente (la propia de la tienda o la de Ágora) y escribe una frase corta, como las de una carta. Para que salga con el mismo tono y largo, se le enseñan hasta tres descripciones de la misma carta. El texto se guarda como **descripción propia** de la tienda. - **Genera un vídeo del plato**: Veo crea, a partir de la foto, un clip de **8 segundos a 720p**, en horizontal (16:9) si la foto es apaisada o en vertical (9:16) si es vertical. Se hace en segundo plano y avisa en la campana del panel cuando está. - En la tienda, al abrir el plato, **el vídeo sale en lugar de la foto**: arranca solo, en bucle, sin sonido y con la foto de cartel mientras carga. - Cada tienda puede **cambiar el prompt** con el que se generan sus vídeos, con huecos para el nombre del plato, su descripción y el formato. - **Asistente «¿Qué te apetece?»** en la carta pública: el cliente escribe qué le apetece, para cuántos o qué no puede comer, y el asistente le propone platos de esa carta con su cantidad y un motivo corto; cada propuesta lleva su botón para añadirla a la cesta. - El asistente **no propone lo que está agotado** en el local y tiene instrucciones de no proponer platos con los alérgenos que el cliente evita según la carta, y de avisar cuando un plato no tiene alérgenos informados. - **Registra cada petición** en **Configuración → Uso de IA**: quién la hizo, qué función, con qué modelo, tokens o segundos de vídeo, coste estimado, estado y duración. ### Qué no hace - No toca Ágora: la descripción, la foto y el vídeo propios son solo de la tienda online, y una nueva importación de la carta no los pisa. - No trabaja sin foto: si el plato no tiene foto, los botones de describir y de generar vídeo no salen. - No genera vídeos de más de 8 segundos (es el tope del modelo), ni varios a la vez para el mismo plato. - No reintenta solo un vídeo que falla, porque cada intento cuesta: hay que volver a pulsar el botón. - No describe toda la carta de golpe: se hace plato a plato. - El asistente no mete nada en la cesta por su cuenta ni inventa platos o precios: propone, la carta valida y el precio que se cobra lo recalcula la tienda. - El asistente no se puede apagar en una tienda concreta: sale en todas en cuanto la plataforma tiene la clave de Gemini. - El coste que enseña el panel es una estimación con tarifas públicas; la factura real la emite Google. ## Requisitos - El delivery propio conectado con Ágora y la carta importada (ver [Delivery propio: conectar la tienda online con Ágora](https://connectmanager.es/docs/delivery-propio-conectar-con-agora)). - Fotos en los platos: las de la ficha de producto de Ágora que trae la carta digital o una subida en la ficha del plato del panel. - La **clave de la API de Gemini** y los modelos configurados en el servidor de Connect Manager (lo hace FOS). El texto usa un modelo Gemini Flash y el vídeo un modelo Veo de la misma API. - Un usuario con el permiso `Delivery: Configurar locales`, que es el que abre Operación → Cartas, Tienda pública y Uso de IA. - **Quién hace qué**: FOS mantiene la clave y los modelos; el distribuidor o el propio cliente generan y revisan descripciones y vídeos; el cliente aporta las fotos y, si quiere, su prompt de vídeo. ## Datos que necesitamos | Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio | | Fotos de los platos | Cliente: en la ficha de producto de Ágora o subida en la ficha del plato (Operación → Cartas) | Imagen apaisada, hasta 4 MB si se sube en el panel | Sí, para describir o hacer vídeos | | Prompt propio para los vídeos | Cliente (opcional) | Texto de hasta 4.000 caracteres con {plato}, {descripcion} y {formato} | No (vacío: el de serie) | | Vídeo propio, si no se quiere generar | Cliente | MP4, WebM o MOV, en vertical, hasta 50 MB | No | | Clave de la API de Gemini | FOS (variable del servidor GEMINI_API_KEY) | No se pide al cliente | Sí | | Modelo de vídeo | FOS (variable DELIVERY_VIDEO_MODEL) | Por defecto veo-3.1-generate-preview | Sí, para los vídeos | | Modelo de texto | FOS (variable DELIVERY_TEXT_MODEL) | Por defecto gemini-2.5-flash | No (tiene valor por defecto) | ## Configuración paso a paso ### En la plataforma (lo hace FOS) - Configura `GEMINI_API_KEY` en el servidor. Sin ella no salen los botones de IA ni el asistente. - Revisa `DELIVERY_VIDEO_MODEL` (un modelo Veo) y `DELIVERY_TEXT_MODEL` (un modelo Gemini Flash que lea imágenes). Se cambian sin desplegar. ### En Ágora - Pon las fotos en la ficha de cada producto (la imagen que enseña la carta digital). - Vuelve a traer la carta en el panel para que lleguen las fotos (Operación → Cartas → «Volver a traer»). ### En Connect Manager: descripciones con IA - Ve a **Operación → Cartas**, elige la carta en el filtro «Carta» y pulsa el plato para abrir su ficha. - En el pie de la ficha, pulsa **Describir con IA** y confirma con **Escribir**. En segundos sale el aviso «Descripción escrita» con el texto. - La frase se guarda sola como **Descripción propia**. Para retocarla, vuelve a abrir la ficha, cámbiala y pulsa **Guardar**. Si vacías el campo, la tienda vuelve a enseñar la descripción de Ágora. > [!NOTE] «Describir con IA» sustituye la descripción propia que hubiera. El filtro «Con foto» de la tabla te dice qué platos se han quedado sin foto y, por tanto, sin botón. ### En Connect Manager: vídeos con Veo - Opcional: en **Configuración → Tienda pública → Vídeo IA** escribe el **Prompt** de la tienda. Puedes usar `{plato}`, `{descripcion}` y `{formato}` («horizontal 16:9» o «vertical 9:16»). Vacío, se usa el de serie, que se enseña de ejemplo en el campo. **Volver al de serie** borra el texto propio; los vídeos ya generados no cambian. - En **Operación → Cartas**, abre el plato y pulsa **Generar vídeo con IA**. El aviso recuerda que son unos 8 segundos, que tarda un par de minutos y que tiene coste por cada vídeo. Confirma con **Generar**. - Mientras se genera, el botón queda desactivado («Ya hay uno en marcha»). Al terminar llega a la campana «Vídeo listo: …» o «No se ha podido generar el vídeo de …» con el motivo. - El vídeo queda en el campo **Vídeo del plato** de la ficha. Para quitarlo o cambiarlo por uno propio, vacía o sube otro fichero y pulsa **Guardar**. ### El asistente de la carta No tiene nada que configurar en la tienda: aparece como un botón flotante con el texto «¿Qué te apetece?» en la carta de cada local en cuanto la plataforma tiene la clave de Gemini. Usa la carta del local y del canal que esté viendo el cliente. ### Revisar el uso - Ve a **Configuración → Uso de IA** con el grupo elegido en la cabecera. - Las funciones de la tienda salen como «Descripción del plato (delivery)», «Vídeo del plato (delivery)» y «Asistente de la carta (delivery)». - Filtra por **Función**, **Estado** o fechas (**Desde** y **Hasta**); la columna «Coste estimado» (en dólares) lleva el total al pie. ## Cómo funciona ### La descripción con Gemini Al pulsar «Describir con IA», Connect Manager lee la foto del plato desde su propio almacén (no por URL), junta el nombre del plato y hasta tres descripciones de la misma carta y se lo manda a Gemini con instrucciones fijas: una sola frase en castellano, de entre 40 y 110 caracteres, que diga qué lleva y cómo está hecho, solo con lo que se ve en la foto o dice el nombre, sin precios, emojis ni exclamaciones. De la respuesta se queda con la primera línea, sin comillas, recortada a 140 caracteres, y la guarda como descripción propia. Va en la misma petición del panel porque tarda segundos. ```mermaid sequenceDiagram participant U as Panel participant C as Connect Manager participant G as Gemini U->>C: Describir con IA C->>C: Foto del plato y hasta 3 descripciones de la carta C->>G: Instrucciones, nombre del plato y foto G-->>C: Una frase C->>C: Primera línea, sin comillas, máximo 140 caracteres C->>C: Guarda la descripción propia y apunta el uso C-->>U: Descripción escrita ``` ### El vídeo con Veo El botón marca el plato como «generando» y encola el trabajo. El trabajo descarga la foto, decide el formato por su orientación y la recorta al centro a 16:9 o 9:16 exactos, porque Veo no recorta: si la proporción no encaja, rellena con bandas negras. Después pide el vídeo a la API de Gemini con el prompt de la tienda (o el de serie) y pregunta cada 10 segundos cómo va, hasta 8 minutos. Cuando está, lo descarga, lo guarda y lo deja asignado al plato. Si falla, el plato queda marcado como fallido con el motivo y se avisa a quien pulsó el botón; no se reintenta solo. Cada vídeo queda apuntado en «Uso de IA» con su coste estimado, que es cero si no se llega a generar. ```mermaid sequenceDiagram participant U as Panel participant Q as Cola participant V as API de Gemini con Veo participant S as Almacén de vídeos U->>Q: Generar vídeo con IA Q->>Q: Descarga la foto y la recorta al formato del vídeo Q->>V: Prompt, foto, 8 segundos y 720p V-->>Q: Operación en curso loop Cada 10 segundos, hasta 8 minutos Q->>V: Consulta la operación end V-->>Q: Vídeo generado Q->>S: Guarda el vídeo del plato Q-->>U: Campana con Vídeo listo ``` ### El asistente «¿Qué te apetece?» Cada pregunta viaja a Gemini con la carta del local entera en formato compacto (nombre, precio, descripción, alérgenos, etiquetas y opciones de cada plato), sin lo que esté agotado en ese local, y con los últimos mensajes de la conversación. Gemini devuelve un mensaje corto y una lista de platos con su cantidad. Antes de enseñarla, Connect Manager comprueba cada plato contra la carta: tiene que existir, la cantidad va de 1 a 10, como mucho 6 líneas, y el precio se pone desde la carta. Al pulsar «Añadir», el plato entra en la cesta por el camino normal de la carta; si tiene opciones obligatorias (el punto de la carne), se abre su ficha para que elija el cliente. ```mermaid sequenceDiagram participant C as Cliente participant A as Asistente participant G as Gemini participant K as Carta y cesta C->>A: Algo sin gluten para dos A->>G: Carta del local sin agotados y conversación G-->>A: Mensaje y platos con cantidad A->>A: Valida cada plato contra la carta A-->>C: Propuesta con botones Añadir C->>K: Añadir K->>K: Relee el precio y mete el plato en la cesta ``` Límites del asistente: 15 preguntas cada 10 minutos por conexión, una pregunta de hasta 300 caracteres y una conversación de hasta 12 mensajes que vive en el navegador del cliente (no se guarda). La carta que se le pasa se renueva cada 15 minutos. ## Comprobar que funciona - En Operación → Cartas, abre un plato con foto: deben salir «Describir con IA» y «Generar vídeo con IA» en el pie de la ficha. - Pulsa «Describir con IA»: la frase debe aparecer en la ficha, en el listado y en la tienda. - Pulsa «Generar vídeo con IA» y espera el aviso de la campana. Abre el plato en la tienda: debe verse el vídeo en lugar de la foto. - En la carta pública, pulsa «¿Qué te apetece?», pide algo concreto («dos menús y una bebida sin alcohol») y añade una propuesta a la cesta. - En Configuración → Uso de IA deben aparecer las tres peticiones con su estado «OK». ## Errores frecuentes y solución | Síntoma | Causa | Solución | | No salen los botones de IA en la ficha del plato | El plato no tiene foto, o la plataforma no tiene la clave de Gemini (o el modelo de vídeo, para ese botón) | Pon una foto (en Ágora o «Foto propia») o avisa a FOS | | «No se ha podido escribir la descripción» con «La IA no ha devuelto ninguna descripción. Prueba otra vez o con otra foto.» | Respuesta vacía de Gemini | Vuelve a intentarlo o cambia la foto | | «El plato no tiene foto de la que partir.» (en el vídeo, «El plato ya no tiene foto de la que partir.») | La foto ya no existe en la tienda ni en Ágora | Sube una foto propia o vuelve a traer la carta | | «Gemini ha descartado el vídeo por su filtro de contenido. Prueba con otra foto.» | El filtro de contenido de Google rechazó el resultado | Cambia la foto o suaviza el prompt de la tienda | | «Gemini está tardando demasiado en generar el vídeo. Vuelve a intentarlo en un rato.» | La operación pasó de 8 minutos | Vuelve a pulsar más tarde | | «Falta la clave de Gemini (GEMINI_API_KEY) o el modelo de vídeo.» | Configuración de la plataforma incompleta | Avisa a FOS | | «No se ha podido pedir el vídeo: …» | La API de Gemini rechazó la petición (cuota, modelo no disponible, clave) | Pasa el mensaje a FOS | | «El vídeo se ha generado pero no se ha podido descargar.» | Fallo al bajar el fichero generado | Vuelve a generarlo | | «Ya hay un vídeo en marcha para este plato» | Se pidió otro vídeo antes de terminar el anterior | Espera al aviso de la campana | | Al vídeo le falta parte del plato por los bordes | La foto se recorta al centro a 16:9 o 9:16 antes de mandarla | Usa una foto con el plato centrado | | El vídeo sale con bandas negras | La foto no se pudo recortar (formato no legible) y se mandó tal cual | Prueba con otra foto en JPG o PNG | | El asistente responde «Vamos a dejar descansar al asistente un rato…» | Límite de 15 preguntas cada 10 minutos desde esa conexión | Esperar; se libera solo | | El asistente dice «Ahora mismo no puedo ayudarte con eso…» | Error al llamar a Gemini | Revisa en Uso de IA si hay peticiones fallidas y avisa a FOS | | El asistente no aparece en la carta | La plataforma no tiene la clave de Gemini | Avisa a FOS | ## Preguntas frecuentes ### ¿Cómo escribo con IA la descripción de un plato en el delivery propio de Ágora? En Operación → Cartas abre el plato y pulsa «Describir con IA» en el pie de la ficha. Gemini escribe una frase a partir de la foto y queda como descripción propia de la tienda; en Ágora no cambia nada. ### ¿Cuánto dura el vídeo del plato y en qué formato sale? Unos 8 segundos a 720p, en horizontal 16:9 si la foto es apaisada o en vertical 9:16 si es vertical. En la tienda se reproduce en bucle y sin sonido. ### ¿Puedo cambiar cómo se generan los vídeos? Sí, con el prompt de Configuración → Tienda pública → Vídeo IA. Los vídeos que ya existen no cambian: hay que volver a generarlos plato a plato. ### ¿Se envían datos de los clientes a la IA? Para describir platos y hacer vídeos solo viajan la foto, el nombre del plato y descripciones de la carta. El asistente recibe la carta y lo que el cliente escribe en el chat. ### ¿Puedo quitar el asistente «¿Qué te apetece?» de una tienda? No desde el panel: aparece en todas las tiendas cuando la plataforma tiene la clave de Gemini. ### ¿Dónde veo cuánto cuesta la IA? En Configuración → Uso de IA, con el coste estimado de cada petición en dólares y el total al pie. Es una estimación con tarifas públicas; la factura real la emite Google. ## Referencias - [Ficha de Google Gemini en el catálogo](https://connectmanager.es/integraciones/google-gemini) y [Google Veo](https://connectmanager.es/integraciones/google-veo) - [Delivery propio: conectar la tienda online con Ágora](https://connectmanager.es/docs/delivery-propio-conectar-con-agora) - [API de Gemini (documentación de Google)](https://ai.google.dev/gemini-api/docs) - [Generación de vídeo con Veo en la API de Gemini](https://ai.google.dev/gemini-api/docs/video)