Requisitos de integración con POS

Fooodo es una capa de pedidos y pagos orientada al cliente que opera sobre un POS existente. Los clientes realizan pedidos y pagan desde la mesa mediante QR; los pedidos se escriben en el POS a través de un conector del lado del servidor y llegan de forma idéntica a los pedidos introducidos en un terminal. El POS no se sustituye: sigue siendo el sistema de registro del menú y la fuente de verdad para las operaciones de cocina y los informes.

Este documento especifica qué requiere una integración de Fooodo de un POS — las operaciones que debe exponer el API del POS, las expectativas de datos a nivel de entidad, los requisitos de conectividad y rendimiento, y la semántica de fallos — seguido de una lista de verificación de evaluación y el camino hacia la puesta en producción. El lector previsto es el equipo de ingeniería de un proveedor de POS que evalúa la viabilidad y el esfuerzo necesario.

Dirección de la integración: Fooodo llama al API del POS. El conector es implementado y operado por Fooodo; vuestra parte proporciona, documenta y da soporte a una superficie de API accesible desde la nube de Fooodo. No se instala ni aloja ningún software de Fooodo en el lado del POS. Un conector de referencia que implementa este contrato está en producción en una cadena multisede; los nuevos conectores se delimitan por cliente en cuanto una cadena firma el acuerdo.

Cómo se estructura la integración

• Fooodo es la capa de pedidos y pagos orientada al cliente; el POS sigue gestionando la cocina — el mismo enrutamiento de impresoras, el mismo KDS, los mismos informes.
• El contrato es: un pedido creado a través de Fooodo llega al POS de forma indistinguible de un pedido introducido en un terminal. El personal de cocina no necesita saber que Fooodo existe.
• Fooodo es el lado que realiza las llamadas. Las lecturas se sondean según un calendario (menú, estado del pedido); las escrituras se envían en el momento en que ocurre un evento (pedido creado, pedido pagado). Fooodo no consume webhooks ni eventos push del POS — no es necesario que los construyáis.
• Vuestra parte proporciona, documenta y da soporte al API — Fooodo construye y gestiona todo lo demás.
• Los datos de referencia son de solo lectura a través del límite: Fooodo nunca modifica el menú, los precios, los modificadores ni otros datos maestros del POS.

Qué debe exponer vuestro POS

El contrato del conector abarca cuatro dominios — ubicaciones, menús, pedidos y pagos. Concretamente, como operaciones — denominadas aquí de forma genérica; vuestro API tendrá sus propios nombres para ellas:

Esta es también la superficie de escritura completa — no existe escritura de cancelación, anulación ni devolución a través de este límite. Las anulaciones se realizan en el terminal POS como hasta ahora (Fooodo las recoge mediante la actualización del pedido en curso), y la gestión de devoluciones queda completamente fuera del conector — nunca toca vuestro API.

Fooodo ejecuta dos flujos de pedidos — Pay-First y Pay-Later dine-in multironda, donde los rounds se añaden a un pedido POS abierto y se pagan al final (véase fooodo.com/docs/order-flows). Las operaciones anteriores cubren ambos; la capacidad de añadir a un pedido abierto es en la que más se apoya Pay-Later.

El contrato se define como operaciones, no como un formato de cable — el conector se construye por cliente contra la interfaz que ya tenéis. El transporte y el formato de vuestro API se revisan durante el proceso de delimitación del alcance; lo que importa para la viabilidad es que las operaciones anteriores estén expuestas de alguna manera.

Si vuestro POS no puede exponer directamente una de las operaciones obligatorias, eso no es automáticamente un punto muerto — es lo primero que se trabaja en una llamada de delimitación del alcance.

Cómo son los datos

Expectativas a nivel de entidad, para que vuestro equipo pueda mapearlas contra vuestro propio modelo de datos. (Los esquemas a nivel de campo se encuentran en el repositorio de integración, que los socios reciben durante el proceso de incorporación.)

• Menú — categorías que contienen productos; los productos llevan precios, indicadores fiscales, variantes (p. ej., tamaños) y grupos de modificadores (añadir / eliminar / sustituir ingredientes, cada uno con su propio precio). El POS sigue siendo la fuente de verdad: Fooodo lee esta estructura, nunca la escribe.
• Pedido — una referencia a una mesa concreta en una ubicación concreta; líneas de artículos con la variante elegida, los modificadores y las cantidades; totales. Los pedidos pueden ampliarse mientras están abiertos (el flujo Pay-Later añade rounds a un pedido POS abierto), y los efectos de descuentos o fidelización se reflejan en el pedido que recibe el POS.
• Pago — una marca de «pagado» aplicada a un pedido existente. Las propinas pueden enrutarse a una línea designada en el POS. Los datos de tarjeta o monedero nunca aparecen en ningún punto de este flujo.
• Estado — ubicación en línea/fuera de línea; disponibilidad por artículo (indicadores de «agotado»); estado por pedido, incluido «bloqueado — abierto en un terminal». Los pedidos extraídos del POS pueden llevar el identificador del camarero asignado, que Fooodo utiliza para la atribución al personal en los informes.

Requisitos de conectividad

Esta es la parte en la que giran la mayoría de las evaluaciones.

• El API del POS de cada ubicación debe ser accesible desde la nube de Fooodo a través de internet, mediante HTTPS, en una URL estable por ubicación. La configuración de Fooodo almacena un endpoint de API y un identificador de ubicación para cada restaurante — ese endpoint debe responder cuando Fooodo llame.
• POS en local: el establecimiento necesita una conexión de banda ancha fiable, y el API del POS debe estar expuesto a Fooodo de forma segura — mediante la pasarela cloud de vuestro proveedor, un túnel VPN o un proxy inverso reforzado en el establecimiento. El mecanismo concreto se acuerda durante la delimitación del alcance; «el POS solo es accesible desde la red local» es la brecha más habitual.
• POS en la nube: una conexión servidor a servidor (S2S) entre la nube de Fooodo y vuestro API cloud, con credenciales e identificadores por ubicación.
• La calidad de la conexión importa, no solo su existencia. La creación de pedidos y el marcado como pagado se encuentran en la ruta crítica del proceso de pago del cliente, y la comprobación de en línea/fuera de línea se ejecuta cada minuto para que Fooodo pueda poner la ubicación en modo de solo lectura en el momento en que el POS deje de ser accesible. Un enlace que cae durante unos minutos se gestiona con elegancia; un enlace que fluctúa todo el día degrada la experiencia del cliente en esa ubicación, independientemente de lo buena que sea la integración.

El rango de rendimiento

El despliegue de referencia ejecuta estas cadencias por ubicación, ininterrumpidamente durante el servicio:

Vuestro API debe sostener este sondeo para cada ubicación conectada de forma simultánea, y las dos escrituras en la ruta crítica — crear pedido, marcar como pagado — deben completarse en segundos. Las escrituras que fallan se reintentan con un calendario de retroceso exponencial, por lo que un rechazo momentáneo es recuperable; un endpoint crónicamente lento no lo es.

Semántica de fallos en la que se apoya Fooodo

La integración está construida para tolerar que un POS no esté disponible brevemente, y se apoya en que el POS devuelva errores distinguibles:

• «Pedido bloqueado / abierto en un terminal» debe poder diferenciarse de un fallo grave. El conector de referencia reconoce códigos de error de bloqueo específicos y responde reintentando con un retroceso corto (aproximadamente cinco intentos en ~2,5 minutos) en lugar de devolver un error. Los rechazos de marcado como pagado se reintentan con un calendario más lento (~15 minutos) porque un pedido pagado está en proceso de conciliación, no bloqueando el servicio.
• Un POS inaccesible pone la ubicación en modo de solo lectura automáticamente. El menú en caché sigue cargándose para los clientes, los nuevos pedidos se bloquean en el proceso de pago con un mensaje claro, y las actualizaciones en cola se procesan cuando el POS vuelve — sin intervención del operador.
• Las escrituras reintentadas deben ser seguras. Fooodo reintenta los envíos de pedidos fallidos; durante la delimitación del alcance verificamos juntos que un reintento tras un tiempo de espera agotado no pueda crear un pedido duplicado en vuestro lado.

Cadenas multisede

Fooodo está construido para cadenas. Cada restaurante de una empresa tiene su propio endpoint POS, identificador de ubicación y credenciales — distintas ubicaciones pueden apuntar a distintas instancias del POS — y, a medida que se construyen más conectores, a distintos sistemas POS. Evaluad para la ubicación con peor conectividad de la cadena, no para la mejor.

Seguridad

• Todo el tráfico del conector circula sobre HTTPS/TLS, con credenciales por ubicación. Los mecanismos de credenciales (clave de API, token, OAuth, mTLS) se acuerdan durante la delimitación del alcance.
• Los datos de tarjeta nunca cruzan el límite del POS. Los pagos se procesan a través del servicio de pagos independiente de Fooodo (Mollie — tarjeta, Apple Pay, Google Pay); vuestro POS recibe un pedido y posteriormente una marca de «pagado», nunca datos del instrumento de pago. La integración no añade ningún flujo de datos de tarjeta a vuestro POS.
• La postura de seguridad más amplia de Fooodo — cifrado, subencargados del tratamiento, GDPR — está documentada en fooodo.com/security.

Entornos y pruebas

• Se espera una instancia de prueba de vuestro POS. El entorno de preproducción de Fooodo se ejecuta contra vuestro entorno de prueba; el tráfico de producción nunca lo toca.
• El modo simulado permite que el desarrollo inicial se ejecute contra la aplicación de menú de Fooodo con el tráfico del POS simulado de extremo a extremo — útil antes de que haya ninguna conectividad establecida.
• Los socios reciben el repositorio de integración — el contrato completo del conector, con fijación de versiones — durante el proceso de incorporación.

Lista de verificación de evaluación

Para vuestra estimación de esfuerzo, el trabajo en vuestro lado se concentra típicamente en cuatro áreas: cerrar cualquier brecha respecto a las operaciones obligatorias; exponer el API por ubicación (véase Conectividad); emitir identificadores y credenciales por ubicación; y poner en marcha un entorno de prueba.

Si podéis responder afirmativamente a estas preguntas, la integración es muy probablemente viable:

1. ¿Expone vuestro POS un API que cubra las operaciones obligatorias anteriores — lectura de menú, creación de pedido, adición de artículos a un pedido ya abierto, marcado como pagado, estado de la ubicación?
2. ¿Puede ese API hacerse accesible desde internet mediante HTTPS para cada ubicación — cloud del proveedor, S2S, VPN o proxy seguro?
3. ¿Tiene cada ubicación un identificador estable y credenciales?
4. ¿Devuelve el API errores distinguibles para «pedido bloqueado en un terminal» frente a fallos graves?
5. ¿Puede sostener el sondeo por minuto por ubicación y completar las escrituras de pedidos en segundos?
6. ¿Existe un entorno de prueba contra el que pueda ejecutarse el entorno de preproducción de Fooodo?
7. ¿Se comportan los pedidos creados mediante el API exactamente igual que los pedidos de terminal en la cocina (impresión, KDS, informes)?
8. ¿Puede hacerse seguro un reintento de creación de pedido tras un tiempo de espera agotado frente a la creación duplicada — mediante una clave de idempotencia o una forma de comprobar si el pedido ya existe?

Un «no» o «no estoy seguro» en cualquiera de estas preguntas es exactamente para lo que sirve la conversación de delimitación del alcance — varias tienen más de una respuesta viable.

De la evaluación a un conector en producción

1. Evaluación — vuestro equipo revisa esta guía, completa la lista de verificación y comparamos notas. Normalmente se activa por un cliente restaurante compartido.
2. Delimitación del alcance — una sesión de trabajo que mapea vuestro API contra el contrato del conector; las brechas reciben opciones. Fooodo delimita el alcance y presupuesta la construcción de su conector por cliente, cuando una cadena se compromete; el trabajo necesario en vuestro lado se dimensiona en la misma conversación, junto con el acuerdo comercial. Es útil tener preparados: vuestra documentación de API, un plan de entorno de prueba, los identificadores por ubicación y un contacto técnico de vuestro lado.
3. Construcción y prueba — el desarrollo comienza en modo simulado, luego pasa a vuestro entorno de prueba contra el entorno de preproducción de Fooodo.
4. Piloto y despliegue — primero una ubicación en producción, luego la cadena completa.

Para comenzar: enviad vuestras respuestas a la lista de verificación y una estimación aproximada del esfuerzo en vuestro lado a partners@fooodo.com, o utilizad el formulario para desarrolladores en fooodo.com/developers. La vista a nivel de construcción — el repositorio de integración con el contrato completo del conector — se entrega durante el proceso de incorporación.