Processus d'intégration étape par étape

Facturation électronique B2B

Émettez et recevez des factures électroniques B2B juridiquement conformes sur les réseaux pris en charge.

Prise en charge multi-pays

Belgique, Allemagne et Italie, avec une conformité spécifique à chaque pays intégrée.

Unified API

Une seule intégration pour la facturation électronique dans tous les pays pris en charge, avec des endpoints cohérents.

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

• Un accès au HUB de fiskaly (environnement TEST)
• Une compréhension de base des API REST et des flux d’authentification
• Les informations d’enregistrement de votre entreprise pour la configuration du Taxpayer

📘Note

Si vous avez déjà intégré SIGN IT ou SIGN FR, les étapes de configuration initiale de ce guide vous seront probablement familières et pourraient déjà être réalisées. Dans ce cas, vous pouvez passer directement à l’étape 10 pour examiner les étapes supplémentaires requises.

Flux d’intégration

📘Important

Les étapes surlignées en jaune doivent être réalisées directement sur le HUB, tandis que les étapes restantes doivent être gérées via l’API. Effectuer chaque action dans le bon contexte est une étape importante vers une intégration réussie.

* Step required for BE 🇧🇪 and DE 🇩🇪
* Not required for IT 🇮🇹

Configuration étape par étape

1. Étape 1 : Inscription sur le HUB

   Commencez par vous inscrire sur le HUB de fiskaly.

   
2. Étape 2 : Création d'un Account et d'une organisation GROUP

   La création d’un Account fiskaly est la première étape ; vous pourrez ensuite mettre en place la première structure organisationnelle de votre entreprise et générer votre clé API.

   L’Account représente le fournisseur de PoS ou un détaillant qui exploite son propre système PoS. Il s’agit de l’organisation de plus haut niveau dans la structure.

   Après avoir créé votre Account fiskaly, vous serez dirigé vers le sélecteur d’organisation où vous pourrez créer votre Group. Un Group est un niveau intermédiaire au sein d’un Account qui vous aide à organiser plusieurs Units en regroupements logiques.

3. Étape 3 : Création d'une clé API

   L’étape suivante consiste à générer une clé API pour votre organisation via le HUB, au sein de votre Group. Cette paire clé API et Secret est requise pour créer votre première organisation de type UNIT (étape 5).

   💡Environnements TEST et LIVE

   Les clés API générées dans l’environnement TEST (https://test.api.fiskaly.com) créeront des ressources TEST, tandis que celles de l’environnement LIVE (https://live.api.fiskaly.com) créeront des ressources LIVE.

1. Étape 4 : MANAGEMENT - Création d'un Token

   Commencez à utiliser l’API E-INVOICE via l’endpoint createToken. Vous devrez créer un token pour vous authentifier lors des étapes suivantes.

2. Étape 5 : MANAGEMENT - Création d'une organisation UNIT

   Poursuivez en créant une organisation de type UNIT via l’endpoint createOrganization. Un UNIT représente une entité juridique unique (commerçant). Vous devrez créer un UNIT pour chaque représentation de Taxpayer que vous gérez.

   Lors de la création de votre première organisation de type UNIT, assurez-vous qu’elle soit associée à votre Group créé via le HUB. Pour cela, utilisez le token généré à partir des clés API créées pour votre Group. Cela reflète la structure hiérarchique dans laquelle le UNIT est imbriqué sous votre GROUP, lequel se trouve à son tour au sein de votre ACCOUNT.

3. Étape 6 : MANAGEMENT - Création d'un Subject (clé API)

   Créez un Subject de type API_KEY via l’endpoint createSubject. La connexion entre l’organisation UNIT et la clé API est établie via le X-Scope-Identifier (en utilisant l’id de l’organisation nouvellement créée).

4. Étape 7 : MANAGEMENT - Création d'un nouveau Token

   Ensuite, créez un token qui sera utilisé pour créer des ressources au sein de l’organisation UNIT correspondante.

5. Étape 8 : OPERATION - Création d'un Taxpayer

   Vous êtes maintenant prêt à créer les Taxpayers requis pour la facturation électronique. Pour ce faire, utilisez l’endpoint createTaxpayer. Vous devrez définir le Taxpayer de type COMPANY.

   Selon le pays, la configuration de fiscalisation requise et les données du Taxpayer nécessaires peuvent différer ; veuillez donc consulter les guides pays dédiés :

   • Belgique
   • Allemagne
   • Italie
   • France (bientôt disponible)
   • Pologne (bientôt disponible)

   Une fois que vous créez un Taxpayer de type COMPANY, son state sera défini sur ACQUIRED. Pour qu’il soit pleinement fonctionnel, le state doit être mis à jour sur COMMISSIONED via l’endpoint updateTaxpayer.

   Lors de l’appel de l’endpoint createTaxpayer, une Location de type HEAD_OFFICE est automatiquement créée. Vous pouvez le confirmer via l’endpoint listLocations.

6. Étape 9 : OPERATION - Création d'une Location

   Les nouveaux clients intégrant uniquement la facturation électronique peuvent ignorer cette étape.

   Pour la fiscalisation des reçus, vous devez créer une Location de type BRANCH via l’endpoint createLocation pour chaque emplacement commercial.

   Lorsque vous créez une Location de type BRANCH, son state est initialement défini sur ACQUIRED. Pour poursuivre, vous devez changer le state sur COMMISSIONED via l’endpoint updateLocation.

7. Étape 10 : OPERATION - Création d'un System

   L’endpoint createSystem est utilisé pour créer une abstraction d’un système utilisé pour les opérations fiscales.

   Selon votre configuration, les cas suivants s’appliquent :

   • Nouveaux clients utilisant uniquement la facturation électronique : créez un seul System E_INVOICE_SERVICE (un seul par Taxpayer) et associez-le à la Location HEAD_OFFICE qui a été automatiquement créée pour vous à l’étape 8.

   • Nouveaux clients utilisant la fiscalisation des reçus et la facturation électronique : créez des Systems FISCAL_DEVICE pour les reçus et un System E_INVOICE_SERVICE supplémentaire (un par Taxpayer). Associez le System E_INVOICE_SERVICE à la Location de type HEAD_OFFICE, et associez le ou les Systems FISCAL_DEVICE à une Location de type BRANCH.

   • Clients existants disposant d’appareils fiscaux commissionnés qui ajoutent la facturation électronique : créez un System E_INVOICE_SERVICE supplémentaire et associez-le à la Location de type HEAD_OFFICE. Lorsqu’un Taxpayer est créé, une Location de type HEAD_OFFICE est automatiquement générée avec le même ID. Cela peut être vérifié en listant vos Locations.

   Lors de la création d’un System, son state initial est défini sur ACQUIRED. Pour poursuivre le processus d’intégration de la facturation électronique, demandez le commissioning du System E_INVOICE_SERVICE via updateSystem.

   ⚠️Important

   Après une demande de commissioning réussie, le System est dans l’état COMMISSIONED et initialement en mode DEGRADED jusqu’à ce que l’étape 11 soit entièrement terminée.

   📘Italie 🇮🇹

   Pour les Taxpayers italiens, le System E_INVOICE_SERVICE passe directement à state=COMMISSIONED, mode=OPERATIVE après le commissioning — aucun envoi de Proof of Ownership, l’étape 11 ne s’applique donc pas, et il peut envoyer des factures immédiatement. Si le Taxpayer doit également recevoir, effectuez l’enregistrement AdE unique — à tout moment, avant ou après le commissioning — consultez le guide Italie. Passez ensuite à l’étape 12.

8. Étape 11 : OPERATION - Envoi du Proof of Ownership

   Cette étape est requise pour les intégrations E-INVOICE BE 🇧🇪 et E-INVOICE DE 🇩🇪.

   Envoyez le PDF du Proof of Ownership via l’endpoint createRecord, en utilisant un Record de type INTENTION et une opération de type UPLOAD. Le document soumis est examiné et vérifié, ce qui peut prendre jusqu’à 72 heures. Une fois la vérification terminée, le System passe automatiquement du mode DEGRADED au mode OPERATIVE.

   Vous trouverez plus de détails sur le contenu requis du document dans la section Proof of Ownership.

   📘Ignorez cette étape pour l'Italie 🇮🇹

   Cette étape ne s’applique pas aux intégrations E-INVOICE IT. Passez directement à l’étape 12.

9. Étape 12 : OPERATION - Création d'un Record

   ⚠️Important

   Tous les Records créés dans l’environnement LIVE sont juridiquement valides ; ils doivent donc toujours représenter des transactions commerciales réelles et valides.

   La création d’un Record dans l’API E-INVOICE nécessite toujours deux appels successifs :

   • Partie A) INTENTION — au début du processus de facturation électronique
   • Partie B) TRANSACTION — une fois que les données de la facture électronique sont complètes

   📘Vous utilisez aussi la fiscalisation des reçus ?

   Si le Taxpayer utilise également la fiscalisation des reçus (par exemple, SIGN IT), créez les Records INTENTION et TRANSACTION sur votre System FISCAL_DEVICE (n’importe lequel sur le même Taxpayer) — lorsqu’un FISCAL_DEVICE est utilisé, il a la priorité. Le System E_INVOICE_SERVICE crée et transmet malgré tout la facture électronique à partir de ces données.

   PARTIE A) Intention

   Pour chaque opération de facturation électronique, appelez d’abord l’endpoint createRecord pour enregistrer l’intention d’émettre une facture électronique.

   Un Record de type INTENTION contiendra les informations suivantes :

   • L’association avec le System E_INVOICE_SERVICE qui sera utilisé pour émettre la facture électronique
   • Une opération de type TRANSACTION, indiquant que le System a l’intention d’effectuer une opération de facturation électronique.

   Partie B) Transaction

   Ensuite, appelez à nouveau l’endpoint createRecord pour créer un Record de type TRANSACTION associé à l’identifiant interne d’un Record de type INTENTION déjà créé. Le type d’opération détermine le document émis.

   Les types d’opération suivants sont pris en charge :

   • INVOICE : émet une facture électronique standard.
   • CORRECTION : émet une note de crédit. Consultez le guide Note de crédit pour connaître les flux de travail et les règles détaillés.

   Une fois la Transaction traitée avec succès, la facture électronique est créée et gérée conformément aux exigences applicables en matière de facturation électronique.

   📘Important

   Pour E-INVOICE, le destinataire doit être de type BUSINESS et le bloc invoicing doit être renseigné, sans quoi la facture électronique ne peut pas être transmise. La méthode de transmission et les champs requis au sein du bloc invoicing varient selon le pays — veuillez consulter les guides pays dédiés ci-dessous.

   L’Italie fait exception : les destinataires CONSUMER y sont également pris en charge pour les factures B2C, avec des champs obligatoires différents. Consultez Envoi de factures électroniques B2C.

   • Belgique
   • Allemagne
   • Italie
   • France (bientôt disponible)
   • Pologne (bientôt disponible)

Étapes suivantes

Guide Belgique

Exigences spécifiques à la facturation électronique belge.

Guide Allemagne

Exigences spécifiques à la facturation électronique allemande.

Proof of Ownership

Découvrez le processus de vérification des documents.

Référence de l'API

Documentation complète de l'API E-INVOICE.