> 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/scripting/endpoints/benefit-provider.md).

# Fournisseur d'avantages

Maintenir les avantages d’une carte en phase avec un système externe en lecture seule, avec runtime.benefit.benefitProvider, son gestionnaire GetBenefits et ses règles de validation.

Un script de fournisseur d’avantages renvoie, pour une Carte, l’ensemble complet des avantages qu’un système externe détient pour le titulaire : bons, offres, cadeau de bienvenue. L’équipe Wallet compare cet ensemble avec les avantages que la Carte possède déjà, ajoute les nouveaux, met à jour ceux qui ont changé et supprime ceux qui ne sont plus renvoyés. C’est l’outil pour un système qui ne peut être que lu. Cette page est la référence pour `runtime.benefit.benefitProvider`.

Trois outils accordent des avantages, et le choix dépend de qui lance l’échange :

* Le système **peut appeler l’équipe Wallet**: utilisez l’API des avantages.
* **L’équipe Wallet émet** l’avantage à partir d’un modèle d’avantage, et seul son code provient d’un script : utilisez le [générateur de code d’avantage](https://docs.thewalletcrew.io/developers-guides/fr/scripting/endpoints/benefit-code-generator.md).
* Le système **ne peut être que lu**: utilisez ce point de terminaison.

<details>

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

* Un commerçant répertorie les bons qu’un client détient dans sa plateforme promotionnelle, et la Carte les affiche comme des avantages.
* Un programme partenaire renvoie les offres auxquelles un membre a droit, avec leurs dates d’activation et d’expiration.
* Une marque laisse son CRM gérer l’utilisation : il signale combien de fois chaque avantage a été utilisé, et la Carte affiche le solde restant.

</details>

## Enregistrement

La clé est `runtime.benefit.benefitProvider`. L’enregistrer suffit : aucun fichier de configuration n’y fait référence, et dès lors elle s’applique à toutes les Cartes du locataire qui ne sont pas elles-mêmes un avantage.

```js
export default function (context) {
  context.register('runtime.benefit.benefitProvider', {
    GetBenefits: async (passId, passType, identifiers) => undefined
  });
}
```

## Quand il s’exécute

La synchronisation s’exécute lorsqu’une Carte est créée et à chaque mise à jour qui recalcule les métadonnées de la Carte. Elle ne s’exécute pas pour les Cartes qui portent un identifiant d’avantage (les Cartes qui portent un avantage), donc elle ne s’exécute jamais récursivement.

Un verrou distribué par Carte empêche deux synchronisations de la même Carte en même temps lors d’une rafale de mises à jour. Une synchronisation attend jusqu’à une minute pour le verrou ; lorsqu’il n’est pas obtenu, la synchronisation est ignorée et un avertissement est consigné.

Comme le script s’exécute à chaque recalcul des métadonnées, un appel au système externe utilise l’ `Cache` option de [fetch](https://docs.thewalletcrew.io/developers-guides/fr/scripting/globals/fetch.md).

## Gestionnaires

| Method        | Paramètres                          | Retour                                | Obligatoire |
| ------------- | ----------------------------------- | ------------------------------------- | ----------- |
| `GetBenefits` | `passId`, `passType`, `identifiers` | une promesse d’un tableau d’avantages | Obligatoire |

`GetBenefits` doit être une `async` fonction : la plateforme lit son résultat comme une promesse, donc une fonction simple qui renvoie un tableau échoue, et l’échec est géré comme une erreur levée (voir ci-dessous). Elle est obligatoire : une méthode manquante ignorerait toutes les Cartes.

* `passId` est l’id de la Carte et `passType` son type de Carte.
* `identifiers` est un objet des identifiants de la Carte, indexés sans le `identifiant.` préfixe : une Carte portant `crm.customerId` se lit comme `identifiers['crm.customerId']`.

## Valeur de retour

Le résultat est l’ **ensemble complet** des avantages de la Carte, sous forme de tableau d’objets avec des clés en camelCase.

| Renvoyé                | Effet                                                                                                      |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| Un tableau d’avantages | La Carte obtient exactement ces avantages. Un avantage fourni auparavant et désormais absent est supprimé. |
| `[]`                   | Tout avantage fourni par le script est supprimé.                                                           |
| `indéfini` ou `null`   | Un avertissement est consigné et rien ne change.                                                           |

Un avantage qui revient après avoir été supprimé est réactivé, pas dupliqué. Les avantages sont stockés avec `origin.generator` défini sur `script`.

### L’objet avantage

| Membre                                               | Type            | Signification                                                                                                                                                                            |
| ---------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `origin.externalId`                                  | chaîne          | Obligatoire. Un identifiant stable, unique dans tout le locataire. C’est l’identité utilisée pour comparer les avantages renvoyés avec les existants.                                    |
| `origin.processId`                                   | chaîne          | Facultatif. L’identifiant du modèle d’avantage, lorsque l’avantage est lié à un modèle.                                                                                                  |
| `type`                                               | chaîne          | `OneTime` (par défaut), `MultiUse` ou `Unlimited`.                                                                                                                                       |
| `catégorie`                                          | chaîne          | Une catégorie. `Autre` par défaut.                                                                                                                                                       |
| `priority`, `balises`                                | nombre, tableau | Ordre et balises facultatifs.                                                                                                                                                            |
| `content.title`, `content.description`               | objet           | Chaque élément est `{ default, localizations }`.                                                                                                                                         |
| `appearance.images`                                  | tableau         | Chaque élément `{ slot, url }`: `emplacement` est `Principal` ou `Miniature`, `url` est `{ default, localizations }` avec des `http` ou `https` URL absolues. Une image par emplacement. |
| `liens`                                              | objet           | Indexés par type de lien (`CallToAction`, `Website`, ...), chacun `{ title, link }`.                                                                                                     |
| `data.content`                                       | chaîne          | Texte libre.                                                                                                                                                                             |
| `behavior.target`                                    | nombre          | L’allocation d’un `MultiUse` avantage. `1` par défaut.                                                                                                                                   |
| `behavior.mode`                                      | tableau         | Où l’avantage apparaît. `ShowOnBenefitListPage` uniquement par défaut ; `[]` n’affiche l’avantage nulle part.                                                                            |
| `code.value`, `code.format`                          | chaîne          | Le code et son format. `Code128` par défaut.                                                                                                                                             |
| `activationDate`, `deactivationDate`, `deletionDate` | chaîne          | Chaînes ISO 8601. Un objet JavaScript est refusé. `Date` objet JavaScript est refusé.                                                                                                    |
| `passType`                                           | chaîne          | Crée une Carte autonome pour l’avantage.                                                                                                                                                 |
| `usedQuantity`                                       | nombre          | Lorsqu’il est défini, le système externe gère l’utilisation : le solde est l’allocation moins `usedQuantity`, et la valeur ne doit qu’augmenter.                                         |

La plateforme gère l’identifiant d’avantage, les mouvements de solde et `origin.generator`: un script ne les définit pas.

## Erreurs et cas limites

* **`GetBenefits` lève une exception ou si sa promesse est rejetée**: l’erreur est ignorée et la Carte conserve ses avantages tels quels.
* **`GetBenefits` renvoie `indéfini` ou `null`**: un avertissement est consigné et rien ne change. Pour supprimer chaque avantage, renvoyez `[]`.
* **Un avantage a une catégorie, un format de code, un mode, un type de lien ou un emplacement d’image inconnus**: la valeur est remplacée par sa valeur par défaut, ou ignorée, et consignée.
* **Un avantage a un `type`, ou une date illisible** (un `Date` objet JavaScript, ou une chaîne au format jour-mois ou mois-jour) : **tout le résultat est refusé**.
* **Le verrou n’est pas obtenu**: la synchronisation est ignorée avec un avertissement.
* **Aucun script n’enregistre la clé**: rien ne se passe.
* **Plusieurs fichiers enregistrent la clé**: le dernier enregistré l’emporte, et l’ordre de chargement des fichiers n’est pas défini.
* **La Carte porte un identifiant d’avantage**: le fournisseur ne s’exécute pas pour elle.

Chaque synchronisation consigne une ligne avec le nombre d’avantages fournis, insérés, mis à jour, retirés, utilisations enregistrées et avantages sans emplacement libre.

## Exemple

Le script lit les bons d’un client dans une API partenaire. Un échec de l’API renvoie `indéfini`, afin que la Carte conserve ses avantages au lieu de les perdre. Les dates sont des chaînes ISO, et le `externalId` est le numéro du bon.

```js
import { getSecret } from 'twc/secrets';

const API_URL = 'https://vouchers.example.com/api/customers';

async function getBenefits(passId, passType, identifiers) {
  const customerId = identifiers['crm.customerId'];
  if (!customerId) {
    return undefined;
  }

  const apiKey = await getSecret('VOUCHER-API-KEY');
  if (!apiKey) {
    console.error('Le secret VOUCHER-API-KEY n’est pas défini : les avantages ne sont pas synchronisés');
    return undefined;
  }

  const response = await fetch(`${API_URL}/${encodeURIComponent(customerId)}/vouchers`, {
    Headers: { 'X-Api-Key': apiKey },
    ThrowOnError: false,
    Cache: { CacheKey: `vouchers|${customerId}`, DurationInMs: 5 * 60 * 1000 }
  });

  if (response.StatusCode !== 200 || !response.ResponseText) {
    console.warn(`La recherche de bons a répondu ${response.StatusCode} : les avantages sont laissés tels quels`);
    return undefined;
  }

  const vouchers = JSON.parse(response.ResponseText).items ?? [];
  return vouchers.map((voucher) => ({
    origin: { externalId: `voucher-${voucher.number}` },
    type: 'OneTime',
    content: { title: { default: voucher.title } },
    code: { value: voucher.number },
    activationDate: voucher.validFrom,
    deactivationDate: voucher.validUntil
  }));
}

export default function (context) {
  context.register('runtime.benefit.benefitProvider', {
    GetBenefits: getBenefits
  });
}
```

Un tableau vide `items` renvoie `[]`, ce qui supprime les avantages que le script avait fournis auparavant : c’est l’effet recherché lorsque le client ne détient plus aucun bon.

## Vérification du résultat

`GET /api/{tenantId}/passes/{passId}/benefits` liste les avantages d’une Carte de test. La surveillance de la plateforme enregistre une ligne par synchronisation, qui indique combien d’avantages ont été insérés, mis à jour ou retirés, et un avertissement lorsqu’un résultat a été ignoré.

## Pièges courants

* Le `externalId` change d’un appel au suivant, donc les avantages sont supprimés puis recréés.
* Un appel au système externe sans `Cache`, répété à chaque recalcul des métadonnées.


---

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/fr/scripting/endpoints/benefit-provider.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
