Overzicht
Open Passen in het Dashboard (hetzij in de algemene workspace-directory, hetzij binnen het tabblad Passen van een specifiek sjabloon) of bevraag /api/v1/passes om uitgegeven pasrecords in realtime te inspecteren, filteren, controleren, bijwerken en migreren. Elke wijziging aan de velden of sjabloontoewijzing van een pasrecord wordt automatisch gesynchroniseerd naar geregistreerde Apple Wallet- en Google Wallet-apparaten.

Systeemarchitectuur: pasquery's, mutaties & sjabloonwisseling
1. Passen zoeken & filteren (GET /api/v1/passes)
Open in het Dashboard Filters om EN / OF-voorwaardegroepen te combineren over systeemkolommen en aangepaste structured JSON-eigenschappen, en sla veelgebruikte query's op als Opgeslagen weergaven:
-
Identiteit & sleutels:
serialNumber,externalId,bundleId,idempotencyKeyof pas-id. -
Levenscyclus & status:
status(pass status),lifecycleStatus(PassLifecycleStatus),walletVoidStatus(WalletPropagationStatus) en artefactgereedheid (appleArtifactStatus,googleArtifactStatus). -
Wallet-installatiestatus:
Installed(Geïnstalleerd),Not Installed(Niet geïnstalleerd) ofRemoved(Verwijderd) voor apparaatregistraties in Apple Wallet (iOS) en Google Wallet (Android). -
Datumbereiken: Bereikfilters voor
createdAt,updatedAt,expirationDateenlastScannedAt. -
Aangepaste structured JSON-eigenschappen (
attribute search index): Razendsnelle inclusie- en vergelijkingsfilters op elke sleutel binnenpass.attributes(bijvoorbeeldattributes.memberTier = "VIP"ofattributes.pointsBalance >= 1000).

Voorbeeld: passen opvragen & opzoeken via External ID
-
GET /api/v1/passes?templateId=tmpl_01hxyz987654321&status=ACTIVE&externalId=crm_usr_44910&page=1&limit=25 -
GET /api/v1/passes/by-external-id/crm_usr_44910(retourneert de actieve, niet-verwijderde pas die overeenkomt metexternalIdrechtstreeks zonder dat u interne UUID's extern hoeft op te slaan)
2. Een individuele pas bijwerken (PATCH /api/v1/passes/:id)
Het bijwerken van een pas voegt nieuwe waarden samen in attributes, past expirationDate of barcodeValue aan en plaatst direct een pushupdate in de wachtrij voor alle apparaten waarop de pas is geïnstalleerd. Als op het sjabloon voor een gewijzigd veld een changeMessage met %@ is geconfigureerd, toont Apple Wallet een native melding op het toegangsscherm.
HTTP-verzoek
PATCH /api/v1/passes/pass_01j8k9m2n3p4q5r6 Headers: X-API-Key: <API_KEY> | Content-Type: application/json
{
"attributes": {
"pointsBalance": 1450,
"memberTier": "Platinum"
},
"barcodeAltText": "44910-PLATINUM",
"expirationDate": "2028-12-31 23:59"
}
HTTP-respons (200 OK)
{
"success": true,
"data": {
"id": "pass_01j8k9m2n3p4q5r6",
"serialNumber": "PI-GOLD-2026-44910",
"externalId": "crm_usr_44910",
"bundleId": null,
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "QUEUED",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"email": "marcus.vance@example.com",
"pointsBalance": 1450,
"memberTier": "Platinum"
},
"updatedAt": "2026-11-15T17:30:00.000Z"
},
"statusCode": 200
}
3. Pasgeschiedenis & gebeurtenissentijdlijn controleren
Passinstance houdt voor elk pasrecord twee aanvullende auditstreams bij:
| Endpoint | Bereik & geretourneerde gegevens | |||
|---|---|---|---|---|
GET /api/v1/passes/:id/history | Retourneert chronologische veld- en eigenschapsmutaties (previousValue, newValue, changedBy, `source: 'API' \ | 'SCANNER' \ | 'DASHBOARD' \ | 'WORKFLOW', timestamp`). |
GET /api/v1/passes/:id/timeline | Retourneert de gecombineerde levenscyclus- en interactiestream, waarin pasaanmaak, e-mail-/sms-bezorggebeurtenissen, Apple-/Google-apparaatinstallaties, scannervalidaties, saldowijzigingen en pushmeldingen samenkomen. |
Voorbeeld: pastijdlijn ophalen
/api/v1/passes/pass_01j8k9m2n3p4q5r6/timeline
{
"success": true,
"data": {
"passId": "pass_01j8k9m2n3p4q5r6",
"events": [
{
"eventId": "evt_03",
"type": "ATTRIBUTE_UPDATED",
"summary": "pointsBalance changed from 500 to 1450",
"actor": "api_key:pi_live_99a8",
"createdAt": "2026-11-15T17:30:00.000Z"
},
{
"eventId": "evt_02",
"type": "WALLET_INSTALLED",
"platform": "APPLE_WALLET",
"deviceLibraryIdentifier": "dlib_8841209a",
"createdAt": "2026-11-15T15:10:05.000Z"
},
{
"eventId": "evt_01",
"type": "PASS_CREATED",
"summary": "Pass issued via REST API",
"createdAt": "2026-11-15T15:04:12.000Z"
}
]
},
"statusCode": 200
}
4. Live sjabloonmigratie (POST /api/v1/passes/:id/switch-template/:targetTemplateId)
Wanneer een klant promoveert naar een hoger niveau-ontwerp of overstapt naar een seizoensprogramma, kunt u een bestaande pas migreren naar een ander PUBLISHED-sjabloon zonder het id, serialNumber, authenticationToken of de actieve apparaatregistraties van de pas te wijzigen.
POST /api/v1/passes/pass_01j8k9m2n3p4q5r6/switch-template/tmpl_platinum_vip_999 Headers: X-API-Key: <API_KEY> | Content-Type: application/json
{
"preserveAttributes": true,
"attributeOverrides": {
"vipLoungeAccess": "Unlimited"
},
"pushUpdateImmediately": true
}
Belangrijk: Om een pas naadloos over te zetten naar
:targetTemplateIdop Apple Wallet-apparaten, moeten zowel het bronsjabloon als het doelsjabloon hetzelfde ApplepassTypeIdentifier(Pass Type ID-certificaat) delen. Als het doelsjabloon een andere Pass Type ID gebruikt, behandelt iOS de pas als een afzonderlijke kaart in plaats van een vervanging ter plaatse.
Voor statusovergangen en regels voor ongeldigverklaring zie Paslevenscyclus & statussen. Voor updates op meerdere records tegelijk zie Bulkacties.
