Overzicht
Passinstance implementeert een architectuur voor sjabloonversiebeheer in één tabel op het Template-model. Hiermee kunnen beheerders werken aan lay-outs, veldkoppelingen en mechanieken binnen een geïsoleerde DRAFT-werkomgeving, terwijl reeds uitgegeven live passen ongestoord blijven functioneren op de actieve PUBLISHED / PRODUCTION-revisie. Externe API-uitgifte (POST /api/v1/passes), CSV-batchimports en openbare PassFlow-inschrijvingen vereisen dat het sjabloon de status PUBLISHED heeft bereikt.

Systeemarchitectuur: versiebeheer in één tabel & publicatielevenscyclus
Versiebeheermodel in één tabel (Template)
Elke sjabloonlijn coördineert revisies via kolommen en enums op de databasetabel template (TemplateRowKind en template status: DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED):
| Kolom | Type | Beschrijving | |
|---|---|---|---|
groupId | UUID | Onveranderlijke lijnidentificatie gedeeld over alle historische snapshots en actieve concept-/productierijen. | |
baseId | `UUID \ | null` | Verwijst naar de canonieke basissjabloonrij (PRODUCTION / PUBLISHED) waarvan de revisie is afgeleid. |
versionNumber | integer | Opeenvolgend revisienummer dat bij publicatie wordt verhoogd. | |
rowKind | TemplateRowKind | PRODUCTION (canonieke basisrij gekoppeld aan passen), PUBLISHED (gepubliceerde snapshot), ARCHIVED (vervangen historische versie) of DRAFT (geïsoleerde werkkopie). |
Verificatiepoorten vóór publicatie
Voordat een DRAFT-revisie wordt gepromoveerd, controleert Passinstance vijf gereedheidsvereisten:
-
1
Visueel ontwerp & verplichte assets: Verplichte Apple Wallet-assets (
icon,logo) en Google Wallet-assets (googlePayLogo, via image asset slot) en organisatiebeschrijvingen zijn ingevuld. -
2
Dynamische velden & aangepaste eigenschappen: Elk
{variable}-token waarnaar inrequest payload(HEADER,PRIMARY,SECONDARY,AUXILIARY,BACK,ADDITIONALINFO,FOOTER) wordt verwezen, komt overeen met een gedefinieerde eigenschap of systeemtoken (serialNumber,externalId,expirationDate). -
3
Consistentie van mechaniek & validatie: Gekoppelde
pass mechanic-parameters (mechanic type), limietgedrag en aangepaste identificatiepatronen (externalIdentifierPattern) zijn geldig. -
4
Cryptografische ondertekeningsgegevens: Een geldig Apple Pass Type ID-certificaat en Google Wallet Issuer-account zijn gekoppeld onder Sjablooninstellingen.
-
5
Publicatierisicocontrole (
GET /api/v1/templates/:id/publish-risk-check): Detecteert ingrijpende wijzigingen in velden of mechanieken en conflicten met geplande publicaties vóór propagatie.
Belangrijk: Publiceren met
propagateUpdates: trueplaatst stille APNs HTTP/2-pushes en Google Wallet-updates in de wachtrij voor geregistreerde apparaten. Voer altijd eerstGET /api/v1/templates/:id/publish-risk-checkuit en test wijzigingen eerst op een enkele pas (activePassesOnly: truebeperkt de verspreiding tot momenteel actieve passen).
API-referentie voor publiceren, inplannen & terugdraaien (Templates API)
1. Risicocontrole vóór publicatie uitvoeren
/api/v1/templates/:id/publish-risk-check
Retourneert waarschuwingen voor kritieke wijzigingen geëvalueerd ten opzichte van actieve passen en eventuele geplande publicaties (TemplatePublishRiskCheckResult verpakt in API response envelope).
2. Sjabloonrevisie direct publiceren (request payload)
Promoveert de conceptrevisie naar de live sjabloonlijn en pusht optioneel visuele en veldwijzigingen naar geïnstalleerde passen:
POST /api/v1/templates/:id/publish Headers: 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-respons (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. Toekomstige publicatie inplannen
Plan een conceptrevisie in om automatisch te publiceren op een lokale of ISO-datum/tijd (als scheduledAt in het verleden of heden ligt, publiceert de server direct):
POST /api/v1/templates/:id/schedule-publication Headers: 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. Werkconcept negeren & terugkeren naar live status
Verwijdert niet-doorgevoerde wijzigingen in de DRAFT-rij en zet het werkconcept terug naar de actieve gepubliceerde basisrevisie:
/api/v1/templates/:id/discard-draft
{
"success": true,
"description": "Template draft discarded successfully",
"data": {
"success": true,
"message": "Draft discarded successfully"
},
"errors": [],
"statusCode": 200
}
Zodra uw sjabloon is gepubliceerd, gaat u verder met Individuele passen maken of Passen in bulk aanmaken.
