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
[ SYSTEEMARCHITECTUURSTROOM: REST API-VERZOEK & LEVENSCYCLUS VAN ENVELOP ]
Externe integratie Passinstance /api/v1/* Wallet-providers & DB
| | |
|-- 1. POST /api/v1/passes --------->| |
| Header: x-api-key: pi_live_.. |-- 2. Valideer DTO & tenant-scope |
| Body: externalId, |-- 3. Onderteken .pkpass (bundleId) |
| idempotencyKey | & bouw Google Wallet JWT ---->|
|<-- 4. 201 Created -----------------| |
| API response (request payload) | |
| | |
|-- 5. PATCH /api/v1/passes/:id ---->| |
| Body: { attributes: {...} } |-- 6. Leg veldwijziging vast ------>|
|<-- 7. 200 OK ----------------------|-- 7. Plaats APNs & Google Push --->|
Catalogus met REST-eindpunten per domein
1. Passen, upserts en batchbewerkingen
Werkwoord
Pad
Beschrijving
POST
/api/v1/passes
Geeft een pasinstantie uit (request payload: templateId, optionele externalId, idempotencyKey, attributes) ondertekend met het sjablooncertificaat (bundleId = Apple passTypeIdentifier).
POST
/api/v1/passes/upsert-by-external-id
Maakt idempotent een pas aan of werkt deze bij op basis van (templateId, externalId) (request payload).
GET
/api/v1/passes
Toont pasinstanties met paginering, statusfiltering (pass status) en zoekopdrachten.
GET
/api/v1/passes/:id
Haalt volledige details, dynamische attributen, externalId, serialNumber en registratiestatus op.
PATCH / PUT
/api/v1/passes/:id
Werkt dynamische velden, niveau of vervaldatum bij en pusht live updates naar geïnstalleerde wallets.
POST
/api/v1/passes/voiding/:id/void
Verklaart een pas ongeldig (request payload + VoidingReason) en verstuurt een stille voided: true push-update.
DELETE
/api/v1/passes/:id
Verwijdert een pas (soft-delete) en trekt actieve wallet-installaties in.
POST
/api/v1/passes/export
Exporteert gefilterde pasrecords als een UTF-8 CSV- of JSON-downloadtaak.
POST
/api/v1/batch-pass-operations/create
Voert synchrone/in wachtrij geplaatste bulkpasaanmaak uit via Batch Operations API (eveneens /update, /upsert, /activate, /deactivate, /delete).
POST
/api/v1/batch-processing
Dient een asynchrone grote CSV/JSON-bulktaak in die wordt gevolgd via Batch Processing API.
2. Sjablonen en mechanieken
Werkwoord
Pad
Beschrijving
GET
/api/v1/templates
Toont passjablonen in de werkruimte, pastypen (PassKind), bundleId-certificaatkoppelingen en publicatiestatussen.
GET
/api/v1/templates/:id
Retourneert het sjabloonschema, de visuele lay-outconfiguratie en actieve mechanieken.
Verwerkt verzilveringen van hardwarematige NFC-lezers geauthenticeerd via X-Reader-Secret (POST /api/v1/reader/validate voor toegangsvalidatie).
4. Pushmeldingen, webhooks en workflows
Werkwoord
Pad
Beschrijving
POST
/api/v1/push-notifications/templates/:id/send
Verstuurt onmiddellijk een melding naar alle apparaten die voor een sjabloon zijn geregistreerd (request payload op /passes/:id/schedule).
POST
/api/v1/push-notifications/segmentation
Richt zich op een gefilterd passegment (request payload) met gelokaliseerde push-updates.
POST
/api/v1/push-notifications/batch
Verstuurt batchmeldingen over paslijsten of CSV-uploads (request payload).
GET / POST
/api/v1/webhooks
Haalt het webhookoverzicht op of beheert uitgaande HTTPS-push-webhookeindpunten (/api/v1/webhooks/subscriptions).
GET
/webhook-payload
Prefixvrije Pull API (GET /api/v3/webhook-payload wordt ook ondersteund) die niet-bevestigde gebeurtenissen ophaalt voor ontvangers achter een beperkende firewall.
POST
/webhook-payload/acknowledge
Prefixvrije bevestiging ({ upTo, webhookId }, of POST /api/v3/webhook-payload/acknowledge).
GET / POST
/api/v1/workflows
Toont of maakt geautomatiseerde gebeurtenisgestuurde workflows aan (Workflow Engine API, naast /api/v1/automations).