Delivery propio: conectar la tienda online con Ágora

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.

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

• 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). 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#

Configuración paso a paso#

En Ágora (ACMS central)#

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

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

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

4. 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í.

5. Revisa que cada local tenga su carta digital creada y con fotos.

En Ágora (cada local)#

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

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

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

4. Si se cobra envío, crea un producto «Gastos de envío» con su formato de venta.

5. Revisa cómo trata Ágora los pedidos de reparto y para llevar (impresión de comanda, preparación): Connect Manager no lo fuerza.

6. 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#

1. Entra en /delivery-propio y elige el grupo en el selector de la cabecera.

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

3. 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#

1. Ve a Configuración → Locales y pulsa Traer locales del grupo. Llegan apagados y sin tocar nada de lo que ya estuviera configurado.

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

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

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

5. En Pasarela de pago, los datos de Redsys del local (ver Redsys).

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

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

En Connect Manager: carta y publicación#

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

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

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

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

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.

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

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#

1. En Conexión ACMS, «Probar ACMS» dice «Todo listo».

2. En Configuración → Locales, la columna «Ágora» del local dice «Conectado» tras «Probar inyección», y «En el mapa» está marcada.

3. En Operación → Cartas se ve la carta con sus precios y fotos.

4. En Tienda pública → General, el local sale como «Listo».

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

6. 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ó.

7. Busca ese pedido en el TPV del local y revisa local, centro de venta, líneas, porte, cliente, notas e importe.

8. Comprueba que llega el correo de pedido confirmado y marca el pedido como «Listo» o «En camino» para ver el segundo correo.

9. Prueba también una recogida y, si se ofrece, un pago a la entrega.

10. Cuando todo cuadre, cambia la pasarela a Producción y abre la tienda.

Errores frecuentes y solución#

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

• Redsys: pasarela de pago de la tienda y de Fidelización

• Correo electrónico: proveedores de envío

• Medición del delivery propio: GA4, Tag Manager y Meta Pixel

• Google Gemini y Veo en el delivery propio

• Fidelización: conectar el club con Ágora

• Zero Connect: conectar Ágora sin abrir puertos

• Catálogo de integraciones de Connect Manager