Skip to content
Guía del Centro de ayuda · Proyectos y organización
4 min de lecturaVerificado 2026-11-16

Gestionar proyectos

Agrupa una plantilla principal con plantillas vinculadas en Wallet Experiences, paquetes y cambios de segmento.

En esta guía

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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
AGRUPACIÓN EN PROYECTOS (.PKPASSES) Y SEGMENTOS
ETAPA 01 PROYECTO DE PASES (PassProject y PassProjectTemplate)
PRIMARY (mainTemplateId): Tarjeta principal de socio, entrada o embarque
LINKED / VIP / CUSTOM: Vales de sala VIP, aparcamiento o evento gala
PRIVACY_MODE / INACTIVE: Diseño reducido de privacidad o tarjeta pausada
ETAPA 02A PAQUETE APPLE PASS (ZIP .pkpasses)
Agrupa hasta 10 archivos .pkpass firmados con igual Pass.bundleId
bundle grouping mode: AUTO | `MANUA
BundleStatus: ACTIVE | CANCELLED
ETAPA 02B ORQUESTADOR DE SEGMENTOS Y FLUJOS
Evalúa reglas PassProjectSegment sobre Pass.attributes (GIN) | | - Lanza accionesAutomationF emitir pase vinculado / cambiar

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):

PassProjectTemplateRoleDónde se almacenaResponsabilidad funcional en el proyecto
PRIMARYPassProject.mainTemplateIdEl 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 / CUSTOMPassProjectTemplate.rolePlantillas 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_MODEPassProjectTemplate.roleUna plantilla alternativa simplificada a la que se migra automáticamente cuando un titular rechaza el seguimiento o la personalización.
INACTIVEPassProjectTemplate.rolePlantilla 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 por Pass Grouping Engine (libs/pass-bundle, /api/v1/bundles/* o POST /api/v1/pass-projects/:id/download-bundle). Empaqueta hasta 10 archivos .pkpass firmados (request payload: 2–10 pases; request payload: 1–10 pases) servidos con tipo application/vnd.apple.pkpasses para 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 .pkpass dentro 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. 1
    Evaluación dinámica de segmentos: Defina reglas de filtrado sobre Pass.attributes (por ejemplo, attributes.spendTotal >= 500) y evalúelas mediante POST /api/v1/pass-projects/:id/segments/:segmentId/evaluate.
  2. 2
    Emisión automatizada de pases complementarios: Cuando un pase principal entra en un segmento, un AutomationFlow asociado emite automáticamente un pase vinculado (LINKED / VIP) y comparte su enlace actualizado de paquete o descarga.
  3. 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 endpointDescripción
GET /api/v1/pass-projectsLista todos los Wallet Experiences (Pass Projects) en el espacio de trabajo activo.
POST /api/v1/pass-projectsCrea un nuevo PassProject con request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug).
GET /api/v1/pass-projects/:idRecupera la configuración del proyecto, plantillas vinculadas, preparación y segmentos.
PATCH /api/v1/pass-projects/:idActualiza el nombre del proyecto, descripción, mainTemplateId, bundleOnDownload, maxBundleSize o slug.
POST /api/v1/pass-projects/:id/templates/:templateIdVincula una plantilla complementaria (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE).
GET / PATCH /api/v1/pass-projects/:id/bundleConfigura el orden del paquete, límites (maxBundleSize) y metadatos de .pkpasses.
POST /api/v1/pass-projects/:id/download-bundleDescarga o genera el archivo .pkpasses coordinado para un pase o emisión.
GET /api/v1/pass-projects/bundle-passes/:passIdLista 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

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)

JSON
{
  "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.

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.