Skip to content
Guida del Centro assistenza
4 min di letturaVerificato 2026-11-16

Problemi noti e limitazioni

Vincoli documentati di Apple, Google, Samsung Wallet, client email e modalità scanner offline.

In questa guida

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.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
LIMITAZIONE DELLA FREQUENZA IN INGRESSO E BLOCCHI DI IDEMPOTENZA
FASE 01 RICHIESTA CLIENT / POS / INTEGRAZIONE
Dimensione massima del corpo JSON/Multipart: 10MB (BODY_LIMIT)
FASE 02 RATE LIMITER GLOBALE BURST DA 1 SECONDO (main.ts)
Emette RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
Se superatoRestituisce HTTP 429 Too Many Requests (Retry-After: 1)
FASE 03 GUARDIA DI IDEMPOTENZA CACHE E DATABASE (Idempotency Engine)
Blocca le richieste duplicate concorrenti con la stessa x-idempotency-key
Applica i vincoli DB: ux_scan_config_idempotency e ux_pos_tx_tenant_idempotency

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 rispostaDescrizione
RateLimit-Limit / X-RateLimit-LimitNumero massimo di richieste consentite nella finestra di burst corrente di 1 secondo.
RateLimit-Remaining / X-RateLimit-RemainingRichieste rimanenti consentite nella finestra attiva prima della limitazione.
RateLimit-Reset / X-RateLimit-ResetSecondi rimanenti prima del ripristino del contatore di rate limit.
Retry-AfterSecondi di attesa prima di riprovare dopo aver ricevuto una risposta HTTP 429.

Payload di risposta limitata HTTP 429:

JSON
{
  "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 di 10MB (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 (o idempotencyKey in POST /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, serialNumber o externalId.

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:

VincoloPiattaformaRealtà 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 condivisaGoogle Wallet rispetto a Apple WalletApple 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 identicoApple WalletiOS 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 abbinatoApple Wallet + watchOSUn 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-appiOS Instagram, TikTok, LinkedInLe 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 AndroidIl 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.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.