Integración de Fourvenues con Ágora: entradas canjeables

La integración de Fourvenues con Ágora lleva al TPV las entradas que el local vende en Fourvenues: cada 15 minutos Connect Manager descarga los eventos próximos y sus entradas, y las carga en Ágora como entradas canjeables (cupones) hasta que termina el evento. Así, en barra o en caja se puede canjear lo que incluye cada entrada leyendo su código, y las entradas anuladas dejan de valer.

Este manual es para el técnico de FOS o del distribuidor que configura la integración en un local que vende con Fourvenues.

Qué hace la integración#

• Cada 15 minutos descarga de Fourvenues los eventos del local desde el día anterior hasta los próximos días, y de cada evento las entradas creadas o modificadas desde la última descarga.
• Carga cada entrada en Ágora como entrada canjeable (cupón), con el código de la entrada de Fourvenues, el tipo de entrada de Ágora que le corresponda y válida hasta el final del evento (24 horas después del inicio si Fourvenues no indica la hora de fin).
• Asigna el tipo de entrada de Ágora por el nombre de la tarifa de Fourvenues: primero con la tabla de Tipos de entrada, después con los Patrones de búsqueda y, si no encaja ninguno, con el tipo de entrada por defecto.
• Cuando una entrada deja de estar activa en Fourvenues, la vuelve a cargar en Ágora ya caducada, para que no se pueda canjear.
• Permite anular una entrada desde el panel, leyendo su código con la cámara o escribiéndolo, y restaurarla después; en los dos casos actualiza Ágora en el momento.
• Guarda todas las entradas en Entradas, con su estado, si se han enviado a Ágora y el dato original de Fourvenues, y deja cambiar el tipo de entrada de una o varias y reenviarlas.

Qué no hace#

• No carga las entradas cuyo tipo no tiene correspondencia en Ágora (ni por tabla, ni por patrón, ni por defecto): se quedan en Connect Manager como «No se ha enviado a Ágora».
• No vende entradas ni crea eventos: solo lee lo que ya está en Fourvenues.
• No avisa a Fourvenues de lo que se canjea en Ágora.
• No factura las entradas. La pantalla tiene una sección Config. de facturas y otra de Config. de envío de cancelación, pero en la versión actual no generan facturas ni correos: no las actives sin hablar con FOS.

Requisitos#

• Cuenta de Fourvenues del local con acceso de integración: un Id. de integración y su Secret, o una X Api Key. Los facilita Fourvenues.
• Local en Connect Manager con la URL de la API y la API key de Ágora. FOS da de alta el local y la integración.
• API de Ágora accesible desde Internet, con puerto abierto o con Zero Connect: las entradas se cargan desde Connect Manager con la API de importación de Ágora.
• Tipos de entrada creados en Ágora (la configuración de entradas o cupones), uno por cada cosa distinta que se canjea, con su identificador numérico.

Datos que necesitamos#

Configuración paso a paso#

En Fourvenues#

1. Pide a Fourvenues las credenciales de integración del local (Id. de integración y Secret, o X Api Key).
2. Saca la lista de tarifas que vende el local con su nombre exacto: es lo que se usará para elegir el tipo de entrada en Ágora.

En Ágora#

1. Crea un tipo de entrada por cada cosa que se canjea (por ejemplo, una consumición o un acceso) y apunta su identificador.
2. Decide cuál será el tipo por defecto para las tarifas nuevas que aparezcan sin configurar.

En Connect Manager#

1. En https://app.connectmanager.es, ve a Administración → Locales, abre el local y revisa la URL de API y la API key de Ágora. Pulsa Guardar.
2. Entra en Integraciones de entradas, pulsa Añadir y en Proveedor elige Four venues.
3. En Configuración de autenticación rellena Id. de integración.: y Secret, «… o …» la X Api Key. Si están los dos primeros, se usan ellos.
4. En Id. de entrada por defecto pon el identificador del tipo de entrada de Ágora para las tarifas sin configurar. Si lo dejas vacío, esas entradas no se cargan.
5. Deja desmarcadas Enviar por email los tickets cancelados y Generar facturación diaria, y pulsa Guardar.
6. En la pestaña Tipos de entrada, pulsa Añadir por cada tarifa: Nombre de entrada en el proveedor (el nombre de la tarifa en Fourvenues) e Id. de tipo de entrada en Agora. El nombre se compara sin distinguir mayúsculas ni espacios al principio o al final.
7. Si muchas tarifas comparten una parte del nombre, usa la pestaña Patrones de búsqueda: Patrón de búsqueda es una expresión regular con sus delimitadores (por ejemplo /VIP/i para todo lo que contenga «VIP») y su Id. de tipo de entrada en Agora. La primera vez que una tarifa encaja con un patrón o con el tipo por defecto, se añade sola a la tabla de Tipos de entrada.

[!TIP] Revisa la tabla de Tipos de entrada después del primer evento: verás las tarifas que se han asignado solas al tipo por defecto y podrás corregirlas.

Cómo funciona#

Cada 15 minutos, Connect Manager pide a Fourvenues los eventos del local y, para cada uno, las entradas modificadas desde la última vez (con cinco minutos de margen), de 500 en 500 y hasta 5.000 por evento en cada pasada. Guarda las entradas, decide el tipo de entrada de Ágora de cada una y manda a Ágora, en un único envío por evento, las que son nuevas o han cambiado. Si Ágora las acepta, quedan marcadas como enviadas.

sequenceDiagram
    participant CM as Connect Manager
    participant FV as Fourvenues
    participant AG as API Ágora
    loop Cada 15 minutos
        CM->>FV: Eventos del local
        FV-->>CM: Eventos de ayer a los próximos días
        CM->>FV: Entradas modificadas de cada evento
        FV-->>CM: Entradas con código, tarifa y estado
        CM->>CM: Asigna el tipo de entrada de Ágora
        CM->>AG: Importa las entradas nuevas o cambiadas
        AG-->>CM: Importación correcta
        CM->>CM: Marca las entradas como enviadas
    end

Qué se envía a Ágora#

• Tipo de entrada: el de la tabla, el del patrón o el de por defecto.
• Código: el código de la entrada de Fourvenues, que es el que se lee al canjear.
• Fecha de creación y validez: hasta el final del evento. Las entradas que ya no están activas en Fourvenues, o que se anulan desde el panel, se envían con una validez pasada y dejan de poder canjearse.

Anular y restaurar desde el panel#

En Entradas → Canc. entrada se lee el código de barras o QR con la cámara del dispositivo (o se escribe) y la entrada se anula: Connect Manager la marca como cancelada y la reenvía a Ágora caducada. En Entradas → Rest. entrada se listan las anuladas y se restauran, volviendo a enviarlas con la validez del evento.

En resumen, una entrada llega a Ágora solo si su tarifa tiene tipo de entrada (por la tabla, por un patrón o por el de por defecto); si no, se queda sin enviar. Una vez cargada, se puede canjear hasta el final del evento mientras siga activa en Fourvenues; si deja de estarlo o se anula en el panel, se vuelve a cargar caducada.

flowchart LR
    A[Entrada en Fourvenues] --> B{Tarifa con tipo de Ágora}
    B -- Tabla, patrón o por defecto --> C[Se carga en Ágora]
    B -- Ninguno --> D[No se envía a Ágora]
    C --> E{Sigue activa}
    E -- Sí --> F[Canjeable hasta el fin del evento]
    E -- No o anulada en el panel --> G[Se recarga caducada]

Si algo falla#

• Si Fourvenues no responde, la descarga de ese evento se reintenta tres veces y, si sigue fallando, se avisa a FOS; la siguiente pasada vuelve a pedir lo pendiente.
• Si Ágora rechaza el envío o no responde, las entradas siguen como no enviadas y se reintentan en la siguiente pasada.
• Si aparecen tarifas sin tipo de entrada, FOS recibe un aviso con la lista para darlas de alta.

Comprobar que funciona#

1. Con un evento publicado en Fourvenues para los próximos días, vende o emite una entrada de prueba.
2. Espera a la siguiente pasada (como mucho 15 minutos) y busca la entrada en Entradas: debe aparecer con su código y «Enviado a Ágora».
3. En Ágora, canjea la entrada leyendo su código: debe aceptarla con el tipo de entrada esperado.
4. Anúlala en Canc. entrada e intenta canjearla otra vez en Ágora: debe rechazarla.
5. Restáurala en Rest. entrada y comprueba que vuelve a ser válida.
6. Anula una entrada en Fourvenues y comprueba, tras la siguiente pasada, que en Ágora ha dejado de valer.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Fourvenues con Ágora?#

Dando de alta en Connect Manager una integración de entradas «Four venues» con las credenciales de Fourvenues y relacionando cada tarifa con un tipo de entrada de Ágora.

¿Cada cuánto llegan las entradas vendidas?#

Cada 15 minutos. Una entrada vendida justo después de una pasada tarda como mucho ese tiempo en poder canjearse.

¿Qué pasa con una entrada anulada en Fourvenues?#

En la siguiente pasada se vuelve a cargar en Ágora caducada y ya no se puede canjear.

¿Hasta cuándo se puede canjear una entrada en Ágora?#

Hasta el final del evento que indica Fourvenues, o 24 horas después del inicio si el evento no tiene hora de fin.

¿Se facturan las entradas en Ágora?#

No. La facturación de entradas que aparece en la configuración no está funcionando en la versión actual.

Referencias#

• Ficha de la integración: Fourvenues en el catálogo de Connect Manager.
• Zero Connect: publicar la API de Ágora sin abrir puertos.
• Fourvenues: https://www.fourvenues.com.