Descripción general
A medida que su organización crece con campañas estacionales, sucursales regionales y entornos de pruebas frente a producción, Passinstance ofrece herramientas de organización del espacio de trabajo en múltiples niveles: categorización y etiquetado de plantillas, clonación de plantillas (Template Duplication Wizard), filtrado de ciclo de vida por rowKind (DRAFT, PUBLISHED, PRODUCTION, ARCHIVED), aplicación compuesta de unicidad de ID externo, búsqueda de atributos indexada con GIN en base de datos (attribute search index) y asignación de plantillas entre proyectos.
Arquitectura del sistema: taxonomía del espacio de trabajo, clonación y vistas guardadas
1. Copiar una plantilla: duplicar una plantilla existente (clonación y duplicación)
En lugar de reconfigurar colores, diseños de campos, códigos de barras y esquemas de propiedades personalizadas desde cero para cada nuevo programa de tarjetas, puede duplicar cualquier plantilla existente en cuestión de segundos.
Cómo clonar desde el panel de control
Los operadores pueden iniciar la clonación de una plantilla desde dos ubicaciones:
-
1
Desde el directorio de Plantillas: En cualquier tarjeta de plantilla, haga clic en el menú de tres puntos (...) y seleccione Duplicar.
-
2
Desde el editor visual: En la barra superior CommandBar, haga clic en Acciones -> Duplicar plantilla.
Flujo de 4 pasos de Template Duplication Wizard
Template Duplication Wizard guía a los operadores en la duplicación de una plantilla:
-
1
Paso 1: Seleccionar plantilla de origen: Confirma la plantilla original e inspecciona su tipo de pase, número de campos e imágenes asociadas.
-
2
Paso 2: Nombre y descripción: Precompleta el nombre de la nueva plantilla como
${sourceTemplate.name} (Copy)y permite introducir una descripción diferente. -
3
Paso 3: Personalización:
- Página de registro PassFlow vinculada: Elija si desea clonar el formulario público de registro asociado mediante duplicatePassFlow (creando una página PassFlow independiente /f/:newUrl) o dejar la nueva plantilla sin formulario vinculado. - Colores de marca: Modifique backgroundColor, foregroundColor y labelColor. El asistente ejecuta una validación de contraste WCAG AA en tiempo real para garantizar la legibilidad. - Activos visuales: Decida si conservar las imágenes de la plantilla original (icon, logo, strip, thumbnail) o cargar nuevos activos de marca.
-
4
Paso 4: Asignación de certificado: Seleccione un certificado de firma Apple Pass Type ID ya registrado en la configuración del espacio de trabajo o cargue un nuevo certificado
.p12/.cer.
2. Aislamiento del espacio de trabajo e higiene en la nomenclatura de plantillas
Passinstance aísla plantillas, pases, certificados y claves API en el límite del espacio de trabajo Customer dentro de su Organization principal (POST /api/v1/organizations/current/workspaces):
-
1
Separe los entornos por espacio de trabajo: Mantenga los borradores experimentales y las pruebas de integración en un espacio de trabajo
sandbox, reservando su espacio de trabajoproductionexclusivamente para programas activos de clientes. -
2
Estandarice nombres y etiquetas de plantillas: Incluya el dominio del programa, la región y la versión en los títulos de las plantillas (por ejemplo,
Loyalty-CoffeeClub-EU-v2) y añadatagsestructuradas (como["retail", "q4-2026", "dach"]) para filtrar el catálogo al instante. -
3
Archive plantillas obsoletas (
rowKind: ARCHIVED): En lugar de eliminar plantillas promocionales históricas que aún tienen registros de pases emitidos, cámbielas a estado Archivada. Las plantillas archivadas se ocultan de los selectores activos predeterminados mientras conservan las analíticas históricas y los registros de escaneo bajo el filtro Todas / Archivadas.
3. Unicidad de ID externo, identificadores personalizados y agrupación en paquetes
Para evitar la emisión de pases duplicados a través de formularios web, terminales TPV y webhooks de CRM, configure las políticas de identificadores y agrupación en la configuración de la plantilla:
| Ajuste / Propiedad del modelo | Aplicación en base de datos y API | |
|---|---|---|
externalId (Pass.externalId) | Cadena proporcionada por el cliente (máx. 255 caracteres) indexada de forma única por pase activo no eliminado del inquilino (@@unique([customerId, externalId]) WHERE archivedAt IS NULL). Las llamadas duplicadas a POST /api/v1/passes se rechazan, mientras que POST /api/v1/passes/upsert-by-external-id actualiza el registro existente. | |
Reglas de identificadores personalizados (Template) | Configure customIdentifiersEnabled, externalIdentifierPattern y customIdentifierValidationPattern en la configuración de la plantilla para exigir formatos regex corporativos en los identificadores externos generados o importados. | |
Agrupación multitarjeta (Pass.bundleId) | Clave foránea bundleId que vincula hasta 10 pases dentro de un único pass bundle (bundle grouping mode: AUTO \ | MANUAL) para entrega .pkpasses. |
Vinculación a un único dispositivo (limitToOneActivePerPass) | Restringe los enlaces inteligentes de descarga para que un pase no pueda compartirse ni instalarse simultáneamente en dispositivos no autorizados. |
Importante: Se recomienda encarecidamente activar la unicidad de
externalIdpara plantillas de fidelización, membresía y tarjetas regalo prepago. El borrado lógico de un pase de prueba (SOFTdelete) establecearchivedAty libera inmediatamente eseexternalIdpara su reutilización.
4. Indexación de atributos JSON estructurados (attribute search index) y vistas guardadas
Cada propiedad personalizada almacenada dentro de Pass.attributes se indexa automáticamente mediante el índice invertido generalizado de la base de datos (attribute search index). Esto permite a los operadores y consumidores de la API organizar y consultar millones de pases sin migraciones de esquema:
-
Vistas guardadas para operadores: En el directorio Pases (
/passes), combine predicados de filtro AND/OR sobrestatus(estado del pase),lifecycleStatus,walletVoidStatus(WalletPropagationStatus),bundleId,externalId, plataforma del dispositivo (APPLE_WALLETfrente aGOOGLE_WALLET) y claves JSON estructuradas personalizadas (attributes.tier,attributes.storeId), y guarde la consulta como una Vista guardada. -
Asignación de plantillas entre proyectos: Agrupe plantillas relacionadas dentro de Wallet Experiences (
PassProject) en lugar de clonar plantillas independientes. Una sola plantilla puede actuar como plantillaLINKED,VIP,CUSTOMoPRIVACY_MODEen distintos contenedoresPassProject(PassProjectTemplateRole), manteniendo centralizada la gobernanza de activos y mecánicas.
Referencia de la API: duplicación y filtrado de plantillas
1. Duplicar una plantilla mediante API (POST /api/v1/templates/:id/duplicate)
Clona una plantilla existente copiando sus campos de diseño, colores, códigos de barras y definiciones de propiedades personalizadas:
POST /api/v1/templates/tmpl_01hxyz987654321/duplicate Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json
{
"name": "Artisan Coffee Club - Platinum Tier (Copy)",
"duplicatePassFlow": true,
"certificateId": "cert_01j7k8m9n2p3"
}
Respuesta HTTP (201 Created)
{
"success": true,
"data": {
"id": "tmpl_new_clone_01h987",
"name": "Artisan Coffee Club - Platinum Tier (Copy)",
"kind": "storeCard",
"status": "PUBLISHED",
"versionNumber": 1,
"rowKind": "PRODUCTION",
"createdAt": "2026-11-16T21:20:00.000Z"
},
"statusCode": 201
}
2. Filtrar plantillas por estado, tipo y etiquetas
/api/v1/templates?rowKind=PRODUCTION&kind=storeCard&tag=retail&search=Coffee&page=1&limit=20
{
"success": true,
"data": {
"items": [
{
"id": "tmpl_01hxyz987654321",
"groupId": "grp_01hxyz987654321",
"name": "Loyalty-CoffeeClub-EU-v2",
"kind": "storeCard",
"rowKind": "PRODUCTION",
"status": "PUBLISHED",
"versionNumber": 2,
"tags": ["retail", "q4-2026", "dach"],
"activePassesCount": 14820
}
],
"total": 1,
"page": 1,
"limit": 20
},
"statusCode": 200
}
Explore Gestionar proyectos para combinar pases de varias plantillas, o lea Comprender su espacio de trabajo para conocer las reglas de tenencia multi-espacio de trabajo.
