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

{% hint style="warning" %}
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 [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 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.

</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 imports de fichiers plats vous permettent de mettre à jour de nombreuses cartes en une seule opération.</p></figcaption></figure></div>

## Vue d’ensemble 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 de fichier

Les fichiers téléversés doivent être valides [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 de 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, 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

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

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

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

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

```js
/**
 * 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

<details>

<summary><strong>Créez-vous de nouvelles cartes, ou mettez-vous seulement à jour celles qui existent déjà ?</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 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/import-and-export/update-pass-using-flat-files.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.