Limiti di API Gateway, payload e concorrenza
Per mantenere una bassa latenza nella generazione dei pass e proteggere la stabilità multi-tenant, Passinstance API applica limiti di frequenza deterministici, tetti massimi per le dimensioni dei payload e blocchi di idempotenza al perimetro di ingresso.
Header di Rate Limit e gestione di HTTP 429
Ogni risposta API include gli header di limitazione della frequenza standard RFC e legacy, in modo che i client di integrazione possano cadenzare automaticamente le operazioni massicce:
| Header di risposta | Descrizione |
|---|---|
RateLimit-Limit / X-RateLimit-Limit | Numero massimo di richieste consentite nella finestra di burst corrente di 1 secondo. |
RateLimit-Remaining / X-RateLimit-Remaining | Richieste rimanenti consentite nella finestra attiva prima della limitazione. |
RateLimit-Reset / X-RateLimit-Reset | Secondi rimanenti prima del ripristino del contatore di rate limit. |
Retry-After | Secondi di attesa prima di riprovare dopo aver ricevuto una risposta HTTP 429. |
Payload di risposta limitata HTTP 429:
{
"error": "Rate limit exceeded",
"retryAfter": 1
}
Vincoli sul payload della richiesta e sull'idempotenza
-
Dimensione massima del corpo della richiesta (
10MB): il gateway API applica un limite rigoroso di10MB(BODY_LIMIT) alle richieste JSON e al caricamento di file. Per l'emissione di pass ad alto volume che supera alcune centinaia di record, utilizzi il worker batch CSV asincrono (POST /api/v1/batch-processing) o le operazioni su array suddivisi in blocchi (POST /api/v1/batch-pass-operations/create) anziché singole richieste sovradimensionate. -
Blocco di idempotenza: le chiamate concorrenti dello scanner o di riscatto POS che condividono la stessa
x-idempotency-key(oidempotencyKeyinPOST /v1/pos/redeem) vengono serializzate tramite lock in-memory cache e indici univoci del database (ux_scan_config_idempotency,ux_pos_tx_tenant_idempotency) per prevenire doppi addebiti su reti instabili nei punti vendita, individuando i pass tramite codice a barre,serialNumberoexternalId.
Vincoli dei wallet a livello di piattaforma (Apple e Google)
Diversi limiti comportamentali dipendono direttamente dalle architetture dei sistemi operativi Apple iOS e Google Android:
| Vincolo | Piattaforma | Realtà tecnica e soluzione consigliata |
|---|---|---|
Limite push silenzioso APNs (4096 bytes) | Apple Wallet (APNs) | Il servizio Apple Push Notification limita i payload a 4096 bytes. Passinstance invia un push leggero vuoto {} per risvegliare l'iPhone, che poi scarica il pacchetto .pkpass completo (firmato dal bundleId / passTypeIdentifier del modello) tramite GET /v1/passes/:passTypeIdentifier/:serialNumber. |
| Caching delle immagini a livello di Classe condivisa | Google Wallet rispetto a Apple Wallet | Apple riscarica l'intero archivio ZIP .pkpass ad ogni aggiornamento, aggiornando immediatamente le immagini strip e le miniature. Google Wallet memorizza nella cache in modo aggressivo gli URL di hero/logo condivisi a livello di Class sui dispositivi Android; aggiunga un nome file con parametro di cache-busting o aggiorni i campi a livello di Object per modifiche visive istantanee. |
| Soppressione dei push con valore identico | Apple Wallet | iOS mostra un banner di notifica sulla schermata di blocco solo quando un campo con changeMessage cambia assumendo un nuovo valore stringa. Il salvataggio ripetuto dello stesso identico valore non genera alcun banner. |
| Registrazione di Apple Watch abbinato | Apple Wallet + watchOS | Un singolo pass installato su un iPhone sincronizzato con un Apple Watch abbinato registra 2 token push di dispositivo distinti (installedDevices = 2) su 1 istanza di pass. |
| Blocco nelle WebView dei social in-app | iOS Instagram, TikTok, LinkedIn | Le WebView integrate nelle app social spesso bloccano i flussi MIME application/vnd.apple.pkpass. Le pagine di download intelligenti (/d/:slug) rilevano le WebView e guidano i titolari del pass ad aprire il link nella versione nativa di Safari. |
NFC crittografato (NFC_VAS / NFC_SMART_TAP) | Hardware NFC iOS e Android | Il riscatto contactless crittografato richiede lettori hardware certificati (ad es. certified NFC) oltre alle autorizzazioni esplicite per esercenti Apple VAS o Google Smart Tap: non è mai abilitato per impostazione predefinita. |
Importante: Durante l'esecuzione di aggiornamenti massivi dei pass su decine di migliaia di carte attive, i worker in background background job queue di Passinstance cadenzano automaticamente i flussi HTTP/2 Apple APNs in uscita e le chiamate REST PATCH di Google Wallet per rispettare le quote dei provider cloud a monte.
Per indicazioni sull'integrazione per sviluppatori, consulti Panoramica delle API e autenticazione e Differenze e limitazioni delle piattaforme.
