Vue d'ensemble
Passinstance met en œuvre une architecture de versionnage des modèles en table unique sur l'entité Template. Cela permet aux équipes de faire évoluer la mise en page, les liaisons de champs et les mécaniques dans un brouillon DRAFT isolé pendant que les passes déjà émis en production continuent de fonctionner sans interruption sur la révision active PUBLISHED / PRODUCTION. L'émission via API externe (POST /api/v1/passes), les imports CSV en masse et les inscriptions publiques PassFlow requièrent que le modèle ait atteint le statut PUBLISHED.

Architecture système : versionnage en table unique & cycle de publication
Modèle de versionnage en table unique (Template)
Chaque lignée de modèle coordonne ses révisions à travers les colonnes et énumérations de la table template (TemplateRowKind et template status : DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED) :
| Colonne | Type | Description | |
|---|---|---|---|
groupId | UUID | Identifiant de lignée immuable partagé entre tous les instantanés historiques et les lignes brouillon/production actives. | |
baseId | `UUID \ | null` | Référence la ligne de base canonique (PRODUCTION / PUBLISHED) dont dérive la révision. |
versionNumber | integer | Compteur séquentiel de révision incrémenté à chaque publication. | |
rowKind | TemplateRowKind | PRODUCTION (ligne de base canonique rattachée aux passes), PUBLISHED (instantané publié), ARCHIVED (version historique remplacée) ou DRAFT (copie de travail isolée). |
Contrôles de validation avant publication
Avant de promouvoir une révision DRAFT, Passinstance évalue cinq critères de conformité :
-
1
Design visuel & visuels obligatoires : les images requises par Apple Wallet (
icon,logo) et Google Wallet (googlePayLogo) (image asset slot) ainsi que les descriptions de l'organisation sont renseignées. -
2
Champs dynamiques & attributs personnalisés : chaque jeton
{variable}référencé dansrequest payload(HEADER,PRIMARY,SECONDARY,AUXILIARY,BACK,ADDITIONALINFO,FOOTER) correspond à une propriété déclarée ou à un jeton système (serialNumber,externalId,expirationDate). -
3
Cohérence de la mécanique et de la validation : les paramètres du
pass mechanicassocié (mechanic type), le comportement au plafond et les expressions d'identifiants personnalisés (externalIdentifierPattern) sont valides. -
4
Identifiants cryptographiques de signature : un certificat Apple Pass Type ID valide et un compte émetteur Google Wallet sont associés dans les paramètres du modèle.
-
5
Analyse de risque avant publication (
GET /api/v1/templates/:id/publish-risk-check) : détecte les modifications critiques de champs ou de mécaniques ainsi que les conflits avec d'éventuelles publications planifiées avant la propagation.
Important : Publier avec
propagateUpdates: truemet en file d'attente des notifications push silencieuses APNs HTTP/2 et des mises à jour Google Wallet vers l'ensemble des appareils enregistrés. Exécutez toujoursGET /api/v1/templates/:id/publish-risk-checket testez vos modifications sur un seul passe test au préalable (activePassesOnly: truelimite la propagation aux seuls passes actuellement actifs).
Référence API de publication, planification & annulation de brouillon (Templates API)
1. Exécuter l'analyse de risque avant publication
/api/v1/templates/:id/publish-risk-check
Retourne les avertissements relatifs aux modifications critiques évalués sur les passes actifs ainsi que les publications planifiées en attente (TemplatePublishRiskCheckResult encapsulé dans API response envelope).
2. Publier immédiatement une révision du modèle (request payload)
Promeut la révision brouillon en ligne de modèle active et pousse éventuellement les changements visuels ou de champs vers les passes installés :
POST /api/v1/templates/:id/publish En-têtes : 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"
}
Réponse 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. Planifier une publication ultérieure
Programme une révision brouillon pour qu'elle soit publiée automatiquement à une date/heure ISO ou locale au client (si scheduledAt est déjà passé ou immédiat, le serveur publie aussitôt) :
POST /api/v1/templates/:id/schedule-publication En-têtes : 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. Abandonner le brouillon en cours & revenir à l'état publié
Supprime les modifications non publiées de la ligne DRAFT et réinitialise le brouillon de travail sur la révision publiée active :
/api/v1/templates/:id/discard-draft
{
"success": true,
"description": "Template draft discarded successfully",
"data": {
"success": true,
"message": "Draft discarded successfully"
},
"errors": [],
"statusCode": 200
}
Une fois votre modèle publié, passez à Créer des passes individuels ou à Création de passes en masse.
