Skip to content
Guia da Central de Ajuda · Modelos de passes
4 min de leituraVerificado 2026-11-16

Exportar e importar como JSON

Faça backup, restaure e transfira modelos de passes entre espaços de trabalho usando esquemas JSON higienizados e proteções de segurança.

Neste guia

Visão geral

A Passinstance suporta a exportação e importação de definições completas de modelos como ficheiros JSON estruturados e portáteis. Esta capacidade permite:

  • Migração entre Ambientes: Promover modelos de passes testados de um espaço de trabalho sandbox para um espaço de trabalho production sem recriação manual.
  • Cópia de Segurança e Recuperação de Desastres: Armazenar configurações canónicas de modelos em repositórios Git ou sistemas de controlo de versões (Configuração como Código).
  • Partilha e Clonagem de Modelos: Distribuir layouts padronizados de fidelização, bilhetes ou cartões de sócio por contas de clientes distintas ou operadores de franchising.

Os ficheiros exportados utilizam a especificação canónica de exportação da Passinstance (TEMPLATE_EXPORT_FORMAT = 'passinstance-template', versão de esquema 1) implementada em template-import-export.util.ts. Identificadores de sistema, chaves primárias de base de dados, IDs de tenant e certificados criptográficos de assinatura são removidos automaticamente para garantir segurança multi-tenant e impedir colisões de identidade.

Arquitetura do sistema: Fluxo de exportação e importação de modelos

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
PIPELINE DE EXPORTAÇÃO E IMPORTAÇÃO DE MODELOS
ETAPA 01 ESPAÇO DE TRABALHO DE ORIGEM (Sandbox / Testes)
Modelo com campos, propriedades personalizadas, cores, barras e relevância
ETAPA 02 MOTOR DE HIGIENIZAÇÃO DE EXPORTAÇÃO (Template Export Engine)
buildSanitizedTemplateExportPayload
1
Injeta envelope: format: 'passinstance-template', version: 1
2
Remove limites de tenant: customerId, tenantId, id, certificateId
3
Remove credenciais Apple: teamIdentifier, passTypeIdentifier
4
Codifica referências de ativos retina ou URLs CDN portáteis
ETAPA 03 ARTEFACTO JSON PORTÁTIL (template-export.json)
Esquema JSON limpo e legível
Independente de IDs de linhas na BD ou segredos do tenant
ETAPA 04 MOTOR DE VALIDAÇÃO E SEGURANÇA NA IMPORTAÇÃO
normalizeTemplateImport
1
Guarda de Tamanho: Impõe maximum upload size limit = 5 * 1024 * 1024 (5 MB)
2
Guarda Prototype Pollution: Remove __proto__, constructor, prototype
3
Reconcilia Propriedades Personalizadas e cria índices GIN na BD de destino
4
Atribui certificado do espaço de trabalho de destino e liga ao tenant local
ETAPA 05 ESPAÇO DE TRABALHO DE DESTINO (Produção / Ativo)
Novo Template criado com status: PUBLISHED (ou revisão DRAFT atualizada)
Pronto para emissão real, inscrição PassFlow e campanhas CSV em lote

Especificação do formato de exportação de modelos da Passinstance

O gerador de exportação (buildSanitizedTemplateExportPayload) produz um envelope JSON padronizado em conformidade com 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 segurança e higienização

Para manter um isolamento de tenant rigoroso e proteger os ativos criptográficos, a Passinstance impõe cinco invariantes centrais de segurança durante a exportação e a importação (template-import-export.util.ts:25-34):

1. Remoção de chaves de sistema

As seguintes chaves são estritamente removidas dos payloads de exportação e rejeitadas durante a importação:

  • Chaves primárias e estrangeiras: id, customerId, tenantId, baseId, groupId.
  • Metadados de revisão: versionNumber, version, rowKind, status.
  • Registos de titulares de passes: passes, activePassesCount.
  • Carimbos temporais: createdAt, updatedAt, archivedAt.
  • Identidade Apple Developer: teamIdentifier, passTypeIdentifier, certificateId.

2. Limites de tamanho do payload

  • maximum upload size limit = 5 * 1024 * 1024 (5 MB): Payloads que excedam 5 megabytes são rejeitados imediatamente com HTTP 413.
  • MAX_ZIP_ENTRY_BYTES = 1 * 1024 * 1024 (1 MB): Para pacotes comprimidos em zip, as entradas individuais não podem exceder 1 MB.
  • MAX_ZIP_ENTRIES = 250: Previne ataques de descompressão zip bomb.
  • MAX_PLIST_DEPTH = 32: Previne expansão recursiva de entidades.

3. Prevenção de Prototype Pollution

Qualquer objeto JSON recebido que contenha __proto__, constructor ou prototype é sinalizado e higienizado antes da construção do objeto.

Exportar um modelo (Painel e API REST)

No Painel

  1. 1
    Abra o modelo no Editor Visual.
  2. 2
    Clique no menu Mais ações (...) na barra de comandos superior.
  3. 3
    Selecione Exportar como JSON.
  4. 4
    O navegador transfere imediatamente <template-slug>-export.json.

Via API REST

GET /api/v1/templates/:templateId/export?format=json
Cabeçalhos
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 um modelo (Painel e API REST)

1. Importar como novo modelo (POST /api/v1/templates/import)

Cria um modelo completamente novo no espaço de trabalho 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

Resposta 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 para um rascunho existente (POST /api/v1/templates/:id/import-draft)

Atualiza a revisão de trabalho DRAFT de um modelo existente sem modificar os passes publicados em produção:

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

Resolução de problemas de exportação e importação

Sintoma / ErroCausa raizResolução
Unrecognized format identifierO JSON não inclui "format": "passinstance-template" ou utiliza um formato desconhecido.Certifique-se de que a raiz do JSON inclui "format": "passinstance-template" e "version": 1.
Payload exceeds 5MB limitImagens grandes ou ativos binários estão incorporados dentro do JSON.Remova os dados base64 em bruto e carregue as imagens através do endpoint de gestão de ativos ou da interface do Painel.
Certificate not assignedO modelo exportado não transporta certificados de assinatura.Este comportamento é intencional. Após a importação, aceda a Definições do Modelo e associe as credenciais Apple Wallet e Google Wallet do espaço de trabalho de destino.

Em seguida, explore Organizar modelos e passes para gerir catálogos de modelos, ou leia Versões e publicação de modelos para promover rascunhos importados para produção.

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.