> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwoty.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe Billing

> Crée automatiquement un Stripe Subscription Schedule lorsqu'une proposition commerciale est signée, incluant les frais de mise en service uniques et les plans récurrents multi-phases.

## Vue d'ensemble

L'intégration Stripe Billing transforme une commande Qwoty signée en Stripe Subscription Schedule. Chaque phase du plan tarifaire devient une phase Stripe avec ses propres éléments, sa fréquence de facturation et sa durée. Les frais uniques (frais de mise en service, matériel, onboarding) sont attachés en tant qu'éléments de facture sur le premier cycle de facturation. Les remises sont appliquées sous forme de coupons Stripe natifs au niveau de l'article, de la phase ou de l'add-invoice-item.

Si la commande contient un délai de démarrage, l'intégration crée automatiquement une période d'essai de cette durée avant le début de la facturation.

## Authentification

<Steps>
  <Step title="Accédez à votre tableau de bord Stripe">
    Rendez-vous sur [dashboard.stripe.com](https://dashboard.stripe.com) et connectez-vous.
  </Step>

  <Step title="Créez une clé API restreinte">
    Accédez à **Developers → API keys → Create restricted key**.

    Accordez un accès en écriture à : **Customers**, **Subscriptions**, **Subscription Schedules**, **Invoices**, **Tax rates**, **Coupons**.
  </Step>

  <Step title="Copiez la clé secrète">
    Copiez la clé commençant par `sk_live_` (ou `sk_test_` pour les tests).
  </Step>

  <Step title="Collez-la dans les paramètres de l'intégration">
    Collez la clé dans le champ **Workspace API token** ci-dessous.
  </Step>
</Steps>

<Warning>
  Si vous utilisez plusieurs comptes Stripe (un par unité commerciale), définissez **Token scope** sur `business_unit` et fournissez une clé par identifiant d'unité commerciale.
</Warning>

## Paramètres

### Authentification

| Clé                   | Défaut      | Description                                                                                      |
| --------------------- | ----------- | ------------------------------------------------------------------------------------------------ |
| `token_scope`         | `workspace` | `workspace` — une clé globale. `business_unit` — une clé par unité commerciale. **Obligatoire.** |
| `workspace_api_token` | —           | Clé secrète Stripe (si `token_scope = workspace`). **Obligatoire.**                              |

### Facturation

| Clé                 | Défaut                 | Description                                                                                                                                                                                                                                                            |
| ------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collection_method` | `charge_automatically` | La façon dont Stripe collecte le paiement. `charge_automatically` débite le moyen de paiement enregistré du client. `send_invoice` envoie une facture par e-mail.                                                                                                      |
| `days_until_due`    | `30`                   | Nombre de jours accordés au client pour payer (utilisé uniquement lorsque `collection_method = send_invoice`).                                                                                                                                                         |
| `payment_behavior`  | `allow_incomplete`     | Comportement en cas d'échec du premier paiement. `allow_incomplete` — crée l'abonnement avec le statut `incomplete`. `default_incomplete` — `incomplete` uniquement si un paiement est requis. `error_if_incomplete` — renvoie une erreur et ne crée pas l'abonnement. |

### Taxes

| Clé        | Défaut   | Description                                                                                                                                                                                        |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tax_mode` | `manual` | `automatic` — Stripe Tax calcule les taux de taxe automatiquement (nécessite l'activation de Stripe Tax). `manual` — les taux de taxe sont issus de la commande Qwoty et synchronisés avec Stripe. |

<Note>
  Lorsque `tax_mode = automatic`, aucun taux de taxe de Qwoty n'est envoyé à Stripe. Stripe Tax doit être configuré dans votre tableau de bord Stripe.
</Note>

### Période d'essai

| Clé                  | Défaut           | Description                                                                                                                                                                                                              |
| -------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `trial_end_behavior` | `create_invoice` | Ce qui se passe si le client n'a pas de moyen de paiement à la fin de la période d'essai. `create_invoice` — génère une facture quoi qu'il en soit. `pause` — met l'abonnement en pause. `cancel` — annule l'abonnement. |

<Note>
  Une période d'essai est créée automatiquement lorsque le type de démarrage de facturation de la commande est `sign_day` avec un `delay_days > 0`. La période d'essai dure exactement `delay_days` jours.
</Note>

### Post-création

| Clé           | Défaut | Description                                                                                                                        |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `post_action` | `none` | Action effectuée après la création du schedule. `none` — aucune action. `send_email` — envoie un e-mail de confirmation via Qwoty. |

## Résultat

### Ce qui est créé dans Stripe

**1. Client** (s'il n'est pas déjà associé)

L'intégration recherche le client par son identifiant Qwoty (stocké dans les métadonnées Stripe), puis par e-mail. S'il n'est pas trouvé, un nouveau client Stripe est créé et l'identifiant Stripe est renvoyé dans Qwoty (`external_ids.accounting`).

**2. Coupons** (un par montant de remise unique)

Pour chaque remise dans la commande, l'intégration recherche un coupon Stripe existant avec l'identifiant `qwoty_{orderId}_{amountCents}_{currency}_{duration}` avant d'en créer un nouveau. Tous les coupons Qwoty sont préfixés par `qwoty_` pour une identification facile dans votre tableau de bord Stripe.

**3. Taux de taxe** (mode manuel uniquement)

Les taux de taxe sont résolus via `external_ids.accounting` sur chaque entrée de taxe. S'ils ne sont pas trouvés, l'intégration effectue une recherche dans Stripe par pourcentage et pays, puis crée un nouveau taux de taxe s'il est absent.

**4. Subscription Schedule**

| Source CPQ               | Champ Stripe               | Notes                      |
| ------------------------ | -------------------------- | -------------------------- |
| Client résolu            | `customer`                 |                            |
| `start.type = sign_day`  | `start_date = "now"`       |                            |
| `start.type = date`      | `start_date`               | Horodatage Unix            |
| Dernière phase `forever` | `end_behavior = "release"` | Renouvellement automatique |
| Dernière phase avec fin  | `end_behavior = "cancel"`  | Annulation à la fin        |
| `order.id`               | `metadata.quote_id`        |                            |
| `order.quote_number`     | `metadata.quote_number`    |                            |
| `order.opportunity_id`   | `metadata.opportunity_id`  | Si renseigné               |

**Phases** — une par phase de plan CPQ :

| Source CPQ                 | Champ Stripe | Notes                                       |
| -------------------------- | ------------ | ------------------------------------------- |
| `end.duration`             | `iterations` | Converti en nombre de cycles de facturation |
| `end.date`                 | `end_date`   | Horodatage Unix                             |
| `end.forever`              | *(absent)*   | Dernière phase, illimitée                   |
| `delay_days > 0` (phase 0) | `trial_end`  | Horodatage Unix, maintenant + delay\_days   |

**Éléments par phase** — un par ligne facturable :

| Source CPQ                | Champ Stripe                   | Notes                       |
| ------------------------- | ------------------------------ | --------------------------- |
| `product.name`            | `price_data.product_data.name` |                             |
| `amounts.unit_price`      | `price_data.unit_amount`       | Prix brut × 100 (centimes)  |
| `billing_frequency`       | `price_data.recurring`         | interval + interval\_count  |
| `amounts.discount_amount` | `items[M].discounts[0].coupon` | Coupon `duration = forever` |
| Taxe résolue              | `default_tax_rates[]`          | Mode manuel uniquement      |

**Éléments uniques** (issus des sections produit, ajoutés à la phase 0) :

| Source CPQ                | Champ Stripe                               | Notes                    |
| ------------------------- | ------------------------------------------ | ------------------------ |
| `product.name`            | `price_data.product_data.name`             |                          |
| `amounts.unit_price`      | `price_data.unit_amount`                   | Prix brut × 100          |
| `amounts.discount_amount` | `add_invoice_items[M].discounts[0].coupon` | Coupon `duration = once` |
| Remises globales          | `phases[0].discounts[0].coupon`            | Coupon `duration = once` |
| Taxe résolue              | `add_invoice_items[M].tax_rates[]`         | Mode manuel uniquement   |

### Exemple — Abonnement 2 phases avec frais de mise en service

Une commande Qwoty avec un frais de mise en service et deux phases récurrentes de 12 mois produit :

```text theme={null}
Subscription Schedule
├── start_date: now
├── end_behavior: cancel
├── Phase 1 (12 iterations)
│   ├── add_invoice_items
│   │   └── "Setup Fee" — 1 400 € HT
│   └── items
│       └── "Licence Enterprise" — 490 €/month × 10 seats
│           └── coupon: qwoty_xxx_4900_eur_forever (-49 €/month)
└── Phase 2 (12 iterations)
    └── items
        └── "Licence Enterprise" — 590 €/month × 10 seats
```

<Note>
  Tous les prix sont envoyés en montants bruts (HT). La taxe est appliquée par Stripe au moment de la génération de la facture, soit automatiquement (Stripe Tax), soit via les taux de taxe résolus.
</Note>