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

Crear una plantilla desde JSON

Importe y aprovisione plantillas de pases mediante programación utilizando definiciones JSON, validación de esquemas y reglas de normalización.

En esta guía

Descripción general

Passinstance ofrece soporte nativo para crear y configurar plantillas de pases mediante programación a través de cargas útiles JSON. En lugar de configurar manualmente diseños visuales, codificaciones de códigos de barras, colores y atributos dinámicos en el editor visual, los desarrolladores e integradores pueden enviar esquemas completos de plantilla a la API REST (POST /api/v1/templates o POST /api/v1/templates/import).

El motor de plantillas del backend procesa el JSON entrante a través de la canalización de normalización y validación con normalización automática de esquemas, validando las geometrías de los pases, aplicando las invariantes de color de Apple Wallet y Google Wallet, y registrando las propiedades personalizadas.

Arquitectura del sistema: canalización de ingesta de plantillas JSON

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
CANALIZACIÓN DE INGESTA DE PLANTILLAS JSON
ETAPA 01 CLIENTE EXTERNO / SCRIPT DE AUTOMATIZACIÓN
Envía documento JSON vía POST/api/v1/templates o POST.../templates/import
Codifica tipos de pase, colores, zonas de campos, códigos y reglas relevancia
ETAPA 02 CANALIZACIÓN DE INGESTA Y NORMALIZACIÓN DE PLANTILLAS
normalizeTemplateImport (template-import-export.util.ts)
1
Límite de tamaño: aplica maximum upload size limit = 5 * 1024 * 1024 (5 MB)
2
Saneamiento de seguridad: elimina claves de sistema (id, customerId, etc.)
3
Control contra Prototype Pollution: rechaza __proto__, constructor, etc.
4
Normalización de colores: convierte hex / RGB al formato rgb(r, g, b)
5
Mapeo de códigos y tránsito: traduce enums Apple PassKit a formatos canónicos
ETAPA 03 CONCILIADOR DE BASE DE DATOS (Template Engine)
Persiste la entidad Template con status: PUBLISHED
Crea entidades relacionales: Field[], Color, Barcode, Location[]
Inicializa índice de búsqueda rápida sobre Pass.attributes para propiedades
ETAPA 04A COMPILACIÓN DE APPLE WALLET
Genera diccionario base pass.json y empaqueta iconos/imágenes semilla
ETAPA 04B CREACIÓN DE CLASE GOOGLE WALLET
Crea la clase Google Wallet vía SDK (p. ej., LoyaltyClass, EventClass)

Especificación del esquema JSON para request payload

Una definición JSON válida de plantilla debe ajustarse a la estructura request payload aceptada por POST /api/v1/templates:

Propiedad de nivel superiorTipoObligatoriaDescripción
namestringSíNombre legible de la plantilla (por ejemplo, "Artisan Coffee Club"). Máx. 255 caracteres.
kindPassKindSíGeometría del tipo de pase: storeCard, coupon, eventTicket, boardingPass, generic o posterGeneric.
organizationNamestringSíNombre de la organización mostrado en los pases de Apple Wallet y Google Wallet.
descriptionstringSíDescripción accesible del pase exigida por Apple PassKit.
statustemplate statusNoEstado inicial. De forma predeterminada se establece en PUBLISHED en la creación programática.
colorsrequest payloadNoObjeto con backgroundColor, foregroundColor, labelColor y stripColor.
barcoderequest payloadNoConfiguración del código de barras (format, messageEncoding, altText, addSecurityAnimation).
fieldsrequest payloadNoColecciones de campos agrupadas por zona (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields).
locationsrequest payload[]NoMatriz de hasta 10 coordenadas GPS que activan notificaciones en la pantalla de bloqueo.
beaconsrequest payload[]NoMatriz de hasta 10 balizas Bluetooth iBeacon para detección de proximidad en interiores.
expirationrequest payloadNoEstrategia de validez y caducidad del pase (none, fixed o duration).

El subobjeto colors

Apple Wallet exige estrictamente el formato CSS RGB (rgb(r, g, b)) para los colores y rechaza los valores hexadecimales o canales alfa. Al importar JSON a través de Passinstance, el normalizador acepta tanto sintaxis hexadecimal como RGB y serializa el formato exacto que requiere cada proveedor de monedero:

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

El subobjeto barcode

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

Los formatos admitidos incluyen: PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec, PKBarcodeFormatCode128, PKBarcodeFormatCode39, PKBarcodeFormatCodabar, PKBarcodeFormatEAN13, PKBarcodeFormatI2of5 y PKBarcodeFormatNone.

Reglas de validación y normalización (normalizeTemplateImport)

Cuando se envía JSON sin procesar a POST /api/v1/templates/import, el backend ejecuta normalizeTemplateImport:

  1. 1
    Normalización del tipo de pase: Traduce nombres de estilo heredados o alternativos (como store_card -> storeCard, event_ticket -> eventTicket, boarding_pass -> boardingPass).
  2. 2
    Detección del tipo de transporte: En los pases boardingPass, asigna las cadenas transitType (PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, PKTransitTypeGeneric).
  3. 3
    Ajuste de ubicación de campos: Valida que los campos colocados en auxiliaryFields cumplan las reglas del tipo de pase (por ejemplo, los pases coupon rechazan los campos auxiliares y los redirigen a secondaryFields).
  4. 4
    Asignación de código de barras de respaldo: Si se configura un código de barras 1D (Code 128, Code 39, EAN-13) sin código de respaldo, el normalizador asigna automáticamente PKBarcodeFormatQR como código de barras alternativo para Apple Watch.
  5. 5
    Eliminación de claves del sistema: Elimina de forma silenciosa claves internas o peligrosas del inquilino (id, customerId, tenantId, certificateId, version, status, passes, createdAt, updatedAt, archivedAt).

Referencia de la API: crear una plantilla desde JSON

Solicitud HTTP

POST /api/v1/templates
Cabeceras
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."
    }
  ]
}

Respuesta 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
}

Errores frecuentes de ingesta JSON y soluciones

Estado HTTPMensaje de errorCausa raíz y solución
400 Bad RequestTemplate icon is requiredAl crear plantillas mediante JSON sin activos semilla existentes, debe proporcionarse un activo icon o data URI, o asignarse el ID de un activo existente en el espacio de trabajo.
400 Bad RequestInvalid color format: must be rgb(r, g, b)Una cadena de color contenía canales alfa (rgba(0,0,0,0.5)) o una sintaxis mal formada. Proporcione un valor estándar rgb(r, g, b) o hexadecimal de 6 dígitos (#RRGGBB).
400 Bad RequestAuxiliary fields are not supported on coupon passesLa carga útil envió auxiliaryFields para un tipo de pase coupon. Mueva los campos auxiliares a secondaryFields o cambie el tipo de pase a storeCard.
413 Payload Too LargeImport payload exceeds 5MB limitLa carga útil JSON superó maximum upload size limit (5 MB), normalmente debido a cadenas de imagen incrustadas en base64. Cargue las imágenes mediante el endpoint de activos de imagen en su lugar.

Continúe con Importar desde Apple Pass Designer para importar proyectos .passdesign existentes, o explore Campos dinámicos y personalización para configurar variables de atributos.

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