Processus d'intégration étape par étape

Facturation électronique B2B

Émettez des factures électroniques légalement conformes via le réseau PEPPOL pour les transactions B2B.

Support multi-pays

Belgique, Allemagne, Italie, France et Pologne avec conformité spécifique au pays intégrée.

API unifiée

Intégration unique pour la facturation électronique dans tous les pays pris en charge avec des endpoints cohérents.

Prérequis

Avant de commencer, assurez-vous d’avoir :

• Accès au HUB fiskaly (environnement TEST)
• Compréhension de base des API REST et des flux d’authentification
• Les données d’enregistrement de votre entreprise pour la configuration du contribuable

📘Note

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

Flux de travail d’intégration

📘Important

Les étapes marquées en jaune doivent être complété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.

Configuration étape par étape

1. Étape 1 : S'inscrire sur le HUB

   Commencez par vous inscrire sur le HUB fiskaly.

   
2. Étape 2 : Créer un compte et un GROUPE d'organisation

   La création d’un compte fiskaly est la première étape, après laquelle vous pouvez procéder à la mise en place de la première structure organisationnelle de votre entreprise et générer votre clé API.

   Le Compte représente le fournisseur du système de caisse ou un détaillant qui exploite son propre système de caisse. C’est l’organisation de niveau supérieur dans la structure.

   Après avoir créé votre compte fiskaly, vous serez dirigé vers le Sélecteur d’organisation où vous pouvez créer votre Groupe. Un Groupe est un niveau intermédiaire au sein d’un Compte qui vous aide à organiser plusieurs Unités en clusters logiques.

3. Étape 3 : Créer une clé API

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

   💡Environnements TEST vs. 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éer un token

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

2. Étape 5 : MANAGEMENT — Créer une UNITÉ d'organisation

   Continuez en créant une Organisation de type UNIT via l’endpoint createOrganization. Une UNIT représente une seule entité légale (commerçant). Vous devrez créer une UNIT pour chaque représentation de contribuable que vous gérez.

   Lors de la création de votre première Organisation de type UNIT, assurez-vous qu’elle est associée à votre Groupe créé via le HUB. Pour ce faire, utilisez le token généré à partir des clés API créées pour votre Groupe. Cela reflète la structure hiérarchique où l’UNIT est imbriquée sous votre GROUP, qui se trouve à son tour dans votre ACCOUNT.

3. Étape 6 : MANAGEMENT — Créer 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 l’X-Scope-Identifier (en utilisant l’id de l’Organisation nouvellement créée).

4. Étape 7 : MANAGEMENT — Créer 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éer un contribuable

   Vous êtes maintenant prêt à créer les Contribuables nécessaires à la facturation électronique. Pour ce faire, utilisez l’endpoint createTaxpayer. Vous devrez définir le Contribuable de type COMPANY.

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

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

   Une fois que vous créez un Contribuable de type COMPANY, son state sera défini sur ACQUIRED. Pour être pleinement fonctionnel, l’état doit être mis à jour sur COMMISSIONED à l’aide de l’endpoint updateTaxpayer.

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

6. Étape 9 : OPERATION — Créer un emplacement

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

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

   Lorsque vous créez un Emplacement de type BRANCH, son state est initialement défini sur ACQUIRED. Pour continuer, vous devez changer l’état en COMMISSIONED à l’aide de l’endpoint updateLocation.

7. Étape 10 : OPERATION — Créer un système

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

   Selon votre configuration, ce qui suit s’applique :

   • Nouveaux clients utilisant uniquement la facturation électronique : créez un seul Système E_INVOICE_SERVICE (un seul par Contribuable) et liez-le à l’Emplacement HEAD_OFFICE qui a été automatiquement créé pour vous à l’étape 8.

   • Nouveaux clients utilisant la fiscalisation des reçus et la facturation électronique : créez des Systèmes FISCAL_DEVICE pour les reçus et un Système E_INVOICE_SERVICE supplémentaire (un par Contribuable). Liez le Système E_INVOICE_SERVICE à l’Emplacement de type HEAD_OFFICE, et liez les Systèmes FISCAL_DEVICE à un Emplacement de type BRANCH.

   • Clients existants avec des appareils fiscaux mis en service ajoutant la facturation électronique : créez un Système E_INVOICE_SERVICE supplémentaire et liez-le à l’Emplacement de type HEAD_OFFICE. Lorsqu’un Contribuable est créé, un Emplacement de type HEAD_OFFICE est automatiquement généré avec le même ID. Cela peut être vérifié en listant vos Emplacements.

   Lors de la création d’un Système, son état initial est défini sur ACQUIRED. Pour continuer avec le processus d’intégration de la facturation électronique, demandez la mise en service du Système E_INVOICE_SERVICE à l’aide de updateSystem.

   ⚠️Important

   Après une demande de mise en service réussie, le Système est dans l’état COMMISSIONED et initialement en mode DEGRADED jusqu’à la fin complète de l’Étape 11.

8. Étape 11 : OPERATION — Télécharger la preuve de propriété

   Téléchargez le PDF de la Preuve de propriété via l’endpoint createRecord, en utilisant un Enregistrement 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 Système passe automatiquement du mode DEGRADED au mode OPERATIVE.

   Plus de détails sur le contenu requis du document sont fournis dans la section Preuve de propriété.

9. Étape 12 : OPERATION — Créer un enregistrement

   ⚠️Important

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

   💡Remarque

   La création d’un Enregistrement dans l’API E-INVOICE nécessitera 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

   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 Enregistrement de type INTENTION contiendra les informations suivantes :

   • Association avec le Système E_INVOICE_SERVICE qui sera utilisé pour émettre la facture électronique
   • Opération de type TRANSACTION, indiquant que le Système a l’intention d’effectuer une opération de facturation électronique.

   Partie B) Transaction

   Appelez ensuite à nouveau l’endpoint createRecord pour créer un Enregistrement de type TRANSACTION associé à l’identifiant interne d’un Enregistrement 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.

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

   📘Important

   Pour E-INVOICE, le destinataire doit être de type BUSINESS et le bloc invoicing doit être renseigné, sinon la facture électronique ne peut pas être transmise. La méthode de livraison et les champs obligatoires dans le bloc invoicing varient selon le pays — veuillez consulter les guides pays dédiés ci-dessous.

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

   • CORRECTION avec data.type = INVOICE : Émet une note de crédit faisant référence à une facture précédemment transmise. La transaction doit inclure une référence au document précédent à la facture originale, et le destinataire doit correspondre à l’original. Consultez le guide sur les notes de crédit pour les workflows et règles détaillés.

   💡Note

   Les Enregistrements CORRECTION::INVOICE ne sont acceptés que depuis un système E_INVOICE_SERVICE.

Prochaines étapes

Guide Belgique

Exigences spécifiques pour la facturation électronique belge.

Guide Allemagne

Exigences spécifiques pour la facturation électronique allemande.

Preuve de propriété

En savoir plus sur le processus de vérification des documents.

Référence API

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