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

Criar um modelo a partir de JSON

Importe e provisione modelos de passes programaticamente usando definições JSON, validação de esquema e regras de normalização.

Neste guia

Visão geral

A Passinstance oferece suporte nativo para criar e configurar modelos de passes programaticamente através de payloads JSON. Em vez de configurar manualmente layouts visuais, codificações de códigos de barras, cores e atributos dinâmicos no Editor Visual, os programadores e integradores de plataformas podem submeter esquemas completos de modelos à API REST (POST /api/v1/templates ou POST /api/v1/templates/import).

O motor de modelos de backend processa o JSON recebido através do pipeline de normalização e validação com normalização automática de esquemas, validando as geometrias dos passes, impondo os invariantes de cor da Apple Wallet e da Google Wallet e registando propriedades personalizadas.

Arquitetura do sistema: Pipeline de ingestão de modelos JSON

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
PIPELINE DE INGESTÃO DE MODELOS JSON
ETAPA 01 CLIENTE EXTERNO / SCRIPT DE AUTOMAÇÃO
Submete documento JSON via POST/api/v1/templates ou POST.../templates/import
Codifica tipos de passe, cores, zonas de campos, barras e regras de relevância
ETAPA 02 PIPELINE DE INGESTÃO E NORMALIZAÇÃO DE MODELOS
normalizeTemplateImport (template-import-export.util.ts)
1
Guarda de Tamanho: Impõe maximum upload size limit = 5 * 1024 * 1024 (5 MB)
2
Higienização de Segurança: Remove chaves de sistema (id, customerId, etc.)
3
Verificação Prototype Pollution: Rejeita __proto__, constructor, prototype
4
Normalização de Cores: Converte strings hex / RGB para rgb(r, g, b) canónico
5
Mapeamento Barras e Trânsito: Traduz enums Apple PassKit para formatos padrão
ETAPA 03 RECONCILIADOR DE BASE DE DADOS (Template Engine)
Persiste entidade Template com status: PUBLISHED
Cria entidades relacionais: Field[], Color, Barcode, Location[]
Inicializa índice de pesquisa rápida na BD em Pass.attributes
ETAPA 04A COMPILAÇÃO APPLE WALLET
Gera o dicionário base pass.json e empacota ícones/imagens base
ETAPA 04B CRIAÇÃO DE CLASSE GOOGLE WALLET
Cria a Google Wallet Class via SDK (ex., LoyaltyClass, EventClass)

Especificação do esquema JSON para request payload

Uma definição JSON válida de modelo deve respeitar a estrutura request payload aceite por POST /api/v1/templates:

Propriedade de topoTipoObrigatórioDescrição
namestringSimNome legível do modelo (por exemplo, "Artisan Coffee Club"). Máx. 255 carateres.
kindPassKindSimGeometria do tipo de passe: storeCard, coupon, eventTicket, boardingPass, generic ou posterGeneric.
organizationNamestringSimNome da organização apresentado nos passes Apple Wallet e Google Wallet.
descriptionstringSimDescrição acessível do passe exigida pelo Apple PassKit.
statusestado do modeloNãoEstado inicial. Predefinido para PUBLISHED aquando da criação programática.
colorsrequest payloadNãoObjeto contendo backgroundColor, foregroundColor, labelColor e stripColor.
barcoderequest payloadNãoConfiguração do código de barras (format, messageEncoding, altText, addSecurityAnimation).
fieldsrequest payloadNãoColeções de campos agrupadas por zona (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields).
locationsrequest payload[]NãoArray de até 10 coordenadas GPS que acionam notificações no ecrã bloqueado.
beaconsrequest payload[]NãoArray de até 10 iBeacons Bluetooth para deteção de proximidade em interiores.
expirationrequest payloadNãoEstratégia de validade e expiração do passe (none, fixed ou duration).

O subobjeto colors

A Apple Wallet impõe estritamente o formato CSS RGB (rgb(r, g, b)) para cores e rejeita valores hexadecimais ou canais alfa. Ao importar JSON através da Passinstance, o normalizador aceita sintaxe hexadecimal ou RGB e serializa o formato exato exigido por cada fornecedor de carteira:

JSON
{
  "backgroundColor": "rgb(24, 24, 27)",
  "foregroundColor": "rgb(255, 255, 255)",
  "labelColor": "rgb(161, 161, 170)",
  "stripColor": "rgb(255, 255, 255)"
}

O subobjeto barcode

JSON
{
  "format": "PKBarcodeFormatQR",
  "messageEncoding": "UTF_8",
  "altText": "{cardNumber}",
  "addSecurityAnimation": true
}

Os formatos suportados incluem: PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec, PKBarcodeFormatCode128, PKBarcodeFormatCode39, PKBarcodeFormatCodabar, PKBarcodeFormatEAN13, PKBarcodeFormatI2of5 e PKBarcodeFormatNone.

Regras de validação e normalização (normalizeTemplateImport)

Quando JSON em bruto é submetido a POST /api/v1/templates/import, o backend executa normalizeTemplateImport:

  1. 1
    Normalização do Tipo de Passe: Traduz nomes de estilo legados ou alternativos (como store_card -> storeCard, event_ticket -> eventTicket, boarding_pass -> boardingPass).
  2. 2
    Deteção do Tipo de Trânsito: Para passes boardingPass, mapeia strings transitType (PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, PKTransitTypeGeneric).
  3. 3
    Ajuste de Posicionamento de Campos: Valida se os campos colocados em auxiliaryFields cumprem as regras do tipo de passe (por exemplo, passes coupon rejeitam campos auxiliares e redirecionam-nos para secondaryFields).
  4. 4
    Atribuição de Fallback de Código de Barras: Se um código de barras 1D (Code 128, Code 39, EAN-13) for configurado sem alternativa, o normalizador atribui automaticamente PKBarcodeFormatQR como código de barras de fallback para o Apple Watch.
  5. 5
    Remoção de Chaves de Sistema: Remove silenciosamente chaves de tenant perigosas ou chaves internas de sistema (id, customerId, tenantId, certificateId, version, status, passes, createdAt, updatedAt, archivedAt).

Referência da API: Criar um modelo a partir de JSON

Pedido HTTP

POST /api/v1/templates
Cabeçalhos
X-API-Key <API_KEY>
Content-Type application/json
JSON
{
  "name": "Acme VIP Club",
  "kind": "storeCard",
  "organizationName": "Acme Retail Group",
  "description": "Acme VIP Rewards Card",
  "colors": {
    "backgroundColor": "rgb(15, 23, 42)",
    "foregroundColor": "rgb(248, 250, 252)",
    "labelColor": "rgb(148, 163, 184)"
  },
  "barcode": {
    "format": "PKBarcodeFormatQR",
    "messageEncoding": "UTF_8",
    "altText": "{externalId}"
  },
  "fields": {
    "headerFields": [
      {
        "key": "tier",
        "label": "TIER",
        "value": "VIP Platinum",
        "textAlignment": "PKTextAlignmentRight"
      }
    ],
    "primaryFields": [
      {
        "key": "holder",
        "label": "MEMBER",
        "value": "{firstName} {lastName}"
      }
    ],
    "secondaryFields": [
      {
        "key": "balance",
        "label": "POINTS",
        "value": "{pointsBalance}",
        "numberStyle": "PKNumberStyleDecimal"
      }
    ],
    "backFields": [
      {
        "key": "terms",
        "label": "TERMS & CONDITIONS",
        "value": "Valid at all participating Acme stores. Points expire after 12 months of inactivity."
      }
    ]
  },
  "locations": [
    {
      "latitude": 40.712776,
      "longitude": -74.005974,
      "maxDistance": 250,
      "relevantText": "Welcome to Acme Flagship! Scan your pass at checkout."
    }
  ]
}

Resposta HTTP (201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "tmpl_01h9x8k7m6n5p4q3r2s1",
    "groupId": "grp_01h9x8k7m6n5p4q3r2s1",
    "name": "Acme VIP Club",
    "kind": "storeCard",
    "status": "PUBLISHED",
    "versionNumber": 1,
    "rowKind": "PRODUCTION",
    "createdAt": "2026-11-16T20:30:00.000Z",
    "updatedAt": "2026-11-16T20:30:00.000Z"
  },
  "statusCode": 201
}

Erros comuns de ingestão JSON e resoluções

Estado HTTPMensagem de erroCausa raiz e resolução
400 Bad RequestTemplate icon is requiredAo criar modelos via JSON sem ativos base existentes, deve ser fornecido um ativo icon ou um data URI, ou atribuído um ID de ativo existente no espaço de trabalho.
400 Bad RequestInvalid color format: must be rgb(r, g, b)Uma string de cor continha canais alfa (rgba(0,0,0,0.5)) ou sintaxe malformada. Forneça rgb(r, g, b) padrão ou hexadecimal de 6 dígitos (#RRGGBB).
400 Bad RequestAuxiliary fields are not supported on coupon passesO payload submeteu auxiliaryFields para um tipo de passe coupon. Mova os campos auxiliares para secondaryFields ou altere o tipo de passe para storeCard.
413 Payload Too LargeImport payload exceeds 5MB limitO payload JSON excedeu o maximum upload size limit (5 MB), normalmente devido a strings de imagem em base64 incorporadas. Carregue as imagens através do endpoint de ativos de imagem.

Continue para Importar do Apple Pass Designer para importar projetos .passdesign existentes ou explore Campos dinâmicos e personalização para configurar variáveis de atributos.

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.