Le connecteur calcule 156 indicateurs répartis en 22 familles directement sur la base
Sage 100, au moment de l'appel : 18 familles de gestion commerciale et 4 familles comptables
(Comptes, Journaux, Trésorerie, Pilotage). Trois routes suffisent : le catalogue, l'exécution d'une
famille entière, l'exécution d'un indicateur précis. Le résultat est toujours indexé par
dossier Sage.
Les trois routes
Méthode et route
Rôle
Exécute du SQL
GET /v2/kpi
catalogue des familles et des codes disponibles
non
GET /v2/kpi/{type}
exécute tous les indicateurs d'une famille
oui
GET /v2/kpi/{type}/{code}
exécute un indicateur
oui
{type} est le code de famille (par exemple clients-ca), {code} celui de l'indicateur
(par exemple ca-n). Les deux doivent correspondre exactement aux valeurs du catalogue.
Les mêmes routes existent sans le préfixe /v2 dans la surface historique du connecteur
(GET /kpi, /kpi/{type}, /kpi/{type}/{code}). Elles renvoient la même charge utile mais sans
l'enveloppe v2, et sont obsolètes : elles portent les en-têtes Deprecation et Sunset, et
leur retrait est prévu au 1er janvier 2027. Utilisez /v2.
Ces trois routes sont des lectures au sens des droits d'accès par opération : si le droit de lecture
d'une route d'indicateurs est retiré à l'utilisateur dans l'outil de configuration (onglet API de
Filtres et accès), l'appel reçoit 403AUTH.FORBIDDEN.
Paramètres
Paramètre
Type
Défaut
Rôle
targets
chaîne
tous les dossiers autorisés
dossiers cibles, séparés par des virgules. Alias hérités acceptés : target_base, target, base, bases (séparateurs , ou \|)
limit
entier
0 (illimité)
nombre maximum de lignes, par dossier et par indicateur
offset
entier
0
décalage, à combiner avec limit
Rien d'autre n'est à fournir : les dates d'exercice, les filtres utilisateur et les seuils métier
sont appliqués côté connecteur.
Ce que le connecteur applique automatiquement
Élément
Valeur
Exercice N
dates d'exercice comptable courant du dossier Sage
Exercice N-1
exercice précédent (N moins un an)
Familles comptables
exercice qui contient la date du jour, arrêté au jour ; N-1 arrêté à la même date (voir Comptabilité)
Filtres utilisateur
filtres par dossier, profil, utilisateur, et restriction collaborateur
Seuil "dormant"
12 mois
Seuil "churn"
24 mois
Seuil "VIP"
50 000
Période de référence
365 jours
Un utilisateur ne voit donc que les données qui le concernent, sans que le client ait à le gérer.
Format des réponses
Sur /v2, la charge utile est emballée dans l'enveloppe habituelle : elle se trouve dans data
(voir Conventions). Sur ces routes, meta.dossiers n'est pas renseigné (null) :
les dossiers interrogés sont les clés de data.
GET /v2/kpi : data est un tableau de familles, chacune listant ses indicateurs. Pas
d'exécution SQL, pas de dimension dossier.
GET /v2/kpi/{type} : data est indexé par dossier, puis par code. La valeur de chaque
code est un tableau de lignes.
{"success":true,"data":{"DEMO":{"ca-n":[{"CA_N":1234567.89}],"ca-n1":[{"CA_N1":1100000.00}],"top10-clients":[{"CT_Num":"C0001","CT_Intitule":"Client de démonstration","CA":250000.00}]},"DEMO2":{}},"meta":{"correlationId":"…","durationMs":840,"dossiers":null}}
GET /v2/kpi/{type}/{code} : data est indexé par dossier, la valeur étant directement le
tableau de lignes.
Un résultat est toujours un tableau d'objets : une entrée par ligne, les clés étant les noms
de colonnes.
Un indicateur scalaire (ca-n par exemple) renvoie un tableau d'une seule ligne : lisez
l'indice [0].
Un indicateur sans donnée renvoie [].
Les dossiers sans données ou non autorisés sont omis de la réponse.
Les dates "vides" de Sage (1753-01-01, 1900-01-01) peuvent apparaître : traitez-les côté
client si besoin.
Si un indicateur échoue sur un dossier, il renvoie [] pour ce dossier ; l'appel entier n'échoue
pas.
Ne jamais supposer un seul dossier
Toute réponse d'exécution est indexée par nom de dossier au premier niveau, même quand un seul
dossier est autorisé. C'est l'erreur d'intégration la plus fréquente.
Catalogue des 156 indicateurs
22 familles : 18 de gestion commerciale, calculées sur les documents de vente et d'achat, et
4 de comptabilité, calculées sur les écritures générales. La colonne Colonnes retournées liste les champs de chaque ligne renvoyée.
Clients
clients-activite : Activité commerciale
Code
Libellé
Colonnes retournées
nb-clients-total
Nombre total de clients (actifs + en sommeil)
NbClientsTotal
nb-clients-actifs-n
Nombre de clients actifs sur l'exercice
NbClientsActifsN
clients-inactifs
Clients inactifs (sommeil ou sans facture sur l'exercice)
ClientsEnSommeil, ClientsSansFactureN
nouveaux-clients-n
Nouveaux clients de l'exercice
NbNouveauxClientsN
clients-churn
Clients perdus : actifs en N-1 mais sans facture en N
NbClientsChurn
taux-churn
Taux de churn : churn / clients actifs N-1
TauxChurn
taux-reactivation
Taux de réactivation : actifs en N mais inactifs en N-1
NbClientsReactives, TauxReactivation
nb-moyen-commandes
Nombre moyen de commandes par client sur l'exercice
NbMoyenCommandesParClient
frequence-achat
Fréquence d'achat (jours moyens entre commandes par client)
JoursMoyensEntreCmd
panier-moyen
Panier moyen HT (montant moyen d'une facture de vente)
PanierMoyenHT
delai-moyen-commandes
Délai moyen entre commandes (vue globale)
DelaiMoyenEntreCmd
clients-ca : Chiffre d'affaires et rentabilité
Code
Libellé
Colonnes retournées
ca-total
CA total clients (toutes périodes, factures - avoirs)
CA_Total_Clients
ca-n
CA exercice N (factures - avoirs)
CA_N
ca-n1
CA exercice N-1
CA_N1
evolution-ca
Évolution du CA en %
CA_N, CA_N1, EvolutionPct
ca-moyen-client
CA moyen par client sur l'exercice
CA_MoyenParClient
top10-clients
Top 10 clients (CA décroissant sur l'exercice)
CT_Num, CT_Intitule, CA
pareto-top20
Part du CA des 20 % meilleurs clients
CA_Top20Pct, CA_Total, PartTop20Pct
marge-brute
Marge brute HT sur l'exercice
MargeBrute
marge-moyenne-client
Marge moyenne par client
MargeMoyenneParClient
rentabilite-client
Rentabilité par client (CA, marge, taux de marge)
CT_Num, CT_Intitule, CA_HT, Marge, TauxMarge
clients-non-rentables
Clients non rentables (marge négative ou nulle)
CT_Num, CT_Intitule, Marge
clients-risque : Risque et finance
Code
Libellé
Colonnes retournées
nb-clients-retard
Nombre de clients en retard de paiement
NbClientsEnRetard
montant-retards
Montant total des retards
MontantRetards
dso
DSO (délai moyen d'encaissement)
DSO_Jours
encours-client
Encours client (factures non réglées, par client)
CT_Num, CT_Intitule, Encours
impayes
Impayés (échéances avec date d'impayé renseignée)
NbImpayes, MontantImpayes
taux-impayes
Taux d'impayés : montant impayés / CA TTC de l'exercice
TauxImpayes
clients-bloques
Clients bloqués (sommeil ou sous surveillance)
CT_Num, CT_Intitule, CT_Sommeil, CT_Surveillance
risque-client
Risque client (plafond d'encours face à l'encours réel)
Détection de baisse d'activité (fréquence en chute de plus de 50 %)
CT_Num, CT_Intitule, Freq_N, Freq_N1, Variation
Comptabilité
Quatre familles, une par rubrique de la partie comptable de l'application (Comptes, Journaux,
Trésorerie, Pilotage). Elles sont calculées sur les écritures générales de Sage 100, et non sur
les documents de vente et d'achat comme les familles précédentes.
Conventions des familles comptables
Exercice N : l'exercice du dossier qui contient la date du jour (à défaut, le dernier
exercice), arrêté au jour. N-1 : l'exercice précédent, arrêté à la même date un an plus
tôt. Les comparaisons N / N-1 sont donc faites "à date".
Date d'une écriture : sa date comptable. Écritures retenues : norme nationale, hors
journaux de situation.
Soldes (bilan, trésorerie, pièces non lettrées) : depuis les derniers à-nouveaux générés.
Si l'exercice précédent n'est pas clôturé, ses écritures sont reprises et son résultat compte
dans les capitaux propres.
Rubriques : comptes du plan comptable général (70 chiffre d'affaires, 60 achats, 64
personnel, 40 fournisseurs, 41 clients, 50 à 54 trésorerie, 519 concours bancaires...).
Clients et fournisseurs : nature du compte collectif. Pièce ouverte : ligne non
lettrée ; son échéance, à défaut sa date comptable.
Montants dans la devise du dossier, taux en fraction (0,25 = 25 %), délais en jours.
Filtres utilisateur appliqués aux écritures et au journal ; les indicateurs de tiers
appliquent aussi les filtres et la restriction collaborateur du tiers, comme la balance âgée.
compta-comptes : Comptes
Code
Libellé
Colonnes retournées
encours-clients
Encours clients : factures non lettrées (nombre, montant, moyenne) et solde net non lettré
DSO = solde clients / ventes TTC des journaux de vente (avoirs déduits) x jours écoulés de
l'exercice ; rotation = ventes TTC / solde clients. Même calcul côté fournisseurs avec les achats
TTC des journaux d'achat.
Les codes des soldes intermédiaires de gestion sont CA, MARGE_COMMERCIALE, PRODUCTION,
VALEUR_AJOUTEE, EBE, RESULTAT_EXPLOITATION, RESULTAT_FINANCIER, RESULTAT_COURANT,
RESULTAT_EXCEPTIONNEL, PARTICIPATION_IMPOTS et RESULTAT_NET. Au bilan, les comptes de tiers,
de TVA et de trésorerie sont classés à l'actif ou au passif selon le signe de leur solde, compte par
compte ; les emprunts (16, 17) ne distinguent pas la part à moins d'un an. EcartActifPassif vaut 0
sur un dossier équilibré.
Exemples
HOTE="https://<votre-connecteur>"# Catalogue des familles et des codescurl-s"$HOTE/v2/kpi"-H"Authorization: Bearer $JETON"# Toute une famille, sur un dossiercurl-s"$HOTE/v2/kpi/clients-ca?targets=DEMO"-H"Authorization: Bearer $JETON"# Un indicateur comptable : délai de règlement clientscurl-s"$HOTE/v2/kpi/compta-comptes/dso-comptable?targets=DEMO"-H"Authorization: Bearer $JETON"# Un indicateur, limité à 10 lignescurl-s"$HOTE/v2/kpi/clients-ca/top10-clients?targets=DEMO&limit=10"\-H"Authorization: Bearer $JETON"
defindicateur(client,famille,code=None,dossiers=None,limite=None):"""Renvoie { "<dossier>": [...lignes] }, ou { "<dossier>": { "<code>": [...] } } quand le code est omis."""chemin=f"/v2/kpi/{famille}"+(f"/{code}"ifcodeelse"")params={}ifdossiers:params["targets"]=",".join(dossiers)iflimite:params["limit"]=limitereturnclient.appeler("GET",chemin,params=params)# Instantané de direction sur le dossier de démonstrationpar_dossier=indicateur(client,"dashboard-direction","snapshot-direction",["DEMO"])lignes=par_dossier.get("DEMO",[])ca_annee=lignes[0]["CA_YTD"]ifligneselse0
GET /v2/kpi/{type} exécute toutes les requêtes de la famille, sur chaque dossier
autorisé. Pour un affichage réactif, préférez des appels ciblés GET /v2/kpi/{type}/{code} et
utilisez limit. Les indicateurs de type liste (top, ABC, encours par tiers) peuvent renvoyer
beaucoup de lignes.
Indicateurs approchés : certains indicateurs fournisseurs et articles (qualité, conformité,
retours, litiges, retour SAV) n'existent pas nativement dans Sage 100. Ce sont des
approximations construites à partir des dates de livraison, des écarts commande / livraison et
des avoirs. Les libellés le signalent.
Seuils des scores composites (santé, couleur du DSO, score fournisseur) : les bornes sont des
valeurs de départ, à calibrer selon le métier.
score-sante et indicateur-couleur-dso sont des indicateurs de direction globaux : ils ne
sont pas filtrés par utilisateur.
Indicateurs comptables et commerciaux : compta-comptes/dso-comptable (écritures générales) et
clients-risque/dso (documents de vente) ne mesurent pas la même chose et peuvent différer ; de
même pour les délais fournisseurs. Les rubriques comptables suivent les comptes du plan comptable
général : un plan très personnalisé peut fausser les ratios.