Fidelización: conectar el club con Ágora

La integración de Fidelización de Connect Manager con Ágora conecta el club de fidelización de un grupo (monedero de saldo, sellos o puntos, cupones y niveles) con el TPV Ágora de cada local: en caja se identifica al socio, se ven su saldo y sus recompensas, se paga con saldo y, al cerrar la factura, se acumula lo que corresponda y se imprime un resumen al pie del ticket. Este manual es para el técnico que deja el club funcionando en el TPV: qué se configura en Connect Manager, qué en Ágora, cómo funciona y cómo comprobarlo.

Qué hace la integración#

• Identifica al socio en caja por su código de socio (el QR o código de barras de su tarjeta del móvil o de su área privada), por su teléfono, con o sin prefijo, o por un código adicional de su ficha (por ejemplo, una tarjeta física). Solo encuentra socios activos de un grupo al que pertenezca el local.
• Enseña en Ágora un saludo con el saldo y las recompensas: los cupones vigentes del socio para ese local y, si el local canjea el saldo como descuento, el monedero en tramos fijos (1, 2, 5, 10, 15, 20 y 40 € de serie) más «todo el saldo».
• Cobra con saldo de una de dos maneras, a elegir por local: como forma de pago, desde una ventana del monedero que se abre en el TPV (acción personalizada) e inyecta el pago en el ticket; o como descuento, con la fidelización nativa de Ágora.
• Acumula al cerrar la factura según el modelo del club: cashback en euros (porcentaje del local, con reglas por producto o familia y el multiplicador del nivel), sellos por visita o puntos por euro, con un cupón de recompensa al completar la tarjeta. Suma la visita y el gasto, recalcula el nivel y, si el club lo tiene activado, pide una reseña de Google.
• Imprime al pie del ticket un bloque «WALLET» con el socio, los cupones aplicados, el saldo gastado, lo acumulado y el saldo restante.
• Deshace la venta al devolverla entera: devuelve el saldo gastado, retira el cashback (aunque deje el saldo en negativo), libera cupones, quita sellos o puntos y descuenta la visita y el gasto.
• No duplica nada si Ágora reenvía la misma factura, y devuelve el saldo en el acto si Ágora rechaza un pago hecho desde la ventana del monedero.
• Convive con otro programa de fidelización en el mismo Ágora: lo que no es un socio del club se le pregunta al otro programa.
• Actualiza la tarjeta del móvil del socio (Apple o Google Wallet) al registrar la venta.
• Opcional: emite en Ágora la factura de anticipo de cada recarga de saldo, y el abono proporcional al gastarlo, a través del ACMS.

Qué no hace#

• No acumula en albaranes: según la guía del integrador de Ágora, solo se notifican las facturas.
• No revierte sola una devolución parcial ni la de un albarán: el ticket imprime «Devolucion registrada. Fidelizacion: revision manual.» y el saldo se ajusta a mano en la ficha del socio. Ninguna pantalla lista estas devoluciones pendientes.
• Una factura con varios socios (varios albaranes) solo se procesa para el primero.
• Un cambio de forma de pago de una factura ya emitida no se notifica, así que no se recalcula nada.
• En modo «Solo wallet» la ventana descuenta saldo, pero no hay acumulación ni cupones en caja.
• No da de alta socios desde el TPV: se dan de alta en el panel, en el portal de registro del club o por importación.
• Sin Api-Token, la ventana del monedero pide el importe a mano y no inyecta el pago: hay que cobrarlo en Ágora con la forma de pago del saldo.
• La fidelización del TPV no pasa por el ACMS: cada local lleva sus propias direcciones.

Requisitos#

• Ágora con el módulo de Servicios de integración activo; su Api-Token solo hace falta para cobrar como forma de pago. El formato de las facturas se comprobó con Ágora 8.9.3; desde Ágora 9.0.2 el TPV exige además credenciales de integrador, que son de Connect Manager y ya están en el servidor.
• Salida a Internet: el servidor de Ágora y el navegador del TPV tienen que llegar por HTTPS a https://hub.connectmanager.es. No hace falta abrir puertos, ni exponer la API de Ágora, ni Zero Connect: la ventana del monedero habla con la API local a través del propio TPV.
• El club creado para el grupo en Configuración → Portal público de clientes y el local asignado a ese grupo.
• Una forma de pago propia para el saldo en Ágora (modo forma de pago).
• Socios dados de alta, con su código de socio (formato CM26-XXXXXXXX).
• Permisos en el panel de Fidelización: «Fidelización: Configurar integración por local» (locales), «Fidelización: Activar por grupo» (club) y, si se usan, «Fidelización: Facturas de anticipo».

Quién hace qué. FOS crea el club, incorpora el local al grupo, cambia el modo de canje en /admin y mantiene las credenciales de integrador. El distribuidor configura Ágora y la ficha del local en el panel de Fidelización. El cliente decide el modelo, el porcentaje de cashback, los tramos y los cupones.

Datos que necesitamos#

Configuración paso a paso#

1. En Connect Manager: el club y el local#

1. En Configuración → Portal público de clientes, abre el club (si no existe, lo da de alta FOS) y, en su subpágina Fidelización, elige el «Modelo» en «Modelo de fidelización»: Cashback (monedero €), Sellos por visita, Puntos por gasto o Sin plan (no acumula nada). Con sellos o puntos, rellena la meta, los sellos por visita o los puntos por euro y el «Cupón de recompensa al completar».
2. Elige el grupo en el selector de la cabecera: la lista de locales se filtra por él.
3. En Configuración → Locales, si el local no está en el grupo, usa Asignar grupos (menú «Más opciones» de la fila). «Incorporar local» y «Crear local nuevo» solo los ve FOS.
4. Pulsa Configurar y rellena:
   • «Fidelización activa»: enciéndelo. Apagado, la ventana del monedero y las URLs de Ágora contestan que el local no está activo.
   • «ID de forma de pago en Ágora» y «Token de API de Ágora» (modo forma de pago).
   • «Porcentaje de acumulación de cashback (%)»: 5 = 5 %. De serie es 0, que no acumula.
   • «Lista blanca de IDs de TPV (Cajas)»: los TPV que pueden abrir la ventana del monedero; vacío = todos.
   • «Importes de descuento del monedero (€)»: los tramos (solo en modo descuento).
   • «Ancho del ticket (columnas)»: 48 o 42.
   • «Reglas de cashback por categoría / producto (opcional)»: cada línea acumula según la primera regla que coincida («Coincidir por» nombre de producto o categoría / familia; «Efecto» % fijo, × del base o Excluir (0 %)). Las de familia solo funcionan si la factura de Ágora trae la familia en sus líneas.
   • «Otro programa: URL de validación de participantes» y «Otro programa: URL de envío de facturas» (paso 7).
   • «Google Place ID / enlace (reseñas)»: ver Reseñas de Google.
5. Guarda y abre Ver enlaces de integración (menú «Más opciones»): ahí están las tres URLs del local.

[!WARNING] El campo de la forma de pago enseña «Ej.: FIDELITY_CM», pero la ventana del monedero solo entiende un número: con un texto descuenta el saldo y no inyecta el pago en el ticket. Pon siempre el Id numérico.

2. En Connect Manager: el modo de canje (solo si el local va a descontar)#

De serie todos los locales cobran el saldo como forma de pago. Para cambiarlo:

1. Entra en /admin → Locales, abre el local y ve a la pestaña Ecosistema Conectado.
2. Edita la fila «Fidelización ConnectManager» (si no existe: Añadir Integración, «Servicio / Proveedor» Fidelización ConnectManager (Loyalty)).
3. En «Cómo se canjea el saldo del cliente» elige Como descuento — Ágora pide los premios al servicio de fidelización y lo aplica al ticket y guarda. En este modo no hacen falta forma de pago ni Api-Token. Si no tienes acceso a /admin, pídeselo a FOS.

[!NOTE] Un solo modo por local: en modo descuento el servidor rechaza el cobro desde la ventana del monedero, para no cobrar el saldo dos veces.

3. En Ágora: forma de pago y Api-Token (modo forma de pago)#

1. Crea una forma de pago para el saldo (por ejemplo, «Monedero club») para que el arqueo la separe del resto, y apunta su Id.
2. Localiza el Api-Token de Servicios de integración y el usuario al que pertenece: su perfil necesita los permisos del paso 4.

4. En Ágora: las consultas personalizadas#

Son dos ficheros XML que facilita FOS y que se copian en la carpeta custom-queries de la instalación de Ágora de cada local; Ágora los instala solo.

1. cm-loyalty-attach.xml («CM Asociar socio fidelización»): al cobrar con saldo, asocia el socio al ticket para que Ágora notifique esa factura y se acumule sobre lo pagado de otra forma. Da el permiso «Consulta: CM Asociar socio fidelización» al perfil del usuario del Api-Token.
2. cm-loyalty-read.xml («CM Leer socio del ticket»), recomendable: si el cajero ya identificó al socio en la fidelización de Ágora, la ventana del monedero lo carga sola. Permiso «Consulta: CM Leer socio del ticket».

Si faltan, el cobro funciona igual; sin la primera, una compra pagada con saldo solo acumula si el socio también se identificó en la fidelización de Ágora.

5. En Ágora: la acción personalizada#

1. En Herramientas → Acciones personalizadas crea una acción y pega la «URL para Acción Personalizada (IFrame)» tal cual, con sus marcadores; Ágora los rellena al abrirla. Tiene esta forma: https://hub.connectmanager.es/loyalty/embed/TOKEN-DEL-LOCAL?user_id={user_id}&pos_id={pos_id}&ticket_id={ticket_id}&ticket_global_id={ticket_global_id}&introduced_value={introduced_value}.
2. Marca la opción de mostrar la URL en un diálogo de Ágora y añade el permiso que crea la acción a los perfiles de los usuarios que vayan a cobrar con saldo.
3. Si el local solo quiere gastar saldo, sin acumular ni cupones, enciende antes en «Ver enlaces de integración» el interruptor «Solo wallet — gastar saldo sin los detalles de la factura»: la URL pasa a llevar wallet_only=1 y no hace falta el paso 6.

En modo descuento la ventana es opcional: consulta saldo y movimientos, pero no cobra.

6. En Ágora: las URLs de fidelización#

1. En Servicios de integración → Fidelización, copia la «URL para Validación de Participantes» en el campo de validación de participantes. Deja {member_id} tal cual: Ágora pone ahí el código leído. Forma: https://hub.connectmanager.es/api/loyalty/TOKEN-DEL-LOCAL/member/{member_id}.
2. Copia la «URL para Envío de Facturas» en el campo de envío de facturas. Forma: https://hub.connectmanager.es/api/loyalty/TOKEN-DEL-LOCAL/invoices.

La URL de validación resuelve también los QR de cupón (códigos que empiezan por CPNT). Los cupones de tipo «Descuento predefinido en Ágora» o «Promoción predefinida en Ágora» necesitan que el código exista ya en Ágora; si no, Ágora ignora la recompensa.

[!WARNING] Cada local tiene sus propias URLs: el token identifica al local. Si el grupo replica la configuración desde Ágora Central (ACMS), comprueba que cada local se queda con las suyas. Tras «Rotar token», vuelve a pegar las tres en Ágora.

7. Opcional: otro programa de fidelización en el mismo Ágora#

Ágora solo admite una URL de validación y una de facturas. En Ágora van las de Connect Manager y, en Configurar, las del otro programa: en la de validación, si la dirección lleva {memberId} o {member_id} ahí se pone el código y, si no, se añade al final; a la de facturas se le reenvía la factura entera y su respuesta es la que ve Ágora. Solo funciona si los códigos de los dos programas no se solapan. El otro servidor tiene 5 segundos para contestar; si no contesta, Ágora recibe el «no encontrado» de Connect Manager.

8. Opcional: facturas de anticipo del monedero (ACMS)#

En Configuración → Facturas de anticipo se rellenan «Activación» («Activar facturación de anticipos», «Facturar recargas manuales», «Facturar recargas recurrentes»), «Conexión con el ACMS de Ágora» («URL del ACMS», «Api-Token» y Probar conexión), «Emisor de las facturas» (Ids de almacén/local, TPV, usuario, forma de pago y, si se usan, centro de venta y tarifa) y «Producto de anticipo y series» (producto, IVA, «Serie anticipos» y «Serie abonos», p. ej. WANT y WABO, con sus contadores). Cada recarga facturable genera una factura de anticipo simplificada (hasta 2.999 €; por encima, solo si el socio tiene datos de facturación) y cada consumo de ese saldo, su abono proporcional. Cashback, regalos e importaciones no se facturan, y un fallo de facturación no bloquea el saldo: se reintenta.

Cómo funciona#

Modo descuento#

El cajero identifica al socio en la fidelización del ticket de Ágora. Ágora llama a la URL de validación con el código; Connect Manager busca al socio en los grupos del local y contesta con un saludo («Hola …, tu saldo disponible es de …») y las recompensas: un descuento por cada tramo que cubra el saldo («Descontar 5 € del monedero»), «Descontar hasta … (todo tu saldo)» y los cupones. El cajero elige. Al emitir la factura, Ágora la envía entera a la URL de facturas: Connect Manager descuenta lo que Ágora restó de verdad en la línea (nunca más que el premio elegido), canjea los cupones, acumula sobre lo pagado y contesta «accepted» con el texto a imprimir. Si algo no cuadra (saldo insuficiente, cupón agotado) contesta «rejected» con el motivo y, según la guía de Ágora, la factura no se cierra hasta corregirlo.

sequenceDiagram
    participant C as Cajero
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    C->>TPV: Identifica al socio con QR, código o teléfono
    TPV->>CM: GET validación de participante con el código
    CM-->>TPV: Saludo con saldo, tramos y cupones
    C->>TPV: Elige el premio y cobra el resto
    TPV->>CM: POST factura emitida con el premio
    CM->>CM: Descuenta saldo, canjea cupón y acumula
    CM-->>TPV: accepted y texto para el ticket
    TPV-->>C: Imprime el bloque WALLET

Modo forma de pago#

El cajero abre la acción personalizada desde el ticket. La ventana comprueba el token y la lista blanca, y abre una sesión de un solo uso de 5 minutos. Carga el socio que ya tenga el ticket o lo identifica con lector, cámara, NFC, código o teléfono, y enseña su saldo, si es «Válido aquí» y sus últimos movimientos. Con Api-Token lee el total del ticket y no deja cobrar más de ese total ni más saldo del disponible. Al cobrar, Connect Manager descuenta el saldo; la ventana asocia el socio al ticket, inyecta el pago con la forma de pago configurada (el ticket se cierra) y se cierra sola. Si Ágora rechaza el pago, el saldo se devuelve en el acto, una sola vez y con la caducidad que tenía. Al emitirse la factura, Ágora la envía a la URL de facturas y se acumula sobre la parte no pagada con saldo.

sequenceDiagram
    participant C as Cajero
    participant V as Ventana monedero
    participant CM as Connect Manager
    participant TPV as TPV Ágora
    C->>V: Abre la acción personalizada
    V->>CM: Pide el saldo del socio
    V->>TPV: Lee el total del ticket
    C->>V: Pulsa cobrar
    V->>CM: Descuenta el saldo
    V->>TPV: Asocia el socio e inyecta el pago
    alt Ágora rechaza el pago
        V->>CM: Revierte el cobro
        CM-->>V: Saldo devuelto
    end
    TPV->>CM: POST factura emitida
    CM-->>TPV: accepted y texto para el ticket

Devoluciones#

Una devolución se procesa aunque el ticket de devolución no lleve el socio: se busca la venta original por su identificador (o por su número) y se actúa sobre el socio de esa venta. Se revierte entera si Ágora indica que es de ticket, de factura, por reapertura o por conversión a factura nominativa, o si no indica el origen pero devuelve exactamente lo que costó la venta. Si es parcial, de albaranes o no aparece la venta original, queda en revisión manual. Una devolución ya revertida no se repite.

flowchart TD
    A[Llega una devolución] --> B{Total o importe igual a la venta}
    B -->|No| R[Revisión manual en el ticket]
    B -->|Sí| C{Venta original encontrada}
    C -->|No| R
    C -->|Sí| D{Ya revertida}
    D -->|Sí| E[Devolucion ya procesada]
    D -->|No| F[Reabona saldo, retira cashback y libera cupones y sellos]
    F --> G[Imprime DEVOLUCION - WALLET]

Lo que se acumula y se imprime#

El cashback es neto × porcentaje del local × multiplicador del nivel (con reglas, el porcentaje es la media ponderada de las líneas). En modo descuento el neto es el importe de la factura, que Ágora ya manda sin el descuento del monedero; en modo forma de pago, el importe menos lo cobrado con saldo. Los sellos son los de «Sellos por visita (ticket)» por factura y los puntos, neto × «Puntos por € gastado»; al llegar a la meta se asigna el cupón de recompensa. Con «Sin plan» no se crea ningún movimiento. El texto que se imprime tiene esta forma, a 48 o 42 columnas:

================================================
                     WALLET
================================================
Cliente: Socio de ejemplo
Cupon aplicado: Café de bienvenida
Saldo redimido                         -5,00 EUR
Acumulado hoy                          +0,75 EUR
Saldo disponible                       20,75 EUR
================================================

Si Ágora reenvía una factura ya aceptada, recibe la misma respuesta; una rechazada se vuelve a procesar. Las URLs de Ágora admiten 300 peticiones por minuto y por IP, y la ventana del monedero, 60.

Comprobar que funciona#

1. En Configuración → Locales, el local aparece con «Fidelización activa».
2. Abre en un navegador la URL de validación con el código de un socio de prueba en lugar de {member_id}: debe devolver un JSON con MemberId, DisplayText y Rewards. Con un código inventado, {"error":"Cliente no encontrado."}.
3. Dale saldo al socio desde su ficha (Administración → Clientes → «Añadir saldo»; si hay facturas de anticipo, desmarca «Emitir factura de anticipo en Ágora»).
4. Modo descuento: identifica al socio en un ticket, aplica «Descontar 2 € del monedero» y factura. Se imprime el bloque WALLET y en el «Historial de saldo» del socio aparece «Consumo de saldo en ticket #…» con origen «Ágora TPV».
5. Modo forma de pago: abre la acción personalizada, identifica al socio, comprueba que sale el total y cobra. El ticket se cierra con la forma de pago del saldo y en la ficha aparece «Pago TPV (Ticket: …)».
6. Devuelve el ticket entero: se imprime «DEVOLUCION - WALLET» y el saldo vuelve.
7. Asigna un cupón al socio y comprueba que sale en las recompensas de Ágora.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto el club de fidelización de Connect Manager con Ágora?#

Configura el local en Configuración → Locales → Configurar, abre «Ver enlaces de integración» y pega en Ágora la URL de la acción personalizada (cobrar con saldo) y las de validación de participantes y envío de facturas (acumular y aplicar premios).

¿Es mejor cobrar el saldo como forma de pago o como descuento?#

Como forma de pago, el saldo sale en el arqueo como un cobro más y se puede gastar cualquier importe. Como descuento no hacen falta Api-Token ni acción personalizada, y el saldo se aplica por tramos o entero. Solo uno por local.

¿Hay que abrir puertos o instalar Zero Connect para la fidelización?#

No. Ágora llama a Connect Manager por HTTPS y la ventana del monedero habla con la API local a través del TPV. Basta con salida a Internet hacia hub.connectmanager.es.

¿Puedo usar el club de Connect Manager y otro programa de fidelización en el mismo Ágora?#

Sí: en Ágora van las URLs de Connect Manager y en la ficha del local las del otro programa, que recibe lo que no es nuestro. Los códigos de los dos no pueden solaparse.

¿Qué pasa con el saldo si se devuelve un ticket pagado con el monedero?#

Si la devolución es total, el saldo vuelve solo y se retira el cashback de esa venta. Si es parcial, el ticket avisa de revisión manual y se ajusta en la ficha del socio.

Referencias#

• Apple Wallet: la tarjeta del club en el iPhone
• Google Wallet: la tarjeta del club en Android
• WhatsApp y Bird: mensajes y campañas del club
• Reseñas de Google
• Pagos con Redsys (cobros online del club: tarjetas regalo, cuotas y entradas)
• Proveedores de envío de correo
• Programa de fidelización de Connect Manager
• Guía del Integrador de Ágora, apartado «Integración con Sistemas de Fidelización» (la facilita Ágora).