Intégration API : environnements, champs obligatoires et correspondances de champs

Cet article répond aux questions les plus fréquentes sur la connexion de vos propres systèmes à l'API faktoora. Les messages d'erreur et les codes de statut HTTP sont décrits séparément dans l'article Gestion des erreurs de l'API, la liste complète des champs BT dans l'article Quels champs BT l'API faktoora prend-elle en charge ? et les champs obligatoires pour XRechnung dans l'article Quelles informations une XRechnung doit-elle contenir au minimum ?.

Environnement de test et de production

L'API faktoora est disponible sous deux URL de base distinctes :

• Environnement de production : https://api.faktoora.com/api/v1
• Environnement de démonstration/test : https://api.demo.faktoora.com/api/v1

Les deux environnements sont des instances indépendantes, avec leurs propres comptes et données. La clé API est générée dans les paramètres du compte de l'environnement concerné et transmise dans l'en-tête X-API-KEY (voir Pourquoi mes appels API sont-ils rejetés avec une erreur 401 ?). Pour passer du test à la production, remplacez l'URL de base par https://api.faktoora.com/api/v1 et utilisez la clé générée dans le compte de production.

Créer une facture : POST /invoices

Pour l'objet Invoice lui-même, seuls les champs suivants sont obligatoires par principe selon le schéma :

• format : format de sortie, par ex. simple, zf:1, zf:2, xrechnung, peppol
• issueDate : date de facture (BT-2)
• invoiceNumber : numéro de facture (BT-1)
• invoiceTypeCode : type de facture, par ex. 380 pour une facture commerciale (BT-3)
• invoiceItems : au moins une ligne de facture
• buyer : l'acheteur

Dans buyer et seller, le nom et l'adresse complète (street, postcode, city, country) sont obligatoires dès que vous transmettez le bloc correspondant. Chaque ligne dans invoiceItems nécessite un id et un objet product avec name, quantity, unitCode, price et taxes. La liste complète des champs obligatoires, qui dépend du format, pour format: xrechnung figure dans l'article Quelles informations une XRechnung doit-elle contenir au minimum ?.

Récupérer une facture : déroulement

La création de factures via POST /invoices est asynchrone : la réponse est 202 Accepted avec une faktooraId, et la facture elle-même est générée en arrière-plan. Un GET /invoices/{faktooraId} envoyé immédiatement après peut échouer avec 404, car le traitement est encore en cours.

Le déroulement correct :

1. Envoyer POST /invoices et enregistrer la faktooraId de la réponse 202.
2. Vérifier le statut de traitement via GET /invoices/{faktooraId}/status ou attendre le webhook enregistré (voir Webhook).
3. Appeler ensuite seulement GET /invoices/{faktooraId}. Ce point de terminaison renvoie directement le fichier finalisé au format application/pdf ou application/xml (pas d'objet de métadonnées JSON).

Les détails sur les codes de statut possibles figurent dans l'article Gestion des erreurs de l'API.

Correspondances de champs

Référence de commande (Order Reference)

Au niveau de la facture, il existe deux champs de référence différents :

• orderNumber sur l'objet Invoice : référence à la commande correspondante (BT-14).
• invoiceItems[].product.orderNumber : référence de commande au niveau de chaque ligne ; selon la description de l'API, non autorisée pour format: xrechnung.

Il existe en outre buyerReference.IssuerAssignedID comme référence de commande de l'acheteur (BT-13), à distinguer de buyerReference.buyerReferenceId, qui est la référence de l'acheteur ou, pour les acheteurs publics, la Leitweg-ID (BT-10).

Lors de la récupération des données de facture via les points de terminaison d'import (voir ci-dessous), le champ correspondant s'appelle references.orderReferenceId (BT-13), ou references.orderNumber pour le numéro de commande de l'acheteur : les noms de champ diffèrent donc entre la création (POST /invoices) et la récupération de factures importées.

Numéro de commande : niveau en-tête ou ligne ?

Les deux sont possibles et indépendants l'un de l'autre : orderNumber sur l'objet Invoice référence la commande au niveau de l'en-tête (BT-14), invoiceItems[].product.orderNumber référence une commande au niveau de chaque ligne. Pour xrechnung, seul le niveau en-tête est autorisé.

Interlocuteur de l'acheteur

L'interlocuteur chez l'acheteur est renseigné via buyer.definedTradeContact :

• firstName / lastName : nom de l'interlocuteur (BT-56)
• departmentName : service (BT-56-0)
• phone : numéro de téléphone (BT-57-00)
• email : adresse e-mail (BT-58-00)

Ces champs sont distincts de buyer.phone/buyer.email (BT-57/BT-58), qui représentent le contact général de l'entreprise acheteuse.

DirectDebitMandateID

directDebitMandateID (mandat de prélèvement SEPA, BG-19/BT-89) appartient à l'objet specifiedTradePaymentTerms, et non à specifiedTradeSettlementPaymentMeans. Si le champ est transmis par erreur dans le bloc Payment Means au lieu du bloc Payment Terms, il n'est pas repris dans le XML, car il n'y constitue pas un champ défini du schéma. Si DirectDebitMandateID manque dans le XML généré, vérifiez d'abord que le champ se trouve bien dans le tableau specifiedTradePaymentTerms.

Codes de moyen de paiement pour PayPal et carte de crédit

Le champ specifiedTradeSettlementPaymentMeans[].typeCode (BT-81) utilise la liste de codes UNTDID 4461. Sont notamment disponibles 10 (espèces), 20 (chèque), 30 (virement), 42 (paiement sur compte bancaire), 48 (paiement par carte), 49 (prélèvement), 57 (ordre permanent), 58 (virement SEPA), 59 (prélèvement SEPA), 97 (report) ainsi que le code chaîne ZZZ (défini librement). Il n'existe pas de code spécifique pour PayPal.

• Carte de crédit : typeCode: 48. Pour ce code, cardNumber (obligatoire) et, en option, holderName sont également admis ; ces deux champs ne sont autorisés qu'avec typeCode: 48.
• PayPal : comme UNTDID 4461 ne connaît pas de code spécifique à PayPal, utilisez typeCode: "ZZZ" (défini librement) et décrivez le moyen de paiement dans le champ de texte libre information, par ex. « Paiement par PayPal ».

Structure de données de l'interface pour les factures entrantes et sortantes

Pour les factures importées, qu'elles soient entrantes (/import/incoming) ou sortantes (/import/outgoing), l'API fournit la même structure de base, répartie en sous-ressources consultables séparément :

• content/summary : vue d'ensemble (statut, montants, format)
• content/seller / content/buyer : données du vendeur ou de l'acheteur
• content/lineitems : lignes de facture
• content/taxes : données fiscales par catégorie de taxe (taxable, rate, amount, category)
• content/paymentterms : conditions de paiement, y compris directDebitMandateID et dueDateTime
• content/paymentmeans : moyens de paiement (typeCode, information, paymentReference)
• content/delivery : données de livraison
• content : toutes les sous-ressources ci-dessus réunies dans une seule réponse
• attachments / attachment/{attachmentId}/file : pièces jointes de l'import
• status : statut de traitement de l'import
• validation / validation/pdf : résultat de la validation

L'import lui-même est asynchrone : un POST /import/incoming renvoie 202 Accepted avec un importId avant que l'analyse et la validation ne soient terminées. Appelez GET /import/incoming/{importId}/status jusqu'à ce que overallStatus ne soit plus pending avant d'exploiter les points de terminaison de contenu.

Pour les factures sortantes importées (/import/outgoing), content contient en plus un bloc references avec les numéros de référence au niveau du document : orderNumber (numéro de commande de l'acheteur), orderReferenceId (BT-13), buyerReferenceId (BT-10), shippingOrderNumber, supplierNumber, contractNumber, assignmentNumber et mandateReference (référence du mandat SEPA).

Factures récurrentes

Les factures récurrentes se configurent dans l'interface faktoora ; le guide correspondant se trouve dans l'article Factures récurrentes. Via l'API, le point de terminaison en lecture GET /recurring-invoices est disponible à cet effet : il renvoie les plannings créés (nom, fréquence, date de début/fin, statut, nextExecutionDate, modèle de facture associé). Aucun point de terminaison permettant de créer ou de modifier un planning via l'API n'est documenté dans la référence de l'API.

Échange de fichiers : SFTP, FTP et WebDAV

Pour échanger des fichiers de facture via un répertoire, vous pouvez configurer une connexion de fichiers dans les workflows. Les protocoles disponibles sont FTP, SFTP et WebDAV. La configuration s'effectue dans l'interface, et non via l'API : la référence de l'API ne contient aucun point de terminaison à cet effet.

Il existe en outre deux autres moyens de connecter un système en amont :

• Par programmation via l'API : générer des données de facture structurées via POST /invoices, ou téléverser des fichiers de facture électronique déjà générés via POST /import/incoming ou l'équivalent pour les factures sortantes.
• Par e-mail : voir Réception des factures via votre propre serveur de messagerie.

Intégration DATEV : traitement des écarts

Lors de l'export DATEV, faktoora compense automatiquement les écarts d'arrondi entre la somme des différentes lignes de facture et le montant consolidé de la facture : si la somme des montants des lignes diffère du montant consolidé, l'écart est imputé au montant de la première ligne dans l'export du grand livre DATEV, de sorte que la somme des lignes exportées corresponde exactement au montant total de la facture.

Systèmes déjà intégrés

Les connexions attestées dans le code et dans les articles existants de la base de connaissances sont : DATEV, Xero, weclapp, HubSpot, Monday, PipeDrive et Bexio. Il existe en outre une connexion Stripe qui synchronise les factures et clients Stripe sous forme de factures dans faktoora ; la génération automatique au format XRechnung n'est pas documentée pour cette connexion : vous continuez à déterminer vous-même le format de sortie d'une facture via le champ format ou les paramètres du compte.