Descripción general
En el panel de Passinstance, los Proyectos multi-pase (modelo PassProject gestionado por Projects API en /api/v1/pass-projects y alias /api/v1/wallet-experiences) aparecen en el centro Wallet Experiences (/wallet-experiences, organizado en las pestañas Overview, Cards, Audience, Automations, Distribution, Analytics y Settings). Un Proyecto coordina una plantilla principal mainTemplateId junto con plantillas complementarias vinculadas dentro de recorridos unificados de cliente, admitiendo paquetes de pases de Apple Wallet (.pkpasses) (Pass.bundleId / pass bundle) y automatización basada en segmentos y reglas.
Arquitectura del sistema: proyectos de pases, paquetes .pkpasses y disparadores de segmentos
Modelos principales y roles de plantilla (PassProjectTemplateRole)
Cada PassProject vincula una mainTemplateId (rol PRIMARY en el propio proyecto) junto con plantillas complementarias vinculadas (PassProjectTemplate, roles escribibles LINKED, PRIVACY_MODE, VIP, CUSTOM, INACTIVE):
PassProjectTemplateRole | Dónde se almacena | Responsabilidad funcional en el proyecto |
|---|---|---|
PRIMARY | PassProject.mainTemplateId | El pase de identidad principal (p. ej., abono de temporada, llave de habitación de hotel o tarjeta de fidelidad) cuyo externalId y atributos de cliente rigen la experiencia. |
LINKED / VIP / CUSTOM | PassProjectTemplate.role | Plantillas complementarias (p. ej., acceso VIP a backstage, vale de bebida, pase de aparcamiento) empaquetadas en la descarga o emitidas dinámicamente mediante reglas de segmento o automatización. |
PRIVACY_MODE | PassProjectTemplate.role | Una plantilla alternativa simplificada a la que se migra automáticamente cuando un titular rechaza el seguimiento o la personalización. |
INACTIVE | PassProjectTemplate.role | Plantilla vinculada excluida temporalmente de nuevas descargas en paquete sin desvincular su historial. |
Paquetes Apple Wallet Pass Bundles (.pkpasses) y Pass.bundleId
Cuando la agrupación está activada (bundleOnDownload: true, maxBundleSize hasta 10), Passinstance vincula los pases complementarios emitidos bajo un Pass.bundleId compartido (bundleId, clave foránea hacia pass bundle):
-
Apple Wallet (Archivo
.pkpasses): Construido porPass Grouping Engine(libs/pass-bundle,/api/v1/bundles/*oPOST /api/v1/pass-projects/:id/download-bundle). Empaqueta hasta 10 archivos.pkpassfirmados (request payload: 2–10 pases;request payload: 1–10 pases) servidos con tipoapplication/vnd.apple.pkpassespara que iOS presente la opción Añadir todo. -
Reclamación multi-pase en Google Wallet: Sirve URL coordinadas de guardado y enlaces de paquete (
GET /api/v1/bundles/:id/google-wallet-link,PassProjectIssuanceProvider:APPLE\|GOOGLE,PassProjectIssuanceStatus:PENDING->VALIDATING->CREATING_PASSES->READY\|PARTIALLY_READY\|FAILED).
Importante: Apple iOS impone un límite máximo de 10 archivos
.pkpassdentro de un único archivo.pkpasses(maxBundleSize <= 10). Toda plantilla incluida en un paquete debe estar publicada con un certificado Apple Pass Type ID válido.
Segmentos de audiencia (PassProjectSegment) y flujos de automatización
Los proyectos se integran directamente con PassProjectSegment y AutomationFlow para orquestar recorridos dinámicos multi-pase sin código puente de webhooks externos:
-
1
Evaluación dinámica de segmentos: Defina reglas de filtrado sobre
Pass.attributes(por ejemplo,attributes.spendTotal >= 500) y evalúelas mediantePOST /api/v1/pass-projects/:id/segments/:segmentId/evaluate. -
2
Emisión automatizada de pases complementarios: Cuando un pase principal entra en un segmento, un
AutomationFlowasociado emite automáticamente un pase vinculado (LINKED/VIP) y comparte su enlace actualizado de paquete o descarga. -
3
Cambio a modo privacidad: Si se desactiva el consentimiento de personalización, la experiencia puede migrar el pase del titular hacia la plantilla
PRIVACY_MODE.
Referencia de la API REST de Pass Projects (Projects API)
Todos los endpoints de proyectos se montan bajo /api/v1/pass-projects (alias /api/v1/wallet-experiences):
| Método HTTP y endpoint | Descripción |
|---|---|
GET /api/v1/pass-projects | Lista todos los Wallet Experiences (Pass Projects) en el espacio de trabajo activo. |
POST /api/v1/pass-projects | Crea un nuevo PassProject con request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug). |
GET /api/v1/pass-projects/:id | Recupera la configuración del proyecto, plantillas vinculadas, preparación y segmentos. |
PATCH /api/v1/pass-projects/:id | Actualiza el nombre del proyecto, descripción, mainTemplateId, bundleOnDownload, maxBundleSize o slug. |
POST /api/v1/pass-projects/:id/templates/:templateId | Vincula una plantilla complementaria (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE). |
GET / PATCH /api/v1/pass-projects/:id/bundle | Configura el orden del paquete, límites (maxBundleSize) y metadatos de .pkpasses. |
POST /api/v1/pass-projects/:id/download-bundle | Descarga o genera el archivo .pkpasses coordinado para un pase o emisión. |
GET /api/v1/pass-projects/bundle-passes/:passId | Lista todos los pases complementarios agrupados con un passId concreto mediante bundleId. |
Ejemplo: crear un proyecto multi-pase (request payload)
POST /api/v1/pass-projects Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json
{
"name": "Alpine Ski Resort - VIP Winter Package",
"description": "Season ski pass with aprés-ski voucher and privacy layout",
"mainTemplateId": "tmpl_ski_season_pass_01",
"bundleOnDownload": true,
"maxBundleSize": 5,
"slug": "alpine-vip-winter-2026"
}
Respuesta HTTP (201 Created)
{
"success": true,
"data": {
"id": "proj_01j9k8l7m6n5p4",
"name": "Alpine Ski Resort - VIP Winter Package",
"slug": "alpine-vip-winter-2026",
"mainTemplateId": "tmpl_ski_season_pass_01",
"bundleOnDownload": true,
"maxBundleSize": 5,
"createdAt": "2026-11-15T19:00:00.000Z"
},
"statusCode": 201
}
Consulte Arquitectura de agrupación de pases para conocer los flujos técnicos de empaquetado y Configuración de flujos de trabajo para reglas de automatización entre proyectos.
