# Déplacer les cartes vers The Wallet Crew

Utilisez ce guide lorsque vous voulez déplacer **déjà-installé** les Cartes Apple Wallet et Google Wallet d'un autre fournisseur vers The Wallet Crew.

L'objectif est la continuité pour les clients. Lorsque la migration est correctement effectuée, ils conservent la même carte sur leur appareil, ils ne réinstallent rien, et votre code-barres et le flux de rédemption restent inchangés.

La majeure partie du travail est de la coordination, pas de l'implémentation. Vous alignez les identifiants d'émetteur, exportez les identifiants techniques qui lient chaque carte à son enregistrement Apple/Google existant, validez avec un petit pilote, puis effectuez une bascule contrôlée.

Si vous avez besoin du flux inverse, voir [Exporter des cartes de The Wallet Crew vers un autre fournisseur](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/configure/wallet/import-and-export/move-pass-from-and-to-the-wallet-crew/export-passes-from-the-wallet-crew-to-another-provider).

<details>

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

* Une marque décide de changer de fournisseur de cartes Wallet, mais souhaite que les clients conservent leurs cartes installées.
* Une marque remplace une configuration Wallet interne par The Wallet Crew pour obtenir une couche opérationnelle plus fiable.
* Une marque change un système sous-jacent (CRM, fidélité, billetterie, PDV) et doit transférer des cartes actives en toute sécurité.

</details>

## Avant de commencer

La plupart des migrations réussissent ou échouent en fonction des contraintes de la plateforme et de qui contrôle les identifiants d'émetteur.

Si vous voulez des informations de base sur les identifiants et les données de carte, lisez [Structure](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/develop/architecture/structure).

### Configurez votre projet The Wallet Crew avant de migrer

Vous ne pouvez pas commencer une migration avant que votre projet The Wallet Crew ne fonctionne de bout en bout.

La migration n'est pas « recréer les cartes ». Il s'agit d'importer les identifiants qui permettent à The Wallet Crew de prendre en charge les mises à jour des cartes déjà installées sur les appareils. Si votre projet n'est pas configuré, les cartes importées existeront, mais elles ne se mettront pas à jour de manière fiable après la bascule.

Avant d'importer quoi que ce soit, assurez-vous :

* Vous avez connecté les fournisseurs de wallet et pouvez signer/posséder les cartes (Apple Pass Type ID et certificats, accès au compte émetteur Google Wallet).
* Vous avez décidé quels **identifiants externes** vous utiliserez pour lier les cartes à vos systèmes (ID client, ID de billet, numéro d'adhérent, ID de commande, ...). Ceux-ci doivent être stables dans le temps.
* Vous pouvez calculer le contenu de la carte à partir de votre source de vérité (intégration API, workflow de fichiers ou processus opérationnel).
* Vous pouvez exécuter un cycle complet sur des cartes de test : émettre, mettre à jour un champ visible et vérifier la mise à jour sur un appareil réel.

<details>

<summary>Liste de contrôle de préparation à la migration</summary>

Utilisez ceci comme liste go/no-go avant de toucher aux cartes de production.

* [ ] Vous savez quel Apple Pass Type ID signe les cartes existantes.
* [ ] Vous disposez des identifiants Apple nécessaires pour conserver la même identité d'émetteur.
* [ ] Vous connaissez le `issuerId` Google qui possède les cartes existantes.
* [ ] Vous avez accès à ce compte émetteur dans la Google Pay & Wallet Console.
* [ ] Votre fournisseur actuel peut exporter une ligne par carte avec les identifiants requis.
* [ ] Votre fournisseur actuel peut envoyer une « mise à jour finale » Apple (voir étape de bascule).
* [ ] Vous avez un lot pilote de 2–3 cartes réelles par plateforme.
* [ ] Vous avez un plan de retour arrière pour Apple (si pris en charge par l'ancien fournisseur).

{% hint style="info" %}
Prévoyez au moins un cycle pilote. La plupart des retards proviennent des exports, des approbations et de la planification de la bascule.
{% endhint %}

</details>

{% hint style="info" %}
Prévoyez au moins un cycle pilote. La plupart des retards proviennent des exports, des approbations et de la planification de la bascule.
{% endhint %}

### Ce que vous importez : identifiants de carte (plateforme + externes)

Vous ne recréez pas les cartes pendant une migration. Vous importez des identifiants afin que The Wallet Crew puisse mettre à jour des cartes qui sont **déjà installées** sur les appareils.

Vous importez deux types d'identifiants :

* **Identifiants de plateforme**. Ceux-ci pointent vers l'enregistrement Apple/Google existant.
  * Apple : `serialNumber` + `authenticationToken`
  * Google : object **resource ID** (souvent appelé object ID)
* **Identifiants externes**. Ceux-ci lient une carte à vos propres systèmes.
  * Exemples : ID client, ID de billet, numéro d'adhérent, ID de commande

Les identifiants de plateforme permettent à The Wallet Crew de mettre à jour la même carte sur l'appareil. Les identifiants externes vous permettent d'associer la carte au bon enregistrement client et de maintenir des mises à jour correctes après la bascule.

Une seule carte peut avoir plusieurs identifiants externes. Cela est utile lorsque vous rapprochez des données entre systèmes.

### Décidez si vous pouvez migrer « sur place »

Apple et Google n'autorisent pas les mêmes modèles de migration.

#### Apple Wallet (la migration sur place est généralement possible)

Vous pouvez généralement migrer sans réinstallation si vous conservez la même identité d'émetteur Apple (même Pass Type ID / identité de signature) et si vous redirigez le point de mise à jour de la carte (`webServiceURL`).

Cela nécessite typiquement que votre fournisseur actuel envoie au moins une « mise à jour finale » aux cartes installées. Cette mise à jour intègre The Wallet Crew `webServiceURL` afin que les appareils commencent à appeler The Wallet Crew pour les mises à jour futures.

#### Google Wallet (uniquement si vous conservez le même compte émetteur)

Les cartes Google Wallet sont liées à un compte émetteur de la Google Pay & Wallet Console (`issuerId`).

Si les cartes existantes ont été créées sous un compte émetteur que vous ne contrôlez pas, vous ne pouvez pas les transférer sur place. Vous devez planifier un flux de réémission (nouveaux liens d'enregistrement, nouveaux objets).

{% hint style="warning" %}
Pour Google Wallet, planifiez la migration autour de votre compte émetteur.

Si votre fournisseur actuel a émis des cartes sous un compte émetteur que vous ne contrôlez pas, planifiez un flux de réémission.
{% endhint %}

### Ce dont vous avez besoin de la part de votre fournisseur actuel

Demandez un export d'une ligne par carte. Vous l'utiliserez pour rattacher The Wallet Crew à la *existante* carte installée.

Au minimum, obtenez :

* **Apple Wallet**: `serialNumber` et `authenticationToken`
* **Google Wallet** : object **resource ID** (souvent appelé « resource ID » ou « object ID »)
* Un identifiant client stable (email, ID client, ID de billet). C'est ainsi que vous rattachez les cartes aux clients.

{% hint style="info" %}
Si votre fournisseur actuel peut également partager le Apple Pass Type ID et le Google `issuerId`, cela accélère la vérification d'éligibilité.
{% endhint %}

## Étapes de migration

### Aperçu de la séquence (ce qui se passe de bout en bout)

Ces diagrammes montrent les points de contrôle dont vous avez besoin pour une bascule propre. L'idée clé est simple : vous importez des identifiants dans The Wallet Crew, puis vous vous assurez que les appareils commencent à récupérer les mises à jour depuis The Wallet Crew.

{% tabs %}
{% tab title="Apple Wallet" %}
La migration Apple sur place fonctionne généralement si vous conservez le même Pass Type ID et si votre fournisseur actuel peut envoyer une « mise à jour finale » qui change la carte `webServiceURL` vers The Wallet Crew.

```mermaid
sequenceDiagram
  autonumber
  participant Brand as Brand systems
  participant Old as Old provider
  participant TWC as The Wallet Crew
  participant Device as Customer device (Apple Wallet)

  Brand->>Old: Request export (serialNumber, authenticationToken, external IDs)
  Old-->>Brand: Export file / feed
  Brand->>TWC: Import identifiers

  Brand->>Old: Ask for "final update" setting webServiceURL = The Wallet Crew
  Old->>Device: Push update notification
  Device->>Old: Fetch updated pass package
  Old-->>Device: Pass updated with new webServiceURL

  Brand->>TWC: Update pass data after cutover
  TWC->>Device: Push update notification
  Device->>TWC: Fetch updated pass package
  TWC-->>Device: Updated pass content
```

{% endtab %}

{% tab title="Google Wallet" %}
La migration Google sur place ne fonctionne que si les cartes existantes appartiennent à un `issuerId` que vous contrôlez. Dans ce cas, The Wallet Crew met à jour les mêmes resource IDs d'objet.

```mermaid
sequenceDiagram
  autonumber
  participant Brand as Brand systems
  participant Old as Old provider
  participant TWC as The Wallet Crew
  participant Google as Google Wallet
  participant Device as Customer device (Google Wallet)

  Brand->>Old: Request export (object resource ID, external IDs)
  Old-->>Brand: Export file / feed
  Brand->>TWC: Import identifiers (resource IDs)

  Brand->>TWC: Update pass data after cutover
  TWC->>Google: Update existing object (same issuerId)
  Google-->>Device: Customer sees updated pass content after sync
```

{% endtab %}
{% endtabs %}

{% stepper %}
{% step %}

### Configurer les identifiants d'émetteur The Wallet Crew

Vous avez besoin que The Wallet Crew s'authentifie en tant que même « émetteur » que les cartes existantes.

* Pour Apple, utilisez le même Pass Type ID que votre fournisseur actuel chaque fois que possible. Ensuite, configurez les certificats.\
  Suivez : [Certificats Apple Wallet](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/configure/wallet/apple-and-google-wallet/apple-wallet-certificates).
* Pour Google, confirmez quel compte émetteur Google Wallet possède les cartes existantes. Vous avez besoin d'accès à ce compte émetteur.\
  Suivez : [Compte Google Wallet](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/configure/wallet/apple-and-google-wallet/google-wallet-account).
  {% endstep %}

{% step %}

### Exporter les identifiants techniques des cartes depuis votre fournisseur actuel

Demandez à votre fournisseur actuel un export d'une ligne par carte.

Au minimum, exportez :

* Apple : **numéro de série** et **jeton d'authentification**
* Google : **resource ID** (ou object ID)
* Vos identifiants externes (afin que vous puissiez associer chaque carte au bon client)
  {% endstep %}

{% step %}

### Importer ces cartes dans The Wallet Crew

Importez les identifiants exportés dans The Wallet Crew afin que chaque enregistrement de carte puisse être lié à ses identifiants Apple/Google existants.

Commencez par [Import & Export](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/configure/wallet/import-and-export). Si vous avez besoin d'un flux de mise à jour en masse basé sur des fichiers, voir [Mettre à jour la carte en utilisant des fichiers plats](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/configure/wallet/import-and-export/update-pass-using-flat-files).

{% hint style="info" %}
Les importations de migration nécessitent souvent des colonnes supplémentaires (token d'auth Apple, resource ID Google).

Si vous ne voyez pas comment mapper ces champs dans votre tenant, demandez à l'équipe The Wallet Crew de confirmer le format de fichier attendu.
{% endhint %}
{% endstep %}

{% step %}

### Bascule : rediriger les mises à jour Apple vers The Wallet Crew

Les cartes Apple Wallet récupèrent les mises à jour depuis le `webServiceURL` intégré dans la carte.

Pour migrer sans réinstallation, votre fournisseur actuel doit mettre à jour `webServiceURL` sur les cartes existantes et déclencher une mise à jour afin que les appareils téléchargent la nouvelle version de la carte.

{% hint style="warning" %}
Ne mettez pas hors service le service web Apple de votre précédent fournisseur tant que vous n'avez pas validé la bascule sur des appareils réels.

Si l'ancien endpoint cesse de répondre avant que les appareils reçoivent la « mise à jour finale », les cartes peuvent cesser de se mettre à jour.
{% endhint %}

Demandez à votre ancien fournisseur de mettre à jour en masse toutes les cartes existantes afin que leur `webServiceURL` correspond à The Wallet Crew `webServiceURL` :

> `https://api-passd.neostore.cloud/api/<tenantId>/passes/apple`

remplacez `<tenantId>` par votre tenantId, confirmez la valeur avec l'équipe de support The Wallet Crew.
{% endstep %}

{% step %}

### Validez sur un petit échantillon

Choisissez 2–3 cartes sur chaque plateforme.

Mettez à jour un champ visible via The Wallet Crew. Puis vérifiez qu'il se met à jour sur les appareils.

Si vous devez accélérer l'actualisation pendant les tests, lancez une mise à jour push depuis The Wallet Crew. Cela est utile sur les deux plateformes : les appareils Apple récupèrent le paquet de carte mis à jour, et les utilisateurs Google voient l'objet mis à jour plus rapidement.
{% endstep %}

{% step %}

### Surveillance après la bascule

Surveillez les mises à jour et la rédemption pendant quelques jours. Conservez une option de retour arrière si votre fournisseur précédent la prend en charge.

Pour Apple, le retour arrière signifie généralement repasser `webServiceURL` et déclencher une mise à jour. N'essayez cela que si vous disposez d'un endpoint fonctionnel confirmé chez l'ancien fournisseur.
{% endstep %}
{% endstepper %}

## Pièges courants

Les échecs Apple et Google se manifestent différemment. Ces vérifications détectent la plupart des problèmes tôt.

### Apple Wallet

Si les clients signalent que les cartes cessent de se mettre à jour après la bascule, c'est généralement l'un de ces cas :

* Le `webServiceURL` n'a pas été mis à jour sur les cartes installées.
* L'ancien fournisseur a mis à jour `webServiceURL` mais n'a pas déclenché de mise à jour push.
* Les identifiants Apple de The Wallet Crew ne correspondent pas à l'identité d'origine de la carte (Pass Type ID / certificat).

### Google Wallet

Si les mises à jour échouent sur Google, c'est généralement l'un de ces cas :

* Les cartes existantes appartiennent à un autre `issuerId`.
* L'« resource ID » exporté ne correspond pas aux object IDs qui sont mis à jour.
* Les permissions de la Google Pay & Wallet Console n'autorisent pas les mises à jour depuis les identifiants The Wallet Crew.

## FAQ

<details>

<summary><strong>Les clients doivent-ils réinstaller leur carte ?</strong></summary>

Généralement non.

Si vous redirigez correctement l' `webServiceURL` Apple, les cartes existantes continuent de se mettre à jour en place.

Pour Google, si vous conservez le même compte émetteur et les mêmes resource IDs, les utilisateurs conservent généralement la même carte.

</details>

<details>

<summary><strong>Pourquoi avons-nous besoin du token d'authentification Apple ?</strong></summary>

Apple utilise le token d'authentification pour authentifier les requêtes de mise à jour pour un numéro de série donné.

Sans celui-ci, un nouveau fournisseur ne peut pas fournir de manière fiable des mises à jour à la même carte installée.

</details>

<details>

<summary><strong>Pouvons-nous migrer des cartes Google Wallet entre comptes émetteurs ?</strong></summary>

Pas sur place.

Les cartes Google Wallet sont liées au compte émetteur. Si l'émetteur change, planifiez un flux de réémission.

</details>

<details>

<summary><strong>Comment savoir si la bascule Apple a fonctionné ?</strong></summary>

Mettez à jour un champ visible dans The Wallet Crew et confirmez le changement sur un appareil réel. Si possible, confirmez également que la carte installée appelle l'endpoint The Wallet Crew en vérifiant les logs serveur ou en demandant au support The Wallet Crew de confirmer le trafic.

</details>

<details>

<summary><strong>Que se passe-t-il si nous ne pouvons pas conserver le même Apple Pass Type ID ?</strong></summary>

Planifiez une réémission.

Si l'identité d'émetteur Apple change, les clients doivent généralement ajouter une nouvelle carte. Effectuez un déploiement contrôlé et maintenez la vieille carte valide pendant une période de transition si possible.

</details>

<details>

<summary><strong>Que se passe-t-il si notre fournisseur actuel ne peut pas envoyer la « mise à jour finale » Apple ?</strong></summary>

Vous ne pourrez peut-être pas migrer les cartes Apple sur place.

Sans mise à jour finale, les cartes installées continuent d'appeler l'ancien `webServiceURL`. Dans ce cas, vous devez soit maintenir l'ancien endpoint en activité, soit planifier un flux de réémission.

</details>

<details>

<summary><strong>Doit-on changer les codes-barres ou la logique de rédemption ?</strong></summary>

Pas nécessairement.

Si vous conservez les mêmes identifiants de carte et que vous continuez à générer la même charge utile de code-barres, votre flux de scan en magasin ou aux portails peut rester inchangé. Validez cela explicitement pendant le pilote en scannant les cartes migrées dans des conditions réelles.

</details>

<details>

<summary><strong>Que devons-nous communiquer aux clients pendant la migration ?</strong></summary>

Si la migration se fait sur place, vous n'avez généralement pas besoin de communiquer quoi que ce soit. Les clients conservent la même carte et elle continue de se mettre à jour.

Si vous devez réémettre des cartes, communiquez clairement et tôt le nouveau flux « Ajouter au Wallet ». Restez concis et concentrez-vous sur ce que les clients doivent faire.

</details>