🌐 Documentation de l'integrazione par FTP
📖 Pour réaliser une integrazione d'un outil partenaire vers Okimia "via FTP", le client doit déposer à intervalle régulier sur nostri serveurs des fichiers con un format spécifique. Nous recommandons un dépôt tous les jours, vers 20h (heure française). En amont de l'integrazione, nous fournissons au client des credenziali "SFTP" per 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 il tuo cas d'usage, puoi 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 fattura dans l'outil partenaire. Il doit être unique pour chaque fattura. |
invoice_number | Char(100) | Oui | Numéro de la fattura |
issue_date | %Y-%m-%d | Oui | Date d'émission de la fattura (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 → fattura 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'aprire la fattura depoi 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, è possibile 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 fattura / é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 → fattura annulée, plus de paiement attendu.
deleted → supprimée, cas marginal |
Synchronisation des comptes et transazioni bancaires (optionnelle)
⚠️ La sincronizzazione des soldes et des transazioni 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 connessione 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 bancas é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 banca
Contraintes réglementaires ou de sécurité interdisant les connessiones DSP2 / EBICS
Si tu n'êtes pas certain de la pertinence de cette option pour il tuo cas d'usage, contactez il tuo interlocuteur Okimia avant toute mise en place.
📖 Deux fichiers complémentaires sont à fournir : un fichier décrivant la liste des conti bancari et leurs soldes, et un fichier décrivant la liste des transazioni 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_transazione_%Y%m%d_%H%M%S
Exemple : un export de transazioni généré le 14 juillet 2025 à 14:33:23 (UTC) doit être nommé bank_transazione_20250714_143323
📖 Le fichier account doit être déposé avant ou en même temps que le fichier bank_transazione : Okimia rattache chaque transazione à un compte via son identifiant, et toute transazione 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 il tuo outil. Il doit être unique et stable dans le temps (utilisé comme clé de rapprochement à chaque sincronizzazione). |
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, senza 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_transazione" — Champs à renseigner
Nom de la colonne | Format | Obligatoire | Commentaire |
id | Char(100) | Oui | Identifiant technique de la transazione dans il tuo 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 transazione déjà importée, elle sera mise à jour (et non dupliquée). |
account_id | Char(100) | Oui | Identifiant du compte auquel rattacher la transazione. 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 transazione tel qu'il apparaîtra dans Okimia |
amount | Float | Oui | Montant signé de la transazione : 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 il tuo 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 à il tuo interlocuteur Okimia : nous appliquerons une transformation automatique pour reconstruire un amount signé conforme.
📖 Catégorisation et modifications manuelles : les transazioni sont catégorisées automaticamente 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 transazione (categoria, commentaire, justificatif…) sont préservées durantes sincronizzaziones ultérieures.
📖 Prévisionnel compte par compte : si tu activez cette fonctionnalité, l'apparition d'un nouveau id dans le fichier "account" déclenchera une notification automatique au responsable du dossier per confirmer le mapping de ce nouveau compte. Aucune action n'est requise côté technique : è sufficiente poursuivre l'envoi du fichier.