Überblick
Passinstance setzt auf dem Template-Modell eine Single-Table-Vorlagenversionierung um. So können Teams Layouts, Feldbindungen und Mechaniken in einem isolierten DRAFT-Arbeitsbereich weiterentwickeln, während bereits ausgegebene Pässe im Feld ungestört mit der aktiven PUBLISHED- / PRODUCTION-Revision weiterlaufen. Die externe API-Ausgabe (POST /api/v1/passes), CSV-Massenimporte und öffentliche PassFlow-Registrierungen setzen voraus, dass die Vorlage den Status PUBLISHED erreicht hat.

Systemarchitektur: Single-Table-Versionierung & Veröffentlichungs-Lebenszyklus
Single-Table-Versionierungsmodell (Template)
Jede Vorlagenlinie koordiniert Revisionen über Spalten und Enums in der Datenbanktabelle template (TemplateRowKind und template status: DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED):
| Spalte | Typ | Beschreibung | |
|---|---|---|---|
groupId | UUID | Unveränderlicher Linien-Bezeichner, der alle historischen Snapshots sowie aktive Entwurfs- und Produktionszeilen verbindet. | |
baseId | `UUID \ | null` | Verweist auf die kanonische Basis-Vorlagenzeile (PRODUCTION / PUBLISHED), von der diese Revision abgeleitet wurde. |
versionNumber | integer | Sequentieller Revisionszähler, der bei jeder Veröffentlichung erhöht wird. | |
rowKind | TemplateRowKind | PRODUCTION (an Pässe gebundene kanonische Basiszeile), PUBLISHED (veröffentlichter Snapshot), ARCHIVED (abgelöste historische Version) oder DRAFT (isolierte Arbeitskopie). |
Prüf-Gates vor der Veröffentlichung
Vor der Freigabe einer DRAFT-Revision wertet Passinstance fünf Bereitschafts-Gates aus:
-
1
Visuelles Design & Pflicht-Assets: Erforderliche Grafiken für Apple Wallet (
icon,logo) und Google Wallet (googlePayLogo) (image asset slot) sowie Organisationsbeschreibungen sind hinterlegt. -
2
Dynamische Felder & benutzerdefinierte Attribute: Jedes in
request payload(HEADER,PRIMARY,SECONDARY,AUXILIARY,BACK,ADDITIONALINFO,FOOTER) verwendete{variable}-Token verweist auf eine deklarierte Eigenschaft oder ein Systemtoken (serialNumber,externalId,expirationDate). -
3
Mechanik- & Validierungskonsistenz: Verknüpfte
pass mechanic-Parameter (mechanic type), Obergrenzen-Regeln und benutzerdefinierte ID-Muster (externalIdentifierPattern) sind gültig. -
4
Kryptografische Signatur-Zugangsdaten: Ein gültiges Apple Pass Type ID-Zertifikat sowie ein Google-Wallet-Issuer-Konto sind unter den Vorlageneinstellungen verknüpft.
-
5
Veröffentlichungs-Risikoprüfung (
GET /api/v1/templates/:id/publish-risk-check): Erkennt kritische Feld- oder Mechanikänderungen sowie Konflikte mit geplanten Veröffentlichungen vor der Verteilung.
Wichtig: Eine Veröffentlichung mit
propagateUpdates: truereiht stille APNs-HTTP/2-Pushs und Google-Wallet-Updates an alle registrierten Geräte ein. Führen Sie stets zuerstGET /api/v1/templates/:id/publish-risk-checkaus und testen Sie Änderungen vorab an einem einzelnen Pass (activePassesOnly: truebegrenzt die Verteilung auf aktuell aktive Pässe).
API-Referenz für Veröffentlichung, Zeitplanung & Verwerfen (Templates API)
1. Vorab-Risikoprüfung ausführen
/api/v1/templates/:id/publish-risk-check
Gibt Warnungen zu kritischen Änderungen auf Basis aktiver Pässe und etwaiger geplanter Veröffentlichungen zurück (TemplatePublishRiskCheckResult verpackt in API response envelope).
2. Vorlagenrevision sofort veröffentlichen (request payload)
Befördert die Entwurfsrevision in die produktive Vorlagenlinie und überträgt Design- oder Feldänderungen optional direkt an installierte Pässe:
POST /api/v1/templates/:id/publish Header: 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"
}
HTTP-Antwort (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. Zukünftige Veröffentlichung planen
Reiht eine Entwurfsrevision zur automatischen Veröffentlichung an einem kundenlokalen oder ISO-Zeitpunkt ein (liegt scheduledAt in der Vergangenheit oder Gegenwart, veröffentlicht der Server sofort):
POST /api/v1/templates/:id/schedule-publication Header: 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. Arbeitsentwurf verwerfen & auf Live-Stand zurücksetzen
Verwirft nicht übernommene Änderungen in der DRAFT-Zeile und setzt den Arbeitsentwurf auf die aktive veröffentlichte Basisrevision zurück:
/api/v1/templates/:id/discard-draft
{
"success": true,
"description": "Template draft discarded successfully",
"data": {
"success": true,
"message": "Draft discarded successfully"
},
"errors": [],
"statusCode": 200
}
Sobald Ihre Vorlage veröffentlicht ist, fahren Sie fort mit Einzelne Pässe erstellen oder Massen-Pass-Erstellung.
