🌐 Documentation de l'Integration par FTP
📖 Pour réaliser une Integration d'un outil partenaire vers Okimia "via FTP", le client doit déposer à intervalle régulier sur unsere serveurs des fichiers mit un format spécifique. Nous recommandons un dépôt tous les jours, vers 20h (heure française). En amont de l'Integration, nous fournissons au client des Anmeldedaten "SFTP" um zu 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 Ihr cas d'usage, Sie können 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 Rechnung dans l'outil partenaire. Il doit être unique pour chaque Rechnung. |
invoice_number | Char(100) | Oui | Numéro de la Rechnung |
issue_date | %Y-%m-%d | Oui | Date d'émission de la Rechnung (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 → Rechnung 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'öffnen la Rechnung dedann Okimia si elle est disponible via une URL publique. |
Gestion des échéances multiples (optionnelle)
📖 De manière optionnelle, Okimia permet la gestion des règlements multiples. Dans ce cas, ist es möglich 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 Rechnung / é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 → Rechnung annulée, plus de paiement attendu.
deleted → supprimée, cas marginal |
Synchronisation des comptes et Transaktionen bancaires (optionnelle)
⚠️ La Synchronisierung des soldes et des Transaktionen 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 Verbindung 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 Banks é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 Bank
Contraintes réglementaires ou de sécurité interdisant les Verbindungs DSP2 / EBICS
Si Sie n'êtes pas certain de la pertinence de cette option pour Ihr cas d'usage, contactez Ihr interlocuteur Okimia avant toute mise en place.
📖 Deux fichiers complémentaires sont à fournir : un fichier décrivant la liste des Bankkonten et leurs soldes, et un fichier décrivant la liste des Transaktionen 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_Transaktion_%Y%m%d_%H%M%S
Exemple : un export de Transaktionen généré le 14 juillet 2025 à 14:33:23 (UTC) doit être nommé bank_Transaktion_20250714_143323
📖 Le fichier account doit être déposé avant ou en même temps que le fichier bank_Transaktion : Okimia rattache chaque Transaktion à un compte via son identifiant, et toute Transaktion 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 Ihr outil. Il doit être unique et stable dans le temps (utilisé comme clé de rapprochement à chaque Synchronisierung). |
name | Char(100) | Oui | Libellé du compte tel qu'il sera affiché dans Okimia (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, ohne espaces |
last_update | %Y-%m-%d %H:%M:%S | Recommandé | Date et heure (UTC) à laquelle le solde a été constaté. Si non renseigné, Okimia utilise la date de traitement du fichier. |
Fichier "bank_Transaktion" — Champs à renseigner
Nom de la colonne | Format | Obligatoire | Commentaire |
id | Char(100) | Oui | Identifiant technique de la Transaktion dans Ihr outil. Il doit être unique et stable dans le temps. Sert de clé de rapprochement : si Okimia reçoit le même id qu'une Transaktion déjà importée, elle sera mise à jour (et non dupliquée). |
account_id | Char(100) | Oui | Identifiant du compte auquel rattacher la Transaktion. 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 Transaktion tel qu'il apparaîtra dans Okimia |
amount | Float | Oui | Montant signé de la Transaktion : 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 Ihr 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 à Ihr interlocuteur Okimia : nous appliquerons une transformation automatique pour reconstruire un amount signé conforme.
📖 Catégorisation et modifications manuelles : les Transaktionen sont catégorisées automatisch par les règles de catégorisation Okimia (et, à défaut, classées en "Non catégorisé"). Les modifications manuelles effectuées dans Okimia sur une Transaktion (Kategorie, commentaire, justificatif…) sont préservées beis Synchronisierungs ultérieures.
📖 Prévisionnel compte par compte : si Sie activez cette fonctionnalité, l'apparition d'un nouveau id dans le fichier "account" déclenchera une notification automatique au responsable du dossier um zu confirmer le mapping de ce nouveau compte. Aucune action n'est requise côté technique : genügt es poursuivre l'envoi du fichier.