Limites de passerelle API, de charge utile et de concurrence
Afin de maintenir une génération de passes à faible latence et de protéger la stabilité multi-locataires, Passinstance API applique des limites de débit déterministes, des plafonds de taille de charge utile et des verrous d'idempotence à la frontière d'entrée.
En-têtes de limitation de débit et gestion des réponses HTTP 429
Chaque réponse de l'API inclut les en-têtes standard RFC et hérités de limitation de débit afin que les clients d'intégration puissent cadencer automatiquement leurs opérations en masse :
| En-tête de réponse | Description |
|---|---|
RateLimit-Limit / X-RateLimit-Limit | Nombre maximal de requêtes autorisées dans la fenêtre de rafale actuelle d'une seconde. |
RateLimit-Remaining / X-RateLimit-Remaining | Requêtes restantes autorisées dans la fenêtre active avant limitation. |
RateLimit-Reset / X-RateLimit-Reset | Secondes restantes avant la réinitialisation du compartiment de limitation de débit. |
Retry-After | Secondes à attendre avant de réessayer après réception d'une réponse HTTP 429. |
Charge utile de réponse limitée HTTP 429 :
{
"error": "Rate limit exceeded",
"retryAfter": 1
}
Contraintes de charge utile de requête et d'idempotence
-
Corps de requête maximal (
10MB) : La passerelle API applique une limite stricte de charge utile de10MB(BODY_LIMIT) sur les requêtes JSON et les téléversements de fichiers. Pour une émission de passes à grand volume dépassant quelques centaines d'enregistrements, utilisez le worker de traitement CSV par lot asynchrone (POST /api/v1/batch-processing) ou les opérations par tableaux découpés (POST /api/v1/batch-pass-operations/create) plutôt que des requêtes uniques surdimensionnées. -
Verrouillage d'idempotence : Les appels concurrents de validation par scanner ou d'échange PDV partageant la même clé
x-idempotency-key(ouidempotencyKeydansPOST /v1/pos/redeem) sont sérialisés via des verrous in-memory cache et des index uniques en base de données (ux_scan_config_idempotency,ux_pos_tx_tenant_idempotency) afin d'éviter toute double déduction sur des réseaux de points de vente instables, en identifiant les passes par code-barres,serialNumberouexternalId.
Contraintes des portefeuilles au niveau des plateformes (Apple et Google)
Plusieurs limites de comportement proviennent directement de l'architecture des systèmes d'exploitation Apple iOS et Google Android :
| Contrainte | Plateforme | Réalité technique et solution de contournement recommandée |
|---|---|---|
Limite de push silencieux APNs (4096 bytes) | Apple Wallet (APNs) | Le service Apple Push Notification limite les charges utiles à 4096 bytes. Passinstance envoie un push vide léger {} pour réveiller l'iPhone, qui récupère ensuite l'archive .pkpass complète (signée par le bundleId / passTypeIdentifier du modèle) via GET /v1/passes/:passTypeIdentifier/:serialNumber. |
| Mise en cache des images de classe partagées | Google Wallet vs Apple Wallet | Apple retélécharge l'archive ZIP .pkpass complète lors d'une mise à jour, actualisant immédiatement les images de bandeau/vignette. Google Wallet met agressivement en cache les URL d'images hero/logo partagées au niveau Class sur les appareils Android ; ajoutez un nom de fichier invalidant le cache ou mettez à jour les champs au niveau Object pour des changements visuels instantanés. |
| Suppression des pushs à valeur identique | Apple Wallet | iOS affiche une bannière de notification sur l'écran verrouillé uniquement lorsqu'un champ doté d'un changeMessage passe à une nouvelle valeur de chaîne. Le réenregistrement d'une valeur strictement identique ne produit aucune bannière. |
| Enregistrement d'une Apple Watch jumelée | Apple Wallet + watchOS | Un seul pass installé sur un iPhone synchronisé avec une Apple Watch jumelée enregistre 2 jetons push d'appareils distincts (installedDevices = 2) pour 1 seule instance de pass. |
| Blocage par les WebViews des réseaux sociaux | Instagram, TikTok, LinkedIn sur iOS | Les navigateurs intégrés aux applications sociales bloquent souvent les flux MIME application/vnd.apple.pkpass. Les pages de téléchargement intelligentes (/d/:slug) détectent les WebViews et guident les détenteurs de passes pour ouvrir le lien dans Safari natif. |
NFC chiffré (NFC_VAS / NFC_SMART_TAP) | Matériel NFC iOS & Android | La validation sans contact chiffrée nécessite un matériel de lecture certifié (par ex., certified NFC) ainsi que des autorisations commerçant explicites Apple VAS ou Google Smart Tap — elle n'est jamais activée par défaut. |
Important : Lors de l'exécution de mises à jour de passes en masse sur des dizaines de milliers de cartes actives, les workers d'arrière-plan background job queue de Passinstance cadencent automatiquement les flux sortants Apple APNs HTTP/2 et les appels REST PATCH Google Wallet afin de respecter les quotas des fournisseurs cloud en amont.
Pour obtenir des conseils d'intégration destinés aux développeurs, consultez Présentation de l'API et authentification ainsi que Différences et limitations des plateformes.
