Requisitos de integración 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 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 lo implementa y opera 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 de varios establecimientos; los nuevos conectores se delimitan por cliente en cuanto una cadena firma el acuerdo.

Cómo se articula 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 una programación (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 — establecimientos, menús, pedidos y pagos. En concreto, 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 pedido — Pay-First y Pay-Later de dine-in con múltiples rounds, en los que 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 la delimitación del alcance; lo que importa para la viabilidad es que las operaciones anteriores estén expuestas de algún modo.

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 un establecimiento concreto; 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 — establecimiento 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 establecimiento debe ser accesible desde la nube de Fooodo a través de internet, mediante HTTPS, en una URL estable por establecimiento. La configuración de Fooodo almacena un endpoint de API y un identificador de establecimiento 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 exponerse a Fooodo de forma segura — a través de 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 en la nube, con credenciales e identificadores por establecimiento.
• La calidad de la conexión importa, no solo su existencia. La creación de pedidos y la marca de pagado están 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 el establecimiento 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 ese establecimiento, por muy buena que sea la integración.

El margen de rendimiento

El despliegue de referencia ejecuta estas cadencias por establecimiento, las veinticuatro horas del día durante el servicio:

Vuestro API debe sostener este sondeo para todos los establecimientos conectados 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 programa 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 (unos cinco intentos en ~2,5 minutos) en lugar de devolver un error. Los rechazos de marca de pagado se reintentan con una programación más lenta (~17 minutos) porque un pedido pagado está reconciliándose, no bloqueando el servicio.
• Un POS inaccesible pone el establecimiento 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 de múltiples establecimientos

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

Seguridad

• Todo el tráfico del conector circula sobre HTTPS/TLS, con credenciales por establecimiento. 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 las brechas respecto a las operaciones obligatorias; exponer el API por establecimiento (véase Conectividad); emitir identificadores y credenciales por establecimiento; 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 del menú, creación de pedidos, adición de artículos a un pedido ya abierto, marca de pagado, estado del establecimiento?
2. ¿Puede ese API hacerse accesible desde internet mediante HTTPS para cada establecimiento — cloud del proveedor, S2S, VPN o proxy seguro?
3. ¿Tiene cada establecimiento 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 establecimiento y completar las escrituras de pedidos en segundos?
6. ¿Existe un entorno de prueba contra el que pueda ejecutarse la preproducción de Fooodo?
7. ¿Los pedidos creados a través del API se comportan 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 restaurador 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 establecimiento y un contacto técnico de vuestra parte.
3. Construcción y prueba — el desarrollo comienza en modo simulado, luego pasa a vuestro entorno de prueba contra la preproducción de Fooodo.
4. Piloto y despliegue — primero un establecimiento en producción, luego la cadena.

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.