Descripción general
Passinstance implementa una arquitectura de versionado de plantillas en una sola tabla sobre el modelo Template. Esto permite a los operadores iterar diseños, enlaces de campos y mecánicas dentro de un espacio aislado en estado DRAFT mientras los pases activos ya emitidos siguen funcionando sin interrupciones contra la revisión activa PUBLISHED / PRODUCTION. La emisión mediante API externa (POST /api/v1/passes), las importaciones masivas CSV y los registros públicos con PassFlow requieren que la plantilla alcance el estado PUBLISHED.

Arquitectura del sistema: versionado en una tabla y ciclo de publicación
Modelo de versionado en una sola tabla (Template)
Cada linaje de plantilla coordina sus revisiones mediante columnas y enums sobre la tabla template de la base de datos (TemplateRowKind y template status: DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED):
| Columna | Tipo | Descripción | |
|---|---|---|---|
groupId | UUID | Identificador inmutable de linaje compartido por todas las instantáneas históricas y filas activas de borrador o producción. | |
baseId | `UUID \ | null` | Referencia la fila base canónica de la plantilla (PRODUCTION / PUBLISHED) de la que deriva la revisión. |
versionNumber | integer | Contador secuencial de revisiones incrementado en cada publicación. | |
rowKind | TemplateRowKind | PRODUCTION (fila base canónica asociada a pases), PUBLISHED (instantánea publicada), ARCHIVED (versión histórica reemplazada) o DRAFT (copia de trabajo aislada). |
Controles de verificación previos a la publicación
Antes de promover una revisión DRAFT, Passinstance evalúa cinco controles de preparación:
-
1
Diseño visual y recursos obligatorios: Comprueba que los recursos necesarios de Apple Wallet (
icon,logo) y Google Wallet (googlePayLogo) (image asset slot) y las descripciones de la organización estén completos. -
2
Campos dinámicos y atributos personalizados: Verifica que cada token
{variable}referenciado enrequest payload(HEADER,PRIMARY,SECONDARY,AUXILIARY,BACK,ADDITIONALINFO,FOOTER) corresponda a una propiedad declarada o a un token del sistema (serialNumber,externalId,expirationDate). -
3
Coherencia de mecánicas y validaciones: Valida los parámetros de
pass mechanicvinculados (mechanic type), comportamientos de límite y expresiones de identificadores personalizados (externalIdentifierPattern). -
4
Credenciales criptográficas de firma: Confirma que exista un certificado Apple Pass Type ID válido y una cuenta Google Wallet Issuer vinculados en la configuración de la plantilla.
-
5
Análisis de riesgo de publicación (
GET /api/v1/templates/:id/publish-risk-check): Detecta modificaciones críticas en campos o mecánicas y conflictos de publicaciones programadas antes de propagar cambios.
Importante: Publicar con
propagateUpdates: trueencola notificaciones push silenciosas APNs HTTP/2 y actualizaciones de Google Wallet para los dispositivos registrados. Ejecute siempreGET /api/v1/templates/:id/publish-risk-checky pruebe primero los cambios sobre un pase individual (activePassesOnly: truelimita la propagación únicamente a los pases activos actualmente).
Referencia de la API de publicación, programación y descarte (Templates API)
1. Ejecutar comprobación de riesgo previa a la publicación
/api/v1/templates/:id/publish-risk-check
Devuelve advertencias de cambios críticos evaluadas frente a los pases activos y cualquier publicación programada pendiente (TemplatePublishRiskCheckResult envuelto en API response envelope).
2. Publicar la revisión de plantilla de inmediato (request payload)
Promueve la revisión en borrador al linaje activo de la plantilla y, opcionalmente, envía cambios visuales y de campos a los pases ya instalados:
POST /api/v1/templates/:id/publish Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json
{
"propagateUpdates": true,
"activePassesOnly": true,
"sendNotifications": true,
"notificationMessage": "New seasonal card layout is live!",
"acknowledgePublishRiskWarning": true,
"overrideReason": "Verified holiday strip colors on test pass"
}
Respuesta HTTP (200 OK)
{
"success": true,
"description": "Template published successfully",
"errors": [],
"data": {
"id": "tmpl_01hxyz987654321",
"groupId": "grp_01hxyz987654321",
"versionNumber": 3,
"rowKind": "PRODUCTION",
"status": "PUBLISHED",
"updatedAt": "2026-11-15T14:00:00.000Z"
},
"statusCode": 200
}
3. Programar una publicación futura
Encola una revisión en borrador para publicarse automáticamente en una fecha y hora local del cliente o ISO (si scheduledAt corresponde al pasado o al presente, el servidor publica de inmediato):
POST /api/v1/templates/:id/schedule-publication Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json
{
"scheduledAt": "2026-11-27 00:00",
"timeZone": "Europe/Berlin",
"activePassesOnly": true,
"sendNotifications": false,
"message": "Black Friday seasonal artwork activated."
}
4. Descartar borrador de trabajo y revertir al estado activo
Descarta los cambios sin confirmar de la fila DRAFT y restablece el borrador de trabajo a la revisión base publicada activa:
/api/v1/templates/:id/discard-draft
{
"success": true,
"description": "Template draft discarded successfully",
"data": {
"success": true,
"message": "Draft discarded successfully"
},
"errors": [],
"statusCode": 200
}
Una vez publicada su plantilla, continúe con Crear pases individuales o Creación masiva de pases.
