Opérations par lots

Mettez à jour des cartes en masse à l’aide de l’API de mise à jour push ou d’importations de fichiers plats SFTP.

Opérations par lot

The Wallet Crew prend en charge deux mécanismes pour mettre à jour des Cartes en masse : l’API de mise à jour push et les imports de fichiers plats SFTP.

API de mise à jour push

L’opération ci-dessous déclenche une mise à jour push sur toutes les Cartes qui correspondent à une condition de filtre. C’est le principal mécanisme par lot pour les systèmes connectés à l’API.

Le point de terminaison accepte le même filtre tableau que le point de terminaison de liste des Cartes. Voir Filtres et opérateurs de requête pour la référence complète des filtres.

Push update for passes matching the filter.

post

/api/{tenantId}/passes/pushUpdate

Authorization: Requires Pass.Write scope.

Filtering: Same as GetPasses�identifiers, metadata, pass type, installation status.

Async: Updates are queued. 200 response means scheduled, not complete. Monitor via statistics endpoint.

Data Merge: Merged into each matching pass. Set UpdateMetadata=true for recomputation (slower). Adjust Throughput for concurrency.

Bulk Operations: Ideal for campaigns, loyalty updates, seasonal offers. Use CorrelationId for tracking.

Use Cases: Campaign push; loyalty tier changes; offer refresh; bulk metadata updates.

Example — push a seasonal offer to all loyalty passes:

POST /api/{tenantId}/passes/pushUpdate
    ?filter[0].field=passType&filter[0].operator=equals&filter[0].value=loyalty
            
{
  "additionalData": { "offer": "summer2025", "discount": "20%" },
  "options": {
    "updateMetadata": true,
    "throughput": 12,
    "correlationId": "campaign-summer-2025"
  }
}

Scopes requis

Cet endpoint nécessite les scopes suivants :

Autorisations

OAuth2implicitRequis

Authorization URL:

Paramètres de chemin

tenantIdstringRequis

Paramètres de requête

Corps

additionalDataobject · nullableOptionnel

Arbitrary data to persist with the pass (for example, loyalty tier, store code, or campaign flags).

passTypestring · nullableOptionnel

Optional pass type to convert the pass to.

updateMetadatabooleanOptionnelObsolète

Specifies if passes metadata should be updated. Updating metadata is time consuming and could be avoided for notification only push update

Default: false

Réponses

200

Passes scheduled for update; returns the count in the response body.

Result returned after scheduling a bulk push update operation.

passCountinteger · int32Optionnel

Count of passes scheduled for update.

post/api/{tenantId}/passes/pushUpdate

POST /api/{tenantId}/passes/pushUpdate HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 158

{
  "identifiers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "additionalData": null,
  "passType": null,
  "options": {
    "throughput": 1,
    "updateMetadata": true,
    "correlationId": null
  }
}

200

Passes scheduled for update; returns the count in the response body.

{
  "passCount": 1
}

Chaque Carte correspondante est mise en file d’attente pour mise à jour indépendamment. La plateforme résout tous les identifiants de Carte correspondants dans la requête, puis les place en file d’attente comme une seule commande contenant N tâches individuelles par Carte. La 200 réponse signifie que le lot a été accepté et planifié — pas qu’il est terminé.

Il n’existe aucune limite stricte au nombre de Cartes qu’un seul appel peut correspondre. bypassQueue n’est pas disponible sur ce point de terminaison.

Vous pouvez fournir un correlationId dans le corps de la requête. La plateforme l’attache à chaque tâche mise en file d’attente, ce qui vous permet de suivre la progression du traitement via le point de terminaison des statistiques. Il n’existe aucun webhook d’achèvement au niveau du lot.

Échecs partiels

Chaque Carte est traitée indépendamment. Un échec sur une Carte — par exemple, une erreur de connecteur ou une Carte introuvable — n’affecte pas les autres Cartes du lot. Les Cartes en échec ne sont pas retentées automatiquement, sauf si l’erreur sous-jacente est transitoire.

Importations de fichiers plats SFTP

Les imports SFTP vous permettent de mettre à jour des données supplémentaires, des identifiants, des modèles de Carte et des métadonnées sur de nombreuses Cartes en téléversant un fichier CSV. Cette méthode est conçue pour les systèmes hérités qui ne peuvent pas appeler l’API directement.

Les imports SFTP constituent une solution de dernier recours. Utilisez l’API de mise à jour push pour tout système prenant en charge les appels HTTP. SFTP est une fonctionnalité optionnelle — contactez The Wallet Crew pour l’activer sur votre tenant.

Chaque ligne du CSV cible une seule Carte. Les Cartes sont mises à jour de manière asynchrone après la détection du fichier sur le serveur SFTP. Comme pour l’API de mise à jour push, les opérations sont par Carte et indépendantes.

Pour le format complet du fichier, la référence des colonnes, les identifiants SFTP et les scripts de mappage personnalisés, voir Mettre à jour une Carte à l’aide de fichiers plats dans l’espace Configuration.

Choisir entre les deux approches

API de mise à jour push

Fichier plat SFTP

Idéal pour

Intégrations en temps réel ou planifiées avec accès à l’API

Systèmes hérités avec exportations de fichiers plats uniquement

Ciblage

Conditions de filtre (n’importe quel champ de données de Carte)

Identifiant par ligne (liste explicite)

Données mises à jour

Déclenche un nouveau chargement du connecteur via push

Met à jour additionalData, identifiants, passType, métadonnées directement

Configuration

Aucune configuration supplémentaire requise

Fonctionnalité optionnelle — doit être activée pour chaque tenant

Suivi de la progression

correlationId + point de terminaison des statistiques

Déclenchement sans suivi

Suivi de la progression du lot dans la console

La console d’administration fournit une vue en temps réel de toutes les opérations par lot. Ouvrez Paramètres → Surveillance → mises à jour Wallet.

La page affiche toutes les opérations de mise à jour push avec les colonnes suivantes :

Colonne

Description

Début

Quand le lot a été mis en file d’attente

Dernière activité

Événement de traitement le plus récent

Opération

Nom interne de l’opération

Corrélation

Le correlationId fourni dans la requête API

Cartes

Nombre total de Cartes dans le lot

Terminées

Cartes traitées avec succès

Erreurs

Cartes dont le traitement a échoué

Apple

Livraisons Apple Wallet

Google

Livraisons Google Wallet

Statut

Statut global du lot, par exemple Terminées

Pour faire correspondre un appel API à une ligne, fournissez un correlationId dans l’opération de mise à jour push. La valeur apparaît dans la Corrélation colonne, ce qui permet de retrouver facilement le lot parmi les opérations concurrentes.

Les opérations en cours peuvent être annulées depuis cette page. Il n’existe aucun webhook d’achèvement au niveau du lot. Utilisez cette vue pour le suivi opérationnel.

Mis à jour il y a 23 jours