Overzicht
Met individuele pasuitgifte kunnen beheerders en backendintegraties één gepersonaliseerde digitale wallet-pas genereren vanuit elk PUBLISHED-sjabloon. Of dit nu handmatig wordt gestart vanuit het paneel Pas maken in het Dashboard of programmatisch via de REST API: Passinstance kent een cryptografisch uniek serialNumber en authenticationToken toe, vult alle dynamische {variable}-velden, ondertekent de Apple .pkpass-bundel en Google Wallet JWT en retourneert direct een slimme distributie-URL (passAccessUrl).

Systeemarchitectuur: enkele pasuitgifte & idempotente upsert
Handmatig een enkele pas uitgeven in het dashboard
-
1
Navigeer naar de overzichtspagina van uw Gepubliceerde sjabloon.
-
2
Klik op Pas maken in de bovenste kopbalk (of onder Snelle acties).
-
3
Vul alle Verplichte aangepaste eigenschappen op het formulier in (bijvoorbeeld klantnaam, e-mailadres/telefoonnummer voor verzendingen, startaantal stempels of
externalId). -
4
Verstuur het formulier om de pas direct te genereren.
-
5
Kopieer de unieke Download-URL (
passAccessUrl), toon de Installatie-QR-code om met een smartphone te scannen of verstuur direct vanuit het detailpaneel van de pas een bezorgings-e-mail.
Vereisten: Publiceer uw sjabloon (
POST /api/v1/templates/:id/publish) met geldige Apple Pass Type ID- / Google Wallet-gegevens voordat u live passen uitgeeft. Intern herleidtresolvePassCreationTemplateIdtemplateIdnaar de onderliggendePRODUCTION/PUBLISHED-basisrevisie en weigert het sjablonen met statusDELETING/DELETED(BadRequestException/NotFoundException).
API-referentie voor programmatische uitgifte
1. Een nieuwe pas maken (POST /api/v1/passes)
Maakt een nieuw pasrecord aan via request payload, met ondersteuning voor een optionele HTTP-header Idempotency-Key (idempotencyKey, max. 128 tekens volgens [A-Za-z0-9._:-]+, beveiligd met een SHA-256-requestdigest) en optionele queryparameters ?includePassSource=apple|google en ?pin=.
request payload-verzoekparameters
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
templateId | string (UUID) | Ja | Sjabloon-UUID (automatisch herleid naar de live PRODUCTION/PUBLISHED-basisrij). |
externalId | string | Optioneel | Tenant-unieke CRM-/POS-/orderidentificatie (max. 255 tekens; afgedwongen uniek per actieve, niet-verwijderde pas via @@unique([customerId, externalId])). |
serialNumber | string | Optioneel | Aangepast uniek serienummer (automatisch gegenereerd indien weggelaten). |
barcodeValue | string | Optioneel | Expliciete barcodepayload. Gebruikt anders de sjabloonbarcodeconfiguratie of een gegenereerde waarde. |
barcodeAltText / barcodeAlternativeText | string | Optioneel | Voor mensen leesbaar bijschrift onder de barcode voor handmatige invoer aan de kassa. |
attributes | Record<string, any> | Optioneel | structured JSON sleutel-waardewoordenboek dat overeenkomt met de sleutels van uw Aangepaste eigenschappen op het sjabloon. |
expirationDate | string | Optioneel | Vervaldatum/-tijd (<= 10 jaar in de toekomst, verwerkt in de workspace-tijdzone). |
validityAsOfDate / validAsOfDate | string | Optioneel | Begindatum/-tijd van geldigheid (issuedDate). |
enableDownloadUntil | string | Optioneel | Einddatum voor downloaden ("YYYY-MM-DD HH:mm" of ISO-tijdstempel). |
sharingProhibited | boolean | Optioneel | Overschrijft de antideelinstelling van het sjabloon (limitToOneActivePerPass). |
validationPlaces | string[] | Optioneel | Overschrijvingen voor toegestane validatielocaties indien ingeschakeld op het sjabloon. |
skipDistributeOnCreate | boolean | Optioneel | Onderdrukt automatische verzendingen (e-mail/sms) na aanmaak bij API-uitgifte. |
Voorbeeldverzoek
POST /api/v1/passes?includePassSource=google Headers: X-API-Key: <API_KEY> | Content-Type: application/json | Idempotency-Key: crm_usr_44910_v1
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44910",
"serialNumber": "PI-GOLD-2026-44910",
"barcodeValue": "PI-GOLD-2026-44910",
"barcodeAltText": "44910-GOLD",
"expirationDate": "2027-12-31 23:59",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"email": "marcus.vance@example.com",
"pointsBalance": 500,
"memberTier": "Gold"
}
}
Voorbeeldrespons (API response envelope)
{
"success": true,
"data": {
"id": "pass_01j8k9m2n3p4q5r6",
"templateId": "tmpl_01hxyz987654321",
"customerId": "cust_ws_88219",
"externalId": "crm_usr_44910",
"bundleId": null,
"idempotencyKey": "crm_usr_44910_v1",
"serialNumber": "PI-GOLD-2026-44910",
"authenticationToken": "a9f4e2c81b7d60359e12c4b8f7a6d5e0",
"downloadCode": "dl_94f8a1",
"barcodeValue": "PI-GOLD-2026-44910",
"barcodeAltText": "44910-GOLD",
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "NONE",
"appleArtifactStatus": "NOT_GENERATED",
"googleArtifactStatus": "READY",
"downloadUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
"passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"email": "marcus.vance@example.com",
"pointsBalance": 500,
"memberTier": "Gold"
},
"expirationDate": "2027-12-31T23:59:00.000Z",
"createdAt": "2026-11-15T15:04:12.000Z"
},
"description": "Pass created successfully",
"errors": [],
"statusCode": 201
}
Tip — Meerdere passen bundelen (
bundleId): Als u bijbehorende passen aanmaakt voor een huishouden, vluchtsegment of VIP-evenementbestelling, wijs ze dan toe aan eenpass bundle(/api/v1/bundles/upsertofPassProject), zodatPass.bundleIdmaximaal10passen groepeert in één uniforme.pkpasses/ multi-card claimlink.
2. Idempotente upsert & opzoeken op External ID (request payload)
Bij webhookgestuurde integraties (Shopify, HubSpot of POS-kassa's) kunnen netwerkherpogingen hetzelfde verzoek herhaaldelijk versturen. Passinstance biedt specifieke externalId-endpoints binnen de scope van uw actieve tenantpassen (archivedAt: null):
-
POST /api/v1/passes/upsert-by-external-id: Maakt een pas aan als geen actieve pas overeenkomt metexternalId(action: "CREATED"), of voegtattributes,expirationDate,status(pass status) en optionelechangeMessage(<=500tekens) samen op de bestaande pas (action: "UPDATED"). -
PUT /api/v1/passes/by-external-id/:externalId: Voert een upsert uit met de padparameter:externalId(externalIdin de body moet overeenkomen of kan worden weggelaten). -
GET /api/v1/passes/by-external-id/:externalId: Haalt de actieve pas direct op viaexternalIdzonder dat u intern UUID's extern hoeft op te slaan.
Voorbeeldverzoek
POST /api/v1/passes/upsert-by-external-id Headers: X-API-Key: <API_KEY> | Content-Type: application/json
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44910",
"status": "ACTIVE",
"changeMessage": "Tier updated to Platinum (%@ pts)",
"attributes": {
"pointsBalance": 750,
"memberTier": "Platinum"
}
}
Voorbeeldrespons (200 OK)
{
"success": true,
"data": {
"pass": {
"id": "pass_01j8k9m2n3p4q5r6",
"externalId": "crm_usr_44910",
"serialNumber": "PI-GOLD-2026-44910",
"status": "ACTIVE",
"walletVoidStatus": "QUEUED"
},
"action": "UPDATED"
},
"description": "Pass updated successfully",
"errors": [],
"statusCode": 200
}
Voor grootschalige CSV-onboarding of batchgeneratie van JSON-arrays raadpleegt u Passen in bulk aanmaken en Bulkacties.
