Intégrer votre propre collecte de factures¶

Votre système de gestion sait produire des factures ; le module sait les certifier. Entre les deux, l'échange se fait par fichiers, sur un dépôt SFTP déclaré au niveau du modèle : votre programme y dépose ses documents et y relève les réponses. L'agent FNE de Minlessika est une implémentation prête à l'emploi de cet échange — rien ne vous oblige à l'utiliser, ce guide décrit le contrat pour que vous écriviez le vôtre.

Prérequis¶

Un modèle créé, avec ses deux flux — Facture et Avoir — et leur mappage
Le droit BACKUP.CONFIGURE, pour déclarer la collecte du modèle
Les accès du dépôt SFTP partagé : hôte, port, utilisateur, mot de passe
Quatre dossiers distincts sur ce dépôt : travail, succès, erreur et retour

Étapes¶

1. Déclarer la collecte du modèle¶

Ouvrez Paramètres › Modèles, ouvrez votre modèle, puis cliquez sur Collecte. La fenêtre Collecte du modèle demande le Canal — SFTP —, les accès, puis les quatre dossiers :

Champ	Rôle
SFTP dossier de travail	Où votre programme dépose ses documents
SFTP dossier succès	Où le module range les fichiers qu'il a lus
SFTP dossier erreur	Où il range ceux qu'il refuse, avec la raison
Dossier de retour	Où il écrit les verdicts et les documents certifiés

Cochez enfin Activer la collecte : sans cette case, rien n'est relevé.

Quatre dossiers, quatre chemins

Ne faites pas pointer deux de ces dossiers au même endroit. Le module relève les fichiers .xml, .csv et .json du dossier de travail : un dossier de retour confondu avec lui verrait ses verdicts relus comme des documents à importer.

2. Relever l'identifiant de flux et les codes de champs¶

Un fichier ne se nomme pas pour être reconnu : il porte, à l'intérieur, l'identifiant du flux auquel il appartient. Dans la section Fichiers modèles du modèle, téléchargez le fichier vide du flux Facture, puis celui du flux Avoir, au format que vous produirez — CSV, XML ou JSON.

Ce fichier est votre spécification : il porte déjà la marque du flux, un élément par champ nommé d'après son code, son type et, le cas échéant, son caractère obligatoire. Les codes des champs livrés avec chaque nature figurent aussi dans la référence.

3. Produire un fichier par document¶

Un fichier porte un document, et un seul : une facture, ou un avoir. En XML, la racine ModelImport porte l'identifiant du flux et un unique Invoice — ou CreditNote pour le flux avoir — dont chaque ligne est un Line :

<?xml version="1.0" encoding="UTF-8"?>
<ModelImport model="6f6b1f2e-2f1c-4a52-9e7b-3d2a5c8f1b04">
  <Invoice>
    <reference>FA-2026-000128</reference>
    <issueDate>2026-08-16</issueDate>
    <customerName>Société Kouassi</customerName>
    <Line>
      <lineNo>1</lineNo>
      <productName>Sac de ciment 50 kg</productName>
      <quantity>40</quantity>
      <unitPrice>4500</unitPrice>
    </Line>
  </Invoice>
</ModelImport>

En JSON, la clé model porte le même identifiant, l'objet invoice — ou creditNote — le document, et son tableau lines les lignes :

{
  "model": "6f6b1f2e-2f1c-4a52-9e7b-3d2a5c8f1b04",
  "invoice": {
    "reference": "FA-2026-000128",
    "issueDate": "2026-08-16",
    "lines": [{ "lineNo": 1, "quantity": 40 }]
  }
}

En CSV, la marque s'écrit en toute première ligne, avant l'en-tête des colonnes :

#model:6f6b1f2e-2f1c-4a52-9e7b-3d2a5c8f1b04

Écrivez les fichiers en UTF-8 et les dates en aaaa-mm-jj. Les formats attendus des nombres et des booléens valent ici comme ailleurs.

4. Nommer chaque fichier¶

Le nom annonce la nature du document et sert de clé à tout l'échange :

Document	Nom
Facture	`INV_{id}.xml`, `INV_{id}.csv` ou `INV_{id}.json`
Avoir	`CRN_{id}.xml`, `CRN_{id}.csv` ou `CRN_{id}.json`

Les préfixes s'écrivent en majuscules. {id} est un identifiant stable et unique de votre système — la clé de la facture dans votre base, par exemple —, sans horodatage ni compteur : le même document redéposé doit donner le même nom. Ce nom, extension retirée, est la clé de corrélation que chaque réponse reprendra.

5. Déposer sans laisser un fichier à moitié écrit¶

Le module ne prend un fichier que si sa taille n'a pas bougé entre deux relevés. C'est une précaution, pas une garantie : écrivez sous un nom temporaire, puis renommez une fois l'écriture terminée. Le renommage est atomique sur un serveur SFTP, et le fichier apparaît alors complet.

6. Déposer les factures avant leurs avoirs¶

Un avoir cite la facture qu'il corrige, et ne vaut qu'après elle. Le module passe les factures en premier à chaque relevé, mais il n'attend pas la certification de la facture pour prendre un avoir déposé en même temps.

L'ordre vous appartient

Ne déposez l'avoir qu'après avoir reçu, dans le dossier de retour, le verdict de certification de sa facture. Un avoir déposé plus tôt est pris pour ce qu'il est : un document qui cite une facture pas encore certifiée.

7. Consommer les retours¶

Une fois le document jugé, le module écrit dans le dossier de retour des fichiers portant le nom que vous aviez déposé. Un document accepté en produit deux :

Fichier	Contenu
`{nom}.json`	Le verdict : `status` à `ACCEPTED`, `reference` attribuée par la FNE, `url` de vérification, `date` de certification et `number`, la référence du document telle qu'elle figurait dans votre fichier
`{nom}.pdf`	Le document certifié

Un document refusé en produit un seul, {nom}.err.json : status à REJECTED, message disant la cause, code de la réponse, source du refus et date.

Relevez ces fichiers au rythme qui vous convient, et déplacez-les une fois traités. Indexez votre traitement sur le nom du fichier : le module peut réécrire un même verdict, à l'identique, et votre programme doit pouvoir le relire sans conséquence.

La collecte importe, elle ne certifie pas

Un document collecté rejoint l'écran Imports et suit ensuite le chemin habituel : voyez Transmettre un import à la FNE. Le retour n'est écrit qu'une fois le verdict de la FNE connu.

8. Traiter les fichiers refusés¶

Un fichier que le module ne sait pas attribuer part dans le dossier d'erreur, accompagné d'une note {nom}.metadata.json qui reprend le nom du fichier et la liste de ses erreurs, chacune avec sa raison. Y atterrissent le fichier illisible, celui dont l'extension n'est pas .xml, .csv ou .json, celui qui ne porte pas de marque de modèle, celui qui en porte une illisible ou inconnue, celui dont la marque désigne le flux d'un autre modèle, et celui qui ne porte pas exactement un document.

Un fichier bien formé mais dont le contenu est refusé — champ obligatoire vide, date mal écrite, règle de champ violée — suit un autre chemin : il rejoint le dossier de succès, puisqu'il a bien été lu, et le refus se lit dans le détail de l'import.

Bonnes pratiques¶

Un document par fichier. Si votre système exporte par lot, découpez avant de déposer.
Des noms déterministes. Ils sont votre clé de déduplication, celle du module et la vôtre.
Aucun renommage après coup. Le nom déposé est celui que porteront les réponses.
Pas de redépôt d'un document déjà passé. Le module refuse une référence déjà certifiée, ou déjà présente dans un import : le document n'est pas certifié deux fois, mais ce refus se lit dans l'écran Imports et non dans le dossier de retour.
Un redépôt de réparation reste possible. Après un {nom}.err.json, le document corrigé peut être redéposé sous le même nom et la même référence.

Et ensuite ?¶

Transmettre un import à la FNE, une fois les documents collectés
Rejouer une transmission en échec
Si vous préférez ne rien écrire, l'agent FNE de Minlessika tient déjà ce contrat : il extrait les documents de votre base, les dépose et rapatrie les réponses. Demandez-le à votre interlocuteur Minlessika, son manuel d'installation l'accompagne.

Changelog¶

1.0 (16 août 2026) : création du document.