Plataformas de reparto: cómo se pide el rider desde Ágora

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

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.

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.

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

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é#

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

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.

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#

1. 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.
2. En Ágora existe el usuario-repartidor de la flota, con la URL de solicitud y la de cancelación, cada una en su campo.
3. En Catcher y en Shipday está puesta la URL de avisos; en Glovo On-Demand se dan de alta solos al guardar.
4. Crea en Ágora un pedido a domicilio real con dirección completa, nombre y teléfono, y asigna el repartidor: Ágora debe aceptar.
5. 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.
6. Espera al primer cambio de estado y a que salga el repartidor.
7. Cancela el reparto en Ágora antes de la recogida y comprueba que la flota lo anula.

Errores frecuentes y solución#

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
• Integración de reparto con Catcher
• Integración de Shipday con Ágora
• Fichas del catálogo: Glovo On-Demand, Catcher y Shipday
• Guía del Integrador de Ágora, capítulos «Integración con Plataformas de Reparto» e «Integración con Sistemas Externos al crear documentos».