Descripción general y arquitectura inteligente de endpoints
Cada pase emitido y cada enlace de distribución de plantilla en Passinstance se resuelve mediante un Motor inteligente de descarga consciente de la plataforma (modelo DownloadPage y Download Page API). En lugar de repartir enlaces distintos para Apple y Android, usted distribuye una única URL canónica (passAccessUrl, /d/:slug o /s/:token) que inspecciona dinámicamente la cabecera HTTP User-Agent del cliente, el contexto del navegador y el estado de seguridad antes de entregar el paquete de monedero correspondiente.

Detección dinámica de User-Agent y comportamiento por plataforma
-
1
iPhone e iPad (Safari en iOS): Transmite en streaming el archivo
.pkpassfirmado criptográficamente con tipo MIMEContent-Type: application/vnd.apple.pkpass, abriendo de inmediato la hoja modal nativa de iOS Añadir a Apple Wallet. -
2
WebViews integradas en aplicaciones iOS (Instagram, TikTok, Facebook, LinkedIn): Dado que los navegadores integrados en redes sociales bloquean flujos binarios
application/vnd.apple.pkpass, Passinstance detecta elUser-Agentintegrado y muestra una pantalla guiada específica indicando al titular que abra el enlace en Safari nativo. -
3
Dispositivos Android: Emite una redirección HTTP
302(o muestra un botón de un toque Añadir a Google Wallet) apuntando ahttps://pay.google.com/gp/v/save/<signed_jwt>, aprovisionando elLoyaltyObject,EventTicketObjectoGenericObjecten la nube directamente en Google Wallet. -
4
Navegadores de escritorio: Muestra una página PassFlow adaptativa con la imagen de marca y un código QR dinámico de alto contraste (
GET /d/:slug/qr), junto con controles de envío autoservicio por correo o SMS (POST /d/:slug/send-link-by-email,POST /d/:slug/send-link-by-sms) para que el usuario traslade el pase a su teléfono en segundos.
Importante: Cuando está activada la Vinculación a un único dispositivo (
limitToOneActivePerPass: true) en una plantilla o pase (sharingProhibited), el enlace inteligente de descarga se bloquea automáticamente en cuanto un dispositivo completa su primer registro mediante el Apple Wallet Web Service (POST /v1/devices/:deviceLibraryIdentifier/registrations/...) o el callbacksavede Google Wallet, impidiendo compartir el enlace sin autorización.
Endpoints de API de enlaces inteligentes y páginas de descarga
Las rutas públicas de resolución de descargas se montan fuera del prefijo /api/v1 en Public Download Page y Public Pass Recovery API (/d/:slug/* y alias /download/:slug/*, además de las rutas autenticadas de gestión bajo /api/v1/download-pages/*):
| Método | Ruta del endpoint | Ámbito de auth | Descripción técnica |
|---|---|---|---|
| GET | /d/:slug | Público | Enrutador inteligente de entrada; redirige navegadores a /download/:slug o sirve metadatos JSON cuando se solicita; admite ?pass=:passId, ?lang=, ?pin=. |
| GET | /d/:slug/info | Público | Devuelve metadatos JSON (request payload), tokens de marca, pasos de PassTour y disponibilidad del pase. |
| GET | /d/:slug/qr | Público | Genera una imagen escaneable de código QR que codifica la URL inteligente de descarga. |
| GET | /d/:slug/download | Público | Detecta el User-Agent y entrega .pkpass (iOS) o redirección JWT Save de Google (Android); respeta ?pin= o X-Wallet-Experience-Pin. |
| POST | /d/:slug/create | Público (con límite de tasa) | Emite un pase directamente desde una página de descarga (request payload: name, email?, phone?, additionalFields?). |
| POST | /d/:slug/send-link-by-email | Público (con límite de tasa) | request payload ({ email, passLink? }) — envía por correo electrónico el enlace de descarga al usuario desde vistas de escritorio. |
| POST | /d/:slug/send-link-by-sms | Público (con límite de tasa) | request payload ({ phoneNumber, passLink? }) — envía el enlace de descarga mediante SMS en formato E.164. |
| POST | /d/:slug/request-recovery | Público (con límite de tasa) | { emailOrPhone } — envía un enlace mágico de recuperación cuando un cliente cambia de teléfono o pierde su enlace. |
| GET | /s/:token | Público | Enlace inteligente canónico vinculado al serialNumber o token de un pase individual. |
Seguridad de tokens, protección por PIN y entrega secundaria
Puede configurar salvaguardas de acceso granulares tanto a nivel de plantilla como en cada emisión individual de pase:
-
Caducidad de descarga (
enableDownloadUntil): Establece un límite"YYYY-MM-DD HH:mm"o marca temporal ISO tras el cual los enlaces de descarga no reclamados dejan de emitir nuevos pases, mientras los ya instalados siguen activos en los monederos. -
Bloqueo a un único dispositivo activo (
limitToOneActivePerPass): Impide nuevas descargas una vez que el pase cuenta con un registro activo en dispositivo. -
Bloqueo por PIN (parámetro
pin/ cabeceraX-Wallet-Experience-Pin): Exige que el titular desbloquee con PIN los enlaces de descarga y paquetes.pkpassesantes de instalarlos (verificado mediantePOST /api/v1/pass-projects/:id/validate-pinen Wallet Experiences). -
Pausar todas las descargas (
passDownloadDeactivated): Interruptor de emergencia en los ajustes de plantilla que detiene nuevas descargas en todos los canales sin revocar pases ya instalados en dispositivos de clientes. -
Prioridad de resolución del pase (
?pass=:passId): La resolución pública evalúa la disponibilidad específica del pase (P1), los valores predeterminados de la página de descarga (P2) y el respaldo del espacio de trabajo (P3), mientraspass bundle(bundleId) coordina las descargas.pkpassesentre tarjetas vinculadas. -
Superposiciones opcionales PassTour: Guíe a los nuevos usuarios de Apple y Google Wallet con instrucciones visuales interactivas (Guía PassTour).
Ejemplo: payloads de entrega secundaria y recuperación
Cuando un cliente visualiza un pase en un ordenador de escritorio o pierde el acceso a su pase del monedero, la página PassFlow invoca los endpoints públicos de acción:
POST /d/vip-gold-2026/send-link-by-email
{
"email": "alex.rivera@example.com",
"passLink": "https://app.passinstance.com/d/vip-gold-2026?pass=pass_01j8k9m2"
}
POST /d/vip-gold-2026/request-recovery
{
"emailOrPhone": "alex.rivera@example.com"
}
Consulte la documentación relacionada sobre Distribución en autoservicio, Entrega por correo electrónico y SMS y Buscar o recuperar su pase.
