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

Création de passes en masse

Importez des fichiers CSV via Opérations en lot ou FTP/SFTP, associez vos colonnes et suivez l'avancement du traitement.

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

Panneau des tâches d'import par lot (Zoom)

Lancez une « New import job » depuis la vue d'ensemble du modèle et suivez les traitements CSV en cours, échoués ou terminés.

Aperçu

Lorsque vous intégrez simultanément des centaines ou des centaines de milliers de titulaires, Passinstance propose un pipeline asynchrone et tolérant aux pannes d'ingestion CSV par lot, propulsé par Batch Jobs API (/api/v1/batch-processing) et des files de workers en arrière-plan soutenues par un cache en mémoire. Les opérateurs peuvent téléverser des feuilles de calcul UTF-8 depuis le tableau de bord (Opérations par lot -> Importer des passes), déclencher des imports FTP/SFTP automatisés ou orchestrer le pipeline CSV en 6 étapes par programmation via l'API REST.

Compteurs des tâches d'import par lot et bouton de nouvel import
Compteurs des tâches d'import par lot et bouton de nouvel import

Architecture système : émission CSV par lot & pipeline de workers en arrière-plan

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : ÉMISSION CSV PAR LOT & PIPELINE ASYNCHRONE
ÉTAPE 01 IMPORT CSV TABLEAU DE BORD / API (Batch Jobs API)
1
GET/api/v1/batch-processing/templates/:templateId/sample-csv
2
POST/api/v1/batch-processing (Envoi multipart CSV UTF-8)
3
POST/api/v1/batch-processing/templates/:templateId/field-mapping-recommendations
ÉTAPE 02 MAPPAGE DE SCHÉMA & VALIDATION PRÉALABLE À BLANC
4
PUT/api/v1/batch-processing/:id/field-mapping (Associe en-têtesclés)
5
POST/api/v1/batch-processing/:id/validate
Vérifie propriétés personnalisées requises, dates ISO, nombres & externalId
Signale les erreurs de syntaxe/schéma ligne par ligne avant écriture en BDD
ÉTAPE 03 PIPELINE WORKER ASYNCHRONE (cache en mémoire)
Traite les lots CSV validés en flux par transactions bornées
Génère fiches Pass, serialNumber, authenticationToken & liens smart
Compile le rapport téléchargeable : GET/api/v1/batch-processing/:id/result.csv

Liste de vérification préalable

Prérequis : avant de lancer une tâche d'import CSV en masse, vérifiez les éléments suivants :

1. Le modèle cible (Template) doit être au statut PUBLISHED.

2. Votre fichier CSV doit être encodé en UTF-8, sans séparateurs malformés ni guillemets non échappés.

3. Incluez les colonnes email et/ou phone si vous prévoyez d'envoyer automatiquement les liens de téléchargement des passes via les campagnes du Delivery Center après génération.

4. Configurez la source External ID dans les paramètres du modèle (externalId) si vous souhaitez une déduplication idempotente lors d'imports répétés.

Parcours d'import CSV étape par étape (Bulk Pass Wizard)

Dans le tableau de bord sous Batch -> Batch Processing (/batch-processing), l'assistant guide les opérateurs à travers cinq étapes (Modèle -> Téléverser le CSV -> Associer les champs -> Options d'envoi (facultatif) -> Traiter) :

  1. 1
    Modèle : sélectionnez le modèle cible PUBLISHED / PRODUCTION (ou ouvrez Passes -> Importer directement depuis un modèle).
  2. 2
    Téléverser le CSV : déposez un fichier CSV UTF-8 ou téléchargez l'exemple CSV dynamique (GET /api/v1/batch-processing/templates/:templateId/sample-csv) pré-rempli avec les en-têtes correspondant aux propriétés personnalisées de votre modèle et aux champs système (externalId, expirationDate, etc.).
  3. 3
    Associer les champs : passez en revue les recommandations automatiques de mappage de colonnes assorties d'un score de confiance (POST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendations) reliant vos en-têtes (par ex. Customer_ID, First_Name) à externalId ou aux clés attributes.*.
  4. 4
    Options d'envoi (si activées) : choisissez un modèle d'e-mail ou de SMS si les nouveaux passes doivent être expédiés automatiquement à la fin du traitement.
  5. 5
    Traiter : validez puis lancez la tâche dans la file de traitement en arrière-plan (statuts de tâche par lot : NEW, READY_TO_RUN, INTEGRATION_MAPPING_COMPLETE, SENDOUT_PENDING, RUNNING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELLED, PAUSED), puis téléchargez /result.csv contenant chaque serialNumber, externalId, bundleId et lien de téléchargement généré.

Référence de l'API REST de traitement par lot (Batch Jobs API)

Tous les endpoints de tâches CSV par lot sont montés sous /api/v1/batch-processing (prenant en charge les types de tâches : CREATE_PASSES, UPDATE_PASSES, DELETE_PASSES, IMPORT_DATA, EXPORT_DATA, MIGRATION et les sources de données : CSV_UPLOAD, API, SEGMENT, QUERY, MANUAL) :

ÉtapeMéthode HTTP & EndpointObjectif
1. Exemple CSVGET /api/v1/batch-processing/templates/:templateId/sample-csvTélécharge un gabarit d'en-têtes CSV UTF-8 dynamique adapté aux propriétés personnalisées du modèle.
2. Téléverser le CSVPOST /api/v1/batch-processingTéléverse un fichier CSV multipart ou une définition JSON de tâche par lot (status: NEW / READY_TO_RUN).
3. Mappage automatiquePOST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendationsAnalyse les en-têtes du CSV et renvoie des suggestions de correspondance d'attributs avec score de confiance.
4. Enregistrer le mappagePUT /api/v1/batch-processing/:id/field-mappingEnregistre sur la tâche le dictionnaire confirmé de correspondance entre colonnes CSV et attributs.
5. Validation à blancPOST /api/v1/batch-processing/:id/validateExécute une validation non destructive sur les lignes du CSV et retourne les avertissements/erreurs par ligne.
6. Démarrer le workerPOST /api/v1/batch-processing/:id/startMet en file le worker d'arrière-plan (status: RUNNING) pour émettre les passes de manière asynchrone.
7. Exporter les résultatsGET /api/v1/batch-processing/:id/result.csvDiffuse un rapport CSV ajoutant passId, serialNumber, les liens de téléchargement et le statut de chaque ligne.

Exemple : demander des recommandations de mappage de champs

POST /api/v1/batch-processing/templates/tmpl_01hxyz987654321/field-mapping-recommendations En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "csvHeaders": [
    "Customer_ID",
    "First_Name",
    "Last_Name",
    "Loyalty_Points",
    "Card_Expiry"
  ]
}

Réponse HTTP (200 OK)

JSON
{
  "success": true,
  "data": {
    "recommendations": [
      { "csvColumn": "Customer_ID", "targetField": "externalId", "confidence": 0.98, "matchType": "SYSTEM" },
      { "csvColumn": "First_Name", "targetField": "attributes.firstName", "confidence": 0.96, "matchType": "CUSTOM_PROPERTY" },
      { "csvColumn": "Last_Name", "targetField": "attributes.lastName", "confidence": 0.96, "matchType": "CUSTOM_PROPERTY" },
      { "csvColumn": "Loyalty_Points", "targetField": "attributes.pointsBalance", "confidence": 0.89, "matchType": "CUSTOM_PROPERTY" },
      { "csvColumn": "Card_Expiry", "targetField": "expirationDate", "confidence": 0.94, "matchType": "SYSTEM" }
    ]
  },
  "statusCode": 200
}

Exemple : confirmer le mappage de champs & valider la tâche

PUT /api/v1/batch-processing/job_batch_77123/field-mapping En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "duplicateStrategy": "UPSERT_BY_EXTERNAL_ID",
  "mappings": {
    "Customer_ID": "externalId",
    "First_Name": "attributes.firstName",
    "Last_Name": "attributes.lastName",
    "Loyalty_Points": "attributes.pointsBalance",
    "Card_Expiry": "expirationDate"
  }
}

Validez ensuite puis démarrez le worker en file d'arrière-plan :

POST /api/v1/batch-processing/job_batch_77123/validate POST /api/v1/batch-processing/job_batch_77123/start

JSON
{
  "success": true,
  "data": {
    "id": "job_batch_77123",
    "status": "RUNNING",
    "jobType": "CREATE_PASSES",
    "dataSource": "CSV_UPLOAD",
    "totalRows": 5000,
    "processedRows": 0
  },
  "statusCode": 200
}

Dépannage & Foire aux questions

Comment vérifier ce qui s'est passé lorsqu'une tâche de traitement par lot échoue ?

Lorsqu'un import CSV asynchrone rencontre une anomalie, consultez l'état et les journaux de la tâche via le tableau de bord ou l'API REST :

  1. 1
    Tiroir de tâche du tableau de bord : accédez à Batch -> Batch Processing (/batch-processing). Les tâches terminées avec erreurs affichent un badge Terminé avec erreurs (COMPLETED_WITH_ERRORS), tandis que les tâches interrompues affichent Échec (FAILED).
  2. 2
    Télécharger le journal d'erreurs : cliquez sur la carte de la tâche et sélectionnez Télécharger le CSV d'erreurs (Download Error CSV) ou appelez GET /api/v1/batch-processing/:id/result.csv. Le fichier généré reprend chaque ligne du CSV source complétée par une colonne status (SUCCESS, SKIPPED ou FAILED) et une colonne errorMessage détaillant le motif d'échec (par exemple : « Propriété personnalisée requise manquante : firstName », « Format de date ISO 8601 invalide » ou « externalId en doublon »).
  3. 3
    Inspecter les détails de la tâche via l'API : appelez GET /api/v1/batch-processing/:id avec votre clé API. La réponse JSON renvoie request payload, incluant totalRows, processedRows, successfulRows, failedRows, ainsi que le tableau errorDetails[] précisant les numéros de ligne exacts et les codes d'erreur de validation.
  4. 4
    Contrôle préalable avant exécution : avant de mettre en file une tâche de 100 000 lignes, appelez toujours POST /api/v1/batch-processing/:id/validate. Cette étape à blanc contrôle les correspondances d'en-têtes et les schémas d'attributs sans créer d'enregistrements en base, et signale les erreurs de syntaxe avant le démarrage des workers.

Pourquoi mon traitement par lot a-t-il créé moins de passes qu'il n'y a de lignes dans le fichier ?

Si votre fichier CSV contenait 5 000 lignes mais que la tâche n'indique que 4 820 passes créés, vérifiez les comportements vérifiés de la plateforme suivants :

  1. 1
    Déduplication par External ID (duplicateStrategy) : si votre modèle impose l'unicité de l'identifiant externe et que duplicateStrategy est défini sur SKIP, les lignes partageant un externalId avec un passe actif existant dans votre espace de travail (ou déjà présent plus haut dans le même fichier CSV) sont ignorées afin d'éviter les émissions en doublon. Pour mettre à jour les passes existants à la place, sélectionnez duplicateStrategy: "UPSERT_BY_EXTERNAL_ID".
  2. 2
    Lignes vides ou finales sans données : les tableurs (Excel, Google Sheets) exportent souvent des lignes vierges en fin de fichier contenant uniquement des virgules. L'analyseur CSV de Passinstance écarte automatiquement les lignes vides sans incrémenter le compteur de passes générés.
  3. 3
    Rejets de pré-validation d'attributs : les lignes comportant des types de données invalides (texte non numérique dans un attribut numérique, syntaxe d'e-mail invalide ou chaîne de date illisible) échouent individuellement à la validation et sont consignées dans le journal d'erreurs sans interrompre toute la tâche.
  4. 4
    Épuisement du quota de passes actifs (PASS_LIMIT_REACHED) : si votre espace de travail atteint 100 % de la limite de passes actifs de son forfait pendant le traitement, les lignes suivantes échouent avec le code PASS_LIMIT_REACHED. Consultez Paramètres de l'entreprise -> Utilisation & facturation pour vérifier votre quota restant.

Est-il normal d'attendre plusieurs heures pour un traitement par lot ?

  • Vitesses de traitement habituelles : les files de workers en arrière-plan de Passinstance génèrent généralement entre 500 et 2 000 passes par minute, selon que les signatures cryptographiques Apple Wallet .pkpass et les images de codes-barres sont générées de façon synchrone ou différées au moment du téléchargement. Un lot de 10 000 passes se termine habituellement en 5 à 15 minutes.
  • Cas où plusieurs heures sont normales :

- Volumes d'ingestion massifs : les très gros imports (de 100 000 à plus de 500 000 passes) prennent plusieurs heures afin de préserver la stabilité des pools de connexions en base de données et des files en mémoire sans saturer votre espace de travail. - Envois sortants immédiats : si vous avez rattaché une campagne d'envoi par e-mail ou SMS à la tâche par lot, les e-mails sortants sont régulés selon les quotas de débit de la livraison e-mail gérée (par ex. 14 à 50 e-mails/seconde) et les limites de connexion de votre serveur SMTP personnalisé afin de protéger la réputation de votre domaine.

  • Cas où une tâche est bloquée ou nécessite une action :

- Si une tâche reste en statut NEW ou READY_TO_RUN pendant des heures, le worker n'a jamais été démarré. Cliquez sur Démarrer la tâche (Start Job) dans le tableau de bord ou appelez POST /api/v1/batch-processing/:id/start. - Si la tâche est au statut PAUSED, reprenez son exécution via POST /api/v1/batch-processing/:id/resume.

Un passe peut-il expirer un nombre fixe de jours après son émission ?

Oui. Passinstance prend en charge à la fois l'expiration à date calendaire fixe et les périodes de validité glissantes dynamiques :

  1. 1
    Durée glissante dynamique (validityInDays) : dans l'éditeur visuel sous Validité & expiration, réglez la stratégie d'expiration sur Durée dynamique (Dynamic Duration) et indiquez le nombre de jours (par ex. 30, 90 ou 365). À chaque création de passe via import CSV, API ou formulaire PassFlow, Passinstance calcule automatiquement :

expirationDate = issuanceTimestamp + (validityInDays * 86400 seconds).

  1. 2
    Surcharge d'expiration par ligne : si chaque client dispose d'une date de fin de contrat propre, associez directement une colonne CSV contenant des horodatages ISO 8601 (par ex. 2027-06-30T23:59:59Z) au champ système expirationDate lors de l'étape Associer les champs.
  2. 3
    Prolongation après émission : vous pouvez prolonger ou modifier les dates d'expiration de milliers de passes en production à tout moment via les Opérations en masse.

Comment migrer des données clients existantes depuis un autre fournisseur Wallet ou un CRM ?

La migration depuis des systèmes existants (tels qu'Airship, PassKit, Braze ou une base de données interne) vers Passinstance se déroule en douceur :

  1. 1
    Exporter les fiches existantes : exportez votre base clients actuelle au format CSV UTF-8 en incluant les noms des membres, coordonnées, soldes de points, statuts de palier et numéros de carte historiques.
  2. 2
    Configurer le modèle cible : créez un modèle équivalent dans Passinstance. Configurez vos propriétés personnalisées (par ex. memberId, pointsBalance, tier) et la symbologie du code-barres (QR, Aztec, Code 128 ou PDF417).
  3. 3
    Associer les identifiants historiques à externalId : reliez votre numéro de carte historique ou UUID client au champ système externalId de Passinstance. Cela garantit une continuité 1:1 et évite les doublons.
  4. 4
    Exécuter l'ingestion CSV par lot : téléversez le fichier CSV via l'assistant en 5 étapes. Choisissez la stratégie UPSERT_BY_EXTERNAL_ID afin que tout enregistrement préexistant soit mis à jour proprement.
  5. 5
    Transition transparente pour les titulaires : si votre organisation conserve le même Apple Pass Type Identifier et le même certificat de signature, les clients recevront leurs passes mis à jour sans devoir supprimer leurs cartes actuelles du portefeuille. À défaut, diffusez de nouveaux liens de téléchargement intelligents via le Delivery Center à l'aide de la variable {passDownloadUrl}.

Comment nettoyer les passes après la fin d'un événement ?

Une fois un concert, un match sportif ou une campagne saisonnière terminé, maintenez votre espace de travail propre et libérez votre quota actif :

  1. 1
    Isoler la cohorte de l'événement : dans le tableau de bord sous Passes (/passes), filtrez sur le modèle de l'événement ou utilisez le tiroir de recherche avancée avec expirationDate < today.
  2. 2
    Sélectionner tous les passes correspondants : cochez la case de StickySelectionToolbar pour sélectionner la vue courante, puis cliquez sur la bannière proposant de sélectionner tous les passes correspondant au filtre sur toutes les pages.
  3. 3
    Exécuter une invalidation / désactivation en masse : cliquez sur Actions en masse -> Désactiver / Invalider (POST /api/v1/batch-pass-operations/deactivate). Le statut des passes passe à VOIDED, un bandeau de code-barres invalidé s'affiche sur l'écran verrouillé et la validation au scanner est désactivée, tout en conservant l'historique des scans et des présences pour vos rapports de conformité.
  4. 4
    Suppression logique (DELETING -> SOFT) : si vous souhaitez retirer les passes expirés de votre vue active du tableau de bord, choisissez Actions en masse -> Supprimer. Les passes supprimés logiquement ne sont plus décomptés dans les limites de passes actifs de votre abonnement et libèrent leur externalId pour un usage futur, tout en restant accessibles dans les exports d'audit historiques.

Pour les opérations par lot directes par tableau JSON sans fichier CSV, consultez Opérations en masse. Pour distribuer par e-mail les passes fraîchement importés, consultez Envoi par e-mail & SMS.

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.