> 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

## 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 Carte doivent être enrichies à partir d'un système externe ou lorsqu'une logique personnalisée doit s'exécuter lors de l'installation ou de la désinstallation d'une Carte.

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 votre logiciel et que l'intégration doit être mise en œuvre avec du scripting au runtime.

### Liste de contrôle de création

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

| Élément                  | Résultat attendu                                                                                                     |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Stratégie d'identifiants | Champs d'ID stables disponibles sur chaque enregistrement lié à une Carte                                            |
| Propriété des données    | Les systèmes sources pour les données de profil, de fidélité, de transaction et de ticket sont explicitement définis |
| Modèle de déclenchement  | Décision claire sur le moment `Remplissage`, les hooks d'installation et de désinstallation sont utilisés            |
| Modèle de sécurité       | Clés API ou stratégie OAuth définies pour les appels externes                                                        |
| Gestion des erreurs      | Comportement de nouvelle tentative, de délai d'attente et de surveillance 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 analytique.

</details>

### Exigences

Pour créer un script, ouvrez **Paramètres → Avancé → Configuration avancée**. 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. Vous pouvez remplacer chaque `customProvider` occurrence par le nom du connecteur qui doit être enregistré, ou vous pouvez le conserver.
{% endhint %}

### Contraintes d'exécution

Les scripts de connecteur personnalisé s'exécutent dans un environnement d'exécution en bac à sable 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 des scripts qui appellent des points de terminaison légers et à faible latence et évitez les opérations bloquantes.

**Uniquement les bibliothèques approuvées**

L'environnement d'exécution 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 font l'objet d'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 dans l'un des deux modes suivants :

* **Synchrone**: exécuté en ligne dans un appel API, en 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é via la 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 surveillance. Si un script provoque une pression soutenue sur les ressources, il sera examiné.

### Créer 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', {
    OnCarteInstalled: onPassInstalled,
    OnCarteUninstalled: onPassUninstalled
  });
}
```

### Fonction de remplissage

La `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, puis 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 `Remplissage` est disponible dans la [référence de l'API](https://docs.thewalletcrew.io/api-reference).

### Exemple d'implémentation

Cet exemple lit les identifiants externes qui sont ajoutés lorsqu'une Carte est créée, appelle une API externe et mappe 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 s'est produite 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 objectif différent.

`runtime.scriptable.customerProvider.customProvider`

Cet enregistrement expose une fonction nommée `Remplissage`. La `Remplissage` fonction est utilisée pour remplir des Cartes avec des données externes.

C'est l'endroit où appeler des API externes et enrichir les données de 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 :

* `OnCarteInstalled`
* `OnCarteUninstalled`

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 utilisations 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 que la Carte est déjà installée.

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

La référence runtime 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 lorsque vous n'avez besoin que d'un seul comportement :

* [Hooks d'installation et de désinstallation de Carte](https://github.com/TheWalletCrew/docs/tree/main/connectors/custom-connector/installation-changed-extensibility.md)
* [Extensibilité EmailSender](https://github.com/TheWalletCrew/docs/tree/main/connectors/custom-connector/emailsender-extensibility.md)

### FAQ

<details>

<summary><strong>Le fichier de script doit-il être nommé <code>customProvider.js</code>?</strong></summary>

Non. Le nom du fichier peut suivre n'importe quelle convention de nommage utilisée par le projet. Ce qui importe, c'est la clé d'enregistrement runtime utilisée à l'intérieur du script.

</details>

<details>

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

Oui. Remplacez `customProvider` par le nom du connecteur qui doit être exposé par l'enregistrement runtime.

</details>

<details>

<summary><strong>Quand <code>runtime.wallet.passUpdater</code> doit-il ê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.