🌐 Documentation de l'intégration par FTP

📖 Pour réaliser une intégration d'un outil partenaire vers Fygr "via FTP", le client doit déposer à intervalle régulier sur nos serveurs des fichiers avec un format spécifique. Nous recommandons un dépôt tous les jours, vers 20h (heure française). En amont de l'intégration, nous fournissons au client des identifiants "SFTP" afin de sécuriser le transfert des données.

Fichiers à préparer par le client

Format des fichiers

Format txt ou csv
Encoding: UTF-8
Séparateur : ;
En-tête / header : Oui, le nom des champs documentés ci-après

Nommage des fichiers

🧾 Receivable / 411 / Echéances clients : les fichiers doivent être nommés : receivable_%Y%m%d_%H%M%S

Exemple : un export d'échéances clients généré le 14 juillet 2025 à 14:33:23 (UTC) doit être nommé receivable_20250714_143323

🧾 Payable / 401 / Echéances fournisseurs : les fichiers doivent être nommés : payable_%Y%m%d_%H%M%S

Exemple : un export d'échéances fournisseurs généré le 14 juillet 2025 à 14:33:23 (UTC) doit être nommé payable_20250714_143323

📖 Selon votre cas d'usage, vous pouvez déposer des fichiers receivable, payable, ou bien les deux. Nous recommandons d'utiliser une unique date pour l'ensemble des fichiers d'un même envoi.

Champs à renseigner

Nom de la colonne	Format	Obligatoire	Commentaire
id	Char(100)	Oui	Identifiant technique de la facture dans l'outil partenaire. Il doit être unique pour chaque facture.
invoice_number	Char(100)	Oui	Numéro de la facture
issue_date	%Y-%m-%d	Oui	Date d'émission de la facture (ex : 2025-07-03, et non 20250703 ou 03/07/2025)
due_date	%Y-%m-%d	Oui	Date d'échéance
projection_date	%Y-%m-%d	Recommandé	= due_date si non renseigné
amount	Float	Recommandé	Montant HT (ex : 1103.12, et non 1 103,12€)
tax_amount	Float	Recommandé	Montant TVA
total_amount	Float	Oui	Montant TTC
currency_iso	Char(3)	Oui	Ex : EUR pour l'€, USD pour le $
outstanding_amount	Float	Oui	Montant restant dû (reste à payer)
status	StatusEnum	Oui	Les valeurs suivantes sont disponibles : paid ongoing (en cours, en retard, partiellement payée) cancelled → facture annulée, plus de paiement attendu. deleted → supprimée, cas marginal
description	Char(500)	Recommandé	Très souvent le nom du tiers (client / fournisseur)
commentary	Char(500)	Non	Commentaire supplémentaire
url	Char(2048)	Non	Permet d'ouvrir la facture depuis Fygr si elle est disponible via une URL publique.

Gestion des échéances multiples (optionnelle)

📖 De manière optionnelle, Fygr permet la gestion des règlements multiples. Dans ce cas, il est possible de nous fournir un troisième type de fichier dit de "règlements". Ce fichier est unique et peut contenir des règlements concernant à la fois les échéances clients et fournisseurs.

🧾 Les fichiers doivent être nommés : payment_%Y%m%d_%H%M%S

Champs à renseigner

Nom de la colonne	Format	Obligatoire	Commentaire
id	Char(100)	Oui	Identifiant technique du règlement dans l'outil partenaire
date	%Y-%m-%d	Oui	Date du règlement (potentiellement dans le futur)
amount	Float	Oui	Montant du règlement
invoice_id	Char(100)	Oui	Identifiant technique de la facture / échéance auquel ce règlement fait référence
document_type	DocumentEnum	Oui	payable receivable Sert à indiquer si le règlement fait référence à une échéance client ou fournisseur
currency_iso	Char(3)	Oui	Ex : EUR pour l'€, USD pour le $
status	StatusEnum	Oui	Les valeurs suivantes sont disponibles : paid ongoing (en cours, en retard, partiellement payée) cancelled → facture annulée, plus de paiement attendu. deleted → supprimée, cas marginal

Synchronisation des comptes et transactions bancaires (optionnelle)

⚠️ La synchronisation des soldes et des transactions bancaires via FTP est une option réservée à des cas d'usage spécifiques. Dans la très grande majorité des situations, nous recommandons fortement de privilégier la connexion via DSP2 ou EBICS, qui offrent une fiabilité supérieure, une mise à jour automatique et ne nécessitent aucun travail technique côté client.

Cette option par FTP n'a de sens que dans les cas suivants :

Comptes bancaires non accessibles via les agrégateurs DSP2 ni via EBICS (certaines banques étrangères, comptes de cantonnement, plateformes de paiement…)
Comptes internes ou comptes miroirs alimentés par un système comptable plutôt que par une banque
Contraintes réglementaires ou de sécurité interdisant les connexions DSP2 / EBICS

Si vous n'êtes pas certain de la pertinence de cette option pour votre cas d'usage, contactez votre interlocuteur Fygr avant toute mise en place.

📖 Deux fichiers complémentaires sont à fournir : un fichier décrivant la liste des comptes bancaires et leurs soldes, et un fichier décrivant la liste des transactions rattachées à ces comptes. Le format général (txt/csv, UTF-8, séparateur ;, en-tête) est identique à celui décrit plus haut. Les fichiers sont déposés sur le même répertoire SFTP que les fichiers d'échéances.

Nommage des fichiers

🧾 Comptes bancaires : les fichiers doivent être nommés : account_%Y%m%d_%H%M%S

Exemple : un export de comptes généré le 14 juillet 2025 à 14:33:23 (UTC) doit être nommé account_20250714_143323

🧾 Transactions bancaires : les fichiers doivent être nommés : bank_transaction_%Y%m%d_%H%M%S

Exemple : un export de transactions généré le 14 juillet 2025 à 14:33:23 (UTC) doit être nommé bank_transaction_20250714_143323

📖 Le fichier account doit être déposé avant ou en même temps que le fichier bank_transaction : Fygr rattache chaque transaction à un compte via son identifiant, et toute transaction faisant référence à un compte inconnu sera ignorée.

Fichier "account" — Champs à renseigner

Nom de la colonne	Format	Obligatoire	Commentaire
id	Char(100)	Oui	Identifiant technique du compte dans votre outil. Il doit être unique et stable dans le temps (utilisé comme clé de rapprochement à chaque synchronisation).
name	Char(100)	Oui	Libellé du compte tel qu'il sera affiché dans Fygr (ex : Compte courant BNP – Holding).
balance	Float	Oui	Solde du compte (ex : 125430.55, et non 125 430,55€). Un historique de solde est conservé à chaque mise à jour.
currency_iso	Char(3)	Oui	Ex : EUR pour l'€, USD pour le $
iban	Char(34)	Recommandé	IBAN du compte, sans espaces
last_update	%Y-%m-%d %H:%M:%S	Recommandé	Date et heure (UTC) à laquelle le solde a été constaté. Si non renseigné, Fygr utilise la date de traitement du fichier.

Fichier "bank_transaction" — Champs à renseigner

Nom de la colonne	Format	Obligatoire	Commentaire
id	Char(100)	Oui	Identifiant technique de la transaction dans votre outil. Il doit être unique et stable dans le temps. Sert de clé de rapprochement : si Fygr reçoit le même id qu'une transaction déjà importée, elle sera mise à jour (et non dupliquée).
account_id	Char(100)	Oui	Identifiant du compte auquel rattacher la transaction. Doit correspondre exactement à un id du fichier "account".
date	%Y-%m-%d	Oui	Date de valeur de l'opération (ex : 2025-07-03, et non 20250703 ou 03/07/2025)
trade_date	%Y-%m-%d	Recommandé	Date d'opération (si différente de la date de valeur)
label	Char(500)	Oui	Libellé de la transaction tel qu'il apparaîtra dans Fygr
amount	Float	Oui	Montant signé de la transaction : négatif pour un débit, positif pour un crédit, du point de vue du titulaire du compte (ex : -1103.12 pour un débit, 2500.00 pour un encaissement). Pas de séparateur de milliers.

📖 Format crédit / débit en colonnes séparées : si votre système exporte les crédits et les débits dans deux colonnes distinctes (l'une renseignée, l'autre vide), il n'est pas nécessaire de retraiter le fichier en amont. Indiquez-le à votre interlocuteur Fygr : nous appliquerons une transformation automatique pour reconstruire un amount signé conforme.

📖 Catégorisation et modifications manuelles : les transactions sont catégorisées automatiquement par les règles de catégorisation Fygr (et, à défaut, classées en "Non catégorisé"). Les modifications manuelles effectuées dans Fygr sur une transaction (catégorie, commentaire, justificatif…) sont préservées lors des synchronisations ultérieures.

📖 Prévisionnel compte par compte : si vous activez cette fonctionnalité, l'apparition d'un nouveau id dans le fichier "account" déclenchera une notification automatique au responsable du dossier afin de confirmer le mapping de ce nouveau compte. Aucune action n'est requise côté technique : il suffit de poursuivre l'envoi du fichier.