Skip to content
Guía del Centro de ayuda · Plantillas de pases
4 min de lecturaVerificado 2026-11-16

Exportar e importar como JSON

Haga copias de seguridad, restaure y transfiera plantillas de pases entre espacios de trabajo utilizando esquemas JSON sanitizados y directrices de seguridad.

En esta guía

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 sandbox hacia un espacio de trabajo production sin 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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
CANALIZACIÓN DE EXPORTACIÓN E IMPORTACIÓN DE PLANTILLAS
ETAPA 01 ESPACIO DE TRABAJO DE ORIGEN (Sandbox / Pruebas)
Plantilla con campos, propiedades personalizadas, colores, códigos y relevancia
ETAPA 02 MOTOR DE SANEAMIENTO DE EXPORTACIÓN (Template Export Engine)
buildSanitizedTemplateExportPayload
1
Inyecta sobre: format: 'passinstance-template', version: 1
2
Elimina límites de inquilino: customerId, tenantId, id, certificateId
3
Elimina credenciales de Apple: teamIdentifier, passTypeIdentifier
4
Codifica referencias de activos retina o URL portables en CDN
ETAPA 03 ARTEFACTO JSON PORTABLE (template-export.json)
Esquema JSON limpio y legible por humanos
Independiente de IDs de fila de base de datos o secretos de inquilino
ETAPA 04 MOTOR DE VALIDACIÓN Y SEGURIDAD DE IMPORTACIÓN
normalizeTemplateImport
1
Límite de tamaño: aplica maximum upload size limit = 5 * 1024 * 1024 (5 MB)
2
Protección Prototype Pollution: elimina __proto__, constructor, prototype
3
Concilia propiedades personalizadas y crea índices GIN en la base de destino
4
Asigna el certificado del espacio de trabajo destino y vincula el inquilino
ETAPA 05 ESPACIO DE TRABAJO DE DESTINO (Producción / Activo)
Nueva Template creada con status: PUBLISHED (o revisión DRAFT editada)
Lista para emisión en vivo, registro PassFlow y campañas CSV por lotes

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:

JSON
{
  "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. 1
    Abra la plantilla en el editor visual.
  2. 2
    Haga clic en el menú Más acciones (...) en la barra superior CommandBar.
  3. 3
    Seleccione Exportar como JSON.
  4. 4
    El navegador descarga de inmediato <template-slug>-export.json.

Mediante API REST

GET /api/v1/templates/:templateId/export?format=json
Cabeceras
X-API-Key <API_KEY>
BASH
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:

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

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

BASH
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 / ErrorCausa raízSolución
Unrecognized format identifierEl 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 limitHay 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 assignedLa 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.

¿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.