Overzicht: hoe live passynchronisatie werkt
In tegenstelling tot statische pdf-tickets of afbeeldingsbarcodes blijven digitale wallet-passen die door Passinstance worden beheerd ook na installatie dynamisch verbonden met de cloud. Telkens wanneer een paseigenschap, mechanieksaldo (stempels, loyaliteitspunten, prepaidtegoed), niveaustatus of sjabloonontwerp wijzigt, orkestreert Passinstance een asynchrone Wallet Propagation Pipeline die de live pas bijwerkt op de iPhone, Apple Watch en het Android-apparaat van de klant.
Levenscyclus van wallet-propagatiestatus (walletVoidStatus / WalletPropagationStatus)
Elk pasrecord houdt de ongeldigmakings-/propagatiestatus over Apple- en Google-cloudnetwerken bij via Pass.walletVoidStatus (WalletPropagationStatus):
| Statusenum | Betekenis & operationele status |
|---|---|
NONE | De pas is aangemaakt of er is geen voor de wallet zichtbare propagatie in de wachtrij geplaatst. |
PENDING | Een veld-, mechanieksaldo- of ongeldigmakings-/sjabloonrevisie is opgeslagen en wacht op verzending via de background job queue-wachtrij. |
QUEUED | Geplaatst in de in-memory cache/background job queue wallet-propagatieworkerwachtrij voor uitvoering via APNs en Google REST. |
SUCCEEDED | De APNs-pushmelding is geaccepteerd door de HTTP/2-gateway van Apple (200 OK) en/of de Google Wallet REST PATCH is geslaagd. |
FAILED | De propagatie stuitte op een upstreamfout (bijv. verlopen Apple Pass Type-certificaat, ingetrokken APNs-token 410 Gone of Google API-quotafout). |
Belangrijk: Het publiceren van een sjabloonconcept via
POST /api/v1/templates/:id/publishmetpropagateUpdates: trueverdeelt propagatietaken over alle actieve passen die aan dat sjabloon gekoppeld zijn (te filteren metactivePassesOnly: true). Voer altijd eerstGET /api/v1/templates/:id/publish-risk-checkuit om kritieke wijzigingen en mogelijke effecten te controleren.
API-endpoints voor het bijwerken van passen
| Methode | Endpointpad | Beschrijving |
|---|---|---|
| PATCH | /api/v1/passes/:id | Werkt aangepaste eigenschappen, status, vervaldatum of barcodepayload van een enkele pas bij en start wallet-propagatie. |
| POST | /api/v1/passes/upsert-by-external-id | Maakt idempotent een pas aan of werkt een bestaande pas bij die overeenkomt met (customerId, externalId) (PUT /api/v1/passes/by-external-id/:externalId wordt ook ondersteund). |
| POST | /api/v1/batch-pass-operations/update | Werkt geselecteerde passIds bij in één batchverzoek (request payload) en plaatst propagatietaken in de wachtrij. |
| POST | /api/v1/templates/:id/publish | Promoveert een sjabloonconcept (request payload met propagateUpdates: true) en vernieuwt actieve passen van dat sjabloon. |
Voorbeeld: update van één pas & propagatietrigger
PATCH /api/v1/passes/c41a8d20-6e11-4f3b-9a81-0029d81a4f10
{
"attributes": {
"points": 1450,
"tier": "Platinum",
"nextReward": "Free Espresso"
},
"expirationDate": "2027-12-31 23:59"
}
Respons (200 OK):
{
"id": "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"externalId": "cust_884910",
"serialNumber": "PI-8849-2026-X9",
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "QUEUED",
"updatedAt": "2026-11-15T14:22:10.114Z"
}
Voorbeeld: batch-arrayupdate van passen (request payload)
POST /api/v1/batch-pass-operations/update
{
"operation": "update",
"passIds": [
"c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"9b2f1e44-8a10-4c92-a711-5530e91b2c01"
],
"updateData": {
"attributes": {
"seasonalOffer": "Winter Bonus Points"
}
}
}
Waarom synchronisatietijden per apparaat kunnen verschillen
-
Vliegtuigmodus & Databesparingsmodus: iOS-apparaten in Vliegtuigmodus of Energiebesparingsmodus stellen APNs-achtergrondophalingen uit totdat de wifi- of mobiele verbinding hersteld is.
-
Schakelaar voor handmatig vernieuwen: Klanten die Automatische updates ("Automatic Updates") op de achterkant van hun Apple Wallet-pas hebben uitgeschakeld, moeten binnen Apple Wallet handmatig omlaag vegen om de nieuwste
.pkpass-bundel op te halen. -
Onderdrukking bij ongeldig verklaarde passen: Standaard onderdrukken passen in de status
VOIDEDofEXPIREDroutinematige marketingpushes, tenzijupdateVoidedExpiredPasses: trueis ingeschakeld op het sjabloon.
Raadpleeg Pushmeldingen, Passen bekijken & bijwerken en Sjabloonversies & publicatie voor verwante workflows.
