Conector de R-Keeper

R-Keeper es la implementación de referencia en producción del contrato de conector POS de Fooodo — el único conector que funciona en producción hoy en día, y la forma sobre la que aterrizan todos los conectores adicionales. El contrato en sí es agnóstico al POS; los nuevos conectores se delimitan por cliente y se presupuestan bajo demanda. Esta página documenta cómo funciona realmente el ciclo completo de R-Keeper: qué datos cruzan el límite, en qué dirección, y qué cabe esperar cuando algo sale mal. Los nombres de métodos específicos de POS que aparecen a continuación son los de R-Keeper; los equivalentes en otros conectores se corresponden con las mismas operaciones del contrato de conector.

Qué solicita Fooodo a R-Keeper

Estas son llamadas de solo lectura — Fooodo nunca modifica el menú, los precios, los modificadores ni los datos de referencia de R-Keeper.

Qué escribe Fooodo en R-Keeper

La creación de pedidos y el marcado como pagado son las dos escrituras que se encuentran en la ruta crítica; ambas se ponen en cola, se reintentan con retroceso exponencial y se registran en detalle. Las otras dos son complementarias.

Configuración por restaurante

Las credenciales de R-Keeper residen en la configuración del restaurante. Cada restaurante en Fooodo incluye:

• URL del endpoint de API
• ID del restaurante dentro de R-Keeper
• Endpoint opcional de precios de fidelización
• Código opcional del programa de tarjeta de fidelización
• Código opcional de artículo de menú para el enrutamiento de propinas

Distintos restaurantes de la misma empresa en Fooodo pueden apuntar a instancias de R-Keeper diferentes. Así es como operan hoy en día las cadenas con múltiples establecimientos.

Cadencias de sincronización de R-Keeper

La integración realiza consultas y envíos según varios calendarios distintos. A los operadores y a los ingenieros de soporte de partners les importan estas cadencias porque establecen las expectativas sobre la rapidez con la que un cambio en el back-office aparece en la aplicación de cara al cliente — y la rapidez con la que un pedido del cliente aparece en el terminal.

Las escrituras de Fooodo a R-Keeper no están programadas — se envían en cuanto ocurre el evento (pedido creado, pedido pagado, mensaje enviado) y se reintentan con retroceso si R-Keeper las rechaza. Los presupuestos de reintento están documentados en Gestión de fallos más abajo.

Precios de fidelización por mesa

Las mesas pueden acogerse a los precios de fidelización de dos maneras, y un restaurante puede utilizar ambas modalidades a la vez:

• Aplicación de tarjeta a posteriori. Cuando la mesa está configurada con un código de tarjeta de fidelización a nivel de restaurante, Fooodo aplica la tarjeta después de exportar el pedido — R-Keeper recalcula las líneas de artículos con la lógica de descuento de la tarjeta y Fooodo refleja los totales ajustados al cliente. El pedido se exporta una vez y luego se actualiza.
• Precios alternativos enrutados por URL. Cuando la mesa está configurada con una URL de conector de precios de fidelización, Fooodo solicita a R-Keeper el menú con precios de fidelización antes de que el cliente vea los precios. El carrito, los precios de los modificadores, los totales — todo lo que ve el cliente es ya el precio de fidelización. Esta es la ruta de menor latencia y la que desplegamos en las nuevas cadenas.

Independientemente de la modalidad que utilice una mesa, los descuentos por código de cupón se aplican correctamente por encima: un cliente con tarjeta de fidelización puede seguir canjeando un cupón, y el descuento del cupón llega a R-Keeper de forma independiente a la ruta de fidelización. Esto no siempre fue así — las versiones anteriores condicionaban los cupones a la ruta a posteriori y los omitían en las mesas enrutadas por URL — por lo que los partners que migren desde un despliegue más antiguo deben verificar que su lado de R-Keeper contabiliza ambos efectos.

Los precios de fidelización provienen de R-Keeper. Fooodo no mantiene una tabla de descuentos paralela.

Atribución de personal y pedidos

Fooodo registra qué camarero está asociado a cada pedido para que los informes de administración puedan desglosar el servicio y las propinas por empleado. El flujo tiene dos partes:

• La sincronización del directorio de personal se ejecuta cada noche a las 08:45 y actualiza la lista de camareros desde el sistema de personal de la cadena — nombres, cargos y los ID externos de personal que se corresponden con R-Keeper. Los camareros no se crean manualmente en Fooodo; la lista de administración es de solo lectura.
• La atribución de pedidos ocurre cuando se obtiene o actualiza un pedido desde R-Keeper. La respuesta de estado de pedido de R-Keeper incluye el ID del camarero asignado; Fooodo lo coteja con el directorio de personal sincronizado y escribe la atribución en el pedido. Los pedidos hijo de una división de cuenta heredan el camarero del pedido padre.

Actualmente esta atribución solo es visible en la administración. La página de pago muestra el camarero en el lado del operador; todavía no existe una ficha de camarero visible para el cliente en la confirmación del pedido. Esa funcionalidad está en la hoja de ruta.

Gestión de fallos

La integración está diseñada para tolerar que R-Keeper no esté disponible brevemente. Tres modos de fallo que se observan en la práctica:

Pedidos bloqueados

R-Keeper devuelve códigos de error específicos (2219 o 13) cuando un camarero tiene el pedido abierto en el terminal del back-office. La respuesta de Fooodo:

• Marcar el pedido como Locked
• Reintentar la exportación con un calendario de retroceso exponencial (5 s → 10 s → 20 s → 40 s → 80 s — cinco intentos, ~155 segundos en total)
• Si todos los reintentos fallan, escalar a Error

En condiciones normales, los bloqueos duran segundos. Un bloqueo persistente suele significar que un camarero se alejó con el pedido abierto en un terminal, y la solución es cerrarlo directamente en R-Keeper.

Reintentos de marcado como pagado

Cuando R-Keeper rechaza la llamada PostPayOrder (la mayoría de las veces porque el pedido está bloqueado en un terminal), Fooodo reintenta con un calendario más lento: 60 s → 120 s → 180 s → 240 s → 300 s — cinco intentos a lo largo de ~17 minutos. La cadencia más lenta es deliberada: un pedido pagado está en proceso de conciliación, no bloqueando el servicio, por lo que le damos tiempo a R-Keeper para que se libere.

Si se agotan los cinco reintentos, el pedido termina en Error. El pago en Fooodo queda registrado; R-Keeper necesita una conciliación manual rápida por parte del camarero.

Restaurante inaccesible

Si R-Keeper está caído o el restaurante se ha desconectado, Fooodo pone el restaurante en modo de solo lectura automáticamente (la comprobación de disponibilidad cada minuto lo detecta):

• El menú de cara al cliente sigue cargándose desde la caché — los clientes no ven una página rota
• Los nuevos pedidos se bloquean en el proceso de pago con un mensaje claro
• Los pedidos existentes ponen en cola las actualizaciones en lugar de descartarlas

Una vez que R-Keeper vuelve, las operaciones en cola se procesan y el restaurante vuelve a la normalidad — sin necesidad de intervención del operador.

Registro de eventos

La integración escribe registros estructurados en cuatro niveles: el rastro completo de solicitud/respuesta, un flujo solo de fallos, un flujo por pedido y un flujo de transiciones de estado. Para los casos de soporte a partners, el registro de solicitudes es el primer lugar donde buscar — la causa más habitual de «el pedido no llegó a cocina» es una interrupción momentánea de R-Keeper que el presupuesto de reintentos no cubrió, y el flujo de fallos lo muestra de inmediato.

Modo simulado para desarrollo

Los entornos de desarrollo pueden ejecutarse con el tráfico de R-Keeper simulado de extremo a extremo — útil para los integradores de partners que quieren probar con la aplicación de menú de Fooodo sin una instancia de R-Keeper en producción. El entorno de preproducción replica el de producción conectándose al entorno de pruebas de R-Keeper; el entorno de producción nunca funciona en modo simulado.

Qué ve la cocina

El contrato establece que: un pedido creado a través de Fooodo llega a R-Keeper de forma indistinguible de un pedido creado en un terminal. El mismo enrutamiento de impresora, el mismo comportamiento en el KDS, los mismos informes. El personal de cocina no necesita saber que Fooodo existe, y los camareros siguen usando R-Keeper exactamente igual que antes.

Esto es intencionado. La integración es invisible por diseño; el sistema operativo extiende R-Keeper, no lo reemplaza.