← Toutes les APIFiche Markdown ↓

Références consultées le 9 septembre 2026

Référence éditeur et spécification de collecte. Les sections « contrat HOLCO » définissent le traitement cible et sa recette ; les outils du compte se découvrent via tools/list.

HOLCO MCP · Documentation développeur

Pennylane — comptabilité et révision

Écritures, lignes, balances, lettrage, factures et flux de changement : le contrat de collecte pour construire une analyse comptable traçable.

Périmètre et authentification

La fiche couvre la Company API v2. La Firm API, destinée au périmètre cabinet et à la découverte des dossiers, possède un contrat distinct : ne pas réutiliser implicitement un jeton société sur un appel cabinet. La base des exemples Company est https://app.pennylane.com/api/external/v2. Le dossier HOLCO doit être associé explicitement à l’entreprise autorisée.

Les appels utilisent Authorization: Bearer <jeton>. Définir les scopes à partir des objets lus : trial_balance:readonly, ledger_entries:readonly, ledger_accounts:readonly, journals:readonly, fiscal_years:readonly, transactions:readonly, customer_invoices:readonly et supplier_invoices:readonly. Les exports ont des scopes propres, notamment exports:fec. Un scope ajouté à une application OAuth peut nécessiter un nouveau consentement. Scopes Company v2.

Objets et relations à récupérer

Balance générale et auxiliaire

GET /trial_balance : définir period_start et period_end, puis choisir le périmètre auxiliaire avec is_auxiliary. Récupérer l’identification des comptes et les montants de la période pour le cadrage. Pagination par cursor, limit de 1 à 1 000, 20 par défaut. Une page ne représente pas nécessairement toute la balance. Référence balance.

Écritures et grand livre

GET /ledger_entries et GET /ledger_entries/{id} permettent de parcourir les en-têtes. Conserver l’identifiant, la date comptable lorsqu’elle existe, la relation au journal et les références de pièce. Les filtres documentés portent notamment sur id, date et journal_id. Écritures.

GET /ledger_entry_lines porte le détail nécessaire au grand livre : rattachement à l’écriture, compte, montants et libellés selon le schéma retourné. Les filtres incluent ledger_account_id, journal_id et date ; le plafond est de 100 lignes par page. Le contrat HOLCO relie chaque ligne à son en-tête et garde les identifiants sources. Lignes d’écriture.

Lettrage et analytique

Les relations lettered_ledger_entry_lines identifient les contreparties lettrées. Interroger les lignes associées avant de calculer un résiduel ou une ancienneté de dette : un groupe peut couvrir plusieurs factures et règlements. Les affectations analytiques doivent rester liées à la ligne source ; leur évolution dispose d’un journal distinct. Évolution du lettrage, changements analytiques.

Factures clients et avoirs

GET /customer_invoices permet de sélectionner les factures et avoirs par date, client, numéro, référence externe ou catégorie. Conserver séparément les indicateurs draft et credit_note. Les factures ne doivent pas être additionnées aux écritures qui les comptabilisent : ce sont des vues reliées d’un même événement économique. Les lignes embarquées via include sont expérimentales ; un traitement durable doit prévoir leur récupération indépendante. Factures clients.

Fournisseurs, achats, banque et référentiels

GET /supplier_invoices fournit le périmètre achats ; le contrat de collecte vise le fournisseur, les dates, les montants, les échéances et les références de justificatif présents dans la réponse. Les droits et les champs doivent être contrôlés sur l’objet renvoyé. Factures fournisseurs.

GET /transactions apporte les opérations bancaires à rapprocher des pièces et écritures. Conserver leur identité et leur rattachement au compte ; une transaction bancaire n’est pas en soi une écriture comptable équilibrée. Transactions.

GET /ledger_accounts sert de référentiel des comptes. Le numéro reste une chaîne, y compris lorsqu’il ne contient que des chiffres ; garder la relation entre compte général et compte auxiliaire lorsqu’elle est renseignée. Plan de comptes.

Synchronisation initiale et incrémentale

  1. Fixer entreprise, exercices, période et inclusion des brouillons ; enregistrer ce périmètre avec le lot.
  2. Charger les référentiels puis toutes les pages d’écritures et de lignes. Dédupliquer sur entreprise + type de ressource + identifiant.
  3. Lire GET /changelogs/ledger_entry_lines pour les changements : start_date au format RFC 3339 ou cursor, jamais les deux ensemble. Le journal conserve quatre semaines ; une reprise au-delà de cette fenêtre exige un rechargement de référence. Les événements sont ordonnés par processed_at.
  4. Traiter aussi les changements de catégories. Une relation de ligne peut être nulle après suppression : ne pas déréférencer aveuglément le lien.
  5. Avancer le point de reprise seulement après validation et écriture durable du lot. Rejouer un lot ne doit pas doubler les montants.

Les étapes de persistance et de rapprochement décrivent le contrat de traitement HOLCO cible. Les contraintes du journal proviennent des références changements de lignes et changements de catégories.

Compatibilité 2026

Utiliser has_more et next_cursor, sans dépendre des anciens attributs de page. Ne pas construire un incrémental sur updated_at de /ledger_entries : les filtres concernés ont été retirés. Les relations journal et compte deviennent des objets imbriqués ; les identifiants doivent être traités comme opaques. Les brouillons et exercices clos ne sont plus exclus par défaut, et une date peut être nulle. Guide des changements 2026.

Exemple de lecture éditeur

GET /api/external/v2/trial_balance?period_start=2026-01-01&period_end=2026-08-31&limit=100 HTTP/1.1
Host: app.pennylane.com
Authorization: Bearer <JETON_PENNYLANE>
Accept: application/json

Cet appel illustre la requête source ; il ne s’envoie pas à l’URL MCP HOLCO. Parcourir ensuite le curseur retourné. Ne jamais placer un jeton réel dans un prompt, une URL ou un journal applicatif.

Recette du contrat HOLCO

Vérifier une période vide, plusieurs pages, des écritures sans date, un avoir, un lettrage partiel, une suppression et une reprise dépassant quatre semaines. Comparer la somme débit/crédit à la balance sur un périmètre identique. Produire une anomalie explicite pour toute relation introuvable, et conserver le décompte des lignes rejetées. La synthèse doit mentionner la période et la date de collecte.