Skip to content
Guía del Centro de ayuda · Introducción a PassinstanceFase de incorporación 1
5 min de lecturaVerificado 2026-11-16

Cómo funciona Passinstance

Recorre la arquitectura completa desde el diseño de plantillas y firma digital hasta el escaneo, avisos y analítica.

En esta guía

Recorridos visuales interactivos

Abrir en la guía de 6 fases

Inspecciona las pantallas reales del panel y las anotaciones ampliadas de esta guía.

Enfoque de interfaz ampliado
Elementos clave de la interfaz

Panel Principal — KPIs y Tendencias en vivo (Ampliado)

Ya en marcha, monitoriza Active in Wallets, Removed, Not Installed y curvas de creación y registro.

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:

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
CICLO DE VIDA COMPLETO DEL PASE
ACTORES DEL SISTEMA
P1 Cliente Admin / API
P2 API Central Passinstance
P3 Nube Apple / Google
P4 Dispositivo cliente
PASO 1 SOLICITUD / ACCIÓN POST/api/v1/templates
›
(Definir diseño y mecánicas)
PASO 2 SOLICITUD / ACCIÓN POST/api/v1/passes
PASO 3 SOLICITUD / ACCIÓN Firmar .pkpass(PKCS#7)
PASO 4 SOLICITUD / ACCIÓN Generar JWT Google
›
Devuelve URL de descarga
›
(https://app.passinstance.com/d/:slug o /p/:passId)
PASO 5 SOLICITUD / ACCIÓN El cliente abre el enlace de descarga inteligente
›
(El navegador detecta OS)
PASO 6 RESPUESTA El dispositivo se registra (POST/v1/devices)
›
(pushToken de Apple guardado en Passinstance database)
PASO 7 SOLICITUD / ACCIÓN Escaneo en mostrador POS (POST/api/v1/scans)
›
(Cabecera: x-scanner-key, Cuerpo: { scannedBarcodeValue })
PASO 8 SOLICITUD / ACCIÓN Ejecutar mecánica
›
(Sumar sellos o puntos)
PASO 9 SOLICITUD / ACCIÓN Enviar push silencioso
›
(Payload vacío APNs)
PASO 10 SOLICITUD / ACCIÓN Despertar APNs
PASO 11 RESPUESTA Obtener pase actualizado (GET/v1/passes)
PASO 12 SOLICITUD / ACCIÓN Entregar nuevo .pkpass
›
(Alerta nativa en pantalla
›
"Saldo actualizado: %@")

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 Packager empaqueta pass.json, hasta 13 ranuras de imagen (image asset slot, incluidas las variantes retina @2x y @3x) y archivos localizados pass.strings en un archivo comprimido .pkpass, calcula los hashes de manifest.json y 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 mismo bundleId (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 con RS256 (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/:serialNumber con la cabecera Authorization: ApplePass <authenticationToken>.
  • Passinstance valida el token y guarda el pushToken del dispositivo en la base de datos, pasando el estado del pase de AWAITING_OPT_IN a ACTIVE.

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/scans autenticada mediante x-scanner-key.
  • Pass Mechanics Engine evalú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 .pkpass actualizado.
  • Cualquier campo configurado con un changeMessage que 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 PATCH al endpoint walletobjects de Google Wallet para actualizar la tarjeta en Android en tiempo real.
Tendencias y KPI de resumen del panel
Tendencias y KPI de resumen del panel

Endpoints principales y verbos de la API

Ruta del endpointMétodo HTTPAutenticaciónFuncionalidad
/api/v1/templatesPOSTBearer / Clave de APICrear una nueva definición de plantilla de pase
/api/v1/templates/:id/publishPOSTBearer / Clave de APIPromover una plantilla en borrador a la versión de producción activa
/api/v1/passesPOSTBearer / Clave de APIEmitir un nuevo pase con valores de campos personalizados
/api/v1/passes/:idPATCHBearer / Clave de APIActualizar atributos de un pase existente y encolar un push
/api/v1/scansPOSTx-scanner-keyValidar el código de barras del pase, aplicar la mecánica y registrar el escaneo
/v1/devices/...POSTApplePass <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 .pkpass desde los servidores de Passinstance.

Explore la guía interactiva de incorporación en 6 fases o consulte nuestra Arquitectura de API.

Documentación de producto y API relacionada

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.