Skip to content
Helpcentrum-gids · Introductie tot PassinstanceOnboardingfase 2
5 min leestijdGecontroleerd 2026-11-16

Kernbegrippen & terminologie

Duidelijke uitleg van Sjablonen, Passes, Mechanieken, Attributen, Wallet Experiences (Projecten), PassFlow en Actieve registraties.

In deze gids

Interactieve UI-weergaven

Openen in onboardinggids (6 fasen)

Bekijk de exacte dashboardpanelen, knoppen en ingezoomde toelichtingen bij deze gids.

Ingezoomde UI-focus
Belangrijke UI-onderdelen

Aangepaste eigenschappen & attributen (Ingesneden)

Definieer herbruikbare klantattributen ({serviceOrDuration}, {holderName}, {passReference}, {validUntil}, {memberQrToken}) en stel gegevenstypen en validatieregels in.

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.

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
ENTITEITSRELATIES
FASE 01 Template (Blauwdruk & versiebeheer)
Lay-out: StoreCard, EventTicket, Coupon, Membership
Kleuren, barcodetype, veldtoewijzing, afbeeldingsposities
FASE 02 1:N Uitgifte | 1:1 Regelkoppeling
Pass (Concrete instantie)
SerialNumber & AuthToken
Dynamische veldwaarden
Status & ExpirationDate
1:N Apparaatregistratie (Apple A
pass mechanic (Statusengine)
Type: STAMP_CARD_ADD, LOYALTY_PROGRAM, PREPAID_CARD,
VALID_ONCE_PER_DAY
Saves)

Schema van backendentiteiten & Passinstance database-modeltoewijzing

Elk platformconcept komt rechtstreeks overeen met een gestructureerde Passinstance database-entiteit binnen de databaselaag van Passinstance API:

ConceptPassinstance database-modelVerantwoordelijkheden & opgeslagen eigenschappen
TemplateTemplateSlaat 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).
PassPassVertegenwoordigt 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 Mechanicpass mechanicConfigureert toestandsafhankelijke regels die aan een sjabloon gekoppeld zijn. Slaat mechanicType (mechanic type), minimumValue, maximumValue, defaultChangeValue, niveaus (PassTier) en limietregels op.
Prepaid Accountprepaid accountBeheert opgeslagen geldwaarde voor cadeau- en prepaidkaarten. Houdt saldi in gehele eenheden bij en koppelt aan onveranderlijke prepaid ledger entry-transactielogboeken.
Pass Bundlepass bundleGroepeert maximaal 10 bijbehorende passen via Pass.bundleId (bundle grouping mode: `AUTO \MANUAL, BundleStatus: ACTIVE \CANCELLED) om multi-card .pkpasses`-archieven te downloaden.
Wallet ExperiencePassProjectOrkestreert een primair sjabloon (mainTemplateId) en gekoppelde sjablonen (PassProjectTemplateRole: `PRIMARY \LINKED \PRIVACY_MODE \INACTIVE \VIP \CUSTOM`), uniforme claimpagina's, bundels, segmenten en visuele automatiseringsstromen.
PassFlowPassFlowBeheert meerstaps selfservice-intakepagina's (/f/:url, PassFlowType, PassFlowStatus) met aanpasbare formulieren, sms-/e-mail-OTP-verificatie, botbescherming (SpamProtectionMode), betaalgateways en directe wallet-overdrachten.
Scanner ConfigurationScannerConfigurationConfigureert 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:

VeldPassinstance database-kolom / BereikVeranderlijkheid & formaatPrimair doel
idUUID primaire sleutelDoor systeem gegenereerd, onveranderlijkInterne API-resourcereferentie (GET /api/v1/passes/:id).
serialNumberWereldwijd unieke tekenreeksDoor systeem gegenereerd (of aangepast indien geconfigureerd), onveranderlijkCanonieke Apple Wallet .pkpass-identificatie en Google-objectachtervoegsel.
externalId@unique([customerId, externalId]) waar archivedAt IS NULLDoor 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.
bundleIdbundleId (UUID foreign key naar pass bundle)Door systeem beheerd via /api/v1/bundles/* of PassProjectGroepeert 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 / authenticationTokenBeveiligingstokens per pasDoor systeem gegenereerde cryptografische tekenreeksenOpenbare 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 de expirationDate; scanners weigeren met reden PASS_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 met PASS_VOIDED.

Paslevenscyclus, verwijdermodus & artefactgereedheid

  • PassLifecycleStatus: Beheert onomkeerbare ongeldigverklaring en opschoningstransities:
TEXT
ACTIVE  --->  VOIDING  --->  VOIDED  --->  DELETING  --->  DELETED
  • PassDeletionMode: Maakt onderscheid tussen zachte verwijdering (SOFT, behoudt auditgeschiedenis en maakt externalId-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 REST PATCH bevestigd.
  • 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.

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.