Skip to content
Guide du centre d'aide · Présentation de PassinstancePhase d'intégration 2
6 min de lectureVérifié 2026-11-16

Concepts clés & terminologie

Définitions claires des Modèles, Passes, Mécaniques, Attributs, Wallet Experiences (Projets), PassFlow et Inscriptions actives.

Dans ce guide

Visites interactives de l'interface

Ouvrir dans le guide en 6 phases

Inspectez les écrans exacts du tableau de bord et les zooms annotés liés à ce guide.

Focus interface zoomé
Éléments clés de l'interface

Propriétés et attributs personnalisés (Zoom)

Définissez des attributs clients réutilisables ({serviceOrDuration}, {holderName}, {passReference}, {validUntil}, {memberQrToken}) ainsi que leurs types et règles.

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.

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : RELATIONS ENTRE ENTITÉS
ÉTAPE 01 Template (Modèle & Versionnage)
Format : StoreCard, EventTicket, Coupon, Membership
Couleurs, symbologie code-barres, champs, visuels
ÉTAPE 02 Émission 1:N | Rattachement de règle 1:1
Pass (Instance concrète)
SerialNumber & AuthToken
Valeurs de champs dynamiques
Statut & ExpirationDate
Enregistrement appareil 1:N (App
pass mechanic (Moteur d'état)
Type : STAMP_CARD_ADD, LOYALTY_PROGRAM, PREPAID_CARD,
VALID_ONCE_PER_DAY gle Saves)

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 :

ConceptModèle Passinstance databaseResponsabilités & attributs stockés
Modèle (Template)TemplateStocke 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)PassRepré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 passepass mechanicConfigure 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 accountGè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 bundleRegroupe 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 ExperiencePassProjectOrchestre 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.
PassFlowPassFlowGè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 ScannerScannerConfigurationConfigure 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 :

ChampColonne Passinstance database / PortéeMutabilité & formatUsage principal
idClé primaire UUIDGénérée par le système, immuableRéférence interne de ressource API (GET /api/v1/passes/:id).
serialNumberChaîne unique globaleGénérée par le système (ou personnalisée si configurée), immuableIdentifiant canonique Apple Wallet .pkpass et suffixe d'objet Google Wallet.
externalId@unique([customerId, externalId]) où archivedAt IS NULLFourni 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.
bundleIdbundleId (clé étrangère UUID vers pass bundle)Géré par le système via /api/v1/bundles/* ou PassProjectRegroupe 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 / authenticationTokenJetons de sécurité par passeChaînes cryptographiques générées par le systèmeCode 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é sa expirationDate ; les scanners rejettent avec le motif PASS_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 avec PASS_VOIDED.

Cycle de vie du passe, mode de suppression & disponibilité des artefacts

  • PassLifecycleStatus : régit les transitions irréversibles d'annulation et de purge :
TEXT
ACTIVE  --->  VOIDING  --->  VOIDED  --->  DELETING  --->  DELETED
  • PassDeletionMode : distingue la suppression logique (SOFT, conserve l'historique d'audit et libère l'unicité de externalId pour 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 REST PATCH Google 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) : configurez changeMessage: "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.

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.