> ## 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 - Facture

> Créez et envoyez automatiquement une facture Stripe à votre client lorsqu'un devis est accepté.

## Vue d'ensemble

L'intégration **Stripe — Facture** crée une facture Stripe à partir des lignes d'un devis Qwoty et la finalise et la remet optionnellement à votre client.

Selon vos paramètres, la facture peut être envoyée directement via Stripe, ou associée à un lien de paiement Stripe Checkout et transmise par e-mail via Qwoty avec le PDF de la facture en pièce jointe.

***

## Authentification

Accédez à **Tableau de bord Stripe → Développeurs → Clés API** et copiez votre clé secrète (`sk_live_...` en production, `sk_test_...` en mode test).

La clé secrète nécessite les permissions Stripe suivantes :

* **Clients** — lecture et écriture (créer, rechercher)
* **Factures** — lecture et écriture (créer, finaliser, envoyer, associer un paiement)
* **Éléments de facture** — écriture (créer)
* **Taux de taxe** — lecture et écriture (lister, créer)
* **Sessions Checkout** — écriture (créer)
* **Points de terminaison Webhook** — lecture et écriture (lister, créer)

Deux portées de jeton sont disponibles selon votre organisation :

**Espace de travail** — une seule clé Stripe partagée entre tous les devis. Saisissez-la dans le champ **Jeton API de l'espace de travail**.

**Unité commerciale** — une clé Stripe différente par unité commerciale. Saisissez un plan JSON dans le champ **Jetons API des unités commerciales** :

```json theme={null}
{
  "business_unit_id_1": "sk_live_...",
  "business_unit_id_2": "sk_live_..."
}
```

<Warning>
  En mode **Unité commerciale**, le devis doit être associé à une unité commerciale dont l'identifiant est présent dans le plan. Dans le cas contraire, la facture ne sera pas créée.
</Warning>

***

## Comportement

### Client

L'intégration trouve ou crée automatiquement un client Stripe pour chaque devis :

1. Si un identifiant client Stripe est déjà enregistré sur le contact Qwoty (`external_ids.accounting`), il est utilisé directement.
2. Sinon, une recherche est effectuée dans Stripe — d'abord par UUID du contact Qwoty, puis par e-mail de facturation.
3. Si aucune correspondance n'est trouvée, un nouveau client Stripe est créé avec le nom, l'e-mail et l'adresse de facturation du contact. L'identifiant client Stripe est ensuite sauvegardé sur le contact Qwoty pour une utilisation future.

### Lignes

Un élément de facture Stripe est créé par produit facturable dans les sections `product` du devis. Si une ligne comporte une remise, un second élément négatif est ajouté sur la même ligne.

Les remises globales sur le devis sont ajoutées sous la forme d'un seul élément de facture négatif en bas.

<Note>
  Seules les sections de type `product` sont incluses. Les sections récurrentes (`plan`) ne sont pas prises en charge dans cette intégration.
</Note>

### Taxes

Les taux de taxe sont résolus automatiquement pour chaque ligne :

1. Si un identifiant de taux de taxe Stripe est déjà enregistré sur la taxe Qwoty (`external_ids.accounting`), il est utilisé directement.
2. Sinon, l'intégration recherche les taux de taxe Stripe existants par pourcentage et par pays (analysé à partir du format `api_name` de Qwoty — par ex. `vat_fr_200` → France, 20 %).
3. Si aucune correspondance n'est trouvée, un nouveau taux de taxe est créé dans Stripe et son identifiant est sauvegardé dans Qwoty.

Les taux de taxe sont toujours exclusifs (prix affichés hors taxe).

### Statut de la facture

Si **Créer la facture comme Brouillon**, la facture est créée mais non finalisée. Aucun e-mail ni lien de paiement n'est envoyé, quels que soient les autres paramètres.

Si **Créer la facture comme Ouverte**, la facture est finalisée et l'une des actions suivantes est déclenchée :

### Actions post-finalisation

| Paramètre                                                | Action                                                                                                                                                                                                                                                                                                             |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Envoyer la facture par e-mail (via Stripe)**           | Stripe envoie la facture finalisée directement à l'e-mail du client.                                                                                                                                                                                                                                               |
| **Envoyer le lien de paiement + la facture (via Qwoty)** | Un lien de paiement Stripe Checkout est créé pour le montant du premier acompte. Un e-mail est envoyé via Qwoty avec le PDF de la facture en pièce jointe et un lien pour payer. Une fois le paiement effectué par le client, la session Checkout est automatiquement associée à la facture via un webhook Stripe. |

<Note>
  Si les deux options sont désactivées, la facture est finalisée mais non envoyée.
</Note>

<Warning>
  L'option **Envoyer le lien de paiement + la facture** nécessite l'enregistrement d'un webhook Stripe. L'intégration gère cela automatiquement lors de la première utilisation — aucune configuration manuelle n'est nécessaire.
</Warning>

***

## Paramètres

| Paramètre                                                | Valeurs             | Par défaut        | Description                                                                                                                     |
| -------------------------------------------------------- | ------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Créer la facture comme**                               | Brouillon / Ouverte | Brouillon         | `Brouillon` : la facture est créée mais non finalisée. `Ouverte` : la facture est finalisée immédiatement.                      |
| **Envoyer la facture par e-mail (via Stripe)**           | Oui / Non           | Non               | Stripe envoie la facture finalisée au client. Actif uniquement lorsque la facture est Ouverte.                                  |
| **Envoyer le lien de paiement + la facture (via Qwoty)** | Oui / Non           | Non               | Envoie un lien de paiement Stripe Checkout et le PDF de la facture par e-mail. Actif uniquement lorsque la facture est Ouverte. |
| **Méthode de paiement**                                  | Par défaut Stripe   | Par défaut Stripe | Méthodes de paiement présentées au client sur la page Checkout.                                                                 |

***

## Exemples

**Devis accepté — 4 acomptes de 2 275,50 €**

Le devis comporte 4 acomptes. L'intégration crée une facture Stripe pour le montant total et envoie un lien de paiement Checkout pour le premier acompte (2 275,50 €) par e-mail.

| Champ                       | Valeur                   |
| --------------------------- | ------------------------ |
| Total de la facture         | 9 102,00 €               |
| Premier acompte             | 2 275,50 € (25 %)        |
| Montant du lien de paiement | 2 275,50 €               |
| PDF joint                   | PDF de la facture Stripe |
| Expiration du lien          | 24 heures                |

Une fois que le client a payé la session Checkout, le paiement est automatiquement associé à la facture. Le statut de la facture passe à `partially_paid`, et les acomptes suivants peuvent être envoyés de la même manière.