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

Sage — organisations et écritures GraphQL

Référence Sage Active Public API V2 : organisations, comptes, écritures, paiements, analytique et documents.

Choisir la gamme avant de coder

« Sage » recouvre plusieurs produits. Cette fiche détaille Sage Active Public API V2, disponible notamment pour le marché français. Sage Accounting REST et Sage 100 ont des contrats d’intégration distincts : l’identification du produit, du pays et de la version fait partie des prérequis du raccordement. Les opérations ci-dessous sont celles de Sage Active. Démarrage Sage Active, portail Sage Accounting.

Accès et périmètre d’organisation

Sage Active utilise GraphQL et OAuth 2.0. Pour la collecte, demander le scope de lecture RDSA ; offline_access concerne le renouvellement hors session. Le scope d’écriture WDSA n’est pas nécessaire à cette collecte. Les requêtes portent le jeton Bearer et la clé d’application x-api-key. Authentification web server.

Le header X-OrganizationId sélectionne l’organisation ; X-TenantId est déprécié. Conserver une correspondance explicite entre organisation Sage et dossier HOLCO. Une organisation ne doit jamais être choisie sur la seule similitude du nom commercial. Écritures et headers, bonnes pratiques.

Ressources à collecter

Organisations et périmètre légal

La ressource organisations fournit le contexte dans lequel sélectionner les données. Le modèle HOLCO vise l’identifiant source, la dénomination, le pays et les identifiants légaux lorsqu’ils sont exposés. Garder les informations absentes à null et vérifier les permissions pour chaque organisation sélectionnée. Organisations.

Plan comptable

La requête accountingAccounts expose les comptes ; id, code et description permettent de constituer le référentiel. Le contrat HOLCO conserve le code d’origine et la relation aux sous-comptes, sans convertir le numéro en entier. Une modification du libellé doit enrichir l’historique sans changer l’identité du compte. Comptes.

Écritures, lignes et règlements

Les requêtes accountingEntries, accountingEntryLines, accountingEntryPayments et accountingEntryDimensionTags structurent le détail. Sur l’en-tête : id, date, documentDate, accountingExerciseId, journalTypeId, currencyId, documentNumber, isClosed. Sur la ligne : accountingEntryId, subAccountId, debitAmount, creditAmount, puis les relations tiers, paiement et dimensions. Garder séparées date comptable et date de pièce ; relier une ligne à son écriture avant agrégation. Schéma comptable.

Factures d’achat

Les factures d’achat complètent l’écriture avec le contexte fournisseur et la ventilation du document. Le contrat HOLCO vise en-tête, lignes, échéances, taxes et relations comptables lorsque ces éléments figurent au schéma de l’organisation. Une facture et son règlement restent deux objets reliés ; le solde ouvert ne se déduit pas du seul total facturé. Purchase invoices.

Banques et pièces

Le référentiel bancaire décrit les banques ; ne pas assimiler une fiche banque à un flux bancaire ou à un solde temps réel. Les opérations et rapprochements doivent être qualifiés par leur ressource dédiée. Banks.

La ressource fichiers permet la récupération des métadonnées et relations documentaires prévues par l’API. Le contrat HOLCO vise identifiant, type, nom et rattachement à la pièce comptable, puis empreinte du contenu après téléchargement autorisé. Le stockage d’un fichier et son indexation pour une recherche sont deux étapes distinctes. Files.

GraphQL : sélectionner puis paginer

Limiter les champs à ceux nécessaires au traitement. Pour chaque collection, parcourir les edges et suivre pageInfo.endCursor tant que hasNextPage vaut true. La pagination documentée est de 20 résultats par défaut et de 500 au maximum. Une sous-collection doit elle aussi être examinée pour éviter une troncature silencieuse. Pagination.

query {
  accountingAccounts(first: 50, order: { code: ASC }) {
    edges {
      node { id code description }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Pour la page suivante, ajouter after avec le curseur reçu ; conserver les mêmes filtres et le même ordre. Le point d’entrée GraphQL est celui de l’environnement déclaré pour votre application Sage. Cet exemple source n’est pas une méthode MCP. Exemples de requêtes officiels.

Agrégations et contrôles

Les agrégations s’appliquent à l’ensemble filtré avant la pagination des groupes. Une limite de groupes n’est donc pas une limite du nombre de lignes prises en compte. Le catalogue d’agrégations permet de découvrir les opérations prises en charge ; il ne faut pas inventer une opération de balance à partir d’un nom métier. Agrégations, catalogue.

Contrat HOLCO de synchronisation

L’adaptateur cible commence par les organisations et référentiels, puis collecte une période comptable explicite. Il conserve les dates de création et de modification lorsqu’elles existent. Un champ de modification présent dans la réponse ne prouve pas qu’un filtre incrémental est disponible : vérifier le schéma avant de l’utiliser. À défaut, recharger des fenêtres bornées et dédupliquer par organisation, ressource et identifiant.

Une réponse GraphQL peut comporter des erreurs et des données partielles : examiner les deux, conserver le chemin du champ en erreur et marquer le lot incomplet. Après expiration du jeton, renouveler selon OAuth, avec un nombre borné de tentatives. Aucun curseur ne doit être partagé entre organisations.

Recette technique

Le contrat de recette HOLCO exige un dossier avec plus de 500 comptes ou lignes, une pièce multiligne, une ventilation analytique, une facture partiellement réglée et une organisation interdite. Contrôler l’équilibre sur des montants décimaux exacts, les relations vers les sous-comptes, la distinction devise de pièce/devise comptable et la présence de toutes les pages. Un contrôle de balance n’est déclaré concluant que si le périmètre est complet.