Skip to content
Guide du centre d'aide · Gestion des passesPhase d'intégration 5
10 min de lectureVérifié 2026-11-16

Opérations en masse

Exécutez des actions groupées sur des cohortes filtrées : mises à jour en série, invalidation, suppression et exports.

Dans ce guide

Visites interactives de l'interface

Ouvrir dans le guide en 6 phases

Inspectez les écrans exacts du tableau de bord et les zooms annotés liés à ce guide.

Focus interface zoomé
Éléments clés de l'interface

Onglet Passes & Actions groupées (Zoom)

Après un import massif, utilisez Passes, les filtres et le menu Bulk actions pour contrôler ou modifier la cohorte.

Aperçu

Une fois que vous avez isolé une cohorte de passes cible dans le tableau de bord à l'aide des filtres rapides ou du tiroir de filtres avancés ET/OU (StickySelectionToolbar), utilisez le menu Actions en masse (Bulk actions) dans la barre d'outils Passes — ou appelez Batch Operations API (/api/v1/batch-pass-operations/*) via l'API REST — pour exécuter des opérations structurées par tableau sur jusqu'à 1 000 passes par appel. Contrairement aux téléversements multipart de fichiers CSV (/api/v1/batch-processing), /api/v1/batch-pass-operations/* traite directement des charges utiles JSON et renvoie les tableaux errors et warnings par élément dans request payload.

Lorsque vous mettez à jour simultanément des milliers ou des dizaines de milliers de passes émis, Passinstance découple les mutations en base de données de la diffusion des notifications push vers les portefeuilles mobiles. Les modifications sont persistées immédiatement en base de données, tandis que les mises à jour sont diffusées vers les appareils Apple Wallet via des connexions HTTP/2 APNs mutualisées avec limitation de débit, et vers les appareils Google Wallet via une propagation instantanée sur l'Issuer Class ou des requêtes REST PATCH individuelles sur les Pass Objects.

Architecture système : opérations en masse, régulation de file & propagation Wallet

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : OPÉRATIONS EN MASSE & PROPAGATION WALLET
ÉTAPE 01 BARRE D'OUTILS GROUPÉE DU TABLEAU DE BORD / API (Batch Operations API)
Sélection de cohorte (StickySelectionToolbar / Tiroir filtres / IDs de passes)
POST/api/v1/batch-pass-operations/update (operation: "update")
POST/api/v1/batch-pass-operations/upsert (Indexé sur externalId)
POST/api/v1/batch-pass-operations/activate (operation: "activate")
POST/api/v1/batch-pass-operations/deactivate (operation: "deactivate")
POST/api/v1/batch-pass-operations/delete (request payload)
POST/api/v1/batch-pass-operations/validate (Contrôle préalable)
ÉTAPE 02 MOTEUR DE VALIDATION ET D'EXÉCUTION ISOLÉ PAR ÉLÉMENT
Supprime les clés protégées par locataire (customerId, tenantId, createdBy)
Pré-valide les attributs via preValidateAttributes (ignore requis sur update)
Normalise les attributs via normalizeAttributes
Renvoie request payload : { success, data, message, errors, warnings }
ÉTAPE 03A FILE WORKER APNs HTTP/2 RÉGULÉE
File de tâches : push-notifications
Pooling de connexions HTTP/2 pers.
Régulation évitant les erreurs 429
Push silencieux réveillant l'appareil
ÉTAPE 03B PROPAGATION DE CLASSE GOOGLE WALLET
Modif. modèle : PATCH Issuer Class
Synchro instantanée sur Android
PATCH individuel par Pass Object pour les attributs dynamiques

Filtrer des cohortes de passes cibles

Avant d'exécuter des opérations en masse, les administrateurs isolent la cohorte d'audience exacte à modifier :

Filtres rapides & tiroir de filtres avancés ET/OU

Dans le tableau de bord sous Passes (/passes) :

  • Filtre par modèle : limite les actions à un modèle de passe spécifique ou à une carte de campagne.
  • Filtre par statut : filtre selon l'état du cycle de vie (ACTIVE, INACTIVE, SUSPENDED, EXPIRED, VOIDED).
  • Filtre d'état d'installation : distingue active_only (installé sur au moins un appareil), inactive_only (désinstallé) et not_registered (liens de téléchargement non réclamés).
  • Tiroir de recherche avancée (Advanced Filter panel) : combine plusieurs attributs avec une logique ET/OU (par exemple tier == "Gold" ET pointsBalance < 500 ET expirationDate < 2027-01-01).
  • Barre de sélection flottante (StickySelectionToolbar) :

- Cliquez sur la case à cocher principale pour sélectionner la page affichée (jusqu'à 100 passes). - Cliquez sur la bannière d'invitation pour sélectionner tous les passes correspondants sur l'ensemble des pages (par ex. « Sélectionner les 4 850 passes correspondant à ce filtre »).

Sélection de cohorte par API

Via l'API REST, récupérez les UUID des passes cibles avec POST /api/v1/passes/query-builder ou POST /api/v1/passes/search, puis transmettez les identifiants obtenus à /batch-pass-operations/*.


Mettre à jour des milliers de passes émis

La mise à jour de grandes flottes de passes émis nécessite d'équilibrer le débit d'écriture en base de données avec les limites de connexion strictes des passerelles de notifications push des portefeuilles mobiles.

Opérations directes par tableau vs ingestion CSV par lot

Passinstance propose deux voies distinctes pour les mises à jour en masse selon le volume :

  1. 1
    Opérations directes par tableau JSON (POST /api/v1/batch-pass-operations/update) :

- Idéal jusqu'à 1 000 passes par requête HTTP. - Accepte un tableau passIds et un unique dictionnaire updateData. - Réponse HTTP synchrone retournant le statut individuel, les erreurs et les avertissements de chaque passe.

  1. 2
    Pipeline CSV asynchrone par lot (/api/v1/batch-processing) :

- Idéal pour 1 000 à plus de 100 000 passes. - Importez un fichier CSV contenant des identifiants uniques (externalId ou serialNumber) et les attributs modifiés. - Définissez l'opération sur UPDATE_PASSES ou UPSERT. - Les files de workers en arrière-plan traitent les lignes de façon asynchrone par transactions bornées de 50 lignes, avec suivi de progression en temps réel et journaux de résultats téléchargeables (result.csv).

Régulation HTTP/2 APNs & pooling de connexions pour Apple Wallet

Lors de la mise à jour de passes Apple Wallet, Passinstance diffuse des notifications push qui invitent les appareils iOS à se réveiller silencieusement et à récupérer le bundle .pkpass mis à jour depuis l'API Passinstance :

  • Notifications push silencieuses : les notifications de passe sont envoyées avec content-available: 1. Elles n'affichent pas de pop-up intrusif sur l'écran verrouillé, sauf si des messages de modification de champ localisés (par ex. « Votre porte d'embarquement est désormais la B12 ») sont configurés.
  • Flux HTTP/2 persistants : le service @passinstance/apns maintient des connexions HTTP/2 persistantes et mutualisées vers les serveurs push d'Apple (api.push.apple.com:443). Plutôt que d'ouvrir et fermer une négociation TLS pour chaque destinataire, les flux sont multiplexés sur les connexions actives.
  • Limitation de débit adaptative & régulation de file :

- Les notifications sortantes transitent par des files de tâches en arrière-plan (push-notifications, individual-push-notifications, silent-push-notifications). - Notification Rate Limiter et Notification Deduplication surveillent le flux de réponses d'Apple. - Si APNs renvoie 429 TooManyRequests ou une contre-pression au niveau connexion, les workers réduisent la concurrence et appliquent un délai d'attente exponentiel, évitant l'invalidation des jetons et le blocage d'adresse IP.

Mises à jour de classe Google Wallet vs PATCH d'objet

Google Wallet s'appuie sur une architecture hiérarchique séparant la Pass Class (définition maître du modèle) du Pass Object (instance individuelle du titulaire) :

  • Mises à jour visuelles et de champs au niveau modèle (Issuer Class) :

Lorsqu'une modification globale est publiée sur un modèle (par ex. changement du logo d'en-tête, de la couleur d'arrière-plan ou des conditions du programme) et cible toutes les cartes sans texte personnalisé (!hasPersonalizedMessage), Passinstance invoque la synchronisation de classe Google Wallet (Google Wallet class sync) dans template.service.ts. Un seul appel REST PATCH est envoyé à l'API Google Wallet pour mettre à jour l'Issuer Class. Comme chaque passe Google Wallet émis référence cette classe parente, les serveurs cloud de Google propagent immédiatement la mise à jour à tous les passes Android actifs simultanément, sans générer des milliers de requêtes API individuelles.

  • Mises à jour d'attributs propres au titulaire (Pass Object) :

Lorsque des attributs varient d'un passe à l'autre (soldes de points individuels, changements de palier ou noms personnalisés), Passinstance exécute des appels HTTP PATCH individuels sur le Pass Object Google Wallet concerné (POST /batch-pass-operations/update).

Règles de validation et de sécurité des attributs

Le service de mise à jour par lot (batch-pass-operations.service.ts) applique une intégrité stricte des données :

  • Isolation multi-locataire : les champs protégés (customerId, tenantId, createdBy, templateId) sont automatiquement retirés des charges utiles entrantes. Les mises à jour ne peuvent ni modifier la propriété d'un passe ni réaffecter son modèle parent.
  • Validation partielle des attributs (preValidateAttributes) : lors de la mise à jour de passes existants (isUpdate = true), les contrôles de champs requis sont ignorés. Vous pouvez mettre à jour une seule propriété personnalisée (par ex. pointsBalance) sans renvoyer les champs inchangés.
  • Normalisation des attributs : les chaînes sont rognées, les nombres sont convertis en flottants/entiers et les dates sont normalisées au format ISO-8601 UTC.

Opérations en masse prises en charge (tableau de bord & API)

OpérationEndpoint APIDTO & comportement
Création par lotPOST /api/v1/batch-pass-operations/createrequest payload (passes[], max 1,000 éléments). Émet de nouveaux passes avec externalId et bundleId facultatifs.
Mise à jour par lotPOST /api/v1/batch-pass-operations/updaterequest payload (operation: "update", passIds[], updateData, bundleOptions facultatif).
Upsert par lotPOST /api/v1/batch-pass-operations/upsertrequest payload (operation: "upsert", passData[]) indexé sur le couple locataire (customerId, externalId).
Activation par lotPOST /api/v1/batch-pass-operations/activaterequest payload (operation: "activate", passIds[]) faisant passer les passes au statut ACTIVE.
Désactivation (invalidation) par lotPOST /api/v1/batch-pass-operations/deactivaterequest payload (operation: "deactivate", passIds[]) faisant passer les passes à SUSPENDED / INACTIVE et invalidant les codes-barres.
Suppression par lotPOST /api/v1/batch-pass-operations/deleterequest payload (passIds[]) faisant transiter les passes par DELETING -> suppression logique (archivedAt: new Date()).
Regroupement en bundle par lotPOST /api/v1/bundles/batch-createRegroupe les IDs de passes sélectionnés dans des conteneurs pass bundle partagés (Pass.bundleId, jusqu'à 10 passes par bundle).

Important : inspectez toujours errors et warnings dans request payload. Lorsque validateBatchOperation détecte des lignes invalides, le contrôleur renvoie success: false avec un diagnostic détaillé par élément dans errors[].


Référence des opérations par lot par programmation (request payload)

1. Upsert de passes par lot (POST /api/v1/batch-pass-operations/upsert)

Idéal pour les synchronisations CRM ou les recalculs de paliers de fidélité indexés sur externalId :

Requête HTTP

POST /api/v1/batch-pass-operations/upsert En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "operation": "upsert",
  "passData": [
    {
      "templateId": "tmpl_01hxyz987654321",
      "externalId": "crm_usr_44910",
      "attributes": {
        "firstName": "Marcus",
        "lastName": "Vance",
        "pointsBalance": 1800,
        "memberTier": "Platinum"
      }
    },
    {
      "templateId": "tmpl_01hxyz987654321",
      "externalId": "crm_usr_44911",
      "attributes": {
        "firstName": "Hannah",
        "lastName": "Abbott",
        "pointsBalance": 250,
        "memberTier": "Silver"
      }
    }
  ]
}

Réponse HTTP (200 OK)

JSON
{
  "success": true,
  "data": [
    {
      "id": "pass_01j8k9m2n3p4q5r6",
      "externalId": "crm_usr_44910",
      "serialNumber": "PI-GOLD-2026-44910",
      "passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6"
    },
    {
      "id": "pass_01j8k9m9z8y7x6w5",
      "externalId": "crm_usr_44911",
      "serialNumber": "PI-GOLD-2026-44911",
      "passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m9z8y7x6w5"
    }
  ],
  "message": "Successfully upserted 2 passes",
  "errors": [],
  "warnings": []
}

2. Mise à jour de passes par lot (POST /api/v1/batch-pass-operations/update)

Met à jour les passIds sélectionnés avec un objet updateData commun et des bundleOptions facultatives :

POST /api/v1/batch-pass-operations/update En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "operation": "update",
  "passIds": [
    "pass_01j8k9m2n3p4q5r6",
    "pass_01j8k9m9z8y7x6w5"
  ],
  "updateData": {
    "expirationDate": "2028-03-31T23:59:59Z",
    "attributes": {
      "seasonalOffer": "2x Winter Bonus Points"
    }
  }
}

Réponse HTTP (200 OK)

JSON
{
  "success": true,
  "data": [
    {
      "id": "pass_01j8k9m2n3p4q5r6",
      "status": "ACTIVE",
      "updatedAt": "2026-11-16T12:00:00.000Z"
    },
    {
      "id": "pass_01j8k9m9z8y7x6w5",
      "status": "ACTIVE",
      "updatedAt": "2026-11-16T12:00:00.000Z"
    }
  ],
  "message": "Successfully updated 2 passes",
  "errors": [],
  "warnings": []
}

3. Activer, désactiver ou supprimer des passes par lot

  • Activer : POST /api/v1/batch-pass-operations/activate ({ "operation": "activate", "passIds": [...] })
  • Désactiver : POST /api/v1/batch-pass-operations/deactivate ({ "operation": "deactivate", "passIds": [...] })
  • Supprimer : POST /api/v1/batch-pass-operations/delete ({ "passIds": [...] } via request payload)

Intégration d'envoi : quelle variable insère le lien du passe ? ({passDownloadUrl})

Quelle variable insère le lien du passe ?

Lorsque vous enchaînez des opérations en masse avec des notifications automatisées par e-mail ou SMS, Passinstance met à disposition un moteur souple de substitution de variables (pass-url-placeholder.util.ts). Le jeton canonique est {passDownloadUrl}.

Variable canonique & alias pris en charge

La variable officielle et canonique est {passDownloadUrl}. Passinstance prend également en charge des alias rétrocompatibles :

Jeton de variableCanonique / AliasExemple de résultat résolu
{passDownloadUrl}Canoniquehttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{passLink}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{smartLink}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{downloadUrl}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{passUrl}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{walletDownloadUrl}Alias dynamiqueLien contextuel redirigeant selon le système d'exploitation du client

Souplesse de formatage : Passinstance normalise automatiquement la syntaxe à doubles accolades {{passDownloadUrl}}, le snake_case {pass_download_url} et le PascalCase {PassDownloadUrl} vers le jeton canonique.

Boutons d'action Wallet directs & indicateurs conditionnels

Pour les modèles d'e-mails HTML responsives, vous pouvez construire des boutons d'ajout direct au portefeuille en un clic plutôt que de passer uniquement par la page intermédiaire PassFlow :

VariableDescription
{appleWalletUrl}Flux binaire direct .pkpass déclenchant l'installation native dans Apple Wallet sous iOS Safari.
{googleWalletUrl}Lien profond direct d'ajout à Google Wallet (https://pay.google.com/gp/v/save/...).
{samsungWalletUrl}Lien profond direct d'enregistrement dans Samsung Wallet.
{walletButtonText}Libellé de bouton contextuel (« Ajouter à Apple Wallet », « Enregistrer dans Google Wallet » ou « Télécharger mon passe »).
{showAppleWalletButton}Indicateur booléen (true/false) signalant si les actifs Apple Wallet sont configurés.
{showGoogleWalletButton}Indicateur booléen signalant si l'intégration Google Wallet est active.

Échecs partiels, gestion des erreurs & journalisation d'audit

Lors de l'appel d'opérations par lot, la requête n'échoue pas dans son ensemble si un sous-ensemble d'éléments contient des erreurs :

  1. 1
    Isolation des échecs par élément : dans updateBatchPasses, chaque passe est traité dans un bloc try-catch isolé. Une erreur sur la ligne 42 (par ex. format de date invalide) n'empêche pas les lignes 1 à 41 ni 43 à 100 de réussir.
  2. 2
    Structure d'erreur standardisée : les éléments en échec sont consignés dans errors[] avec passId, le message error et errorCode :
JSON
{
     "passId": "pass_01j8k9m2n3p4q5r6",
     "error": "Attribute 'pointsBalance' must be a valid number",
     "errorCode": "ATTR_VALIDATION"
   }
  1. 3
    Journal d'audit de l'espace de travail : chaque opération en masse génère une entrée dans le journal d'audit des passes (pass audit log) et dans le journal d'audit de l'espace de travail (GET /api/v1/audit-log/export.csv), enregistrant l'identifiant de l'acteur, l'adresse IP, le type d'opération, le nombre d'éléments affectés et l'horodatage.

Pour les imports par lot basés sur des fichiers CSV, consultez Création de passes en masse. Pour l'invalidation massive sur tout un modèle, consultez Cycle de vie & statuts des passes.

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.