Skip to content
Helpcentrum-gids · Wallet-updates & meldingen
3 min leestijdGecontroleerd 2026-11-16

Bestaande passen bijwerken

Lees hoe serverwijzigingen stille APNs-updates op Apple Wallet en object-patches op Google Wallet versturen.

In deze gids

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.

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
PIPELINE VOOR WALLET-UPDATES & PROPAGATIE
FASE 01 MUTATIE-TRIGGERBRONNEN
Enkele update: PATCH/api/v1/passes/:id of POST.../upsert-by-external-id
Batch array-update: POST/api/v1/batch-pass-operations/update
Sjabloonpublicatie: POST/api/v1/templates/:id/publish (propagateUpdates)
Scanner / POS: POST/api/v1/scans / POST/v1/pos/redeem / /api/v1/reader/redeem
FASE 02 DATABASECOMMIT & OVERGANG VAN PROPAGATIESTATUS
1
Verhoog pasrevisie & leg pass audit log-auditlogboek vast
2
Zet walletVoidStatus (WalletPropagationStatus): NONEPENDINGQUEUED
3
Plaats background job queue-propagatietaak in wachtrij (wallet-propagation wachtrij)
Apple Wallet-apparaatregistraties
FASE 03A
1
Apple Push Delivery stuurt lege HTTP push {} naar elk gereg. apparaat
2
iOS ontwaakt & pollt:GET/v1/devices/.../registrations
3
iOS haalt nieuwe ondertekende .pkpassGET/v1/passes/:typeId/:serial`
Google Wallet-cloudobject
FASE 03B
1
Google Wallet Sync voert geauthenticeerde REST PATCH uit op walletobjects/v1/...
2
Google Cloud pusht bijgewerkte objectstatus naar Android-apparaten via Google Play Services
FASE 04 DEFINITIEVE TELEMETRIE & UPDATE VAN PROPAGATIESTATUS
walletVoidStatus (WalletPropagationStatus): SUCCEEDED of FAILED

Levenscyclus van wallet-propagatiestatus (walletVoidStatus / WalletPropagationStatus)

Elk pasrecord houdt de ongeldigmakings-/propagatiestatus over Apple- en Google-cloudnetwerken bij via Pass.walletVoidStatus (WalletPropagationStatus):

StatusenumBetekenis & operationele status
NONEDe pas is aangemaakt of er is geen voor de wallet zichtbare propagatie in de wachtrij geplaatst.
PENDINGEen veld-, mechanieksaldo- of ongeldigmakings-/sjabloonrevisie is opgeslagen en wacht op verzending via de background job queue-wachtrij.
QUEUEDGeplaatst in de in-memory cache/background job queue wallet-propagatieworkerwachtrij voor uitvoering via APNs en Google REST.
SUCCEEDEDDe APNs-pushmelding is geaccepteerd door de HTTP/2-gateway van Apple (200 OK) en/of de Google Wallet REST PATCH is geslaagd.
FAILEDDe 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/publish met propagateUpdates: true verdeelt propagatietaken over alle actieve passen die aan dat sjabloon gekoppeld zijn (te filteren met activePassesOnly: true). Voer altijd eerst GET /api/v1/templates/:id/publish-risk-check uit om kritieke wijzigingen en mogelijke effecten te controleren.

API-endpoints voor het bijwerken van passen

MethodeEndpointpadBeschrijving
PATCH/api/v1/passes/:idWerkt aangepaste eigenschappen, status, vervaldatum of barcodepayload van een enkele pas bij en start wallet-propagatie.
POST/api/v1/passes/upsert-by-external-idMaakt 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/updateWerkt geselecteerde passIds bij in één batchverzoek (request payload) en plaatst propagatietaken in de wachtrij.
POST/api/v1/templates/:id/publishPromoveert een sjabloonconcept (request payload met propagateUpdates: true) en vernieuwt actieve passen van dat sjabloon.

Voorbeeld: update van één pas & propagatietrigger

JSON
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):

JSON
{
  "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)

JSON
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 VOIDED of EXPIRED routinematige marketingpushes, tenzij updateVoidedExpiredPasses: true is ingeschakeld op het sjabloon.

Raadpleeg Pushmeldingen, Passen bekijken & bijwerken en Sjabloonversies & publicatie voor verwante workflows.

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.