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
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 superior | Tipo | Obligatoria | Descripción |
|---|---|---|---|
name | string | Sí | Nombre legible de la plantilla (por ejemplo, "Artisan Coffee Club"). Máx. 255 caracteres. |
kind | PassKind | Sí | Geometría del tipo de pase: storeCard, coupon, eventTicket, boardingPass, generic o posterGeneric. |
organizationName | string | Sí | Nombre de la organización mostrado en los pases de Apple Wallet y Google Wallet. |
description | string | Sí | Descripción accesible del pase exigida por Apple PassKit. |
status | template status | No | Estado inicial. De forma predeterminada se establece en PUBLISHED en la creación programática. |
colors | request payload | No | Objeto con backgroundColor, foregroundColor, labelColor y stripColor. |
barcode | request payload | No | Configuración del código de barras (format, messageEncoding, altText, addSecurityAnimation). |
fields | request payload | No | Colecciones de campos agrupadas por zona (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields). |
locations | request payload[] | No | Matriz de hasta 10 coordenadas GPS que activan notificaciones en la pantalla de bloqueo. |
beacons | request payload[] | No | Matriz de hasta 10 balizas Bluetooth iBeacon para detección de proximidad en interiores. |
expiration | request payload | No | Estrategia 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:
{
"backgroundColor": "rgb(24, 24, 27)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(161, 161, 170)",
"stripColor": "rgb(255, 255, 255)"
}
El subobjeto barcode
{
"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
Normalización del tipo de pase: Traduce nombres de estilo heredados o alternativos (como
store_card->storeCard,event_ticket->eventTicket,boarding_pass->boardingPass). -
2
Detección del tipo de transporte: En los pases
boardingPass, asigna las cadenastransitType(PKTransitTypeAir,PKTransitTypeTrain,PKTransitTypeBus,PKTransitTypeBoat,PKTransitTypeGeneric). -
3
Ajuste de ubicación de campos: Valida que los campos colocados en
auxiliaryFieldscumplan las reglas del tipo de pase (por ejemplo, los pasescouponrechazan los campos auxiliares y los redirigen asecondaryFields). -
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áticamentePKBarcodeFormatQRcomo código de barras alternativo para Apple Watch. -
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
/api/v1/templates
{
"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)
{
"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 HTTP | Mensaje de error | Causa raíz y solución |
|---|---|---|
| 400 Bad Request | Template icon is required | Al 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 Request | Invalid 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 Request | Auxiliary fields are not supported on coupon passes | La 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 Large | Import payload exceeds 5MB limit | La 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.
