Kernarchitectuur van het platform & entiteiten
Om betrouwbare wallet-workflows op te zetten, moeten ontwikkelaars en beheerders begrijpen hoe Passinstance sjablonen, dynamische pasrecords, bedrijfslogicamechanieken en apparaatregistratiestatussen organiseert.
Schema van backendentiteiten & Passinstance database-modeltoewijzing
Elk platformconcept komt rechtstreeks overeen met een gestructureerde Passinstance database-entiteit binnen de databaselaag van Passinstance API:
| Concept | Passinstance database-model | Verantwoordelijkheden & opgeslagen eigenschappen | |||||
|---|---|---|---|---|---|---|---|
| Template | Template | Slaat visuele configuratie, lay-outtype (pass type), assetrelaties (image asset slot), barcoderegels, aangepaste regexen voor identificaties en versiebeheer in één tabel op (groupId, versionNumber, rowKind: `PRODUCTION \ | PUBLISHED \ | ARCHIVED \ | DRAFT, status`: template status). | ||
| Pass | Pass | Vertegenwoordigt een individuele uitgegeven pas. Bevat id, unieke serialNumber, authenticationToken, downloadCode, optionele tenant-unieke externalId, optionele bundleId (bundleId), optionele idempotencyKey, structured JSON attributes, expirationDate, gereedheidsstatus van artefacten (appleArtifactStatus, googleArtifactStatus) en levenscyclus-/ongeldigheidsmarkeringen. | |||||
| Pass Mechanic | pass mechanic | Configureert toestandsafhankelijke regels die aan een sjabloon gekoppeld zijn. Slaat mechanicType (mechanic type), minimumValue, maximumValue, defaultChangeValue, niveaus (PassTier) en limietregels op. | |||||
| Prepaid Account | prepaid account | Beheert opgeslagen geldwaarde voor cadeau- en prepaidkaarten. Houdt saldi in gehele eenheden bij en koppelt aan onveranderlijke prepaid ledger entry-transactielogboeken. | |||||
| Pass Bundle | pass bundle | Groepeert maximaal 10 bijbehorende passen via Pass.bundleId (bundle grouping mode: `AUTO \ | MANUAL, BundleStatus: ACTIVE \ | CANCELLED) om multi-card .pkpasses`-archieven te downloaden. | |||
| Wallet Experience | PassProject | Orkestreert een primair sjabloon (mainTemplateId) en gekoppelde sjablonen (PassProjectTemplateRole: `PRIMARY \ | LINKED \ | PRIVACY_MODE \ | INACTIVE \ | VIP \ | CUSTOM`), uniforme claimpagina's, bundels, segmenten en visuele automatiseringsstromen. |
| PassFlow | PassFlow | Beheert meerstaps selfservice-intakepagina's (/f/:url, PassFlowType, PassFlowStatus) met aanpasbare formulieren, sms-/e-mail-OTP-verificatie, botbescherming (SpamProtectionMode), betaalgateways en directe wallet-overdrachten. | |||||
| Scanner Configuration | ScannerConfiguration | Configureert fysieke inchecklocaties (ValidationPlace), afgeschermde ScannerKey-tokens, validatiemodi (ScanMode), NFC-lezerinstellingen (NfcReaderMode) en offline synchronisatie van datasets. |
Belangrijkste pasidentificaties & correlatiesleutels
Bij het integreren van CRM's, e-commerce check-outs of ticketingsystemen moet u weten wat de exacte rol is van elke identificatie op een Pass:
| Veld | Passinstance database-kolom / Bereik | Veranderlijkheid & formaat | Primair doel |
|---|---|---|---|
id | UUID primaire sleutel | Door systeem gegenereerd, onveranderlijk | Interne API-resourcereferentie (GET /api/v1/passes/:id). |
serialNumber | Wereldwijd unieke tekenreeks | Door systeem gegenereerd (of aangepast indien geconfigureerd), onveranderlijk | Canonieke Apple Wallet .pkpass-identificatie en Google-objectachtervoegsel. |
externalId | @unique([customerId, externalId]) waar archivedAt IS NULL | Door aanroeper aangeleverde tekenreeks (max. 255 tekens) | Bedrijfssleutel uit uw CRM-, POS- of ticketingdatabase voor idempotente POST /api/v1/passes/upsert-by-external-id en opzoeken via GET /api/v1/passes/by-external-id/:externalId. |
bundleId | bundleId (UUID foreign key naar pass bundle) | Door systeem beheerd via /api/v1/bundles/* of PassProject | Groepeert maximaal 10 passen in een multi-card .pkpasses Apple-bundel of uniforme claimervaring. |
idempotencyKey | @unique([customerId, idempotencyKey]) | Aangeleverd via Idempotency-Key-header (<=128 tekens [A-Za-z0-9._:-]+) | Voorkomt dubbele pasuitgifte als een HTTP POST /api/v1/passes-verzoek opnieuw wordt verzonden; geverifieerd via SHA-256-hash van de requestbody. |
downloadCode / authenticationToken | Beveiligingstokens per pas | Door systeem gegenereerde cryptografische tekenreeksen | Openbare korte downloadcode en gedeeld geheim voor Apple Web Service Authorization: ApplePass <token>. |
Toestandsmachine-enums & levenscyclusoverzicht
Pasrecords doorlopen strikte toestandsmachines over Passinstance database-enums tijdens aanmaak, wallet-synchronisatie en ongeldigverklaring of verwijdering:
Passtatus (pass status)
-
DRAFT: Aangemaakt als nog niet uitgegeven concept en nog niet beschikbaar voor openbare installatie. -
AWAITING_OPT_IN: Gegenereerd tijdens opt-in-/OTP-registratiestromen; wacht op verificatie vóór activering. -
GENERATING: Ondergaat asynchrone pas- of artefactgeneratie. -
ACTIVE: Uitgegeven en geldig. Beschikbaar voor wallet-installatie en scannervalidatie. -
INACTIVE: Tijdelijk gepauzeerd/gedeactiveerd; scanners weigeren validatie totdat de pas opnieuw wordt geactiveerd. -
EXPIRED: Voorbij deexpirationDate; scanners weigeren met redenPASS_EXPIRED. -
REDEEMED: Eenmalige kortingsbon of voucher waarvan de inwisseling is voltooid. -
CANCELLED,SUSPENDED,PENDING_ACTIVATION: Gespecialiseerde statussen voor facturatie, beheer en vooractivering. -
VOIDED: Ingetrokken of ongeldig verklaard door een beheerder of scanregel; scanners weigeren metPASS_VOIDED.
Paslevenscyclus, verwijdermodus & artefactgereedheid
-
PassLifecycleStatus: Beheert onomkeerbare ongeldigverklaring en opschoningstransities:
ACTIVE ---> VOIDING ---> VOIDED ---> DELETING ---> DELETED
-
PassDeletionMode: Maakt onderscheid tussen zachte verwijdering (SOFT, behoudt auditgeschiedenis en maaktexternalId-uniciteit vrij voor actieve passen) en permanente verwijdering (HARD,DELETE /api/v1/passes/:id/hard). -
ArtifactStatus(appleArtifactStatus&googleArtifactStatus): Houdt de generatiestatus per ecosysteem bij (NOT_GENERATED,GENERATING,READY,FAILED,INVALIDATED).
Wallet-ongeldigmaking & propagatiestatus (walletVoidStatus / WalletPropagationStatus)
Volgt de asynchrone propagatie van ongeldigmakings- of updatestatus naar Apple APNs en Google Wallet op het veld Pass.walletVoidStatus:
-
NONE: Geen propagatie in behandeling. -
PENDING: Status vastgelegd in database; wacht op plaatsing in wachtrij. -
QUEUED: Verzonden naar background job queue wallet-syncworkers. -
SUCCEEDED: Apple APNs-wakeup of Google RESTPATCHbevestigd. -
FAILED: Downstream wallet-push mislukt (komt in aanmerking voor automatische herpoging of handmatige regeneratie).
Aangepaste eigenschappen & dynamische tokeninterpolatie
Passinstance gebruikt dynamische accolade-syntaxis {propertyName} om klantgegevens aan pasvelden te koppelen:
-
Syntaxis: Plaats
{firstName},{pointsBalance}of{membershipTier}in een label of waarde van een primair, secundair, aanvullend of achterkantveld. -
Wijzigingsmeldingen: Configureer
changeMessage: "U heeft een stempel verdiend! U heeft nu %@ stempels."op Apple Wallet-velden. Bij een update wordt het%@-token vervangen door de nieuwe waarde, wat direct een melding op het iOS-toegangsscherm genereert. -
Waarden met attributen: Achterkantvelden van Apple Wallet ondersteunen HTML-ankertags (
<a href="https://example.com">Voorwaarden</a>) voor klikbare weblinks, telefoonnummers en e-mailadressen.
Belangrijk: Facturatiecapaciteit meet Actieve Wallet-passen (het totale aantal apparaten dat momenteel is geregistreerd via Apple APNs of Google Wallet-objecten), in plaats van niet-uitgegeven conceptrecords of verlopen passen.
