Solución de problemas frecuentes de instalación y escaneo
La mayoría de los inconvenientes al instalar un pase o escanearlo en caja se deben a navegadores integrados dentro de aplicaciones sociales, cuentas de Google distintas, barreras de seguridad de descarga (verifyDownloadPin / downloadUntil) o reflejos en la pantalla en el punto de venta.
Referencia de diagnóstico para barreras de descarga
Al diagnosticar por qué un enlace inteligente (/d/:slug, /download/:slug o /s/:token) no abre de inmediato Apple Wallet o Google Wallet, verifique el estado de la respuesta y el comportamiento de la puerta de seguridad:
| Síntoma / Comportamiento de bloqueo | Mecanismo del backend | Causa y solución para el titular |
|---|---|---|
| «Safari no puede descargar este archivo» o pantalla en blanco en iPhone | Restricción MIME de WKWebView integrado | El enlace se abrió dentro de Instagram, TikTok, Facebook, LinkedIn o un visor de correo. Toque ... -> Abrir en el navegador (Safari) para que iOS pueda instalar el .pkpass firmado con bundleId. |
| El pase solicita un PIN de 4 a 6 dígitos | verifyDownloadPin (Public Download Page) | El emisor activó la protección por PIN (pinVerified: false hasta validarlo). Introduzca el PIN en la página PassFlow (GET /d/:slug?pin=...) o en el aviso por correo/SMS para desbloquear los enlaces Wallet. |
Enlace caducado (downloadUntil) | Validación de marca temporal downloadUntil | El token de descarga temporal ha expirado. Utilice el botón de recuperación en pantalla (POST /d/:slug/request-recovery con { emailOrPhone }) para recibir un nuevo enlace. |
Límite de dispositivos alcanzado (HTTP 403 Forbidden) | limitToOneActivePerPass: true | El pase ya está activo en otro dispositivo. Elimine primero el pase de su teléfono anterior o solicite al emisor que restablezca la vinculación. |
| Tarjeta guardada en Android, pero ausente en Google Wallet | Cuenta de Google distinta | Chrome inició sesión con una cuenta de Gmail secundaria distinta de la cuenta principal abierta en Google Wallet. Cambie de cuenta desde el avatar superior derecho en Google Wallet. |
Desbloquear una página de descarga protegida por PIN
Cuando una plantilla, un paquete Wallet Experience o una página de descarga exige verificación de PIN antes de entregar el .pkpass firmado o la URL de Google Save, Public Download Page valida el PIN mediante verifyDownloadPin (aceptando la cabecera o el parámetro de consulta ?pin= en /d/:slug y /d/:slug/download) y retiene las URLs de Wallet (error=pin_required / pinVerified: false) hasta que se introduce el PIN válido en la interfaz de la página.
Corregir errores de lectura de códigos de barras y NFC en caja
Si un escáner TPV o la cámara de un terminal de tienda tiene dificultades para leer su pase en el mostrador:
-
1
Suba al máximo el brillo de pantalla: Apple Wallet y Google Wallet aumentan automáticamente la retroiluminación al mostrar un código, pero los modos agresivos de ahorro de batería pueden anularlo. Suba el brillo manualmente.
-
2
Retire o incline protectores de privacidad oscuros: Los cristales polarizados de privacidad reducen drásticamente el contraste en ángulos laterales bajo la iluminación de tienda. Mantenga el teléfono plano y frente a la ventana del escáner (
10–15 cmde distancia). -
3
Acerque el dispositivo al símbolo sin contacto NFC: Para pases configurados con Apple VAS o Google Smart Tap (
NFC), acerque el borde superior del iPhone o la parte trasera central de su Android al icono de ondas del lector durante 1 segundo y complete Face ID / Touch ID / biometría si se solicita. -
4
Use el número de serie legible: Todo pase con código de barras incluye un código alternativo (
serialNumbero ID de socio) impreso bajo el gráfico QR/PDF417/Code128 para que el personal lo consulte medianteGET /api/v1/scans/pass?barcode=...si la pantalla está dañada.
Importante: Si ve una insignia de caducado o anulado en su pase (pass status:
VOIDEDoEXPIRED), la tarjeta ya ha sido canjeada o ha alcanzado su fecha límite de validez y será rechazada por el escáner (ALREADY_VOIDED/PASS_VOIDED_AFTER_SCANoEXPIRED).
¿Sigue necesitando ayuda? Consulte Añadir un pase a su Wallet o escriba a través de Contactar con soporte.
