Skip to content
Helpcentrum-gids · Pass-uitgifteOnboardingfase 3
4 min leestijdGecontroleerd 2026-11-16

Individuele passen maken

Genereer één kaart op basis van een gepubliceerd sjabloon met directe QR- en testdownloadlink.

In deze gids

Interactieve UI-weergaven

Openen in onboardinggids (6 fasen)

Bekijk de exacte dashboardpanelen, knoppen en ingezoomde toelichtingen bij deze gids.

Ingezoomde UI-focus
Belangrijke UI-onderdelen

Enkele pas aanmaken & Snelle acties (Ingesneden)

Klik op '+ Create pass' in de koptekst of op 'Create single pass' onder Snelle acties om een testpas vanuit uw gepubliceerde sjabloon te genereren.

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).

Snelle sjabloonacties om een enkele pas te maken
Snelle sjabloonacties om een enkele pas te maken

Systeemarchitectuur: enkele pasuitgifte & idempotente upsert

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
ENKELE PASUITGIFTE & IDEMPOTENTE UPSERT
FASE 01 DASHBOARDPANEEL / CRM / POS-BACKEND
Standaard uitgifte: POST/api/v1/passes (request payload)
Idempotente upsert: POST/api/v1/passes/upsert-by-external-id
FASE 02 PASUITGIFTESERVICE (Pass Issuance Engine)
1
Verifieert of doel-Template PUBLISHED is & binnen workspace (customerId)
2
Evalueert samengestelde sleutel (customerId, externalId) voor ontdubbeling
3
Genereert uniek serialNumber & 32-byte hex authenticationToken
4
Valideert structured JSON attributes tegen sjabloonschema van Aangepaste eigenschappen
5
Slaat Pass-rij op (status: ACTIVE) & initialiseert pass mechanic-grootb.
FASE 03 WALLET-ONDERTEKENING & VERPAKKING VAN SLIMME LINK
Genereert slimme downloadlink (passAccessUrl) & QR-code-endpoint
Bereidt ondertekende Apple .pkpass-stream & Google Wallet Save JWT voor
Retourneert API response (request payload) met 201 Created of 200 OK

Handmatig een enkele pas uitgeven in het dashboard

  1. 1
    Navigeer naar de overzichtspagina van uw Gepubliceerde sjabloon.
  2. 2
    Klik op Pas maken in de bovenste kopbalk (of onder Snelle acties).
  3. 3
    Vul alle Verplichte aangepaste eigenschappen op het formulier in (bijvoorbeeld klantnaam, e-mailadres/telefoonnummer voor verzendingen, startaantal stempels of externalId).
  4. 4
    Verstuur het formulier om de pas direct te genereren.
  5. 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 herleidt resolvePassCreationTemplateId templateId naar de onderliggende PRODUCTION/PUBLISHED-basisrevisie en weigert het sjablonen met status DELETING/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

VeldTypeVerplichtBeschrijving
templateIdstring (UUID)JaSjabloon-UUID (automatisch herleid naar de live PRODUCTION/PUBLISHED-basisrij).
externalIdstringOptioneelTenant-unieke CRM-/POS-/orderidentificatie (max. 255 tekens; afgedwongen uniek per actieve, niet-verwijderde pas via @@unique([customerId, externalId])).
serialNumberstringOptioneelAangepast uniek serienummer (automatisch gegenereerd indien weggelaten).
barcodeValuestringOptioneelExpliciete barcodepayload. Gebruikt anders de sjabloonbarcodeconfiguratie of een gegenereerde waarde.
barcodeAltText / barcodeAlternativeTextstringOptioneelVoor mensen leesbaar bijschrift onder de barcode voor handmatige invoer aan de kassa.
attributesRecord<string, any>Optioneelstructured JSON sleutel-waardewoordenboek dat overeenkomt met de sleutels van uw Aangepaste eigenschappen op het sjabloon.
expirationDatestringOptioneelVervaldatum/-tijd (<= 10 jaar in de toekomst, verwerkt in de workspace-tijdzone).
validityAsOfDate / validAsOfDatestringOptioneelBegindatum/-tijd van geldigheid (issuedDate).
enableDownloadUntilstringOptioneelEinddatum voor downloaden ("YYYY-MM-DD HH:mm" of ISO-tijdstempel).
sharingProhibitedbooleanOptioneelOverschrijft de antideelinstelling van het sjabloon (limitToOneActivePerPass).
validationPlacesstring[]OptioneelOverschrijvingen voor toegestane validatielocaties indien ingeschakeld op het sjabloon.
skipDistributeOnCreatebooleanOptioneelOnderdrukt 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

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

JSON
{
  "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 een pass bundle (/api/v1/bundles/upsert of PassProject), zodat Pass.bundleId maximaal 10 passen 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 met externalId (action: "CREATED"), of voegt attributes, expirationDate, status (pass status) en optionele changeMessage (<=500 tekens) samen op de bestaande pas (action: "UPDATED").
  • PUT /api/v1/passes/by-external-id/:externalId: Voert een upsert uit met de padparameter :externalId (externalId in de body moet overeenkomen of kan worden weggelaten).
  • GET /api/v1/passes/by-external-id/:externalId: Haalt de actieve pas direct op via externalId zonder 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

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "externalId": "crm_usr_44910",
  "status": "ACTIVE",
  "changeMessage": "Tier updated to Platinum (%@ pts)",
  "attributes": {
    "pointsBalance": 750,
    "memberTier": "Platinum"
  }
}

Voorbeeldrespons (200 OK)

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

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.