> 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/importation-et-exportation/mettre-a-jour-la-carte-a-laide-de-fichiers-plats.md).

# 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. Cela est utile pour les mises à jour en masse et pour les systèmes hérités qui ne peuvent exporter que des fichiers plats.

{% hint style="warning" %}
Les importations SFTP sont une fonctionnalité facultative. Demandez à The Wallet Crew d’activer SFTP sur votre tenant avant de mettre en place ce flux.

Considérez les importations SFTP comme un **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 [Broken mention](broken://pages/7bc855a760c8626e5d57afe837e12d5a1e71c84a).
{% endhint %}

<details>

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

* 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 cartes exactes juste avant l’ouverture des portes.
* Une chaîne de salles de sport exporte chaque nuit le statut des adhésions (active, gelée, expirée). Le lendemain, les membres voient le bon statut lors de l’enregistrement.
* Une équipe support corrige un mauvais identifiant à grande échelle en téléversant un fichier de correction ponctuelle.

</details>

<div data-with-frame="true"><figure><img src="/files/88c3844c568c58695f616d831d9ef53e3a8c7997" alt="Diagram showing a CSV file uploaded to SFTP, then processed by The Wallet Crew to update passes."><figcaption><p>Les importations de fichiers plats vous permettent de mettre à jour de nombreuses Cartes en une seule opération.</p></figcaption></figure></div>

## Aperçu du processus

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

## Format du fichier

Les fichiers téléversés doivent être des [RFC 4180](https://www.ietf.org/rfc/rfc4180.txt){target="\_blank"} fichiers CSV conformes.

* **Séparateurs**: Soit `,` ou `;`
* **Ligne d’en-tête**: Obligatoire. Doit contenir les noms des colonnes.
* **Encodage**: UTF-8 recommandé
* **Analyseur**: The Wallet Crew utilise [CsvHelper](https://joshclose.github.io/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, additionalData ou metadata.

## Nom du fichier

Il n’existe pas d’exigences strictes concernant le nom de 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 modèle de nommage basé sur l’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 de colonne

### Colonnes d’identifiant de Carte

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

* `id`: Identifiant interne de Carte de 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 des données supplémentaires sur la Carte, utilisez la syntaxe suivante :

* `additionalData.<key>`: Met à jour la clé dans le `additionalData` dictionnaire\
  Exemple : `additionalData.notification_content`

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

### Modèle de Carte

Pour changer le modèle de la Carte vers un autre modèle, incluez :

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

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

### Actualisation des métadonnées

Pour déclencher un recalcul des métadonnées internes (par exemple, 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 de The Wallet Crew pour demander vos identifiants SFTP.

## Exemples

### Exemple 1 : Mettre à jour la notification et 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
04503295;Merci pour votre achat ! Il ne vous reste que 10 points avant d’échanger un bon de 10 €
02319202;Merci pour votre achat ! Il ne vous reste 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

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

## Extensibilité et mappage personnalisé

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

Cela vous permet de :

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

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

Si vous avez le fichier CSV suivant :

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

Vous pouvez utiliser le script suivant :

```js
/**
 * Transforme une ligne CSV en un objet de type UpdatePassInformation.
 *
 * @param {Object<string, string>} row - La ligne CSV, sous forme de dictionnaire de noms de colonnes vers des valeurs.
 * @returns {Object} Informations de ligne transformées.
 * @returns {Object<string, string>} return.Identifiers - Identifiants pour cette ligne (par exemple, 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 permettant de 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 le format de votre 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

<details>

<summary><strong>Créez-vous de nouvelles Cartes, ou mettez-vous seulement à jour celles qui existent ?</strong></summary>

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`.

</details>

<details>

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

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.

</details>

<details>

<summary><strong>Puis-je mettre à jour plusieurs <code>additionalData</code> clés dans une seule ligne ?</strong></summary>

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 la Carte.

</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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.thewalletcrew.io/configure/fr/advanced-configuration/wallet/importation-et-exportation/mettre-a-jour-la-carte-a-laide-de-fichiers-plats.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.