// API

Envoyer des factures dans Pennylane depuis un script : authentification, premier appel, doublons

Votre application facture déjà : une boutique, un outil de réservation, un SaaS maison. Le cabinet comptable, lui, travaille dans Pennylane et attend les factures clients là-bas, pas dans un export CSV envoyé en fin de mois. Pousser chaque facture par l’API est la solution propre, à condition de régler trois questions dès le départ : quel jeton utiliser, à quoi ressemble un appel valide, et comment empêcher qu’une même vente arrive deux fois quand le script relance un envoi. Ce tutoriel répond aux trois en Python, avec la bibliothèque requests, en s’appuyant sur la documentation publique de l’API v2 de Pennylane.

Avant le premier appel : jeton, droits et bac à sable

Pour un script interne à une entreprise, la documentation de Pennylane prévoit un jeton d’API Company. Il se génère dans les paramètres de la société, onglet « Développeurs » (Settings > Connectivity > Developers dans la documentation en anglais). Trois conditions à connaître avant de chercher cet onglet :

  • l’abonnement doit être au moins de niveau Essential ; sur une formule Starter, l’onglet n’apparaît pas ;
  • seuls les rôles d’administration (dirigeant, comptable interne ou externe) y ont accès ;
  • le jeton ne s’affiche qu’une fois. Pennylane ne le conserve pas : perdu, il faut en générer un autre.

À la création, vous choisissez lecture seule ou lecture et écriture, puis une durée de validité (1, 6 ou 12 mois, ou illimitée). Pour créer des factures, il faut l’écriture. Créez un jeton par usage, nommé d’après ce qu’il fait (« export boutique », par exemple), pour pouvoir le révoquer sans casser le reste.

Ne testez pas sur le compte réel. Pennylane permet de créer un bac à sable depuis le profil (« Test environment », puis « Create my sandbox ») : un compte séparé où les factures de test ne polluent pas la comptabilité. Paramétrez-y la facturation (coordonnées, numérotation), sans quoi les créations échoueront.

Le jeton se range dans une variable d’environnement, jamais dans le dépôt :

export PENNYLANE_TOKEN="..."

Premier appel : vérifier que le jeton fonctionne

Toutes les routes de l’API v2 partent de https://app.pennylane.com/api/external/v2. Le point de contrôle le plus simple est /me, qui renvoie l’utilisateur et la société liés au jeton :

import os
import requests

BASE = "https://app.pennylane.com/api/external/v2"
session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {os.environ['PENNYLANE_TOKEN']}",
    "Accept": "application/json",
})

r = session.get(f"{BASE}/me", timeout=15)
r.raise_for_status()
print(r.json()["company"]["name"])

Si le nom affiché est celui du bac à sable, vous êtes au bon endroit. Un 401 signale un jeton absent ou expiré, un 403 un jeton valide mais sans le droit demandé (souvent un jeton en lecture seule). Si Session, les en-têtes ou raise_for_status() ne vous sont pas familiers, notre guide des requêtes HTTP en Python les reprend pas à pas.

Créer une facture client

Une facture se rattache à un client qui existe déjà dans Pennylane, désigné par son customer_id. La documentation recommande de chercher d’abord le client par sa external_reference, puis de le créer s’il est absent ; le même principe vaudra pour les factures, plus bas. Une fois l’identifiant en main :

def creer_facture(customer_id: int, commande: dict) -> dict:
    payload = {
        "customer_id": customer_id,
        "date": commande["date"],            # "2026-11-19"
        "deadline": commande["echeance"],
        "external_reference": f"BOUTIQUE-{commande['numero']}",
        "draft": True,
        "invoice_lines": [
            {
                "label": ligne["libelle"],
                "quantity": ligne["quantite"],
                "unit": "piece",
                "raw_currency_unit_price": ligne["prix_ht"],  # "49.90", une chaîne
                "vat_rate": "FR_200",
            }
            for ligne in commande["lignes"]
        ],
    }
    r = session.post(f"{BASE}/customer_invoices", json=payload, timeout=30)
    r.raise_for_status()
    return r.json()

Deux détails font perdre du temps. D’abord, les montants s’envoient en chaînes ("49.90"), pas en nombres : un flottant renvoie une erreur 400. Ensuite, le taux de TVA passe par un code (FR_200 pour 20 % en France), dont la liste complète figure dans la référence de l’endpoint.

Le champ draft mérite réflexion. Sans lui, la facture est finalisée immédiatement, et une facture finalisée ne se supprime pas : pour l’annuler, il faut un avoir. Pendant la mise au point, gardez "draft": True et finalisez à la main dans l’interface.

Doublons : faire de la référence externe une clé

C’est le point qui casse le plus de scripts. La requête part, Pennylane crée la facture, mais la réponse se perd (coupure réseau, délai dépassé). Le script considère l’envoi comme raté et recommence : vous avez deux factures pour une vente. Or la documentation est claire sur ce point : l’idempotence n’est pas assurée par l’API, sauf pour l’import de factures fournisseurs.

La parade tient en une règle : chaque facture porte une external_reference dérivée de votre propre identifiant (le numéro de commande), et le script vérifie qu’elle n’existe pas avant de créer. La liste des factures accepte justement un filtre d’égalité sur ce champ :

import json

def facture_existe(reference: str) -> bool:
    filtre = json.dumps([{"field": "external_reference", "operator": "eq", "value": reference}])
    r = session.get(f"{BASE}/customer_invoices", params={"filter": filtre}, timeout=15)
    r.raise_for_status()
    return len(r.json()["items"]) > 0

ref = f"BOUTIQUE-{commande['numero']}"
if not facture_existe(ref):
    creer_facture(customer_id, commande)

Ce contrôle ne couvre pas deux processus qui envoient la même commande à la même seconde : si votre script peut tourner en parallèle, ajoutez un verrou de votre côté (une ligne en base, un fichier). C’est le même raisonnement que pour toute synchronisation, détaillé dans notre guide des API REST.

Ce script convient bien à un outil maison qui émet peu de factures. Pour une boutique WooCommerce, Shopify ou PrestaShop, Pennylane propose aussi des connecteurs prêts à l’emploi, qui ne produisent pas tous le même résultat (facture par commande ou écritures regroupées) ; avant d’écrire votre propre flux, la page de Newp consacrée à l’API Pennylane et aux connecteurs e-commerce aide à voir ce que chaque option fait réellement arriver dans la comptabilité.

Limite de débit et réessais

L’API autorise 25 requêtes toutes les 5 secondes par jeton, bac à sable compris. Au-delà, elle répond 429 avec un en-tête retry-after qui donne le nombre de secondes à attendre. Les réponses normales portent aussi ratelimit-remaining, utile pour ralentir avant d’être bloqué.

La règle de la documentation : ne réessayer que sur 429 (et sur les 5xx passagers), jamais sur une erreur de validation ou de droits, qui échouera de la même façon à chaque tentative.

import time

def appel(methode, url, **kwargs):
    for tentative in range(5):
        r = session.request(methode, url, timeout=30, **kwargs)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("retry-after", "2")))
            continue
        if r.status_code >= 500:
            time.sleep(2 ** tentative)
            continue
        return r
    r.raise_for_status()
    return r

Combiné au contrôle de la référence externe, ce réessai devient sans danger : si une création a réussi sans que vous le sachiez, la vérification suivante la retrouvera.

Ce qu’il reste à surveiller en production

Un 422 est la réponse la plus fréquente une fois l’authentification réglée : totaux incohérents, code de TVA inconnu, champ métier manquant, référence en double. Le corps de la réponse contient un objet details qui désigne le champ en cause ; journalisez-le tel quel avec le numéro de commande, sinon le diagnostic se fera à l’aveugle.

Pensez enfin à l’expiration du jeton si vous avez choisi une durée limitée : notez la date quelque part, et faites échouer le script bruyamment (une alerte, un mail) plutôt que silencieusement. Une facture qui n’arrive pas dans Pennylane ne se remarque souvent qu’à la clôture du mois.

Source : documentation de l’API de Pennylane, « Create a Customer Invoice via API », et page « Rate Limiting in API v2 », consultées le 19 novembre 2026.