API-gateway, payload- & gelijktijdigheidsgrenzen
Om lage latentie bij pasgeneratie te behouden en stabiliteit over alle tenants te garanderen, hanteert Passinstance API deterministische rate limits, maximale payloadgroottes en idempotentievergrendelingen aan de toegangsgrens.
Rate-limitheaders & afhandeling van HTTP 429
Elke API-respons bevat standaard RFC- en legacy rate-limiting-headers zodat integratieclients bulkoperaties automatisch kunnen doseren:
| Responsheader | Beschrijving |
|---|---|
RateLimit-Limit / X-RateLimit-Limit | Maximaal toegestaan aantal verzoeken binnen het huidige burstvenster van 1 seconde. |
RateLimit-Remaining / X-RateLimit-Remaining | Resterende verzoeken die binnen het actieve venster zijn toegestaan vóór beperking. |
RateLimit-Reset / X-RateLimit-Reset | Resterende seconden totdat de rate-limit-teller wordt gereset. |
Retry-After | Aantal seconden om te wachten alvorens opnieuw te proberen na HTTP 429. |
HTTP 429 Throttled Antwoordpayload:
{
"error": "Rate limit exceeded",
"retryAfter": 1
}
Beperkingen voor verzoekpayload & idempotency
-
Maximale verzoekbody (
10MB): De API-gateway hanteert een strikte10MB-limiet (BODY_LIMIT) voor JSON-verzoeken en bestandsuploads. Gebruik voor grote aantallen boven enkele honderden passen de asynchrone CSV-batchworker (POST /api/v1/batch-processing) of gesplitste bulkbewerkingen (POST /api/v1/batch-pass-operations/create) in plaats van één te groot verzoek. -
Idempotency Locking: Gelijktijdige scanner- of POS-verzilverschrijvingen met dezelfde
x-idempotency-key(ofidempotencyKeyinPOST /v1/pos/redeem) worden geserialiseerd via in-memory cache-vergrendelingen en unieke database-indexen (ux_scan_config_idempotency,ux_pos_tx_tenant_idempotency) om dubbele afschrijving op instabiele winkelnetwerken te voorkomen, waarbij passen worden gekoppeld op barcode,serialNumberofexternalId.
Platformbeperkingen vanuit Wallet-aanbieders (Apple & Google)
Verschillende systeemgrenzen komen rechtstreeks voort uit de besturingssysteemarchitectuur van Apple iOS en Google Android:
| Beperking | Platform | Technische realiteit & aanbevolen aanpak |
|---|---|---|
APNs Stille Pushlimiet (4096 bytes) | Apple Wallet (APNs) | Apple Push Notification service beperkt payloads tot 4096 bytes. Passinstance verstuurt een lichte lege push {} om de iPhone te wekken, die vervolgens de volledige .pkpass-bundel (ondertekend met bundleId / passTypeIdentifier van het sjabloon) ophaalt via GET /v1/passes/:passTypeIdentifier/:serialNumber. |
| Gedeelde Class-afbeeldingscaching | Google Wallet vs. Apple Wallet | Apple downloadt het volledige .pkpass-ZIP-archief bij updates en ververst strip-/miniatuurafbeeldingen direct. Google Wallet cachet gedeelde hero/logo-URL's op Class-niveau agressief op Android; gebruik een cache-busting bestandsnaam of werk Object-velden bij voor directe visuele updates. |
| Onderdrukking van gelijke waarden | Apple Wallet | iOS toont alleen een melding op het toegangsscherm wanneer een veld met changeMessage verandert naar een nieuwe tekenreekswaarde. Exact dezelfde waarde opnieuw opslaan toont geen melding. |
| Gekoppelde Apple Watch-registratie | Apple Wallet + watchOS | Eén pas die op een iPhone mét gekoppelde Apple Watch is geïnstalleerd registreert 2 afzonderlijke push-tokens (installedDevices = 2) voor 1 pasinstantie. |
| Blokkade in In-App Social WebView | iOS Instagram, TikTok, LinkedIn | Ingebouwde webviews in social apps blokkeren vaak application/vnd.apple.pkpass-streams. Slimme downloadpagina's (/d/:slug) detecteren webviews en vragen pashouders de link in Safari te openen. |
Versleutelde NFC (NFC_VAS / NFC_SMART_TAP) | iOS & Android NFC-hardware | Versleutelde tap-to-redeem vereist gecertificeerde lezerhardware (bijv. certified NFC) plus expliciete Apple VAS- of Google Smart Tap-merchantrechten—dit staat nooit standaard aan. |
Belangrijk: Bij bulkupdates over tienduizenden actieve kaarten doseren de background job queue-achtergrondworkers van Passinstance uitgaande Apple APNs HTTP/2-streams en Google Wallet REST PATCH-aanroepen automatisch binnen de quota van de cloudproviders.
Raadpleeg voor technische richtlijnen API-overzicht & authenticatie en Platformverschillen & beperkingen.
