Skip to content
REST API-referentie & SDK's

Passinstance Documentatie voor Ontwikkelaars

Bouw grootschalige Apple Wallet (.pkpass) en Google Wallet integraties. Uitgeven, bijwerken, scannen en realtime meldingen versturen via productieklare REST-API's.

API-sleutels ophalen
Live docs-workbench — fragmenten worden bijgewerkt terwijl je typt
Overzicht

Introductie — API-overzicht

Met de Passinstance API kunnen ontwikkelaars dynamisch digitale passen uitgeven, distribueren, bijwerken en valideren voor Apple Wallet (iOS) en Google Wallet (Android). Alle API-verzoeken verlopen via HTTPS en retourneren een gestandaardiseerde API-responsenvelop met machineleesbare statuscodes.

Productie Basis-URL
Actief
https://api.passinstance.com/api/v1
Staging Sandbox Basis-URL
https://staging-api.passinstance.com/api/v1
Aanvraag- & responsformaatapplication/json (UTF-8) met standaard responsenvelop
Tijdzone backendserverEurope/Berlin (ISO 8601-tijdstempels)
Beveiliging

Authenticatie — API-sleutels & autorisatie

Gebruik X-API-Key: <key> of Authorization: ApiKey <key> voor endpoints die API-sleutels ondersteunen. Bearer is bedoeld voor toegangs-JWT's. Bewaar inloggegevens op de server.

Productiesleutels (Live)
Authorization: ApiKey pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Sandbox-sleutels (Test)
Authorization: ApiKey pi_test_xxxxxxxxxxxxxxxxxxxxxxxx
Hardware-scannersleutels
x-scanner-key: scan_key_77a8b9c0d1e2f3a4...
Beveiligingsinvariant:Alleen server-naar-server. Sluit nooit geheime sleutels in frontend-bundles in.
Snelstart

Snelstart — Eerste API-verzoek

Maak uw eerste bruikbare pas in minder dan 5 minuten. Stel uw API-sleutelheader in, roep POST /api/v1/passes aan met een geldige templateId en stuur de ontvangen passAccessUrl naar uw eindgebruiker.

Stap 1: Sleutel instellen
export PASSINSTANCE_API_KEY="pi_test_..."
Stap 2: Pas uitgeven

POST /api/v1/passes met templateId en serialNumber

Stap 3: URL ophalen

Haal response.data.passAccessUrl uit de 201 Created-respons

Stap 4: Distribueren

Stuur URL via sms/e-mail; gebruiker tikt op "Toevoegen aan Apple/Google Wallet"

Bronnen

Postman-collectie — API-verzoeken importeren & testen

Importeer de Passinstance OpenAPI 3.0-specificatie (/api/docs/openapi.json) rechtstreeks in Postman, Insomnia of Bruno om eindpunten te testen, schema's te inspecteren en getypeerde HTTP-clients te genereren.

OpenAPI 3.0 JSON-specificatie openen
1. OpenAPI 3.0-specificatie-URL
https://passinstance.com/api/docs/openapi.json
2. Importeren in Postman / Bruno

Klik op Import in Postman, Insomnia of Bruno en plak /api/docs/openapi.json om alle routes te laden

3. Omgeving configureren

Stel baseUrl = https://api.passinstance.com en PASSINSTANCE_API_KEY = pi_test_... in

4. Verbinding controleren

Voer GET /api/v1/templates uit met X-API-Key: om uw workspace te testen

Operaties & FAQ

FAQ — Veelgestelde vragen & foutafhandeling

Elke respons gebruikt de standaard API-responsenvelop. Los 4xx-fouten op voordat u het opnieuw probeert; wacht bij 5xx en 429 op basis van Retry-After.

200 OK / 201 CreatedGeslaagd
{
  "success": true,
  "data": { ... },
  "errors": [],
  "statusCode": 200
}
Kernbegrippen

Architectuur & Levenscyclus van passen

Pasbeheer volgt een levenscyclus in 6 fasen: 1. Sjabloon (visuele blauwdruk) → 2. Pas (cryptografisch ondertekend record) → 3. Distributie (beveiligde passAccessUrl) → 4. Wallet-registratie (apparaat meldt zich aan bij APNs / Google Push) → 5. Live updates (realtime meldingen) → 6. Scan- & inwisseltelemetrie (validatie & webhook-stream).

1. SjabloonPOST /api/v1/templates

Hoofdlay-out, streepjescodetype, merkkleuren en schemavelden

Platformgidsen

Apple Wallet vs. Google Wallet matrix

Passinstance ondertekent automatisch .pkpass-pakketten voor iOS en genereert ondertekende JWT-objecten voor Google Wallet. Afbeeldingen, streepjescodes en triggers passen zich automatisch aan beide besturingssystemen aan.

Apple WalletiOS · .pkpass
Apple Wallet-ondertekening

Cryptografische PKCS#7-handtekening met Apple Pass Type ID-certificaat

Google WalletAndroid · JWT
Google Wallet-uitgever

Google Cloud Service Account REST JWT-payload

Cross-platform pariteit (één REST-aanroep)iOS + Android
Hero- / Strip-afbeeldingenApple: 375×123 px (3:1) | Google: 1032×336 px (circa 3:1)
Universele streepjescodesQR-code en PDF417 standaard ondersteund op beide mobiele platformen
Kernbegrippen

Pasmechanica & Loyaliteitsoplossingen

Koppel stateful bedrijfsmechanica aan sjablonen voor 8 kant-en-klare oplossingen (Loyaliteit, Stempelkaarten, Coupons, Cadeau-/Prepaidkaarten, Evenementtickets, Lidmaatschappen, Personeelspassen, VIP-kaarten). Regels worden atomair uitgevoerd bij een scan of API-aanroep.

LOYALTY_PROGRAM

LOYALTY_PROGRAM & Niveaus

Puntenopbouw per scan (defaultChangeValue) met automatische niveauverhoging

STAMP_CARD

STAMP_CARD_ADD / DEDUCT

Houdt stempelposities bij (0..maximumValue) met onCap ('noop' | 'reset') en rewardClaimBehavior

PREPAID_CARD

PREPAID_CARD Grootboek

ISO 4217-grootboekadministratie voor prepaid in kleinste eenheden met disallowNegativeBalance-handhaving

VALID_ONCE_PER_DAY

VALID_ONCE_PER_DAY & RENEW

Tijdzonebewuste dagelijkse inchecklimieten en automatische verlenging van expirationDate bij scan

End-to-end Platform- & API-documentatie

Passinstance Helpcentrum: Bekijk alle 10 onderwerpen & 94 gidsen

Verken stapsgewijze handleidingen, workflow-architectuurdiagrammen, JSON-payloadschema's en probleemoplossing voor elk domein.

Helpcentrum openen

Alles wat u nodig hebt om vlot te starten met Passinstance.