Integración de Wine Advisor con Ágora: carta de vinos en el TPV

La integración de Wine Advisor con Ágora lleva la carta de vinos de Wine Advisor al TPV: cada noche, o cuando se pide desde el panel, Connect Manager descarga los vinos y los crea o actualiza en Ágora como productos, con su familia por tipo de vino, su precio de botella y, si se sirven por copas, su formato de copa. Los vinos que dejan de estar disponibles en Wine Advisor dejan de poder venderse en Ágora.

Este manual es para el técnico de FOS o del distribuidor que deja la sincronización funcionando en un local. Se configura en el hub de Connect Manager (https://hub.connectmanager.es), no en la app de integraciones.

Qué hace la integración#

• Descarga todos los vinos de Wine Advisor y los crea o actualiza en Ágora como productos, con el nombre «Nombre (tipo, añada)» y el identificador de Wine Advisor como código de barras.
• Crea en Ágora una familia por cada tipo de vino (tinto, blanco…) que aún no exista, dentro de la familia raíz que elijas; los vinos sin tipo van a esa familia raíz.
• Pone el precio de botella en todas las tarifas activas de Ágora. Si Wine Advisor no trae precio, conserva el que ya tenga el producto en Ágora.
• Crea un formato de venta por cada formato de copa que el vino tenga activo en Wine Advisor («Copa de …»), con su precio y su proporción de la botella.
• Marca como no vendibles los vinos que Wine Advisor da como no disponibles, y los vuelve a activar cuando vuelven a estarlo.
• Recuerda qué producto de Ágora es cada vino de Wine Advisor, para que un cambio de nombre o de añada no cree un producto duplicado.
• Se ejecuta cada noche a las 05:00 (hora de Madrid) y, a mano, desde el panel, con un histórico de cada sincronización que nombra los vinos que no entraron y por qué.
• Opcionalmente: vende el vino también como añadido de otro producto, aplica orden y tipo de preparación, calcula el precio de copa como botella entre copas y envía «precio abierto» cuando no hay precio.

Qué no hace#

• No envía a Wine Advisor el stock ni las ventas de Ágora: la información va solo de Wine Advisor a Ágora.
• No borra de Ágora los vinos que desaparecen de Wine Advisor: siguen como estaban hasta que se quiten a mano.
• No crea una copa sin precio: si Wine Advisor no da precio de copa y no está activado el cálculo botella entre copas, la copa nueva no se crea y se avisa en el histórico.
• No gestiona el stock en Ágora ni permite elegir un IVA por vino: todos los vinos van con el impuesto configurado.

Requisitos#

• Cuenta de Wine Advisor con la carta del local y su token de API (una clave de unos 32 caracteres que se obtiene en Wine Advisor). El usuario y la contraseña del panel web de Wine Advisor no se usan.
• Local en el hub con la conexión con Ágora configurada en Datos de Conexión con ágora: ACMS, o la URL y el token de la API del local.
• API de Ágora accesible desde Internet, con puerto abierto o con Zero Connect: el hub lee el catálogo de Ágora y le importa los productos. Si el local usa ACMS, los vinos se crean en el ACMS del grupo.
• En Ágora: el impuesto que llevarán los vinos y, si quieres ordenarlos, la familia raíz; opcionalmente, el orden y el tipo de preparación. Necesitas el Id. de cada uno.
• Permisos en el hub: el alta de la integración se hace en /admin; para sincronizar y ver el histórico desde el panel Integraciones hacen falta los permisos «Entorno: Acceder a Integraciones» e «Integraciones: Acceder a WineAdvisor».

Datos que necesitamos#

Configuración paso a paso#

En Wine Advisor#

1. Consigue el token de API del local en el panel de Wine Advisor (o pídeselo a Wine Advisor).
2. Revisa que los vinos que se sirven por copas tienen configurado y activo su formato de copa, con precio y número de copas por botella. El listado de vinos de Wine Advisor no trae el precio de copa por otra vía.
3. Marca como no disponibles los vinos que no se deben vender.

En Ágora#

1. Crea, si no existe, la familia raíz de los vinos (por ejemplo «Vinos») y apunta su Id.
2. Apunta el Id. del impuesto que llevarán los vinos y, si los vas a usar, los del orden y el tipo de preparación.

En Connect Manager (hub)#

1. En https://hub.connectmanager.es/admin, ve a Locales y abre el local. En Datos de Conexión con ágora comprueba ¿Utiliza arquitectura ACMS? y, según el caso, Local: URL de la API y Local: API Token o ACMS: URL de la API y ACMS: API Token.
2. En la pestaña de integraciones del local (Ecosistema Conectado), pulsa Añadir Integración y en Servicio / Proveedor elige WineAdvisor (Others). Solo se permite una por local.
3. Deja activado Estado Operativo (desactivado, la sincronización nocturna se salta el local) y rellena la sección WineAdvisor:
   • URL de la API de WineAdvisor: normalmente https://api.wineadvisor.mx.
   • Token de API de WineAdvisor: el token; se guarda cifrado.
   • ID de impuesto (IVA) en Ágora.
   • ID de familia raíz en Ágora.
   • ID de orden de preparación e ID de tipo de preparación, opcionales.
   • Precio 0 como «precio abierto»: si un vino nuevo no tiene precio, Ágora lo pedirá al venderlo en vez de cobrar 0.
   • Copa sin precio: calcular botella ÷ copas: calcula el precio de copa que falta dividiendo el de la botella entre las copas por botella, redondeado a céntimos.
   • Permitir venta como añadido: deja vender el vino como añadido de otro producto.
4. Guarda y pulsa Sincronizar vinos en la fila de la integración para lanzar la primera sincronización.

[!TIP] La primera sincronización de una carta grande puede tardar varios minutos. Mira el resultado en el panel Integraciones → WineAdvisor, botón Histórico.

Cómo funciona#

Cada noche a las 05:00, o al pulsar Sincronizar ahora, el hub descarga de Wine Advisor todos los vinos, de 50 en 50; lee de Ágora los productos, las familias y las tarifas; crea las familias de tipo que falten; convierte cada vino en un producto (reutilizando el que ya le corresponde en Ágora) y lo importa en Ágora en lotes de 100. Al terminar guarda qué producto es cada vino y deja en el histórico el resultado.

sequenceDiagram
    participant HUB as Connect Manager hub
    participant WA as Wine Advisor
    participant AG as API Ágora
    HUB->>WA: Lista de vinos por páginas
    WA-->>HUB: Vinos con tipo, añada, precio, copas y disponibilidad
    HUB->>AG: Exporta productos, familias y tarifas
    AG-->>HUB: Catálogo actual del local
    HUB->>AG: Importa las familias de tipo que faltan
    HUB->>AG: Importa los productos en lotes de 100
    AG-->>HUB: Lote aceptado o producto rechazado
    HUB->>HUB: Guarda la relación vino y producto y el histórico

Qué se crea en Ágora#

• Producto: nombre «Nombre (tipo, añada)» de hasta 90 caracteres, familia por tipo, impuesto configurado, código de barras con el Id. de Wine Advisor, vendible si el vino está disponible y precio de botella en cada tarifa activa.
• Formatos de copa: uno por cada formato de copa activo en Wine Advisor, llamado «Copa de …» (o el nombre del formato), con proporción 1 / copas por botella y su precio.
• Identificadores: un vino nuevo recibe un Id. libre por encima de los de productos y formatos que ya existen; un vino conocido mantiene su producto.

Rechazos de Ágora#

Ágora rechaza un lote entero en cuanto un producto no le cuadra. Cuando su mensaje señala el producto culpable, el hub lo aparta y reenvía el resto; si no lo señala, manda el lote de uno en uno. Así un vino problemático no deja fuera a los demás. Si el error no tiene que ver con un producto (sin conexión, token incorrecto), ese lote se da por perdido y se apunta en el histórico.

flowchart TD
    A[Lote de 100 vinos] --> B{Ágora acepta}
    B -- Sí --> C[Todos aceptados]
    B -- No y nombra un producto --> D[Aparta ese producto y reintenta]
    D --> B
    B -- No y no nombra producto --> E{Error de producto}
    E -- Sí --> F[Envía uno a uno]
    E -- No, conexión o token --> G[Lote perdido y anotado]

El histórico#

En Integraciones → WineAdvisor cada local integrado muestra la última sincronización (Completada, Error o En curso), la fecha y los productos. El botón Histórico lista cada pasada con fecha, estado, vinos, productos, familias nuevas, duración, origen (Programada o Manual) y un mensaje que nombra los primeros vinos rechazados con su error y las copas que no se crearon por falta de precio. Si ya hay una sincronización manual en marcha para ese local, otra petición manual se descarta y no aparece en el histórico: espera a que termine.

Comprobar que funciona#

1. Lanza Sincronizar vinos y, en el Histórico, espera a ver la pasada como Completada con el número de vinos y de productos.
2. En Ágora, busca un vino: debe estar en la familia de su tipo, con el precio de Wine Advisor en todas las tarifas.
3. Busca un vino por copas: debe tener su formato «Copa de …» con precio.
4. Marca un vino como no disponible en Wine Advisor, sincroniza y comprueba que en Ágora ya no se puede vender.
5. Cambia un precio en Wine Advisor, sincroniza y comprueba que Ágora lo recoge sin crear un producto nuevo.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Wine Advisor con Ágora?#

En el hub de Connect Manager: se añade la integración WineAdvisor al local con el token de Wine Advisor y el Id. del impuesto de Ágora, y se lanza la primera sincronización.

¿Cada cuánto se actualiza la carta de vinos en Ágora?#

Cada noche a las 05:00 (hora de Madrid) y siempre que se pulse Sincronizar ahora.

¿Por qué un vino por copas no tiene copa en Ágora?#

Porque en Wine Advisor no tiene un formato de copa activo con precio. Configúralo allí o activa el cálculo botella entre copas.

¿Wine Advisor recibe el stock o las ventas de Ágora?#

No. La integración solo lleva la carta de Wine Advisor a Ágora.

Si cambio un precio en Ágora, ¿se mantiene?#

Solo si Wine Advisor no trae precio para ese vino o copa. Si lo trae, la siguiente sincronización pone el de Wine Advisor.

Referencias#

• Ficha de la integración: Wine Advisor en el catálogo de Connect Manager.
• Zero Connect: publicar la API de Ágora sin abrir puertos.