Descripción general
Passinstance automatiza todo el ciclo de vida de los pases digitales en diseño, empaquetado criptográfico, distribución multicanal, validación en punto de venta y sincronización push silenciosa. Al separar la configuración visual del diseño de la lógica de negocio de las mecánicas y los protocolos de comunicación con los dispositivos, la plataforma ofrece una experiencia uniforme tanto en iOS como en Android.
Secuencia técnica completa de principio a fin
El siguiente diagrama de secuencia detalla el flujo completo desde la creación de la plantilla hasta la sincronización en tiempo real con el monedero:
Ciclo de vida técnico paso a paso
1. Diseño y versionado de plantillas
Cada pase se origina a partir de un registro Template. Passinstance utiliza un versionado en una sola tabla controlado mediante TemplateRowKind (PRODUCTION, PUBLISHED, ARCHIVED, DRAFT) y template status (DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED). Las ediciones en borrador permanecen aisladas en una revisión DRAFT hasta que un operador o una llamada a la API ejecuta POST /api/v1/templates/:id/publish, lo que promueve el borrador a la fila base canónica PRODUCTION y conserva instantáneas históricas inmutables PUBLISHED / ARCHIVED. Antes de publicar, la plataforma evalúa GET /api/v1/templates/:id/publish-risk-check para inspeccionar cambios en campos críticos y calcular cuántos pases activos se actualizarán.
2. Firma criptográfica, estado de artefactos y emisión del pase
Cuando se genera un registro de pase (POST /api/v1/passes), la creación resuelve templateId mediante resolvePassCreationTemplateId hacia la fila base activa, vincula un externalId opcional único por inquilino, respeta la cabecera opcional Idempotency-Key (idempotencyKey) e inicializa appleArtifactStatus y googleArtifactStatus (ArtifactStatus: NOT_GENERATED -> GENERATING -> READY \| FAILED \| INVALIDATED):
-
Apple Wallet: En la descarga,
Apple Wallet Packagerempaquetapass.json, hasta 13 ranuras de imagen (image asset slot, incluidas las variantes retina@2xy@3x) y archivos localizadospass.stringsen un archivo comprimido.pkpass, calcula los hashes demanifest.jsony firma el manifiesto mediante cifrado PKCS#7 independiente con su Apple Pass Type ID y los certificados Apple WWDR. Múltiples pases complementarios que comparten un mismobundleId(Pass.bundleId) pueden entregarse juntos como un archivo.pkpasses. -
Google Wallet: El backend sincroniza las definiciones de clase (
LoyaltyClass,EventTicketClass,GenericClass, etc.) con las API REST de Google Wallet y firma una URL Save JWT conRS256(https://pay.google.com/gp/v/save/:jwt).
3. Distribución mediante enlaces inteligentes
Passinstance genera URL canónicas inteligentes de presentación (https://app.passinstance.com/d/:slug, https://app.passinstance.com/p/:passId o /s/:token en hosts de API o dominios personalizados). Cuando un usuario final accede:
-
El endpoint público de descarga (
GET /d/:slug/download) detecta el agente de usuario:
- Safari en iOS recibe una respuesta HTTP con el tipo MIME application/vnd.apple.pkpass, abriendo la hoja nativa para añadir a Apple Wallet. - Chrome en Android redirige a https://pay.google.com/gp/v/save/:jwt, iniciando Google Wallet. - Los navegadores de escritorio muestran la página PassFlow de descarga con un código QR de alto contraste (GET /d/:slug/qr) y envío automático opcional por correo electrónico o SMS.
4. Registro del dispositivo y protocolo del servicio web
Al guardarse en Apple Wallet, el dispositivo iOS inicia el protocolo oficial Apple Wallet Web Service:
-
Envía
POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumbercon la cabeceraAuthorization: ApplePass <authenticationToken>. -
Passinstance valida el token y guarda el
pushTokendel dispositivo en la base de datos, pasando el estado del pase deAWAITING_OPT_INaACTIVE.
5. Validación en punto de venta y ejecución de mecánicas
En la caja física o en el control de acceso del recinto, un operador escanea el pase mediante la aplicación Passinstance Scanner o un sistema POS integrado:
-
Se envía una solicitud a
POST /api/v1/scansautenticada mediantex-scanner-key. -
Pass Mechanics Engineevalúa las reglas activas (por ejemplo, añadir sellos, descontar saldo prepago, validar cupones de un solo uso o verificar la asistencia una vez al día).
6. Sincronización push silenciosa en la nube
Cuando cambian los datos de un pase:
-
Passinstance envía un payload JSON vacío
{}por HTTP/2 a los servidores APNs de Apple. -
El dispositivo Apple se despierta silenciosamente en segundo plano, consulta
GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>y descarga el paquete.pkpassactualizado. -
Cualquier campo configurado con un
changeMessageque incluya el marcador%@genera una notificación nativa en la pantalla de bloqueo de iOS. -
De forma simultánea, Passinstance envía una solicitud REST
PATCHal endpointwalletobjectsde Google Wallet para actualizar la tarjeta en Android en tiempo real.

Endpoints principales y verbos de la API
| Ruta del endpoint | Método HTTP | Autenticación | Funcionalidad |
|---|---|---|---|
/api/v1/templates | POST | Bearer / Clave de API | Crear una nueva definición de plantilla de pase |
/api/v1/templates/:id/publish | POST | Bearer / Clave de API | Promover una plantilla en borrador a la versión de producción activa |
/api/v1/passes | POST | Bearer / Clave de API | Emitir un nuevo pase con valores de campos personalizados |
/api/v1/passes/:id | PATCH | Bearer / Clave de API | Actualizar atributos de un pase existente y encolar un push |
/api/v1/scans | POST | x-scanner-key | Validar el código de barras del pase, aplicar la mecánica y registrar el escaneo |
/v1/devices/... | POST | ApplePass <token> | Callback de registro de dispositivo de Apple Wallet |
Importante: Las actualizaciones de Apple Wallet funcionan bajo un modelo pull (extracción): Passinstance no envía los datos del pase dentro de la notificación APNs. En su lugar, una señal vacía de activación de APNs indica al dispositivo Apple que descargue de forma segura la última versión firmada del
.pkpassdesde los servidores de Passinstance.
Explore la guía interactiva de incorporación en 6 fases o consulte nuestra Arquitectura de API.
