> 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/developers-guides/fr/integration-guides/custom-connectors.md).

# Connecteurs personnalisés

Étendez The Wallet Crew avec des scripts côté locataire pour les appels externes et les hooks d'exécution.

## Connecteurs personnalisés

Les connecteurs personnalisés étendent The Wallet Crew avec des scripts côté locataire. Ils sont utiles lorsque les données de la Carte doivent être enrichies à partir d’un système externe ou lorsqu’une logique personnalisée doit s’exécuter lorsqu’une Carte est installée ou désinstallée.

Ce modèle maintient l’intégration dans le runtime du locataire. Il évite d’exposer la logique du connecteur dans le code côté client et facilite le contrôle des appels externes.

Utilisez ce guide lorsqu’aucun connecteur natif n’existe pour le logiciel cible et que l’intégration doit être implémentée avec du script d’exécution.

### Liste de vérification

Avant d’écrire des scripts, confirmez les points suivants :

| Élément                    | Sortie attendue                                                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Stratégie d’identification | Champs d’ID stables disponibles sur chaque enregistrement lié à la Carte                                                |
| Propriété des données      | Les systèmes sources pour les données de profil, de fidélité, de transaction et de billet sont explicites               |
| Modèle de déclenchement    | Décision claire sur le moment où `le remplissage`, les hooks d’installation et de désinstallation sont utilisés         |
| Modèle de sécurité         | Des clés API ou une stratégie OAuth sont définies pour les appels externes                                              |
| Gestion des erreurs        | Le comportement en matière de réessai, de délai d’attente et de supervision est convenu avec les équipes d’exploitation |

Si l’un de ces éléments manque, alignez-le d’abord pour éviter un comportement instable du connecteur en production.

<details>

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

* Une marque enrichit une Carte de fidélité avec des points et des données de niveau provenant d’un CRM externe.
* Un partenaire remplit une Carte avec des attributs de profil provenant d’une API propriétaire.
* Une équipe synchronise le statut d’installation de la Carte avec une plateforme marketing ou d’analyse.

</details>

### Prérequis

Pour créer un script, ouvrez **Settings → Advanced → Advanced Configuration**. Cette section contient les fichiers de configuration du locataire.

Les fichiers de script sont stockés sous `/server/script/...`.

{% hint style="info" %}
`customProvider` n’est qu’un nom d’exemple. Chaque `customProvider` occurrence peut être remplacée par le nom du connecteur qui doit être enregistré, ou laissée telle quelle.
{% endhint %}

### Contraintes d’exécution

Les scripts de connecteur personnalisé s’exécutent dans un environnement d’exécution sandboxé et versionné. Les contraintes suivantes s’appliquent à tous les scripts, quel que soit l’endroit où ils sont exécutés.

**Temps d’exécution**

Chaque invocation de script dispose d’un temps d’exécution maximal strict de 5 secondes. Les scripts qui dépassent cette limite sont interrompus. Concevez les scripts pour appeler des points de terminaison légers à faible latence et éviter les opérations bloquantes.

**Bibliothèques approuvées uniquement**

Le runtime nil.js expose un ensemble restreint de bibliothèques explicitement approuvées et maintenues par The Wallet Crew. Les bibliothèques externes ou tierces ne peuvent pas être importées. Cela garantit un comportement déterministe, réduit la surface d’attaque et maintient des performances prévisibles.

**Validation automatisée**

Les scripts sont soumis à une validation automatisée — y compris le linting et les vérifications de schéma — avant de pouvoir être enregistrés et exécutés. Un script qui échoue à la validation ne peut pas être déployé.

**Modèle d’exécution**

Selon le point de terminaison d’extensibilité, un script peut s’exécuter selon l’un des deux modes suivants :

* **Synchrone**: exécuté en ligne au sein d’un appel API, contribuant à la réponse. La latence est critique dans ce mode.
* **Asynchrone**: exécuté dans le cadre d’un flux de travail en arrière-plan déclenché par messagerie. Plus tolérant au temps de traitement, mais toujours soumis à la limite de 5 secondes par invocation.

L’utilisation de la mémoire n’est pas plafonnée par un quota fixe, mais une consommation anormale déclenche des alertes de supervision. Si un script provoque une pression soutenue sur les ressources, il fera l’objet d’un examen.

### Créez le fichier de script

Dans l’explorateur de fichiers, créez un fichier tel que `/server/script/customProvider.js`.

Si le dossier ou le fichier n’existe pas encore, créez-le d’abord. Pour créer un dossier depuis l’explorateur de fichiers, saisissez le nom du dossier suivi de `/`.

### Enregistrer le connecteur

Une fois le fichier de script créé, ajoutez l’enregistrement du connecteur :

```js
export default function(context) {
  context.register('runtime.scriptable.customerProvider.customProvider', {
    Remplissage : fill
  });
  context.register('runtime.wallet.passUpdater', {
    OnPassInstalled: onPassInstalled,
    OnPassUninstalled: onPassUninstalled
  });
}
```

### Fonction de remplissage

La `le remplissage` fonction est le point d’entrée utilisé pour récupérer et injecter des données externes dans le cycle de vie de la Carte.

En pratique, cette fonction reçoit le contexte actuel de la Carte, appelle les services externes requis et renvoie ou applique les données nécessaires au connecteur. L’implémentation exacte dépend du système externe connecté.

Le contrat d’exécution pour `le remplissage` est disponible dans le [référence de l’API](https://docs.thewalletcrew.io/api-reference/).

### Exemple d’implémentation

Cet exemple lit les identifiants externes ajoutés lorsqu’une Carte est créée, appelle une API externe et remappe la réponse dans l’entité.

```javascript
async function fill(entity) {
  const externalId = entity["id.externalId"];
  if (!externalId) {
    return false;
  }

  try {
    const res = await fetch("https://example.com/api/wallet", {
      Method: "GET",
      Headers: {
        "Content-Type": "application/json",
        "X-API-KEY": API_KEY,
      }
    });

    const item = JSON.parse(res.ResponseText)[0];

    entity.eventName = item?.eventName ?? `event ${externalId}`;
    entity.external_last_name = item?.lastName ?? null;
    entity.external_first_name = item?.firstName ?? null;
    entity.external_image_url = item?.imageUrl ?? null;
    entity.external_logo = item?.logo ?? null;
    entity.external_color = item?.color ?? null;
    entity.external_background_color = item?.backgroundColor ?? null;

    return true;
  } catch (e) {
    entity.external_error = `Une erreur est survenue lors de l’appel à l’API externe : ${e}`;
    return true;
  }
}
```

### Ce que fait cet enregistrement

Le script enregistre deux points d’entrée d’exécution. Chacun sert à un usage différent.

`runtime.scriptable.customerProvider.customProvider`

Cet enregistrement expose une fonction nommée `le remplissage`. La `le remplissage` fonction est utilisée pour alimenter les Cartes avec des données externes.

C’est ici qu’il faut appeler des API externes et enrichir les données de la Carte avec des informations provenant de systèmes partenaires, de plateformes CRM, de moteurs de fidélité ou de tout autre backend connecté au projet.

`runtime.wallet.passUpdater`

Cet enregistrement expose deux hooks de cycle de vie :

* `OnPassInstalled`
* `OnPassUninstalled`

Ces hooks sont déclenchés lorsqu’une Carte est installée ou désinstallée. Ils permettent d’exécuter la logique du connecteur au moment exact où le cycle de vie du Wallet change.

Les usages typiques incluent la synchronisation du statut d’installation, le lancement d’un parcours de bienvenue ou l’arrêt des communications de rappel une fois la Carte déjà installée.

Le contrat d’exécution de ces hooks est disponible dans le [référence de l’API](https://docs.thewalletcrew.io/api-reference/).

La référence d’exécution ci-dessus est la source de vérité pour le comportement des hooks d’installation et de désinstallation.

### Modèles associés

Utilisez les pages spécifiques au connecteur lorsqu’un seul comportement est nécessaire :

* [Hooks d’installation et de désinstallation de la Carte](/connectors/fr/custom-connector/installation-changed-extensibility.md)
* [Extensibilité EmailSender](/connectors/fr/custom-connector/emailsender-extensibility.md)

### FAQ

<details>

<summary><strong>Le fichier de script doit-il s’appeler <code>customProvider.js</code>?</strong></summary>

Non. Le nom de fichier peut suivre n’importe quelle convention de nommage utilisée par le projet. Ce qui compte, c’est la clé d’enregistrement d’exécution utilisée dans le script.

</details>

<details>

<summary><strong>Peut <code>customProvider</code> être remplacé avec un autre nom de connecteur ?</strong></summary>

Oui. Remplacez `customProvider` par le nom du connecteur qui doit être exposé par l’enregistrement d’exécution.

</details>

<details>

<summary><strong>Quand doit <code>runtime.wallet.passUpdater</code> être enregistré ?</strong></summary>

Enregistrez-le lorsque l’intégration doit réagir aux événements d’installation ou de désinstallation de la Carte. Si seul l’enrichissement de la Carte est nécessaire, l’enregistrement du fournisseur client peut suffire.

</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/developers-guides/fr/integration-guides/custom-connectors.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.