Descripción general
Passinstance permite exportar e importar definiciones completas de plantillas como archivos JSON estructurados y portables. Esta capacidad facilita:
-
Migración entre entornos: Promocionar plantillas de pases validadas desde un espacio de trabajo
sandboxhacia un espacio de trabajoproductionsin recrearlas manualmente. -
Copia de seguridad y recuperación ante desastres: Almacenar configuraciones canónicas de plantillas en repositorios Git o sistemas de control de versiones (Configuración como código).
-
Compartición y clonación de plantillas: Distribuir diseños estandarizados de fidelización, entradas o membresía entre distintas cuentas de clientes o franquiciados.
Los archivos exportados siguen la especificación canónica de exportación de Passinstance (TEMPLATE_EXPORT_FORMAT = 'passinstance-template', versión de esquema 1) implementada en template-import-export.util.ts. Los identificadores del sistema, las claves primarias de base de datos, los ID de inquilino y los certificados criptográficos de firma se eliminan automáticamente para garantizar la seguridad multiinquilino y evitar colisiones de identidad.
Arquitectura del sistema: flujo de exportación e importación de plantillas
Especificación del formato de exportación de plantillas de Passinstance
El generador de exportación (buildSanitizedTemplateExportPayload) produce un sobre JSON estandarizado conforme a TEMPLATE_EXPORT_SCHEMA_VERSION = 1:
{
"format": "passinstance-template",
"version": 1,
"exportedAt": "2026-11-16T20:40:00.000Z",
"template": {
"name": "Artisan Coffee Club - Gold Tier",
"kind": "storeCard",
"organizationName": "Artisan Roasters",
"description": "Artisan Coffee Loyalty Card",
"colors": {
"backgroundColor": "rgb(20, 35, 28)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(167, 243, 208)",
"stripColor": "rgb(255, 255, 255)"
},
"barcode": {
"format": "PKBarcodeFormatQR",
"messageEncoding": "UTF_8",
"altText": "{cardNumber}",
"addSecurityAnimation": true
},
"fields": {
"headerFields": [
{
"key": "tier",
"label": "TIER",
"value": "Gold Member",
"textAlignment": "PKTextAlignmentRight"
}
],
"primaryFields": [
{
"key": "holder",
"label": "MEMBER",
"value": "{firstName} {lastName}"
}
],
"secondaryFields": [
{
"key": "balance",
"label": "POINTS BALANCE",
"value": "{pointsBalance}",
"numberStyle": "PKNumberStyleDecimal"
}
],
"auxiliaryFields": [
{
"key": "since",
"label": "MEMBER SINCE",
"value": "{memberSince}",
"dateStyle": "PKDateStyleMedium"
}
],
"backFields": [
{
"key": "terms",
"label": "TERMS & CONDITIONS",
"value": "Points are earned on every purchase. Terms subject to change."
}
]
},
"locations": [
{
"latitude": 52.520008,
"longitude": 13.404954,
"maxDistance": 150,
"relevantText": "Welcome to Artisan Roasters! Scan your card for points."
}
],
"sharing": {
"sharingProhibited": false
}
}
}
Invariantes de seguridad y saneamiento
Para mantener un aislamiento estricto de inquilinos y proteger los activos criptográficos, Passinstance aplica cinco invariantes fundamentales de seguridad durante la exportación y la importación (template-import-export.util.ts:25-34):
1. Eliminación de claves del sistema
Las siguientes claves se eliminan estrictamente de las cargas de exportación y se rechazan durante la importación:
-
Claves primarias y foráneas:
id,customerId,tenantId,baseId,groupId. -
Metadatos de revisión:
versionNumber,version,rowKind,status. -
Registros de titulares:
passes,activePassesCount. -
Marcas temporales:
createdAt,updatedAt,archivedAt. -
Identidad de Apple Developer:
teamIdentifier,passTypeIdentifier,certificateId.
2. Límites de tamaño de carga útil
-
maximum upload size limit = 5 * 1024 * 1024(5 MB): Las cargas que superan los 5 megabytes se rechazan de inmediato con HTTP 413. -
MAX_ZIP_ENTRY_BYTES = 1 * 1024 * 1024(1 MB): En paquetes comprimidos, cada archivo individual no puede superar 1 MB. -
MAX_ZIP_ENTRIES = 250: Previene ataques de descompresión tipo zip bomb. -
MAX_PLIST_DEPTH = 32: Previene la expansión recursiva de entidades.
3. Prevención de contaminación de prototipos (Prototype Pollution)
Cualquier objeto JSON entrante que contenga __proto__, constructor o prototype se marca y sanea antes de construir el objeto.
Exportar una plantilla (panel de control y API REST)
En el panel de control
-
1
Abra la plantilla en el editor visual.
-
2
Haga clic en el menú Más acciones (...) en la barra superior CommandBar.
-
3
Seleccione Exportar como JSON.
-
4
El navegador descarga de inmediato
<template-slug>-export.json.
Mediante API REST
/api/v1/templates/:templateId/export?format=json
curl -X GET "https://api.passinstance.com/api/v1/templates/tmpl_01h9x8k7m6n5p4/export?format=json" \
-H "X-API-Key: <API_KEY>" \
-o template-export.json
Importar una plantilla (panel de control y API REST)
1. Importar como una nueva plantilla (POST /api/v1/templates/import)
Crea una plantilla completamente nueva en el espacio de trabajo de destino:
curl -X POST "https://api.passinstance.com/api/v1/templates/import" \
-H "X-API-Key: <API_KEY>" \
-H "Content-Type: application/json" \
-d @template-export.json
Respuesta HTTP (201 Created)
{
"success": true,
"data": {
"id": "tmpl_new_destination_01",
"name": "Artisan Coffee Club - Gold Tier",
"kind": "storeCard",
"status": "PUBLISHED",
"versionNumber": 1,
"rowKind": "PRODUCTION",
"createdAt": "2026-11-16T20:45:00.000Z"
},
"statusCode": 201
}
2. Importar sobre un borrador existente (POST /api/v1/templates/:id/import-draft)
Actualiza la revisión DRAFT de trabajo de una plantilla existente sin modificar los pases publicados en producción:
curl -X POST "https://api.passinstance.com/api/v1/templates/tmpl_existing_01/import-draft" \
-H "X-API-Key: <API_KEY>" \
-H "Content-Type: application/json" \
-d @template-export.json
Resolución de problemas de exportación e importación
| Síntoma / Error | Causa raíz | Solución |
|---|---|---|
Unrecognized format identifier | El JSON no incluye "format": "passinstance-template" o emplea un formato desconocido. | Asegúrese de que la raíz del JSON incluya "format": "passinstance-template" y "version": 1. |
Payload exceeds 5MB limit | Hay imágenes grandes o activos binarios incrustados dentro del JSON. | Elimine los datos base64 sin procesar y cargue las imágenes a través del endpoint de gestión de activos o la interfaz del panel. |
Certificate not assigned | La plantilla exportada no transporta certificados de firma. | Es un comportamiento intencionado. Tras importar, vaya a Configuración de la plantilla y vincule las credenciales de Apple Wallet y Google Wallet del espacio de trabajo destino. |
A continuación, explore Organizar plantillas y pases para gestionar catálogos de plantillas, o lea Versiones y publicación de plantillas para promocionar borradores importados a producción.
