Bouw grootschalige Apple Wallet (.pkpass) en Google Wallet integraties. Uitgeven, bijwerken, scannen en realtime meldingen versturen via productieklare REST-API's.
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.
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"
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.
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.
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
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
Promoveer een conceptrevisie (rowKind: DRAFT) naar PUBLISHED, markeer changesToPush: true en zet APNs- en Google Wallet-updates in de wachtrij voor alle actieve passen.
Headers (kopteksten)1 vereist
X-API-Keystring
Vereist
Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.
Werk dynamische velden, kleuren of streepjescode van een pas bij en verstuur automatisch APNs- en Google Wallet-pushmeldingen naar geïnstalleerde apparaten.
Headers (kopteksten)1 vereist
X-API-Keystring
Vereist
Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.
Haal een openbare gebrandete pas-downloadpagina op via slug (zonder prefix GET /d/{slug}/info). Gebruik voor geauthenticeerd beheer GET /api/v1/download-pages/slug/{slug}.
Stuur direct een pushmelding op het vergrendelscherm naar een geïnstalleerde Apple Wallet- (.pkpass) of Google Wallet-pas. Gebruik voor geplande verzendingen of koptekstaanpassing POST /api/v1/push-notifications/passes/{id}.
Headers (kopteksten)1 vereist
X-API-Keystring
Vereist
Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.
Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idUUID
Vereist
Unieke pasinstantie-UUID die de melding moet ontvangen.
Voorbeeld: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
Verzoekpayload met berichttekst en optionele kopteksttitel.
Aanvraagtekst1 vereist • 1 optioneel
messagestring
Vereist
Tekstbericht dat op het vergrendelscherm van de gebruiker wordt weergegeven.
Voorbeeld: Your reward points have been updated! You now have 250 points.
Elke barcode- of NFC-scan doorloopt een deterministische validatiepijplijn van 14 regels (status, vervaldatum, tijdvensters, geofencing, mechanica, snelheidslimieten, anti-replay) met optionele cryptografische nonces en offline datasetsynchronisatie.
Anti-replay Nonce
POST /api/v1/scans/prepare geeft een kortlevende cryptografische anti-replay nonce uit gekoppeld aan de barcode
Valideer een optische streepjescode, QR-code of Apple VAS / Google Smart Tap NFC-scan vanaf een terminal of mobiele scanner via de 14-regels validatie-engine.
Headers (kopteksten)2 vereist • 2 optioneel
x-scanner-keystring
Vereist
Gekoppelde scannerconfiguratiesleutel aangemaakt in het Dashboard of via een koppelingslink.
Voorbeeld: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Content-Typestring
Vereist
Moet application/json zijn.
Voorbeeld: application/json
Verzoekpayload met gescande streepjescode, optionele anti-replay nonce, kanaal-/protocolmetadata en operatorcontext.
Aanvraagtekst1 vereist • 8 optioneel
scannedBarcodeValuestring
Vereist
De ruwe tekenreeks gelezen van QR-code, PDF417, CODE128, AZTEC of NFC-tap.
Download een cursor-gepagineerde pas-snapshotdataset binnen het bereik van de x-scanner-key voor lokale offline validatie wanneer de netwerkverbinding wegvalt.
Headers (kopteksten)1 vereist
x-scanner-keystring
Vereist
Gekoppelde scannerconfiguratiesleutel aangemaakt in het Dashboard of via een koppelingslink.
Verifieer X-Webhook-Signature als HMAC-SHA256 van de exacte onbewerkte aanvraaginhoud met uw abonnementsgeheim. Vergelijk in constante tijd en verwerk gebeurtenissen idempotent.
Handtekening-header
X-Webhook-Signature: sha256=9f8e7d6c5b4a3...
Tijdstempel-header
X-Webhook-Timestamp: 2026-08-21T20:30:00.000Z
Replaybescherming
Controleer of X-Webhook-Id overeenkomt met de ondertekende eventId, dedupliceer gebeurtenissen en valideer de ondertekende tijdstempel volgens uw replaybeleid.
Ontvang realtime pas- en scangebeurtenissen via uitgaande HMAC-SHA256 Push-webhooks (met exponentiële backoff en circuit breakers) of inkomende Pull-webhookpolling voor afgeschermde netwerken, plus no-code Workflows.
Push-webhook veerkracht
5 pogingen met jittered exponentiële backoff; circuit breaker opent na 10 opeenvolgende fouten
Pull-webhook polling
GET /api/v1/webhook-payload & POST /api/v1/webhook-payload/acknowledge voor privénetwerken