Skip to content
Helpcentrum-gids · Introductie tot PassinstanceOnboardingfase 1
4 min leestijdGecontroleerd 2026-11-16

Hoe Passinstance werkt

Volg de volledige architectuur van sjabloonontwerp en ondertekening tot scannen, updates en analyses.

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

Werkruimte-dashboard — Live KPI's & trends (Ingezoomd)

Volg in productie direct Active in Wallets, Removed, Not Installed en de uitgifte- en registratiecurves.

Overzicht

Passinstance automatiseert de levenscyclus van digitale passen voor ontwerp, cryptografische verpakking, meerkanaalsdistributie, kassavalidatie en stille pushsynchronisatie. Door de visuele lay-outconfiguratie te scheiden van de bedrijfslogicamechanieken en communicatieprotocollen voor apparaten, levert het platform een uniforme ervaring op zowel iOS- als Android-ecosystemen.

Technische keten van begin tot eind

Het onderstaande sequentiediagram beschrijft de volledige stroom vanaf het aanmaken van het sjabloon tot realtime wallet-synchronisatie:

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
END-TO-END PASLEVENSCYCLUS
DEELNEMENDE SYSTEEMACTOREN
P1 Admin / API Client
P2 Passinstance Core API
P3 Apple / Google Cloud
P4 Klantapparaat
STAP 1 VERZOEK / ACTIE POST/api/v1/templates
›
(Lay-out & mechanieken)
STAP 2 VERZOEK / ACTIE POST/api/v1/passes
STAP 3 VERZOEK / ACTIE Teken .pkpass(PKCS#7)
STAP 4 VERZOEK / ACTIE Genereer Google JWT
›
Retourneert download-URL
›
(https://app.passinstance.com/d/:slug of /p/:passId)
STAP 5 VERZOEK / ACTIE Klant opent slimme downloadlink
›
(Browser herkent OS)
STAP 6 ANTWOORD Apparaat registreert (POST/v1/devices)
›
(Apple pushToken opgeslagen in Passinstance database)
STAP 7 VERZOEK / ACTIE Kassascan aan balie (POST/api/v1/scans)
›
(Header: x-scanner-key, Body: { scannedBarcodeValue })
STAP 8 VERZOEK / ACTIE Mechaniek uitvoeren
›
(Stempels/punten ophogen)
STAP 9 VERZOEK / ACTIE Stille push sturen
›
(Lege APNs-payload)
STAP 10 VERZOEK / ACTIE Stille APNs-wakeup
STAP 11 ANTWOORD Bijgewerkte pas ophalen (GET/v1/passes)
STAP 12 VERZOEK / ACTIE Nieuwe .pkpass leveren
›
(Toegangsschermmelding:
›
"Saldo bijgewerkt: %@")

Stapsgewijze technische levenscyclus

1. Sjabloonontwerp & versiebeheer

Elke pas komt voort uit een Template-record. Passinstance maakt gebruik van versiebeheer in één tabel dat wordt bijgehouden via TemplateRowKind (PRODUCTION, PUBLISHED, ARCHIVED, DRAFT) en template status (DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED). Conceptbewerkingen blijven geïsoleerd in een DRAFT-revisie totdat een beheerder of API-client POST /api/v1/templates/:id/publish uitvoert, waardoor het concept wordt gepromoveerd naar de canonieke PRODUCTION-basisrij en onveranderlijke PUBLISHED / ARCHIVED geschiedenissnapshots bewaard blijven. Vóór publicatie evalueert het platform GET /api/v1/templates/:id/publish-risk-check om kritieke veldwijzigingen te inspecteren en te berekenen hoeveel actieve passen worden bijgewerkt.

2. Cryptografische ondertekening, artefactstatus & pasuitgifte

Wanneer een pasrecord wordt gegenereerd (POST /api/v1/passes), herleidt de pasaanmaak templateId via resolvePassCreationTemplateId naar de actieve basisrij, koppelt optioneel een tenant-unieke externalId, respecteert de optionele header Idempotency-Key (idempotencyKey) en initialiseert appleArtifactStatus en googleArtifactStatus (ArtifactStatus: NOT_GENERATED -> GENERATING -> READY \| FAILED \| INVALIDATED):

  • Apple Wallet: Bij het downloaden verpakt Apple Wallet Packager pass.json, maximaal 13 afbeeldingsposities (image asset slot, inclusief @2x- en @3x-retinavarianten) en gelokaliseerde pass.strings in een .pkpass-ziparchief, berekent manifest.json-hashes en ondertekent het manifest met een losse PKCS#7-versleuteling met uw Apple Pass Type ID- en Apple WWDR-certificaten. Meerdere bijbehorende passen die een bundleId (Pass.bundleId) delen, kunnen gezamenlijk als een .pkpasses-archief worden geleverd.
  • Google Wallet: De backend synchroniseert klassedefinities (LoyaltyClass, EventTicketClass, GenericClass, enz.) met de REST API's van Google Wallet en ondertekent een RS256 JWT Save URL (https://pay.google.com/gp/v/save/:jwt).

Passinstance verstrekt canonieke slimme presentatie-URL's (https://app.passinstance.com/d/:slug, https://app.passinstance.com/p/:passId of /s/:token op API-/eigen domeinen). Wanneer een eindgebruiker deze opent:

  • Openbaar download-endpoint (GET /d/:slug/download) detecteert de user-agent:

- iOS Safari ontvangt een HTTP-respons met MIME-type application/vnd.apple.pkpass, waardoor het native toevoegvenster van Apple Wallet wordt geopend. - Android Chrome wordt doorgestuurd naar https://pay.google.com/gp/v/save/:jwt, waarmee Google Wallet wordt geopend. - Desktopbrowsers tonen de PassFlow-downloadpagina met een contrastrijke QR-code (GET /d/:slug/qr) en optionele zelfverzending per e-mail of sms.

4. Apparaatregistratie & webservice-handshake

Na het opslaan in Apple Wallet start het iOS-apparaat het officiële Apple Wallet Web Service-protocol:

  • Het verstuurt POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber met de header Authorization: ApplePass <authenticationToken>.
  • Passinstance valideert het token en slaat het pushToken van het apparaat op in de database, waarmee de passtatus overgaat van AWAITING_OPT_IN naar ACTIVE.

5. Kassavalidatie & uitvoering van mechanieken

Bij fysiek afrekenen of inchecken op locatie scant een medewerker de pas met de Passinstance Scanner-app of een geïntegreerd kassasysteem:

  • Er wordt een verzoek verstuurd naar POST /api/v1/scans, geauthenticeerd via x-scanner-key.
  • De Pass Mechanics Engine evalueert actieve regels (bijv. stempels toevoegen, prepaidtegoed afschrijven, eenmalige kortingsbonnen valideren of dagelijkse aanwezigheid verifiëren).

6. Stille cloud-pushsynchronisatie

Wanneer pasgegevens wijzigen:

  • Passinstance verstuurt een lege JSON-payload {} via HTTP/2 naar Apple APNs-servers.
  • Het Apple-apparaat wordt op de achtergrond stil gewekt, bevraagt GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag> en downloadt de bijgewerkte .pkpass-bundel.
  • Elk veld met een geconfigureerde changeMessage die de tijdelijke aanduiding %@ bevat, genereert een native iOS-melding op het toegangsscherm.
  • Gelijktijdig stuurt Passinstance een REST PATCH-verzoek naar het Google Wallet walletobjects-endpoint, waarmee de Android-pas in realtime wordt bijgewerkt.
Dashboardoverzicht trends en KPI's
Dashboardoverzicht trends en KPI's

Belangrijkste API-endpoints & HTTP-methoden

EndpointpadHTTP-methodeAuthenticatieFunctionaliteit
/api/v1/templatesPOSTBearer / API-sleutelEen nieuwe passjabloondefinitie aanmaken
/api/v1/templates/:id/publishPOSTBearer / API-sleutelConceptsjabloon promoveren naar actieve productieversie
/api/v1/passesPOSTBearer / API-sleutelEen nieuwe pas uitgeven met aangepaste veldwaarden
/api/v1/passes/:idPATCHBearer / API-sleutelBestaande paseigenschappen bijwerken en push in wachtrij plaatsen
/api/v1/scansPOSTx-scanner-keyPasbarcode valideren, mechaniek toepassen, scan vastleggen
/v1/devices/...POSTApplePass <token>Callback voor apparaatregistratie van Apple Wallet

Belangrijk: Apple Wallet-updates werken op basis van ophalen (pull): Passinstance verstuurt geen pasgegevens binnen de APNs-melding zelf. In plaats daarvan geeft een leeg APNs-wake-upsignaal het Apple-apparaat opdracht om veilig de nieuwste ondertekende .pkpass op te halen bij de servers van Passinstance.

Bekijk de volledige onboardinggids in 6 fasen of raadpleeg onze API-architectuur.

Gerelateerde product- en ontwikkelaarsdocs

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.