> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/configure/fr/advanced-configuration/wallet/import-and-export/update-pass-using-flat-files.md).

# Mettre à jour des cartes avec des fichiers CSV via SFTP

Mettre à jour en masse les passes Apple Wallet et Google Wallet existantes à partir de fichiers CSV téléchargés sur SFTP : données, modèle, thème, avantages et notifications.

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. Chaque ligne du fichier peut modifier les données affichées sur une carte, changer son modèle ou son thème, accorder un avantage et envoyer une notification aux appareils qui la contiennent.

{% hint style="warning" %}
Les imports SFTP sont une fonctionnalité facultative. Demandez à The Wallet Crew d’activer SFTP sur le tenant avant d’implémenter ce flux : contactez l’assistance The Wallet Crew pour demander le point de terminaison SFTP et les identifiants. **Paramètres → Général → Mises à jour SFTP** explique comment contacter l’équipe d’assistance.

Traitez les imports SFTP comme une **solution de dernier recours**, par exemple pour un système hérité qui ne peut exporter que des fichiers plats. Voir le [flux de mise à jour de l’API](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/wallet/pass-lifecycle.md). Pour comparer ce flux avec l’import XLSX et l’API, voir [Importation et exportation](https://docs.thewalletcrew.io/configure/fr/advanced-configuration/wallet/import-and-export.md).
{% endhint %}

<details>

<summary><strong>Exemples concrets</strong></summary>

* Un programme de carte cadeau recalcule le solde chaque heure. Un export de fichier plat met à jour `additionalData.balance` pour toutes les cartes actives.
* Un programme de fidélité fait passer les membres à Gold chaque nuit. Un fichier applique le thème Gold à chaque carte mise à niveau, accorde un avantage de bienvenue et notifie le membre dans sa langue.
* Une campagne saisonnière se termine. Un fichier définit `themeId` vers `-` sur chaque carte qui portait le thème de la campagne, ce qui retire le thème de chacune d’elles.
* Un système de billetterie exporte les changements de dernière minute (porte d’embarquement, siège ou horaire). Une mise à jour CSV en masse maintient les billets exacts juste avant l’ouverture des portes, et une notification indique à chaque détenteur ce qui a changé.
* Une chaîne de salles de sport exporte chaque nuit l’état des abonnements (actif, gelé, expiré). Le lendemain, les membres voient le bon statut à l’enregistrement.
* Une équipe d’assistance corrige un identifiant erroné à grande échelle en téléversant un fichier de correction ponctuel.

</details>

<div data-with-frame="true"><figure><img src="https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2FAlMXw1s03rRnSwC6F8AC%2Fconfigure-update-pass-using-flat-diagram-showing-csv-file-uploaded-sftp-then.png?alt=media&#x26;token=e4e1a102-e785-4bdf-885d-e1867a09db3f" alt="Diagram showing a CSV file uploaded to SFTP, then processed by The Wallet Crew to update passes."><figcaption><p>Un fichier CSV téléversé sur SFTP est traité par The Wallet Crew pour mettre à jour de nombreuses cartes en une seule opération.</p></figcaption></figure></div>

## Vue d’ensemble du processus

1. Téléversez le fichier CSV sur le serveur SFTP fourni.
2. The Wallet Crew détecte automatiquement les nouveaux fichiers et les traite immédiatement.
3. Chaque ligne est vérifiée, puis transformée en mise à jour pour chaque carte qu’elle identifie. Une ligne qui fait référence à quelque chose que le tenant ne possède pas est refusée et ne change rien ; les autres lignes continuent.
4. Une fois chaque ligne lue, le fichier est déplacé vers `.processed/`. Un fichier dont l’import échoue est déplacé vers `.error/`.
5. Les mises à jour des cartes sont mises en file d’attente et livrées de manière asynchrone, à un rythme constant sur l’ensemble du fichier (voir [Rythme de livraison](#delivery-pace)).
6. Le résultat de l’import, ligne par ligne et carte par carte, est visible dans la console (voir [Suivre un import](#follow-an-import)).

## Format du fichier

Les fichiers téléversés doivent être valides [RFC 4180](https://www.ietf.org/rfc/rfc4180.txt) fichiers CSV conformes.

* **Séparateurs**: Soit `,` ou `;`
* **Ligne d’en-tête**: Obligatoire. Doit contenir des noms de colonnes, chacun non vide et présent une seule fois. Les noms de colonnes sont comparés sans tenir compte de la casse, donc `themeId` et `ThemeId` dans le même en-tête comptent comme la même colonne deux fois.
* **Encodage**: UTF-8 recommandé
* **Analyseur**: The Wallet Crew utilise [CsvHelper](https://joshclose.github.io/CsvHelper/) avec les options par défaut

Un fichier sans ligne d’en-tête, avec un nom de colonne vide ou répété, ou un CSV mal formé (par exemple un guillemet non fermé) est rejeté et déplacé vers `.error/`. Lorsque la ligne mal formée est trouvée au milieu du fichier, certaines des lignes précédentes ont peut-être déjà été mises en file d’attente ; elles sont tout de même appliquées.

Chaque ligne de données cible une ou plusieurs cartes et peut inclure plusieurs mises à jour de leurs champs, de additionalData, du thème ou des métadonnées.

## Nom du fichier

Il n’y a pas d’exigences strictes concernant le nom du fichier. Pour une meilleure organisation et une meilleure traçabilité, utilisez cette convention de nommage :

```
<source>-passes-<YYYYMMDD>-<HHMMSS>.csv
```

Exemples :

```
crm-passes-20250801-083000.csv 
loyalty-passes-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
* Lorsqu’un script ou une intégration génère les fichiers, adopter 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 pour s’assurer qu’il est entièrement écrit avant le traitement.

## Référence des colonnes

Seules les colonnes ci-dessous sont lues. Toute autre colonne est ignorée, et le journal d’import la répertorie afin qu’un nom de colonne mal orthographié ne passe pas inaperçu. Les noms de colonnes et les préfixes sont reconnus quelle que soit la casse. Une cellule vide laisse la valeur correspondante inchangée, sauf indication contraire.

### 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é sur le tenant)\nExemple : `id.y2.customerId`

Lorsque `id` a une valeur, il sélectionne à lui seul la carte. Sinon, la ligne cible chaque carte portant tous les identifiants externes indiqués dans ses `id.<externalId>` colonnes, ce qui peut correspondre à plusieurs cartes. Une cellule d’identifiant vide est ignorée, donc une ligne dont toutes les cellules d’identifiant sont vides ne cible aucune carte et compte comme **Aucune correspondance** dans le journal d’import.

### 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 de la carte `additionalData` de la carte\nExemple : `additionalData.notification_content`

Plusieurs clés additionalData peuvent être mises à jour sur une seule ligne. Une cellule vide supprime la clé de la carte.

### Modèle de carte

Pour faire passer la carte à un autre modèle, incluez :

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

S’il est omis ou vide, la carte conservera son modèle actuel.

### Thème

Un thème modifie l’apparence d’une carte sans changer son modèle, pour une campagne, une saison ou un niveau d’adhésion. Pour en appliquer ou en retirer un, incluez :

* `themeId`: L’identifiant du thème à appliquer
* `-` (un simple tiret) dans la `themeId` colonne : supprime le thème actuel

S’il est omis ou vide, la carte conserve son thème actuel.

### Modèle d’avantage

Un modèle d’avantage décrit un avantage, comme un bon ou un cadeau de bienvenue, qui peut être accordé à des cartes. Pour en accorder un avec la mise à jour, incluez :

* `benefitTemplateId`: L’identifiant du modèle d’avantage

L’avantage est accordé à chaque carte ciblée par la ligne, avant la mise à jour de la carte. S’il est omis ou vide, aucun avantage n’est accordé.

### Notification

Une notification est envoyée aux appareils qui possèdent la carte avec la mise à jour. Pour en envoyer une, incluez :

* `notification`: Le texte de notification par défaut
* `notification.<language>`: Le texte pour une langue, en utilisant son code langue\nExemple : `notification.fr`, `notification.de`

Un appareil dont la langue correspond à une colonne de langue reçoit ce texte ; tout autre appareil reçoit le texte par défaut. Si chaque cellule de notification d’une ligne est vide, aucune notification n’est envoyée pour cette ligne.

### Actualisation des métadonnées

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

* `updateMetadata`: Définissez 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`

Chaque `identifiers.<idName>` colonne nécessite une valeur : une ligne avec une valeur vide est refusée, afin qu’un identifiant ne soit jamais effacé par accident.

## Lignes refusées

Avant toute modification, chaque ligne est vérifiée par rapport à la configuration du tenant. Cela évite qu’une faute de frappe dans une colonne n’applique qu’une partie d’une mise à jour, par exemple une notification annonçant un thème qui n’a jamais été appliqué. Une ligne est refusée, et rien n’est modifié pour elle, lorsqu’elle :

* nomme un modèle de carte qui n’existe pas (`Modèle de carte inconnu '…'`)
* nomme un thème qui n’existe pas (`Thème inconnu '…'`)
* nomme un modèle d’avantage qui n’existe pas (`Modèle d’avantage inconnu '…'`)
* a une `identifiers.<idName>` cellule vide (`Valeur manquante pour l’identifiant '…'`)

Une ligne refusée n’arrête pas le fichier : toutes les autres lignes sont tout de même importées. Le journal d’import regroupe les lignes refusées par motif, avec le nombre de lignes pour chacun, de sorte qu’un thème mal orthographié sur l’ensemble du fichier n’apparaît que sur une seule ligne.

## Rythme de livraison

Les mises à jour des cartes ne sont pas toutes livrées en même temps. Elles sont réparties à un rythme constant sur l’ensemble du fichier, afin qu’un fichier volumineux ne submerge pas les appareils, Apple et Google avec des mises à jour au même moment. Les dernières cartes d’un gros fichier sont donc mises à jour bien après la lecture du fichier. Un rythme par défaut s’applique, et un script d’import peut le modifier pour chaque fichier (voir `getThroughput` ci-dessous).

## Suivre un import

Chaque fichier importé dispose d’un journal d’import dans la console d’administration, sous **Paramètres → Général → Mises à jour SFTP**. Il montre ce qui est arrivé au fichier sans nécessiter d’accès aux journaux techniques.

L’état de l’import vient en premier :

* **Import terminé**: chaque ligne a été lue. Certaines ont peut-être encore été refusées ou ont échoué ; les chiffres ci-dessous indiquent combien.
* **Import échoué**: l’import s’est arrêté avant la dernière ligne, avec la raison (fichier illisible, arrêt ou erreur inattendue). Les lignes mises en file d’attente avant l’arrêt sont tout de même appliquées.
* **Import interrompu**: l’import a démarré mais n’a jamais signalé de fin, car le traitement a été arrêté au milieu du fichier. Les lignes mises en file d’attente avant l’arrêt sont tout de même appliquées.
* **Résultat pas encore enregistré**: l’import est récent et son résultat n’est pas encore disponible.

Les chiffres décrivent ensuite chaque ligne lue : **Appliqué** (mises à jour mises en file d’attente pour au moins une carte), **Aucune correspondance** (aucune carte ne porte les identifiants donnés), **Refusé** (voir [Lignes refusées](#refused-rows)) et **Échoué** (erreur technique). **Mises à jour des cartes** est le nombre de cartes mises en file d’attente, ce qui peut dépasser le nombre de lignes appliquées lorsqu’une ligne cible plusieurs cartes. Les lignes refusées sont listées par motif, et les colonnes qui ont été ignorées sont listées dans un avertissement.

Enfin, chaque carte touchée par l’import est listée avec son résultat, une fois sa mise à jour exécutée :

* **Mis à jour**: la carte a été mise à jour, ou sa notification a été envoyée.
* **Ignoré**: rien n’a été appliqué à la carte, généralement parce qu’une autre source l’a mise à jour après sa mise en file d’attente par l’import. La mise à jour la plus récente est conservée.
* **Carte introuvable**: aucune carte ne possède cet identifiant, par exemple une valeur incorrecte dans la `id` colonne.
* **Annulé**: la mise à jour a été annulée avant d’être appliquée.
* **Échoué**: la mise à jour ou sa notification n’a pas pu être terminée ; le message d’erreur précise lequel.

### Événements d’import

Chaque import émet également des événements qui peuvent être envoyés à un système externe via [les webhooks](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/webhooks.md), par exemple pour alerter une équipe d’exploitation lorsqu’un fichier échoue ou lorsque des lignes sont refusées, sans surveiller la console. S’abonner à `Import:*` couvre les trois :

* `Import:Started` quand la lecture d’un fichier commence
* `Import:Completed` une fois chaque ligne lue
* `Import:Failed` quand l’import s’arrête avant sa dernière ligne

Chaque événement transporte un `import` objet avec `type` (`cartes` pour cet import) et `fileName`. `Import:Completed` et `Import:Failed` ajoute `lignes`, avec les comptes `lus`, `appliqués`, `noMatch`, `refusés` et `échoués` comme dans le journal d’import, `passCount`, le nombre de mises à jour de cartes mises en file d’attente, et `ignoredColumns`. `Import:Completed` contient également `refusals`, les dix motifs les plus fréquents de refus des lignes, chacun avec `reason` et `rowCount`. `Import:Failed` contient `reason`: `invalidFile`, `canceled` ou `unexpected`.

`Import:Completed` signifie que chaque ligne a été lue, et non que chaque carte a été mise à jour : les mises à jour sont livrées ensuite, au rythme de l’import.

## Exemples

### Exemple 1 : mise à jour de la notification et de l’URL de l’offre

```csv
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é

```csv
id.y2.customerId;additionalData.notification_content
00100123;Profitez de 30 % de réduction sur votre prochain achat
Merci pour votre achat ! Il ne vous reste plus que 10 points pour échanger un bon de 10 €
Merci pour votre achat ! Il ne vous reste plus que 120 points pour échanger un bon de 10 €
```

### Exemple 3 : changer le modèle de carte et forcer l’actualisation des métadonnées

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

### Exemple 4 : mettre à jour l’identifiant externe y2.customerId et forcer l’actualisation des métadonnées

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

### Exemple 5 : appliquer un thème, accorder un avantage et notifier

La première ligne fait passer le membre au thème Gold, accorde l’avantage de bienvenue et envoie une notification, en français sur les appareils français et en anglais ailleurs. La deuxième ligne retire le thème d’un autre membre et n’envoie rien.

```csv
id.y2.customerId;themeId;benefitTemplateId;notification;notification.fr
00100123;gold;gold-welcome;Bienvenue en Gold ! Un cadeau vous attend sur votre carte.;Bienvenue en Gold ! Un cadeau vous attend sur votre carte.
04503295;-;;;
```

## Extensibilité et mappage personnalisé

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

Cela permet de :

* Adapter un format d’export existant (par ex. depuis un CRM ou un point de vente)
* Faire correspondre des noms de colonnes hérités à des clés compatibles avec The Wallet Crew
* Injecter des valeurs dynamiques (par ex. la date actuelle, les points calculés)
* Enrichir les données avec des recherches provenant de sources externes

Pour personnaliser le processus d’import, créez un `import.custom.js` fichier dans le `scripts/` dossier de l’ [Configuration avancée](https://docs.thewalletcrew.io/configure/fr/advanced-configuration/platform/advanced-configuration.md) éditeur. Le script reçoit chaque ligne et renvoie ce qu’il faut mettre à jour ; les valeurs renvoyées passent par les mêmes vérifications que les colonnes ci-dessus, donc un thème inconnu renvoyé par un script refuse la ligne de la même manière. Un script qui génère une erreur arrête tout le fichier, ce qui apparaît comme **Import échoué** dans le journal d’import. Le contrat complet est décrit dans [Transformation d’une ligne de mise à jour en masse de cartes](https://docs.thewalletcrew.io/developers-guides/fr/scripting/endpoints/bulk-pass-update-row-transformation.md).

Pour le fichier CSV suivant :

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

Le script suivant peut être utilisé :

```js
/**
 * Transforme une ligne CSV en objet UpdatePassInformation.
 *
 * @param {Object<string, string>} row - La ligne CSV, sous forme de dictionnaire des noms de colonnes vers les valeurs.
 * @returns {Object} Informations de ligne transformées.
 * @returns {Object<string, string>} return.Identifiers - Identifiants pour cette ligne (par ex. ID client).
 * @returns {string|null} return.PassType - Le modèle de carte vers lequel basculer, ou null pour conserver le modèle actuel.
 * @returns {string|null} return.ThemeId - Le thème à appliquer, "" pour supprimer le thème, ou null pour le conserver.
 * @returns {string|null} return.BenefitTemplateId - Le modèle d’avantage à accorder, ou null pour n’en accorder aucun.
 * @returns {string|null} return.Notification - Le texte de notification par défaut, ou null pour n’en envoyer aucune.
 * @returns {Object<string, string>} return.NotificationLocalizations - Texte de notification par code langue.
 * @returns {Object<string, string>} return.AdditionalData - Données supplémentaires facultatives provenant 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,
    ThemeId: row.tier ? row.tier : null,
    Notification: row.neo_notification_content || null,
    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
  });
}
```

Le script renvoie des clés avec majuscule initiale (`Identifiers`, `PassType`, `ThemeId`). Dans le fichier CSV lui-même, les noms de colonnes ne tiennent pas compte de la casse.

Contactez The Wallet Crew pour obtenir de l’aide afin d’implémenter une logique de mappage personnalisé pour les imports.

## Astuces et bonnes pratiques

* Vérifiez les identifiants : le **Aucune correspondance** nombre et le **Carte introuvable** résultat dans le journal d’import montrent ceux qui sont incorrects.
* Testez le format du fichier dans l'environnement de QA avant de le téléverser en production, et vérifiez son journal d'importation pour repérer les lignes refusées et les colonnes ignorées.
* Ne téléversez pas deux fois le même fichier pour le réessayer : chaque ligne est importée à nouveau, ce qui envoie ses notifications une deuxième fois. Téléversez un fichier contenant uniquement les lignes qui en ont besoin.

## FAQ

<details>

<summary><strong>Que se passe-t-il si une ligne comporte à la fois <code>id</code> et <code>id.&#x3C;externalId></code>?</strong></summary>

Le `id` la colonne l'emporte. Utilisez si possible un identifiant par ligne, ce qui évite toute ambiguïté et facilite le dépannage.

</details>

<details>

<summary><strong>Pourquoi une ligne a-t-elle été refusée ?</strong></summary>

Voir [Lignes refusées](#refused-rows). Corrigez la valeur, puis téléversez un fichier contenant uniquement les lignes refusées.

</details>

<details>

<summary><strong>Une Carte apparaît comme Ignorée dans le journal d'importation. Pourquoi ?</strong></summary>

La Carte était généralement mise à jour par une autre source, comme l'API ou un autre import, après que cet import a mis sa mise à jour en file d'attente. Pour éviter d'envoyer la même Carte deux fois à ses appareils, la mise à jour la plus récente est conservée et les modifications de l'import ne sont pas appliquées à cette Carte. Importez à nouveau la ligne si ses modifications sont toujours nécessaires.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/configure/fr/advanced-configuration/wallet/import-and-export/update-pass-using-flat-files.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
