Skip to content
Helpcentrum-gids · Ontwikkelaars-API
5 min leestijdGecontroleerd 2026-11-16

API-referentie

Verken het volledige REST-overzicht voor Passes, Sjablonen, Scanner, Bezorging, Webhooks en Bulkacties.

In deze gids

Overzicht

De Passinstance REST API is georganiseerd in modulaire domeincontrollers die hoofdzakelijk zijn gekoppeld onder /api/v1 (met speciale prefixvrije koppelingen voor POS /v1/pos/*, Pull Webhooks /webhook-payload, inkomende leverancierswebhooks /webhooks/*, gezondheidsprobes /health/* en slimme links /s/:token & /d/:slug). Elk eindpunt maakt gebruik van standaard HTTP-werkwoorden (GET, POST, PUT, PATCH, DELETE), dwingt tenant-isolatie van de werkruimte af op basis van uw API-inloggegevens en retourneert een deterministische JSON-payload (API response (T) op werkruimte-API's).

Vereisten: Genereer een API-sleutel voor de werkruimte (pi_live_... of pi_test_...) met de vereiste API_KEY_SCOPE_VALUES (passes, templates, scans, webhooks, analytics of *) op /settings/workspace/developer/api-credentials voordat u /api/v1/*-routes aanroept. Interactieve OpenAPI-documentatie is beschikbaar via GET /api/public/docs en /docs.

Levenscyclus van verzoeken en antwoorden

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
SYSTEEMARCHITECTUURSTROOM: REST API-VERZOEK & LEVENSCYCLUS VAN ENVELOP
DEELNEMENDE SYSTEEMACTOREN
P1 Externe integratie
P2 Passinstance /api/v1/*
P3 Wallet-providers & DB
STAP 1 VERZOEK / ACTIE POST/api/v1/passes
STAP 2 VERZOEK / ACTIE Valideer DTO & tenant-scope
STAP 3 VERZOEK / ACTIE Onderteken .pkpass (bundleId)
›
idempotencyKey
›
& bouw Google Wallet JWT
STAP 4 ANTWOORD 201 Created
›
API response (request payload)
STAP 5 VERZOEK / ACTIE PATCH/api/v1/passes/:id
STAP 6 VERZOEK / ACTIE Leg veldwijziging vast
STAP 7 ANTWOORD 200 OK
›
7. Plaats APNs & Google Push

Catalogus met REST-eindpunten per domein

1. Passen, upserts en batchbewerkingen

WerkwoordPadBeschrijving
POST/api/v1/passesGeeft een pasinstantie uit (request payload: templateId, optionele externalId, idempotencyKey, attributes) ondertekend met het sjablooncertificaat (bundleId = Apple passTypeIdentifier).
POST/api/v1/passes/upsert-by-external-idMaakt idempotent een pas aan of werkt deze bij op basis van (templateId, externalId) (request payload).
GET/api/v1/passesToont pasinstanties met paginering, statusfiltering (pass status) en zoekopdrachten.
GET/api/v1/passes/:idHaalt volledige details, dynamische attributen, externalId, serialNumber en registratiestatus op.
PATCH / PUT/api/v1/passes/:idWerkt dynamische velden, niveau of vervaldatum bij en pusht live updates naar geïnstalleerde wallets.
POST/api/v1/passes/voiding/:id/voidVerklaart een pas ongeldig (request payload + VoidingReason) en verstuurt een stille voided: true push-update.
DELETE/api/v1/passes/:idVerwijdert een pas (soft-delete) en trekt actieve wallet-installaties in.
POST/api/v1/passes/exportExporteert gefilterde pasrecords als een UTF-8 CSV- of JSON-downloadtaak.
POST/api/v1/batch-pass-operations/createVoert synchrone/in wachtrij geplaatste bulkpasaanmaak uit via Batch Operations API (eveneens /update, /upsert, /activate, /deactivate, /delete).
POST/api/v1/batch-processingDient een asynchrone grote CSV/JSON-bulktaak in die wordt gevolgd via Batch Processing API.

2. Sjablonen en mechanieken

WerkwoordPadBeschrijving
GET/api/v1/templatesToont passjablonen in de werkruimte, pastypen (PassKind), bundleId-certificaatkoppelingen en publicatiestatussen.
GET/api/v1/templates/:idRetourneert het sjabloonschema, de visuele lay-outconfiguratie en actieve mechanieken.
POST/api/v1/templates/:id/publishPubliceert conceptwijzigingen (request payload) en verstuurt gebatchte push-updates (GET .../publish-risk-check vooraf).
GET/api/v1/templates/:templateId/attributesToont dynamische veldsleutels en typen die vereist zijn bij het uitgeven van passen (ondersteunt OAuth templates:read).
POST/api/v1/mechanics/redeemVerzilvert een ontgrendelde loyaliteits- of stempelkaartbeloning (request payload: UUID passId, mechanicId).
GET/api/v1/mechanics/:mechanicId/passes/:passId/ledgerRetourneert het transactiegrootboek voor het tegoed- of loyaliteitsmechaniek van een pas (GET /api/v1/balance-changes voor tenantfeed).

3. Scans, apparaten en POS-validatie

WerkwoordPadBeschrijving
POST/api/v1/scansEvalueert een barcode-/NFC-scan tegen de Validation Rules Engine met 14 regels (ScanMode & scan status).
POST/api/v1/scans/prepareGeeft een kortlevende cryptografische scan nonce uit voor anti-replaybeveiliging.
GET/api/v1/scans/passAlleen-lezen paszoekopdracht via ?barcode=... (of padparameter GET /api/v1/scans/pass/:barcodeValue).
POST/api/v1/scans/pass/:passId/useVoert rechtstreeks een request payload-actie uit (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET).
GET/api/v1/scans/result/:scanIdHaalt het auditrecord en de ruleTrace van een voltooide scan op.
GET/api/v1/scans/offline-datasetCursorgepagineerde passnapshot (offline scan dataset) voor offline handscanners.
POST/v1/pos/redeemPrefixvrij POS-eindpunt dat atomaire PosOperation-opdrachten uitvoert (DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID, CUSTOM).
POST/api/v1/reader/redeemVerwerkt verzilveringen van hardwarematige NFC-lezers geauthenticeerd via X-Reader-Secret (POST /api/v1/reader/validate voor toegangsvalidatie).

4. Pushmeldingen, webhooks en workflows

WerkwoordPadBeschrijving
POST/api/v1/push-notifications/templates/:id/sendVerstuurt onmiddellijk een melding naar alle apparaten die voor een sjabloon zijn geregistreerd (request payload op /passes/:id/schedule).
POST/api/v1/push-notifications/segmentationRicht zich op een gefilterd passegment (request payload) met gelokaliseerde push-updates.
POST/api/v1/push-notifications/batchVerstuurt batchmeldingen over paslijsten of CSV-uploads (request payload).
GET / POST/api/v1/webhooksHaalt het webhookoverzicht op of beheert uitgaande HTTPS-push-webhookeindpunten (/api/v1/webhooks/subscriptions).
GET/webhook-payloadPrefixvrije Pull API (GET /api/v3/webhook-payload wordt ook ondersteund) die niet-bevestigde gebeurtenissen ophaalt voor ontvangers achter een beperkende firewall.
POST/webhook-payload/acknowledgePrefixvrije bevestiging ({ upTo, webhookId }, of POST /api/v3/webhook-payload/acknowledge).
GET / POST/api/v1/workflowsToont of maakt geautomatiseerde gebeurtenisgestuurde workflows aan (Workflow Engine API, naast /api/v1/automations).

5. Analytics, facturering en privacybeheer

WerkwoordPadBeschrijving
GET/api/v1/analyticsMeerdelig telemetrierapport (passes, registrations, walletAppsShare; zie /api/v1/analytics/passes/overview).
GET/api/v1/analytics/wallet-installationsInstallatiematrix voor Apple Wallet versus Google Wallet op apparaat- en pasniveau (request payload).
GET/api/v1/billing/subscriptionRetourneert het actieve abonnement, de factureringscyclus en de verlengingsstatus.
GET/api/v1/billing/invoices/:id/downloadStreamt de btw-factuur als PDF (application/pdf).
POST/api/v1/customer/:customerId/privacy-settings/data-subject-exportGenereert een AVG-conform archief met persoonsgegevens voor een pashouder.

Standaard API response (T)-envelop en statuscodes

Succesenvelop (200 OK / 201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01hxyz8821",
    "templateId": "tmpl_vip_member",
    "serialNumber": "PI-VIP-8821",
    "externalId": "crm_cust_44910",
    "bundleId": "pass.com.passinstance.vip",
    "status": "ACTIVE",
    "passAccessUrl": "https://api.passinstance.com/s/vip-8821-x9a2"
  },
  "meta": {
    "requestId": "req_99481a2b7c",
    "timestamp": "2026-11-16T10:10:00.000Z"
  }
}

Standaard HTTP-statuscodes

StatuscodeBetekenisOplossing
200 OK / 201 CreatedVerzoek synchroon geslaagd.Lees de resultaatpayload uit data.
400 Bad RequestDTO-validatiefout of geschonden domeinbeperking.Inspecteer errorCode, messageKey en de details-array.
401 UnauthorizedOntbrekende, verlopen of ongeldige API-sleutel / Bearer-token.Controleer de x-api-key- of Authorization-header (en de overeenkomst tussen pi_test_ vs pi_live_ en uw werkruimte).
403 ForbiddenGeldige sleutel mist de vereiste scope (bijv. ontbrekende 'passes') of tenanttoegang.Controleer de toegewezen scopes via GET /api/v1/api-keys.
404 Not FoundDoelbron-ID bestaat niet in de geauthenticeerde werkruimte.Controleer UUID / serialNumber / externalId en de werkruimteomgeving.
409 ConflictDubbele externalId, serialNumber of gelijktijdige idempotentiebotsing.Gebruik /api/v1/passes/upsert-by-external-id of geef een unieke idempotencyKey mee.
429 Too Many RequestsPieklimiet van 1 seconde of quotumsnelheidslimiet overschreden.Respecteer de antwoordheaders Retry-After en RateLimit-Reset.

Blader door de volledige schemadefinities in de Documentatiehub voor ontwikkelaars en het API-overzicht en authenticatie.

Gerelateerde product- en ontwikkelaarsdocs

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.