Architecture centrale & entités de la plateforme
Pour concevoir des workflows Wallet fiables, les développeurs et administrateurs doivent comprendre comment Passinstance structure les modèles, les fiches de passes dynamiques, les mécaniques métier et les états d'enregistrement des appareils.
Schéma des entités backend & correspondance Passinstance database
Chaque concept de la plateforme correspond directement à une entité Passinstance database structurée dans la couche de base de données de Passinstance API :
| Concept | Modèle Passinstance database | Responsabilités & attributs stockés | |||||
|---|---|---|---|---|---|---|---|
| Modèle (Template) | Template | Stocke la configuration visuelle, le type de mise en page (pass type), les relations d'images (image asset slot), les règles de code-barres, les expressions régulières d'identifiants personnalisés et le versionnage en table unique (groupId, versionNumber, rowKind : `PRODUCTION \ | PUBLISHED \ | ARCHIVED \ | DRAFT, status` : template status). | ||
| Passe (Pass) | Pass | Représente une carte individuelle émise. Contient id, serialNumber unique, authenticationToken, downloadCode, externalId optionnel unique par locataire, bundleId optionnel (bundleId), idempotencyKey optionnel, les attributs structured JSON attributes, expirationDate, l'état de préparation des artefacts (appleArtifactStatus, googleArtifactStatus) et les indicateurs de cycle de vie ou d'annulation. | |||||
| Mécanique de passe | pass mechanic | Configure les règles dynamiques rattachées à un modèle. Stocke mechanicType (mechanic type), minimumValue, maximumValue, defaultChangeValue, les paliers (PassTier) et les règles de plafonnement. | |||||
| Compte prépayé | prepaid account | Gère le solde monétaire des cartes cadeaux et prépayées. Suit les soldes entiers en sous-unités et se lie aux écritures immuables prepaid ledger entry. | |||||
| Lot de passes (Bundle) | pass bundle | Regroupe jusqu'à 10 passes complémentaires via Pass.bundleId (bundle grouping mode : `AUTO \ | MANUAL, BundleStatus : ACTIVE \ | CANCELLED) pour télécharger des archives multi-cartes .pkpasses`. | |||
| Wallet Experience | PassProject | Orchestre un modèle principal (mainTemplateId) et des modèles liés (PassProjectTemplateRole : `PRIMARY \ | LINKED \ | PRIVACY_MODE \ | INACTIVE \ | VIP \ | CUSTOM`), des pages de retrait unifiées, des bundles, des segments et des automatisations visuelles. |
| PassFlow | PassFlow | Gère les pages d'auto-inscription multi-étapes (/f/:url, PassFlowType, PassFlowStatus) avec formulaires personnalisables, vérification OTP SMS/e-mail, protection anti-bot (SpamProtectionMode), passerelles de paiement et remise directe au Wallet. | |||||
| Configuration Scanner | ScannerConfiguration | Configure les lieux physiques de contrôle (ValidationPlace), les jetons cloisonnés ScannerKey, les modes de validation (ScanMode), les paramètres de lecteurs NFC (NfcReaderMode) et la synchronisation hors ligne. |
Identifiants principaux d'un passe & clés de corrélation
Lorsque vous intégrez un CRM, une caisse e-commerce ou un système de billetterie, comprenez le rôle exact de chaque identifiant sur un objet Pass :
| Champ | Colonne Passinstance database / Portée | Mutabilité & format | Usage principal |
|---|---|---|---|
id | Clé primaire UUID | Générée par le système, immuable | Référence interne de ressource API (GET /api/v1/passes/:id). |
serialNumber | Chaîne unique globale | Générée par le système (ou personnalisée si configurée), immuable | Identifiant canonique Apple Wallet .pkpass et suffixe d'objet Google Wallet. |
externalId | @unique([customerId, externalId]) où archivedAt IS NULL | Fourni par l'appelant (max. 255 caractères) | Clé métier issue de votre CRM, POS ou base billetterie permettant POST /api/v1/passes/upsert-by-external-id idempotent et la recherche via GET /api/v1/passes/by-external-id/:externalId. |
bundleId | bundleId (clé étrangère UUID vers pass bundle) | Géré par le système via /api/v1/bundles/* ou PassProject | Regroupe jusqu'à 10 passes dans une archive Apple .pkpasses ou une expérience de retrait unifiée. |
idempotencyKey | @unique([customerId, idempotencyKey]) | Transmis via l'en-tête Idempotency-Key (<=128 car. [A-Za-z0-9._:-]+) | Empêche la création en double d'un passe lorsqu'une requête POST /api/v1/passes est relancée ; vérifié via l'empreinte SHA-256 du corps de requête. |
downloadCode / authenticationToken | Jetons de sécurité par passe | Chaînes cryptographiques générées par le système | Code court de téléchargement public et secret partagé Authorization: ApplePass <token> du service web Apple. |
Énumérations de la machine à états & cycle de vie
Les fiches de passes évoluent selon des machines à états strictes à travers les énumérations Passinstance database lors de la création, de la synchronisation Wallet et de l'annulation/suppression :
Statut du passe (pass status)
-
DRAFT: provisionné comme brouillon non émis et pas encore disponible à l'installation publique. -
AWAITING_OPT_IN: généré lors des parcours d'inscription avec opt-in ou OTP ; en attente de vérification avant activation. -
GENERATING: en cours de génération asynchrone du passe ou de ses artefacts. -
ACTIVE: émis et valide. Disponible pour l'installation dans le Wallet et la validation au scanner. -
INACTIVE: temporairement mis en pause ou désactivé ; les scanners rejettent la validation jusqu'à réactivation. -
EXPIRED: a dépassé saexpirationDate; les scanners rejettent avec le motifPASS_EXPIRED. -
REDEEMED: coupon ou bon à usage unique ayant déjà été encaissé. -
CANCELLED,SUSPENDED,PENDING_ACTIVATION: états spécialisés de facturation, d'administration et de pré-activation. -
VOIDED: révoqué ou annulé par un administrateur ou une règle de scan ; les scanners rejettent avecPASS_VOIDED.
Cycle de vie du passe, mode de suppression & disponibilité des artefacts
-
PassLifecycleStatus: régit les transitions irréversibles d'annulation et de purge :
ACTIVE ---> VOIDING ---> VOIDED ---> DELETING ---> DELETED
-
PassDeletionMode: distingue la suppression logique (SOFT, conserve l'historique d'audit et libère l'unicité deexternalIdpour les passes actifs) de la suppression définitive (HARD,DELETE /api/v1/passes/:id/hard). -
ArtifactStatus(appleArtifactStatus&googleArtifactStatus) : suit la santé de génération par écosystème (NOT_GENERATED,GENERATING,READY,FAILED,INVALIDATED).
Statut d'annulation et de propagation Wallet (walletVoidStatus / WalletPropagationStatus)
Suit la propagation asynchrone des états d'annulation ou de mise à jour vers Apple APNs et Google Wallet sur le champ Pass.walletVoidStatus :
-
NONE: aucune propagation en attente. -
PENDING: état enregistré en base de données ; en attente d'insertion dans la file. -
QUEUED: transmis aux workers de synchronisation Wallet background job queue. -
SUCCEEDED: réveil Apple APNs ou requête RESTPATCHGoogle acquittés. -
FAILED: échec de la poussée vers le portefeuille en aval (éligible à une nouvelle tentative automatique ou à une régénération manuelle).
Propriétés personnalisées & interpolation dynamique des jetons
Passinstance utilise la syntaxe dynamique à accolades {propertyName} pour lier les données clients aux champs de la carte :
-
Syntaxe : insérez
{firstName},{pointsBalance}ou{membershipTier}dans n'importe quel libellé ou valeur de champ principal, secondaire, auxiliaire ou au verso. -
Messages de modification (
changeMessage) : configurezchangeMessage: "Vous avez gagné un tampon ! Vous avez désormais %@ tampons."sur les champs Apple Wallet. Lors d'une mise à jour, le jeton%@est remplacé par la nouvelle valeur, générant une bannière de notification immédiate sur l'écran verrouillé iOS. -
Valeurs enrichies (
attributedValue) : les champs au verso d'Apple Wallet acceptent les balises HTML d'ancrage (<a href="https://example.com">Conditions</a>) pour des liens web, numéros de téléphone et adresses e-mail cliquables.
Important : La facturation mesure les passes Wallet actifs (le nombre total d'appareils actuellement enregistrés via Apple APNs ou des objets Google Wallet), et non les brouillons non émis ni les passes expirés.
