Apple Wallet: la tarjeta del socio en el iPhone

Configura Apple Wallet en el club de Connect Manager: tarjeta de socio en el iPhone con saldo al día, avisos y código que se escanea en Ágora.

La integración de Apple Wallet del club de fidelización de Connect Manager pone la tarjeta de socio en la app Cartera del iPhone, con su saldo al día y el código que se escanea en el TPV Ágora para identificarle. Este manual es para el técnico: qué tiene que haber en el servidor, qué se configura en cada club, cómo se genera y se actualiza el pase y cómo diagnosticarlo cuando no llega o no cambia.

Qué hace la integración#

Emite a cada socio su tarjeta del club con su nombre, su saldo, su código de socio y un código escaneable (QR, PDF417 o Código 128) cuyo valor es el código de socio: el mismo que Ágora valida en la fidelización.
La mantiene al día sola: cada movimiento de saldo, cambio de nivel o de membresía y cada cambio de diseño del club reescribe el pase y avisa al iPhone, que se descarga la versión nueva. El campo del saldo lleva el aviso «Tu saldo ahora es …» en la pantalla de bloqueo.
Muestra los avisos de las campañas del canal «Tarjeta del móvil» en la pantalla de bloqueo y los deja 30 días en el reverso.
Personaliza la tarjeta por club: logo cuadrado y logo apaisado, colores de fondo, texto y etiquetas, qué dato va en cada una de las cuatro posiciones del frontal, formato del código y, si el club tiene niveles, el color del nivel de cada socio como fondo.
Rellena el reverso con «CÓMO FUNCIONA» (un texto según el modelo del club), la membresía y el nivel del socio, «INVITA A UN AMIGO» con su código y «Invitar por WhatsApp», hasta 8 enlaces de interés, «PEDIR A DOMICILIO» si el club lo elige, «TU ÁREA PRIVADA» («Ver mi perfil») y «ACTUALIZAR TARJETA» («Actualizar ahora»).
Da acceso al área privada desde el pase, si el club lo enciende: el enlace del reverso es personal, entra sin pedir el correo y solo deja mirar. En ese caso el pase no se puede compartir desde Cartera.
Avisa cerca de los locales: hasta 10 locales del club con su ubicación; el iPhone saca la tarjeta en la pantalla de bloqueo con el nombre público del local.
Anula la tarjeta si el socio pierde el móvil: pasa a «Tarjeta anulada», sin código ni saldo, y deja de actualizarse.
Emite también las entradas de la agenda del club como pase de evento.
Funciona en el Apple Watch: con Código 128 el pase lleva además el mismo código en QR, porque el reloj no pinta códigos de barras 1D.

Qué no hace#

No usa cuentas de Apple del cliente. Todos los clubes firman sus pases con el certificado de Connect Manager; no se puede emitir con el identificador de pase (Pass Type ID) de un cliente.
No actualiza una entrada de evento ya añadida a Cartera si el evento cambia o se cancela.
No repite un aviso con el mismo texto: iOS solo avisa cuando el valor cambia, así que una campaña con el mismo texto que la anterior no suena.
Los enlaces para añadir la tarjeta caducan: 1 hora en la pantalla final del portal de registro, 1 día en el área privada y 14 días en los correos y en WhatsApp.
No cambia los pases al instante al tocar el diseño: se reescriben en segundo plano, socio a socio, y tardan unos minutos.

Requisitos#

En el servidor de Connect Manager (lo mantiene FOS): el certificado de tipo Pass Type ID en formato .p12, vigente, con su contraseña; el Pass Type ID y el Team ID que coinciden con ese certificado; el secreto del servicio web, de al menos 16 caracteres; y una dirección pública https para el servicio web de los pases. Todo se revisa con php artisan loyalty:check-apple-cert.
La cola de trabajos funcionando: las actualizaciones de los pases van encoladas.
El club creado en Configuración → Portal público de clientes, con su «Título de la aplicación» (sale como organización y nombre del club en el pase) y su logo.
La integración con el TPV funcionando (ver Fidelización: conectar el club con Ágora), para que el código de la tarjeta sirva en caja.
Un lector en el TPV que lea el formato elegido: QR y PDF417 necesitan un lector 2D o cámara; un lector láser 1D solo lee Código 128.
Socios con iPhone y la app Cartera.
Permisos en el panel: «Fidelización: Activar por grupo» para editar Monederos y «Fidelización: Emitir wallet passes» para «Enviar wallet».

Quién hace qué. FOS mantiene el certificado y el servidor. El técnico configura el diseño en Monederos, elige el formato del código según el lector del local y hace las pruebas. El cliente aporta logos, colores, textos y enlaces.

Datos que necesitamos#

Dato	Quién lo facilita / dónde se saca	Ejemplo o formato	Obligatorio
Logotipo cuadrado de los pases	Cliente	Imagen 1:1, mínimo 660 × 660 px, máximo 2 MB	Recomendado (si no, el del portal)
Logotipo apaisado para Apple	Cliente	PNG con fondo transparente, 480 × 150 px	Recomendado
Colores de fondo, texto y etiquetas	Cliente	Hexadecimal de 6 cifras, p. ej. `#0f172a`	No (fondo: color del portal; texto blanco; etiquetas gris claro)
Etiqueta del saldo	Cliente	«Saldo»	No («Saldo Acumulado»)
Dato de cada posición del frontal	Técnico y cliente	Cabecera: Saldo · Principal: Nombre del cliente · Secundario: Código de socio · Auxiliar: Nombre del club	Sí (esos son los de serie)
Formato del código	Técnico, según el lector del TPV	QR, PDF417 o Código 128	Sí (QR de serie)
Enlaces de interés	Cliente	`https://…`, `tel:…` o `mailto:…`, hasta 8	No
Ubicación de cada local	Delivery propio → Configuración → Locales → Ubicación y contacto	Latitud y longitud	Solo para avisos por cercanía
Certificado, Pass Type ID, Team ID y secreto del servicio web	FOS (cuenta de Apple de Connect Manager)	—	Ya en el servidor

Configuración paso a paso#

1. En el servidor de Connect Manager (FOS)#

Ejecuta php artisan loyalty:check-apple-cert. Enseña la organización, el Pass Type ID, el Team ID y las fechas de validez del certificado, y debe decir «El certificado está VIGENTE ahora mismo.» y que el Pass Type ID y el Team ID coinciden con la configuración.
En el mismo informe, el apartado del servicio web debe indicar que el pase llevará la dirección del servicio y un secreto correcto. Un pase con dirección de servicio y sin secreto lo rechaza iOS.
Si el certificado ha caducado, FOS lo renueva en su cuenta de Apple Developer, lo sube al servidor con su contraseña y vuelve a desplegar.

2. En Connect Manager: el diseño de la tarjeta#

Ve a Configuración → Portal público de clientes, abre el club y entra en la subpágina Monederos. El mismo formulario está en Delivery propio → Tienda → Pases: los dos guardan la misma tarjeta.

«Logotipo de los pases»: sube el «Logotipo para Apple/Google Wallet» (cuadrado, del que sale el icono) y el «Logotipo apaisado para Apple Wallet» (Apple lo pinta en una banda de 160 × 50 puntos y un logo cuadrado queda diminuto). Para quitar el apaisado, «Quitar el logotipo apaisado (Apple usará el de arriba)».
En «Personalizador de tarjetas», en «Selecciona el monedero a personalizar», elige Apple Wallet (iOS). El selector solo cambia lo que se ve: lo tocado en la otra plataforma también se guarda.
«Etiqueta del saldo (Apple y Google)»: la misma para las dos tarjetas.
«Apariencia y colores»: «Color de fondo de tarjeta», «Color de texto primario» y «Color de etiquetas», siempre en hexadecimal de seis cifras.
«Distribución de campos»: elige el dato de «Campo de cabecera (arriba a la derecha)», «Campo principal (gran tamaño)», «Campo secundario (bajo el principal, a la izquierda)» y «Campo auxiliar (misma fila, a la derecha)» entre Nombre del cliente, Saldo, Código de socio, Nombre del club, Nivel de fidelización, Membresía de socio (nivel del club) y Ocultar / ninguno. Un dato solo puede estar en una posición. Después elige el «Formato de código de barras»: Código QR (recomendado), PDF417 (código 2D clásico) o Código 128 (código de barras 1D).
«Detalles del pase»: «Enlaces de interés» (cada uno con «Título», «Qué es» —Un enlace o Un texto— y su «Dirección» o «Texto»), «Código de invitación del socio» (necesita el programa de referidos y el portal de registro encendidos), «Entrar al área privada desde el pase», «Botón del pase de Google» (en Apple salen los dos en el reverso), «Avisar cerca de los locales» (indica cuántos locales tienen la ubicación puesta) y «Color del nivel en la tarjeta» (solo aparece si el club tiene niveles activos con color).
Comprueba el resultado en «Vista previa del monedero» y guarda. Si ya hay pases emitidos, sale el aviso «Actualizando los pases ya emitidos»: recibirán el diseño nuevo en unos minutos.

[!NOTE] Cambiar el logotipo o el «Título de la aplicación» en la subpágina Apariencia también reescribe los pases de Apple ya emitidos.

3. Entregar la tarjeta a los socios#

En su área privada del portal del club, con el botón de Apple Wallet.
Por correo: la bienvenida y el «Envío del wallet para descarga» (Comunicaciones del club) llevan el botón «Añadir mi tarjeta al móvil». Por WhatsApp, ver WhatsApp y Bird.
A mano, desde la ficha del socio con Enviar wallet (necesita el permiso «Fidelización: Emitir wallet passes»).
Al terminar el alta en el portal de registro del club.
En «Mi cuenta» de la tienda online propia del grupo.

Los enlaces de los correos llevan a una página que, en un iPhone, abre directamente el pase de Apple; en Android lleva al de Google y en un ordenador enseña los dos botones.

4. En Ágora#

No hay nada específico: el código del pase es el código de socio y se lee en la fidelización de Ágora como cualquier otro. Basta con tener puesta la URL de validación de participantes y elegir un formato que el lector del local lea.

Cómo funciona#

Alta del pase en el iPhone#

El socio abre un enlace firmado. Connect Manager compone el pase con el contenido completo del club (colores, campos, código y reverso), lo firma con el certificado de Connect Manager y lo guarda. El número de serie es el código de socio y cada pase lleva su propio token, calculado a partir de ese número, para hablar con el servicio web. Al añadirlo, el iPhone se registra en el servicio web de pases de Connect Manager (las rutas /passkit/v1/…), que apunta ese dispositivo para avisarle de los cambios.

sequenceDiagram
    participant I as iPhone
    participant CM as Connect Manager
    I->>CM: Abre el enlace firmado
    CM->>CM: Compone y firma el pase
    CM-->>I: Pase con el código de socio
    I->>I: El socio lo añade a Cartera
    I->>CM: Registra el dispositivo con el token del pase
    CM-->>I: Registro guardado

Actualizaciones#

Cuando cambia algo del socio (una factura en Ágora, una recarga, un cambio de nivel) o del club (el diseño), se encola una sincronización de ese socio. El trabajo reconstruye el pase entero —así un campo que se oculta desaparece también de los pases ya emitidos—, lo guarda y avisa a APNs, el servicio de notificaciones de Apple, para cada iPhone registrado. El iPhone pide entonces la versión nueva al servicio web y, si el saldo ha cambiado, enseña «Tu saldo ahora es …». Si la sincronización falla se reintenta hasta 3 veces, cada 30 segundos, y los cambios seguidos del mismo socio se agrupan en una sola.

sequenceDiagram
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant APNs as Apple APNs
    participant I as iPhone
    TPV->>CM: Factura con socio
    CM->>CM: Encola la actualización del pase
    CM->>APNs: Aviso de pase cambiado
    APNs->>I: Aviso de actualización
    I->>CM: Pide la última versión del pase
    CM-->>I: Pase nuevo con el saldo
    I->>I: Muestra Tu saldo ahora es

Avisos de campaña#

Una campaña con el canal «Tarjeta del móvil» (Administración → Campañas) guarda el aviso en el socio (se conservan los 5 últimos), reescribe el pase con el aviso en el reverso y lo envía como cualquier actualización: al cambiar el texto, iOS lo enseña en la pantalla de bloqueo. El aviso se queda 30 días y solo llega a quien tiene la tarjeta añadida. Las campañas de este canal se envían a un ritmo de 5 socios por segundo.

Seguridad#

El token de cada pase solo sirve para ese pase: con un pase propio no se puede descargar el de otro socio. Los pases emitidos antes de este cambio, que llevan el secreto común antiguo, se rechazan y hay que volver a enviarlos.
Los enlaces para añadir la tarjeta van firmados y caducan; uno caducado lleva al acceso del portal del club con un aviso.
«Actualizar ahora» lleva su propia firma, no necesita sesión y admite 10 pulsaciones por minuto.

Comprobar que funciona#

FOS: php artisan loyalty:check-apple-cert dice que el certificado está vigente y que coincide con la configuración.
Guarda Monederos y revisa la vista previa.
Con un socio de prueba con correo, pulsa Enviar wallet, abre el correo en un iPhone y añade la tarjeta.
En la ficha del socio, pestaña «Wallet (Apple / Google)», aparece el pase de Apple Wallet con su fecha de emisión.
Escanea la tarjeta en Ágora: el socio se identifica.
Añade 1 € de saldo desde la ficha: en unos segundos la tarjeta cambia y sale «Tu saldo ahora es …».
FOS puede comprobar los dispositivos registrados con php artisan loyalty:apple-push-test CM26-XXXXXXXX --dry y, sin --dry, mandar un aviso real y ver la respuesta de Apple.

Errores frecuentes y solución#

Síntoma	Causa	Solución
El iPhone no deja añadir la tarjeta	Certificado caducado o que no coincide con el Pass Type ID o el Team ID, o servicio web sin secreto.	FOS: `loyalty:check-apple-cert` y renovar o corregir.
«Apple Wallet no configurado. Contacte al administrador.»	No hay certificado en el servidor.	Avisa a FOS.
«Error al generar la firma del pase de Apple Wallet.»	Falló la firma (certificado o contraseña) o la preparación de las imágenes.	FOS revisa el registro del servidor.
El enlace lleva al acceso del portal con «El enlace para añadir tu tarjeta al móvil ha caducado. Inicia sesión y vuelve a generarlo desde tu área.»	Enlace caducado.	Vuelve a enviar la tarjeta o que el socio la descargue desde su área privada.
La tarjeta no se actualiza	El iPhone no está registrado, la cola está parada o falló el aviso a Apple.	«Resincronizar saldo» en la pestaña «Wallet (Apple / Google)» de la ficha (fuerza el aviso aunque no haya cambios); el socio puede pulsar «Actualizar ahora» en el reverso. FOS: `loyalty:apple-push-test`.
El lector del TPV no lee la tarjeta	Lector láser 1D con código QR o PDF417.	Elige Código 128 en «Formato de código de barras»: los pases ya emitidos se reescriben.
El logo sale diminuto	Solo hay logotipo cuadrado.	Sube el «Logotipo apaisado para Apple Wallet».
«Tiene que ser un color hex, por ejemplo #926f2d.»	Color en otro formato.	Escríbelo como `#rrggbb`.
«Ese dato ya está en otra posición de la tarjeta.»	El mismo dato en dos posiciones.	Cambia una de ellas o ponla en «Ocultar / ninguno».
En el registro: «Pase de Apple con el token global antiguo: hay que reemitirlo.»	Pase emitido antes del token por pase.	Vuelve a enviar la tarjeta al socio para que la sustituya.
Un aviso de campaña no sonó	Mismo texto que el aviso anterior, o el socio no tiene la tarjeta de Apple.	Cambia el texto del aviso.

Preguntas frecuentes#

¿El restaurante necesita una cuenta de desarrollador de Apple para tener su tarjeta en Apple Wallet?#

No. Los pases se firman con el certificado de Connect Manager; en cada club solo se configura el diseño: logos, colores, campos y enlaces.

¿Cómo se actualiza el saldo de la tarjeta de Apple Wallet después de pagar en Ágora?#

Al registrar la factura, Connect Manager reescribe el pase y avisa al iPhone a través de Apple; el iPhone descarga la versión nueva en segundos y muestra «Tu saldo ahora es …».

¿Qué formato de código elijo para que el TPV Ágora lea la tarjeta del iPhone?#

QR si el lector del local es 2D o con cámara; Código 128 si es un láser 1D. Con Código 128 el Apple Watch enseña el mismo código en QR.

¿Qué hago si un socio pierde el iPhone?#

En su ficha, pestaña «Wallet (Apple / Google)», pulsa «Anular pases»: la tarjeta queda anulada, deja de actualizarse y el enlace personal de su área privada deja de valer. Después envíale la tarjeta de nuevo con «Enviar wallet».

¿Se pueden mandar notificaciones a la tarjeta de Apple Wallet?#

Sí: con una campaña del canal «Tarjeta del móvil» el aviso sale en la pantalla de bloqueo y queda 30 días en el reverso. Además, cada cambio de saldo avisa solo.