🌐 Documentation de l'integración par FTP
📖 Pour réaliser une integración d'un outil partenaire vers Okimia "via FTP", le client doit déposer à intervalle régulier sur nuestros 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'integración, nous fournissons au client des credenciales "SFTP" para 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 su cas d'usage, puede 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 factura dans l'outil partenaire. Il doit être unique pour chaque factura. |
invoice_number | Char(100) | Oui | Numéro de la factura |
issue_date | %Y-%m-%d | Oui | Date d'émission de la factura (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 → factura 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'abrir la factura deluego 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, es posible 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 factura / é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 → factura annulée, plus de paiement attendu.
deleted → supprimée, cas marginal |
Synchronisation des comptes et transacciones bancaires (optionnelle)
⚠️ La sincronización des soldes et des transacciones 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 conexión 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 bancos é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 banco
Contraintes réglementaires ou de sécurité interdisant les conexións DSP2 / EBICS
Si usted n'êtes pas certain de la pertinence de cette option pour su cas d'usage, contactez su interlocuteur Okimia avant toute mise en place.
📖 Deux fichiers complémentaires sont à fournir : un fichier décrivant la liste des cuentas bancarias et leurs soldes, et un fichier décrivant la liste des transacciones 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_transacción_%Y%m%d_%H%M%S
Exemple : un export de transacciones généré le 14 juillet 2025 à 14:33:23 (UTC) doit être nommé bank_transacción_20250714_143323
📖 Le fichier account doit être déposé avant ou en même temps que le fichier bank_transacción : Okimia rattache chaque transacción à un compte via son identifiant, et toute transacción 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 su outil. Il doit être unique et stable dans le temps (utilisé comme clé de rapprochement à chaque sincronización). |
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, sin 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_transacción" — Champs à renseigner
Nom de la colonne | Format | Obligatoire | Commentaire |
id | Char(100) | Oui | Identifiant technique de la transacción dans su 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 transacción déjà importée, elle sera mise à jour (et non dupliquée). |
account_id | Char(100) | Oui | Identifiant du compte auquel rattacher la transacción. 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 transacción tel qu'il apparaîtra dans Okimia |
amount | Float | Oui | Montant signé de la transacción : 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 su 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 à su interlocuteur Okimia : nous appliquerons une transformation automatique pour reconstruire un amount signé conforme.
📖 Catégorisation et modifications manuelles : les transacciones sont catégorisées automáticamente 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 transacción (categoría, commentaire, justificatif…) sont préservées durantes sincronizacións ultérieures.
📖 Prévisionnel compte par compte : si usted activez cette fonctionnalité, l'apparition d'un nouveau id dans le fichier "account" déclenchera une notification automatique au responsable du dossier para confirmer le mapping de ce nouveau compte. Aucune action n'est requise côté technique : basta con poursuivre l'envoi du fichier.