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

# Pennylane

> Synchronisez vos devis Qwoty vers Pennylane — factures, devis et abonnements créés automatiquement à la signature.

***

## Ce que fait cette intégration

À chaque signature d'un devis Qwoty, l'intégration Pennylane crée automatiquement les documents comptables correspondants dans votre espace Pennylane :

* **Devis one-off** → une ou plusieurs factures (selon vos conditions de paiement) ou un devis
* **Abonnements** → un abonnement récurrent par phase tarifaire
* **Client inconnu** → le client est créé automatiquement dans Pennylane si besoin

***

## Prérequis

### Créer une clé API Pennylane

Rendez-vous dans **Paramètres → API** dans votre espace Pennylane et créez une clé en mode **Read and write** avec les scopes suivants :

* `Manage billing subscriptions`
* `Manage customer invoices`
* `Manage clients`
* `Manage quotes`
* `Customer mandates`

<Info>
  Consultez la [documentation Pennylane](https://pennylane.readme.io/docs/generating-my-api-token) pour le détail des étapes de création de clé API.
</Info>

### Configurer un premier numéro de document

Avant d'utiliser l'intégration, Pennylane requiert qu'un **premier numéro de facture et de devis** soit défini dans votre espace — sans quoi la création de documents échoue. Configurez-les dans **Paramètres → Numérotation** avant de lancer votre premier sync.

<Warning>
  Cette étape est requise aussi bien sur la sandbox que sur votre environnement live. Sans numérotation configurée, l'intégration retournera une erreur à la création du premier document.
</Warning>

### Tester sur la sandbox

Pennylane met à disposition un environnement de sandbox pour tester l'intégration sans impacter vos données de production. Les tests sur sandbox sont **recommandés** avant mise en production.

<Tip>
  Pensez à configurer la numérotation sur votre sandbox également, et à utiliser une clé API sandbox distincte de votre clé de production.
</Tip>

***

## Configuration

### Documents

<ParamField path="document_type" default="Invoice" type="liste" required>
  Détermine le type de document créé dans Pennylane pour vos devis **one-off** (produits sans abonnement).

  | Valeur      | Comportement                                                        |
  | ----------- | ------------------------------------------------------------------- |
  | **Invoice** | Crée une ou plusieurs **factures** selon vos conditions de paiement |
  | **Quote**   | Crée un **devis** dans Pennylane                                    |

  <Note>
    Ce paramètre n'a pas d'effet sur les sections **abonnement** — celles-ci créent toujours un `billing_subscription`.
  </Note>
</ParamField>

***

### Factures

<ParamField path="invoice_status" default="Yes (brouillon)" type="liste" required>
  Définit si les factures sont créées en **brouillon** ou **finalisées**.

  | Valeur  | Comportement                                                                   |
  | ------- | ------------------------------------------------------------------------------ |
  | **Yes** | Facture créée en brouillon — vous devez la valider manuellement dans Pennylane |
  | **No**  | Facture finalisée immédiatement à la création                                  |

  <Warning>
    Une facture finalisée ne peut plus être modifiée. Utilisez le mode brouillon si vous souhaitez vérifier les montants avant envoi.
  </Warning>
</ParamField>

<ParamField path="invoice_send_by_email" default="No" type="liste" required>
  Envoie automatiquement la facture au client par email après sa création dans Pennylane.

  | Valeur  | Comportement                                                               |
  | ------- | -------------------------------------------------------------------------- |
  | **Yes** | La facture est envoyée par email à l'adresse du contact principal du devis |
  | **No**  | La facture est créée sans envoi automatique                                |

  <Note>
    L'envoi email utilise le template configuré dans Pennylane. Ce paramètre s'applique uniquement aux factures — les devis ne sont jamais envoyés par email automatiquement.
  </Note>
</ParamField>

***

### Abonnements

<ParamField path="subscription_mode" default="Awaiting validation" type="liste" required>
  Définit le mode de création des abonnements récurrents dans Pennylane.

  | Valeur                  | Comportement                                                                  |
  | ----------------------- | ----------------------------------------------------------------------------- |
  | **Awaiting validation** | L'abonnement est créé en attente de validation — vous le validez manuellement |
  | **Finalized**           | L'abonnement est activé immédiatement                                         |
  | **Email**               | Pennylane envoie un email de validation au client                             |
</ParamField>

<ParamField path="subscription_payment_conditions" default="Upon receipt" type="liste" required>
  Conditions de paiement appliquées aux factures générées par l'abonnement.

  | Valeur           | Délai                   |
  | ---------------- | ----------------------- |
  | **Upon receipt** | Paiement dès réception  |
  | **30 days**      | Paiement sous 30 jours  |
  | **45 days**      | Paiement sous 45 jours  |
  | **60 days**      | Paiement sous 60 jours  |
  | **End of month** | Paiement en fin de mois |
</ParamField>

<ParamField path="subscription_payment_method" default="Offline (wire transfer)" type="liste" required>
  Méthode de paiement associée à l'abonnement.

  | Valeur                      | Description                                   |
  | --------------------------- | --------------------------------------------- |
  | **Offline (wire transfer)** | Virement bancaire — aucune action automatique |
  | **GoCardless direct debit** | Prélèvement automatique via GoCardless        |

  <Note>
    Si vous choisissez **GoCardless direct debit**, activez également **Send GoCardless SEPA mandate request** pour que votre client reçoive automatiquement la demande de mandat.
  </Note>
</ParamField>

<ParamField path="subscription_send_sepa" default="No" type="liste" required>
  Envoie automatiquement une demande de mandat SEPA GoCardless au client après la création de l'abonnement.

  | Valeur  | Comportement                                                          |
  | ------- | --------------------------------------------------------------------- |
  | **Yes** | Une demande de mandat est envoyée au contact principal via GoCardless |
  | **No**  | Aucune demande automatique                                            |

  <Warning>
    Ce paramètre ne fonctionne que si **Subscription payment method** est réglé sur **GoCardless direct debit** et que votre compte Pennylane est connecté à GoCardless.
  </Warning>
</ParamField>

***

## Comportements automatiques

### Création du client

Si le client du devis n'existe pas encore dans Pennylane, il est créé automatiquement avec les informations suivantes :

* Nom de l'entreprise
* Adresse de facturation
* Email du contact principal
* Référence externe (ID Qwoty) — permet d'éviter les doublons lors des prochains devis

### Conditions de paiement et installments

Si votre devis Qwoty contient des **conditions de paiement échelonnées** (acompte + solde), l'intégration crée **une facture par échéance** :

* Les montants sont calculés proportionnellement au pourcentage de chaque échéance
* La première facture suit le statut brouillon/finalisé configuré
* Les factures suivantes sont toujours créées en **brouillon**

### Abonnements multi-phases

Si votre devis contient un plan tarifaire avec **plusieurs phases** (ex : tarif lancement puis tarif standard), l'intégration crée **un abonnement par phase** dans Pennylane, avec la date de démarrage calculée automatiquement.

### Remises globales

Les remises globales appliquées sur l'ensemble du devis sont reportées sur chaque document Pennylane via le champ `discount`.

***

## Questions fréquentes

<AccordionGroup>
  <Accordion title="Un client existe déjà dans Pennylane — sera-t-il créé en double ?">
    Non. L'intégration vérifie d'abord si un client avec la même référence externe (ID Qwoty) existe déjà dans Pennylane. Si c'est le cas, il est réutilisé. Si vous avez renseigné manuellement l'ID Pennylane sur la fiche client dans Qwoty, cette valeur est utilisée directement sans aucune recherche.
  </Accordion>

  <Accordion title="Quelle TVA est appliquée sur les lignes ?">
    La TVA est lue depuis les paramètres de chaque produit dans Qwoty et convertie au format Pennylane (ex : 20% → `FR_200`). Si aucune TVA n'est configurée sur un produit, la ligne est créée en exonérée (`exempt`).
  </Accordion>

  <Accordion title="Mon devis a des produits one-off ET un abonnement. Que se passe-t-il ?">
    L'intégration crée les deux types de documents indépendamment : une facture (ou devis) pour la partie one-off, et un abonnement pour la partie récurrente.
  </Accordion>

  <Accordion title="L'envoi d'email ne fonctionne pas — pourquoi ?">
    Vérifiez que votre espace Pennylane a un template d'email configuré et que l'adresse email du contact principal est renseignée sur le devis Qwoty. L'envoi email ne fonctionne que sur les **factures finalisées** — si votre facture est en brouillon, l'email ne sera pas envoyé.
  </Accordion>

  <Accordion title="La demande SEPA n'est pas envoyée — pourquoi ?">
    Deux conditions sont nécessaires : (1) **Subscription payment method** doit être réglé sur **GoCardless direct debit**, et (2) votre compte Pennylane doit être connecté à GoCardless. Si l'une des deux conditions n'est pas remplie, la demande ne peut pas être envoyée.
  </Accordion>
</AccordionGroup>