Integración de Shipday con Ágora: repartos desde el TPV

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#

Configuración paso a paso#

En Shipday#

1. El cliente copia la API Key de su cuenta (My Account → API Key).
2. 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)#

1. Entra en el panel /admin del hub y ve a Seguridad → Locales. Abre el local.
2. Baja hasta la sección Ecosistema Conectado y pulsa Añadir Integración.
3. Servicio / Proveedor: elige Shipday (Delivery).
4. Estado Operativo: déjalo activado. Si está apagado, Connect Manager rechaza las peticiones de ese local.
5. 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.
6. Revisa los tres datos y pulsa Crear. Después no se pueden editar desde esta pantalla.
7. 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)#

1. 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.
2. 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.
3. Explica al personal que, para mandar un pedido a Shipday, basta con asignar ese repartidor al pedido a domicilio.

De vuelta en Shipday#

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

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:

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

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#

1. 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.
2. 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.
3. 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.
4. En el panel de Shipday debe aparecer el pedido con el mismo número que en Ágora.
5. 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.
6. 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.
7. Cancela el reparto en Ágora: el pedido desaparece de Shipday y la solicitud pasa a «Cancelled».

Errores frecuentes y solución#

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
• Plataformas de reparto: cómo se pide el rider desde Ágora
• Integración de reparto con Catcher
• Integración de Glovo On-Demand (Glovo Local) con Ágora
• Documentación oficial de la API de Shipday: docs.shipday.com
• Guía del Integrador de Ágora, capítulo «Integración con Plataformas de Reparto».