# Personnaliser la facturation avec des scripts

Utilisez des scripts pour programmer une logique de facturation personnalisée qui s’exécute directement sur Stripe.

Grâce à [un sous-ensemble de Typescript](https://docs.stripe.com/billing/scripts/script-language.md), vous pouvez écrire et soumettre une logique personnalisée dans Stripe. Grâce aux scripts, vous pouvez :

- définir votre propre logique pour des objets Stripe spécifiques
- adapter votre compte Stripe aux besoins propres à votre entreprise
- développer Stripe hors des limites de ses fonctionnalités standard

Par exemple, vous pouvez utiliser des scripts pour [créer une logique de réduction personnalisée sur les nouveaux bons de réduction](https://docs.stripe.com/billing/subscriptions/script-coupons.md), puis appliquer les bons de réduction aux Subscriptions et aux Factures.

## Cycle de vie des scripts

Reportez-vous au cycle de vie des scripts suivant pour comprendre comment les utiliser :

- Commencez par créer une logique personnalisée pour un cas d’usage pris en charge.
- Dans le cadre de la création de scripts, vous pouvez définir des valeurs de configuration. Ce sont des paramètres qu’un utilisateur de script transmet lors de la création d’un objet personnalisé.
- Stripe enregistre votre script sur le service de script une fois que vous l’avez soumis pour vérification.
- Vous pouvez ensuite appeler le script lors de la création d’objets, p. ex. un objet `Coupon` ou `Subscription`.

## Arguments de la fonction

Vous pouvez classer l’argument des fonctions dans deux catégories :

### Valeurs définies par l’auteur

On peut considérer que les valeurs définies par l’auteur ont deux publics :

- **Auteur du script** : L’auteur du script définit la fonction (c’est-à-dire la logique réelle) et les valeurs d’entrée de la fonction. Par exemple, vous pourriez écrire un script appliquant un pourcentage avec plafond dans lequel l’auteur définit deux valeurs d’entrée (`percent` et `maximum`).

- **Utilisateur du script** : une fois que l’auteur du script a défini les valeurs, l’utilisateur du script peut définir les valeurs pour les deux entrées via le Dashboard ou l’API (par exemple, 10 % de réduction sur un maximum de 100 USD).

L’auteur du script détermine les parties du script que l’utilisateur du script peut personnaliser. L’utilisateur du script applique ensuite ses propres valeurs aux parties personnalisables du script.

```typescript
export type scriptConfiguration = {
  max_discount_amount: {
    amount: number;
    currency: string;
  },
  discount_percent: number;
};
```

[Le SDK](https://github.com/stripe/scripts/blob/main/src/types.ts) fournit des types intégrés que vous pouvez utiliser dans le cadre de votre définition de configuration. Ces types préconfigurés s’affichent sous la forme d’une interface utilisateur de champ de saisie adaptée dans le Dashboard. Si vous avez de nouveaux types préconfigurés à suggérer, contactez [scripts-preview@stripe.com](mailto:scripts-preview@stripe.com) ou notre service Support.

```typescript
import type {PositiveMonetaryAmount, Percent} from '@stripe/scripts';

export type scriptConfiguration = {
  max_discount_amount: PositiveMonetaryAmount;
  discount_percent: Percent;
};
```

Les valeurs de configuration disposent de validations de schéma par défaut lorsque l’utilisateur du script tente de définir les valeurs. En outre, vous pouvez définir une validation personnalisée en vous référant aux [validations de schémas](https://docs.stripe.com/billing/scripts/script-language.md#schema-validation). Si nous ne prenons pas en charge votre cas d’usage de validation, nous vous recommandons d’intégrer le contrôle de validation dans la définition de votre fonction et de contacter [scripts-preview@stripe.com](mailto:scripts-preview@stripe.com).

### Valeurs définies par Stripe

Lors de l’exécution de la fonction, Stripe fournit des valeurs d’argument que vous ne pouvez pas personnaliser, comme les objets `Customer` ou `DiscountableLineItem`. Les objets spécifiques varient selon l’interface de fonction. Si vous avez besoin de données manquantes, contactez [scripts-preview@stripe.com](mailto:scripts-preview@stripe.com).

Nous passons également un objet `RunContext` à votre fonction qui fournit le contexte de l’exécution actuelle (par exemple, quel compte est en cours d’exécution, s’il s’agit du mode production, ou encore de l’heure de horloge de simulation). Cette option est disponible en tant que premier argument de votre fonction (par exemple, `context: RunContext`).

```typescript
export interface RunContext {
  account_id: string;
  livemode: boolean;
  clock_time: Date;
}
```

```typescript
/**
 * DiscountableLineItem data structure
 *
 * @typedef {Object} DiscountableLineItem
 * @property {MonetaryAmount} subtotal
 * @property {number | null} quantity
 * @property {TimeRange} period
 * @property {Price | null} price
 */
export interface DiscountableLineItem {
  subtotal: MonetaryAmount;
  quantity?: number | null;
  period: TimeRange;
  price?: Price | null;
}
```

## Logique de fonction

L’auteur du script définit la personnalisation utilisée par la logique de la fonction de script. Tous les arguments sont « transmis par valeur », ce qui signifie qu’aucune modification apportée aux valeurs d’argument dans la fonction n’affecte la valeur d’origine en dehors de la fonction.

### Gestion appropriée des erreurs d’exécution

Dans la plupart des cas, vous chercherez à détecter l’erreur et à disposer un comportement de secours. Dans de rares cas, vous souhaiterez peut-être lever une exception. La levée d’une exception interrompt l’exécution complète du code associé au script. Veillez donc à lever une exception uniquement en l’absence d’autres options.

### Rédiger des tests

Bien que l’utilisation d’une suite de tests automatisés pour vos fonctions de script ne soit pas obligatoire, elle est recommandée. Vous pouvez écrire des tests dans votre environnement de test ou en mode test. Pour obtenir des conseils, contactez [scripts-preview@stripe.com](mailto:scripts-preview@stripe.com).

### Valeur renvoyée par la fonction

La valeur renvoyée par la fonction doit respecter l’interface, qui varie en fonction de la personnalisation. Consultez le [SDK](https://github.com/stripe/scripts) pour la définition spécifique de l’interface et assurez-vous que votre fonction respecte l’interface.

## See also

- [Bons de réduction de type script](https://docs.stripe.com/billing/subscriptions/script-coupons.md)