Skip to content
Guide du centre d'aide
4 min de lectureVérifié 2026-11-16

Limites & comportements connus

Contraintes documentées d'Apple, Google, Samsung Wallet, fournisseurs mail et cache scanner hors ligne.

Dans ce guide

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.

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : LIMITATION DE DÉBIT ENTRANT & VERROUS D'IDEMPOTENCE
ÉTAPE 01 REQUÊTE CLIENT / PDV / INTÉGRATION
Taille max. du corps JSON/Multipart : 10MB (BODY_LIMIT)
ÉTAPE 02 LIMITEUR GLOBAL DE RAFALES SUR 1 SECONDE (main.ts)
Émet RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
En cas de dépassementRenvoie HTTP 429 Too Many Requests (Retry-After:1)
ÉTAPE 03 PROTECTION D'IDEMPOTENCE (Idempotency Engine)
Verrouille les requêtes concurrentes dupliquées ayant le même x-idempotency-key
Applique les contraintes DB : ux_scan_config_idempotency & ux_pos_tx_...

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éponseDescription
RateLimit-Limit / X-RateLimit-LimitNombre maximal de requêtes autorisées dans la fenêtre de rafale actuelle d'une seconde.
RateLimit-Remaining / X-RateLimit-RemainingRequêtes restantes autorisées dans la fenêtre active avant limitation.
RateLimit-Reset / X-RateLimit-ResetSecondes restantes avant la réinitialisation du compartiment de limitation de débit.
Retry-AfterSecondes à attendre avant de réessayer après réception d'une réponse HTTP 429.

Charge utile de réponse limitée HTTP 429 :

JSON
{
  "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 de 10MB (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 (ou idempotencyKey dans POST /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, serialNumber ou externalId.

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 :

ContraintePlateformeRé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éesGoogle Wallet vs Apple WalletApple 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 identiqueApple WalletiOS 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éeApple Wallet + watchOSUn 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 sociauxInstagram, TikTok, LinkedIn sur iOSLes 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 & AndroidLa 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.

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.