Alimenter le grand livre : export ERP, colonnes et appel API

Schéma stylisé : fichier CSV vers l’endpoint d’import, écritures rangées par entité et période.

Tout ERP capable d’exporter des lignes en table peut alimenter Ninon. Chaque ligne importée devient une écriture du grand livre rattachée à une entité du groupe et à une période : c’est la matière première du rapprochement intercompagnie. Pour enchaîner avec le lancement du rapprochement par API, reportez-vous au guide « Intégration REST » du même hub.

Parcours métier minimal

(1) Déclarer les entités juridiques du périmètre dans Ninon. (2) Ouvrir ou créer une session de rapprochement pour la période à traiter (souvent au format YYYY-MM, aligné sur votre calendrier de clôture). (3) Charger les écritures pertinentes via l’import CSV ou Excel décrit dans ce guide (parcours recommandé pour Sage 1000 et les autres ERP sans connecteur natif). (4) Lancer le rapprochement depuis le tableau de bord ou via le guide d’intégration REST une fois les lignes présentes.

Sens métier des champs

entityId : identifiant technique de l’entité dans Ninon (voir section suivante) — ce n’est pas automatiquement votre code société ERP exporté brut. period : période de rattachement de la ligne, en pratique alignée sur la session (ex. 2025-03). date : date de l’écriture ; utilisez de préférence une date-heure ISO 8601 pour éviter les ambiguïtés. amount : montant numérique signé (séparateur décimal point). currency : code devise de la ligne (ex. EUR). accountCode : compte ou segment tel que vous filtrez l’interco dans vos exports. description : libellé ou narration utile au rapprochement. reference : pièce, lettrage ou référence ERP (facultatif). source : libellé de traçabilité de la provenance ; si vous l’omettez, la valeur par défaut côté serveur est csv.

En-têtes du fichier CSV

La première ligne doit nommer les colonnes exactement comme suit (respect de la casse) : entityId, date, amount, currency, description, accountCode, period — tous obligatoires sur chaque ligne de données. Colonnes facultatives : reference ; source. Séparateur : virgule ou point-virgule ; la détection repose sur la ligne d’en-tête (si le point-virgule y apparaît sans virgule, le séparateur est le point-virgule). Encodage recommandé : UTF-8 ; un caractère BOM en début de fichier est toléré sur la première clé.

Obtenir les entityId (API)

Les lignes dont l’entityId ne correspond pas à une entité de votre organisation sont ignorées à l’insertion. Listez les entités via l’API documentée « entités » avec une session utilisateur autorisée (rôles admin, member ou viewer pour la lecture). Chaque élément renvoyé contient id (à recopier dans le CSV), name, country, currency. Création d’entité : API admin documentée (corps JSON name, country, currency) ; erpSystem et erpSecrets sont optionnels pour votre traçabilité interne.

Endpoint import CSV

Deux points d’entrée partagent les mêmes règles de validation. (1) Méthode POST, chemin /api/integrations/csv : corps JSON avec un champ csvText contenant l’intégralité du CSV en une chaîne (en-tête inclus). (2) Méthode POST, chemin /api/integrations/ledger-import : multipart/form-data avec un champ file — fichier .csv UTF-8 ou .xlsx (première feuille uniquement ; la ligne 1 reprend les mêmes en-têtes que ci-dessous). Taille max 10 Mo. Authentification : session connectée. Rôles : admin ou member (pas viewer). Lorsque l’application impose la facturation sur ce déploiement, un abonnement actif est requis (HTTP 402).

Réponse JSON

inserted : écritures créées. scanned : nombre de lignes de données dans le fichier (l’en-tête n’est pas compté dans ce total). parsedValid : lignes ayant passé la validation de champs. skippedWrongOrg / skippedBadDate : compteurs de rejets après validation. errors : tableau d’objets (line, message, code) pour les problèmes au parse ou à l’insertion ; errorsTruncated vaut true si plus de 80 erreurs ont été omises. Les lignes mal formées apparaissent dans errors avec un numéro de ligne lorsqu’il est connu.