Mettre à jour la Carte à l'aide de fichiers plats

The Wallet Crew peut mettre à jour des cartes Apple Wallet et Google Wallet existantes à partir d’un fichier CSV. C’est utile pour les mises à jour en masse et pour les systèmes hérités qui ne peuvent exporter que des fichiers plats.

Les imports SFTP sont une fonctionnalité optionnelle. Demandez à The Wallet Crew d’activer SFTP sur votre tenant avant de mettre en œuvre ce flux.

Considérez les imports SFTP comme une solution de dernier recours. Évitez ce flux sauf si vous n’avez aucune autre option (par exemple, un système hérité qui ne peut exporter que des fichiers plats).

Pour la plupart des projets, l’API est l’approche recommandée. Elle est plus facile à automatiser, plus facile à surveiller et se met à jour en temps réel.

Si vous préférez une intégration en temps réel, utilisez plutôt le flux de mise à jour via l’API. Voir .

Exemples concrets

Un programme de cartes-cadeaux recalcule le solde toutes les heures. Une exportation de fichier plat met à jour additionalData.balance pour toutes les cartes actives.
Une équipe d’automatisation marketing exporte un CSV pour préparer une campagne push. Chaque ligne met à jour additionalData.notification_content avant l’envoi des notifications.
Un système de billetterie exporte les changements de dernière minute (porte, siège ou horaire). Une mise à jour CSV en masse maintient les billets exacts juste avant l’ouverture des portes.
Une chaîne de salles de sport exporte chaque nuit le statut d’adhésion (actif, gelé, expiré). Le lendemain, les membres voient le bon statut à l’enregistrement.
Une équipe support corrige un identifiant erroné à grande échelle en téléversant un fichier de correction ponctuel.

Diagram showing a CSV file uploaded to SFTP, then processed by The Wallet Crew to update passes.

Vue d’ensemble du processus

Téléversez votre fichier CSV sur le serveur SFTP fourni.
The Wallet Crew détecte automatiquement les nouveaux fichiers et les traite immédiatement.
Une fois traité, le fichier est déplacé vers .processed/ ou .error/.
Chaque ligne est interprétée comme une instruction de mise à jour pour une seule carte.
Les cartes sont mises en file d’attente pour mise à jour et traitées de manière asynchrone.

Format de fichier

Les fichiers téléversés doivent être valides RFC 4180{target="_blank"} fichiers CSV conformes.

Séparateurs: soit , ou ;
Ligne d’en-tête: Obligatoire. Doit contenir les noms de colonnes.
Encodage: UTF-8 recommandé
Analyseur: The Wallet Crew utilise CsvHelper{target="_blank"} avec les options par défaut

Chaque ligne de données cible une seule carte et peut inclure plusieurs mises à jour de ses champs, de additionalData ou des métadonnées.

Nom de fichier

Il n’existe aucune exigence stricte pour le nom du fichier. Cependant, pour une meilleure organisation et traçabilité, nous recommandons la convention de nommage suivante :

<source>-cartes-<YYYYMMDD>-<HHMMSS>.csv

Exemples :

crm-cartes-20250801-083000.csv 
loyalty-cartes-20250731-235959.csv

Remarques :

L’extension du fichier doit être .csv.
Évitez d’utiliser des caractères spéciaux (espaces, #, %, &, etc.) dans les noms de fichier
Si vous utilisez un script ou une intégration pour générer des fichiers, l’adoption d’un schéma de nommage basé sur un horodatage aide à éviter les doublons et facilite le débogage.
Si le fichier est volumineux, The Wallet Crew surveille brièvement sa taille afin de s’assurer qu’il est entièrement écrit avant le traitement.

Référence de colonne

Colonnes d’identifiant de Carte

Pour sélectionner la Carte cible, utilisez l’une des colonnes suivantes :

id: identifiant interne de Carte The Wallet Crew
id.<externalId>: nom de l’identifiant externe (tel que configuré dans votre tenant) Exemple : id.y2.customerId

Au moins une colonne d’identifiant doit être présente dans chaque ligne.

Colonnes de données supplémentaires

Pour mettre à jour les données supplémentaires sur la carte, utilisez la syntaxe suivante :

additionalData.<key>: Met à jour la clé dans le dictionnaire additionalData de la carte additionalData dictionnaire Exemple : additionalData.notification_content

Plusieurs clés additionalData peuvent être mises à jour dans une seule ligne.

Modèle de Carte

Pour basculer la carte vers un autre modèle, incluez :

passType: le nom du nouveau modèle (tel que défini dans The Wallet Crew)

Si elle est omise ou vide, la carte conservera son modèle actuel.

Actualisation des métadonnées

Pour déclencher un recalcul des métadonnées internes (p. ex. codes-barres, expiration, champs d’affichage) :

updateMetadata: définir sur true pour déclencher la mise à jour des métadonnées

Identifiants externes

Pour mettre à jour un identifiant externe, utilisez la syntaxe suivante :

identifiers.<idName>: Met à jour l’identifiant nommé idName Exemple : identifiers.y2.customerId

Accès SFTP

Téléversez vos fichiers CSV vers le point de terminaison SFTP de votre environnement :

QA: triglav-qa.walletcrew.net (port 22)
Production: triglav.walletcrew.net (port 22)

Contactez le support The Wallet Crew pour demander vos identifiants SFTP.

Exemples

Exemple 1 : Mise à jour du contenu de notification et de l’URL de l’offre

id;additionalData.notification_content;additionalData.offer_url
Gk440DNzvfZcDmlA;Joyeux Noël Alice !;https://acme.com/xmas1
HKlhrhrEXx2ZASYs;Joyeux Noël Bob !;https://acme.com/xmas1

Exemple 2 : Mise à jour par identifiant externe avec informations de fidélité

id.y2.customerId;additionalData.notification_content
00100123;Profitez de 30 % de réduction sur votre prochain achat
04503295;Merci pour votre achat ! Plus que 10 points avant d’échanger un bon de 10 €
02319202;Merci pour votre achat ! Plus que 120 points avant d’échanger un bon de 10 €

Exemple 3 : Changer le modèle de Carte et forcer l’actualisation des métadonnées

id;passType;updateMetadata
gH67xKlPzLZ99xa2;vip_template;true
dAk21jvUZYx39q77;standard_template;true

Exemple 4 : Mettre à jour l’id externe y2.customerId et forcer l’actualisation des métadonnées

id.y2.customerId;identifiers.y2.customerId;passType;updateMetadata
04503295;1010013295;;true
04503296;1010013296;;true

Extensibilité et mappage personnalisé

The Wallet Crew prend en charge des transformations de fichiers personnalisées à l’aide de scripts d’import.

Cela vous permet de :

Adapter votre format d’export existant (p. ex. depuis un CRM ou un système de point de vente)
Mapper les anciens noms de colonnes vers des clés compatibles avec The Wallet Crew
Injecter des valeurs dynamiques (p. ex. la date actuelle, les points calculés)
Enrichir les données avec des recherches dans des sources externes

Pour personnaliser le processus d’import, vous pouvez créer un import.custom.js fichier dans le scripts/ dossier de la configuration avancée.

Si vous avez le fichier CSV suivant :

id.y2.customerId,neo_notification_content,neo_offer_title,neo_offer_body
abc12345,"Salut Arthur !","Votre offre de 20 %","20 % de réduction sur votre prochain achat"

Vous pouvez utiliser le script suivant :

/**
 * Transforme une ligne CSV en objet de type UpdatePassInformation.
 *
 * @param {Object<string, string>} row - La ligne CSV, sous forme de dictionnaire associant les noms de colonnes aux valeurs.
 * @returns {Object} Informations de ligne transformées.
 * @returns {Object<string, string>} return.Identifiers - Identifiants pour cette ligne (p. ex. ID client).
 * @returns {string|null} return.PassType - Le type de Carte, ou null s’il n’est pas présent.
 * @returns {Object<string, string>} return.AdditionalData - Données supplémentaires facultatives issues des colonnes préfixées.
 */
function transform(row){
  const identifiers = {
      "id.y2.customerId" : row["id.y2.customerId"]
  };

  const passType = row.passType || null; 

  const properties = [
    "notification_content",
    "offer_title", 
    "offer_body"
   ];

  let additionalData = {};
  for(const property of properties){
    if(row["neo_" + property] !== undefined){
      additionalData[property] = row["neo_" + property].toString(); 
    }
  }

  return {
    Identifiers : identifiers, 
    PassType: passType,
    AdditionalData : additionalData
  }
}

/**
 * Méthode facultative pour renvoyer un débit personnalisé pour un fichier d’import donné.
 *
 * @param {string} fileName - Le nom du fichier d’import.
 * @returns {number|null} Remplacement du débit, ou null pour utiliser la valeur par défaut.
 */
function getThroughput(fileName) {
  // Exemple : renvoyer null pour utiliser la valeur par défaut
  return null;
}

export default function(context) {
  context.register('runtime.import.updatePasses.rowTransformer', {
    Transform: transform, 
    GetThroughput: getThroughput
  });
}

Contactez notre équipe si vous avez besoin d’aide pour implémenter une logique de mappage personnalisée pour vos imports.

Conseils et bonnes pratiques

Assurez-vous que les identifiants sont exacts pour éviter que des lignes soient ignorées.
Testez toujours votre format de fichier en QA avant de le téléverser en production.
Utilisez un encodage cohérent (UTF-8) pour éviter les problèmes d’analyse avec les caractères spéciaux.

FAQ

Créez-vous de nouvelles cartes, ou mettez-vous seulement à jour celles qui existent déjà ?

Ce flux met à jour des cartes existantes. Chaque ligne doit cibler une carte en utilisant id ou une colonne d’identifiant externe comme id.y2.customerId.

Que se passe-t-il si une ligne contient à la fois id et id.<externalId>?

Utilisez un identifiant par ligne si possible. Si vous en incluez plusieurs, assurez-vous qu’ils pointent tous vers la même carte. Cela évite toute ambiguïté et facilite le dépannage.

Puis-je mettre à jour plusieurs additionalData clés dans une seule ligne ?

Oui. Ajoutez une colonne par clé, en utilisant additionalData.<key>. La ligne mettra à jour toutes les clés fournies en une seule mise à jour de carte.