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.