Skip to content
Helpcentrum-gids
3 min leestijdGecontroleerd 2026-11-16

Bekende beperkingen & richtlijnen

Duidelijke platformregels vanuit Apple, Google, Samsung Wallet, e-mailproviders en offline scannercache.

In deze gids

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.

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
INGRESS RATE LIMITING & IDEMPOTENTIEVERGRENDELING
FASE 01 CLIENT- / POS- / INTEGRATIEVERZOEK
Max. JSON/Multipart Body-grootte: 10MB (BODY_LIMIT)
FASE 02 GLOBALE 1-SECONDE BURST RATE LIMITER (main.ts)
Geeft RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset terug
Bij overschrijdingHTTP 429 Too Many Requests (Retry-After: 1)
FASE 03 IDEMPOTENCY PROTECTION GUARD
Vergrendelt gelijktijdige dubbele x-idempotency-key-verzoeken
Handhaaft DB-constraints: ux_scan_config_idempotency & ux_pos_tx_tenant_idempotency

Rate-limitheaders & afhandeling van HTTP 429

Elke API-respons bevat standaard RFC- en legacy rate-limiting-headers zodat integratieclients bulkoperaties automatisch kunnen doseren:

ResponsheaderBeschrijving
RateLimit-Limit / X-RateLimit-LimitMaximaal toegestaan aantal verzoeken binnen het huidige burstvenster van 1 seconde.
RateLimit-Remaining / X-RateLimit-RemainingResterende verzoeken die binnen het actieve venster zijn toegestaan vóór beperking.
RateLimit-Reset / X-RateLimit-ResetResterende seconden totdat de rate-limit-teller wordt gereset.
Retry-AfterAantal seconden om te wachten alvorens opnieuw te proberen na HTTP 429.

HTTP 429 Throttled Antwoordpayload:

JSON
{
  "error": "Rate limit exceeded",
  "retryAfter": 1
}

Beperkingen voor verzoekpayload & idempotency

  • Maximale verzoekbody (10MB): De API-gateway hanteert een strikte 10MB-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 (of idempotencyKey in POST /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, serialNumber of externalId.

Platformbeperkingen vanuit Wallet-aanbieders (Apple & Google)

Verschillende systeemgrenzen komen rechtstreeks voort uit de besturingssysteemarchitectuur van Apple iOS en Google Android:

BeperkingPlatformTechnische 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-afbeeldingscachingGoogle Wallet vs. Apple WalletApple 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 waardenApple WalletiOS 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-registratieApple Wallet + watchOSEé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 WebViewiOS Instagram, TikTok, LinkedInIngebouwde 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-hardwareVersleutelde 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.

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.