Formats des données
L'API accepte pour l'instant le format csv pour les données et le format pdf pour les factures.
Le csv a été privilégié car c'est actuellement le format le plus couramment utilisé pour les exports en comptabilité.
Fichiers autorisés
2 cas de figure :
L’API peut recevoir soit les données au format csv, soit les factures pdf
accompagnées des données au format csv (dans une archive zip), permettant de
conserver le fichier pdf de facture original.
- Dans le premier cas, l’API ezfacture génère un lisible pdf à partir des données csv, et incorpore les données de facture au format xml pour générer le fichier factur-X.
- Dans le second cas, l’API ezfacture incorpore les données de facture au format xml dans le ou les pdf(s) fourni(s).
Sont acceptés par envoi (requête POST) :
- 1 fichier zip contenant 1 fichier csv (utf-8) contenant de 1 à 100 factures et 0 à 100 fichiers pdf. Les données dans le csv doivent correspondre à un seul et même profil (ex. : basic, voir profils). Les pdf de facture doivent être nommés selon leur numéro de facture, ex. F20235.pdf
- Ou un fichier csv contenant les données de 1 à 100 factures.
La taille maximum autorisée pour le fichier est de 10M.
Structure du fichier csv
Les fichiers csv seront rejetés si :
- la structure ou le type de données attendues ne sont pas respectés,
- les données envoyées ne sont pas cohérentes.
Le détail des erreurs est indiqué, pour chaque envoi, dans le dashboard de l’utilisateur (https://www.ezfacture.fr/dashboard/).
Le fichier peut comporter de 1 à 100 factures.
Ce format accepte les factures B2B France, B2B International et B2C.
- Le fichier csv doit être encodé en utf-8 avec des colonnes séparées par le caractère ;.
- Le fichier ne comporte pas de ligne d’entête.
- L’ordre et la position des colonnes doivent être respectés, toutes les colonnes doivent être présentes.
Le format attendu est spécifique : à chaque type de ligne correspond un ensemble de colonnes précis.
Types de lignes
Pour chaque ligne, la première colonne du fichier csv définit toujours le type de ligne :
- F pour Facture (données d’entête de facture)
- L pour Ligne (ligne de facture)
- T pour Taxe (ligne de taxe)
- N pour Note de facture
- R pour Remise
- C pour Charge
Une facture contient obligatoirement une ligne F unique, une ou plusieurs lignes L, et une ou plusieurs lignes T.
Pour chaque ligne, la deuxième colonne du fichier contient toujours le numéro de facture. Cette donnée est particulièrement importante car elle fait le lien entre les différentes lignes du fichier csv pour constituer les données d’une facture.
Modèles à télécharger
- Fichier excel
contenant 3 onglets : ⤓ Télécharger (.xlsx)
- Définition des colonnes pour chaque type de ligne
- Définition formats de données attendus pour chaque ligne / colonne (.xlsx)
- Template complet avec en-têtes de lignes et données d’exemple
- Fichier csv avec données d’exemple au format définitif attendu : ⤓ Télécharger (.csv)
Les profils factur-X
- Profil MINIMUM : contient les données obligatoires de facturation (correspondant aux données minimum exigées par la plateforme Chorus Pro).
- Profil BASIC WL (pour basic without lines) : profil « MINIMUM » avec en plus les données de facturation d’entête et pied de factures les plus couramment demandées et utiles aux acheteurs pour leurs traitements (référence de livraison, nom et adresse du fournisseur, mode de paiement, référence bancaire).
- Profil BASIC : profil BASIC WL avec avec les données essentielles de ligne de facture (numéro de ligne, référence, désignation, quantité, unité, prix unitaire HT, prix total HT).
- Profil EN 16931 : contient l’ensemble des données de la norme sémantique européenne EN 16931, soit 165 champs de données possibles qui font appel à des listes de codes standardisés.
- Profil EXTENDED : profil EN 16931 augmenté de données additionnelles (ex. : plusieurs lieux de livraison).