Skip to content
Guía del Centro de ayuda · Plantillas de pasesFase de incorporación 3
4 min de lecturaVerificado 2026-11-16

Versiones de plantillas y publicación

Supera los controles de publicación, vincula certificados, pasa de Borrador a Publicado y gestiona cambios.

En esta guía

Recorridos visuales interactivos

Abrir en la guía de 6 fases

Inspecciona las pantallas reales del panel y las anotaciones ampliadas de esta guía.

Enfoque de interfaz ampliado1 / 2
Elementos clave de la interfaz

Lista de verificación de publicación — Configuración completa (Zoom)

Comprueba que el Certificado de firma, las Reglas de validación y la Página de descarga muestren «Ready» (3 de 3 completados) antes de emitir pases.

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.

Lista de verificación previa a la publicación
Lista de verificación previa a la publicación

Arquitectura del sistema: versionado en una tabla y ciclo de publicación

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
VERSIONADO EN UNA TABLA Y PUBLICACIÓN
ETAPA 01 Tabla Template (Linaje de revisiones en una tabla)
groupId: UUID compartido que vincula todas las revisiones de la plantilla
baseId: Puntero a la revisión base canónica en PRODUCTION
versionNumber: Entero incremental monótono (v1, v2, v3...)
rowKind (TemplateRowKind): PRODUCTION | PUBLISHED | ARCHIVED | DRAFT
status (template status): DRAFT | PUBLISHED | ARCHIVED | ...
ETAPA 02 EVALUADOR DE RIESGOS Y PUERTAS DE PUBLICACIÓN
Verifica certificado Apple Pass Type (.p12) y vínculo Google Issuer
Resuelve todos los tokens {variable} contra Propiedades personalizadas
Evalúa si las actualizaciones programadas podrían sobrescribir campos vivos
ETAPA 03 PROMOCIÓN ATÓMICA Y COLA DE PROPAGACIÓN AL WALLET
Promueve los cambios del borrador al linaje canónico PRODUCTION / PUBLISHED
Conserva las revisiones anteriores en el historial con fila ARCHIVED
Si propagateUpdates: trueencola actualizaciones a pases instalados

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):

ColumnaTipoDescripción
groupIdUUIDIdentificador 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.
versionNumberintegerContador secuencial de revisiones incrementado en cada publicación.
rowKindTemplateRowKindPRODUCTION (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. 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. 2
    Campos dinámicos y atributos personalizados: Verifica que cada token {variable} referenciado en request payload (HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER) corresponda a una propiedad declarada o a un token del sistema (serialNumber, externalId, expirationDate).
  3. 3
    Coherencia de mecánicas y validaciones: Valida los parámetros de pass mechanic vinculados (mechanic type), comportamientos de límite y expresiones de identificadores personalizados (externalIdentifierPattern).
  4. 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. 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: true encola notificaciones push silenciosas APNs HTTP/2 y actualizaciones de Google Wallet para los dispositivos registrados. Ejecute siempre GET /api/v1/templates/:id/publish-risk-check y pruebe primero los cambios sobre un pase individual (activePassesOnly: true limita 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

GET /api/v1/templates/:id/publish-risk-check
Cabeceras
X-API-Key <API_KEY>

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

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)

JSON
{
  "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

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:

POST /api/v1/templates/:id/discard-draft
Cabeceras
X-API-Key <API_KEY>
JSON
{
  "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.

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