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
sandboxpara um espaço de trabalhoproductionsem 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
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:
{
"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
Abra o modelo no Editor Visual.
-
2
Clique no menu Mais ações (...) na barra de comandos superior.
-
3
Selecione Exportar como JSON.
-
4
O navegador transfere imediatamente
<template-slug>-export.json.
Via 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 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:
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)
{
"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:
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 / Erro | Causa raiz | Resolução |
|---|---|---|
Unrecognized format identifier | O 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 limit | Imagens 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 assigned | O 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.
