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:
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 Packagerpass.json, maximaal 13 afbeeldingsposities (image asset slot, inclusief@2x- en@3x-retinavarianten) en gelokaliseerdepass.stringsin een.pkpass-ziparchief, berekentmanifest.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 eenbundleId(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 eenRS256JWT Save URL (https://pay.google.com/gp/v/save/:jwt).
3. Distributie via slimme links
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/:serialNumbermet de headerAuthorization: ApplePass <authenticationToken>. -
Passinstance valideert het token en slaat het
pushTokenvan het apparaat op in de database, waarmee de passtatus overgaat vanAWAITING_OPT_INnaarACTIVE.
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 viax-scanner-key. -
De
Pass Mechanics Engineevalueert 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
changeMessagedie de tijdelijke aanduiding%@bevat, genereert een native iOS-melding op het toegangsscherm. -
Gelijktijdig stuurt Passinstance een REST
PATCH-verzoek naar het Google Walletwalletobjects-endpoint, waarmee de Android-pas in realtime wordt bijgewerkt.

Belangrijkste API-endpoints & HTTP-methoden
| Endpointpad | HTTP-methode | Authenticatie | Functionaliteit |
|---|---|---|---|
/api/v1/templates | POST | Bearer / API-sleutel | Een nieuwe passjabloondefinitie aanmaken |
/api/v1/templates/:id/publish | POST | Bearer / API-sleutel | Conceptsjabloon promoveren naar actieve productieversie |
/api/v1/passes | POST | Bearer / API-sleutel | Een nieuwe pas uitgeven met aangepaste veldwaarden |
/api/v1/passes/:id | PATCH | Bearer / API-sleutel | Bestaande paseigenschappen bijwerken en push in wachtrij plaatsen |
/api/v1/scans | POST | x-scanner-key | Pasbarcode valideren, mechaniek toepassen, scan vastleggen |
/v1/devices/... | POST | ApplePass <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
.pkpassop te halen bij de servers van Passinstance.
Bekijk de volledige onboardinggids in 6 fasen of raadpleeg onze API-architectuur.
