Intégration étape par étape

⚠️Aperçu

SIGN ES (Unified API) est actuellement disponible dans l’environnement de test pour le développement et les tests initiaux, bien qu’à ce stade seul un ensemble limité d’options puisse être testé. La production n’est pas encore activée. Pour une utilisation en production, veuillez utiliser l’API Spécialisée SIGN ES.

Pour commencer le processus d’intégration, veuillez consulter les instructions détaillées étape par étape fournies ici.

Le diagramme ci-joint illustre le flux de travail et met en évidence les étapes essentielles nécessaires pour mener à bien votre intégration, pour laquelle vous devrez utiliser notre SIGN ES (Unified API).

1. S'enregistrer sur le HUB

   Commencez par vous enregistrer sur le fiskaly HUB. Pour plus de conseils sur la prise en main, rendez-vous dans notre section HUB - Premiers pas.

2. Créer un Compte et une Organisation GROUP

   Créer un Compte fiskaly est la première étape, après quoi vous pouvez procéder à la mise en place de la première structure organisationnelle pour votre entreprise et générer votre Clé API.

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

   Après avoir créé votre Compte fiskaly, vous accéderez au Sélecteur d’Organisation où vous pourrez créer votre Groupe.

   Un Groupe est un niveau intermédiaire au sein d’un Compte qui vous aide à organiser plusieurs Units en clusters logiques.

3. Créer une Clé API

   L’étape suivante consiste à générer une Clé API pour votre organisation via le HUB. 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. Créer un Token

   À partir de cette étape, vous utiliserez la SIGN ES (Unified API).

   Appelez le point de terminaison createToken avec la Clé API et le Secret de l’étape 3 pour obtenir un token bearer. Incluez ce token dans l’en-tête Authorization des étapes 5 et 6.

2. Créer une Organisation UNIT

   Créez une Organisation de type UNIT via le point de terminaison createOrganization. Une UNIT représente une seule entité légale (commerçant). Vous devrez créer une Organisation UNIT pour chaque représentation de contribuable que vous gérez.

   L’utilisation du token bearer généré à l’Étape 4 avec la Clé API et le Secret créés pour votre Groupe garantit que la UNIT est correctement imbriquée sous ce Groupe dans la hiérarchie.

3. Créer un Subject (Clé API)

   Créez un Subject de type API_KEY pour l’Organisation UNIT via le point de terminaison createSubject.

   Pour associer le Subject (Clé API) à votre UNIT, incluez l’en-tête X-Scope-Identifier avec l’id de l’Organisation UNIT dans votre requête.

4. Créer un nouveau Token

   Créez un token en utilisant la Clé API Subject et le Secret que vous venez de générer. Ce token bearer sera utilisé pour toutes les étapes suivantes pour créer des ressources au sein de l’Organisation UNIT correspondante.

1. Créer un Contribuable

   Vous êtes maintenant prêt à commencer à créer les parties opérationnelles requises pour la fiscalisation en Espagne.

   Utilisez le point de terminaison createTaxpayer pour créer la représentation d’un contribuable comme suit :

   • Définissez le contribuable comme type Company (personne morale) ou Individual (personne physique).
   • Indiquez le NIF (Número de Identificación Fiscal) espagnol du contribuable.
   • Le territoire fiscal du contribuable déterminera si Verifactu, SII ou TicketBAI s’applique — consultez l’introduction à SIGN ES pour savoir comment ces réglementations s’appliquent aux territoires espagnols.

   Une fois que vous créez un Taxpayer, son état est défini à ACQUIRED par défaut. Pour le rendre pleinement fonctionnel, mettez à jour l’état à COMMISSIONED en utilisant le point de terminaison updateTaxpayer.

2. Créer un Site

   📘Note

   Un site HEAD_OFFICE est automatiquement créé lors de la création du Taxpayer et partage le même UUID que le Taxpayer. Cependant, à des fins de fiscalisation, nous recommandons de créer un site séparé de type BRANCH (il peut avoir la même adresse). S’il y a plusieurs sites, une branche correspondante doit être créée pour chacun.

   Pour chaque site commercial opérationnel, créez un Site de type BRANCH via le point de terminaison createLocation.

   Une fois un Site créé, son état est défini à ACQUIRED par défaut. Mettez à jour l’état à COMMISSIONED en utilisant le point de terminaison updateLocation avant de continuer.

3. Créer un Système

   Le point de terminaison createSystem vous permet de créer une abstraction de chaque Système d’Enregistrement Électronique utilisé pour les opérations fiscales. Chaque caisse enregistreuse ou point de vente doit être fourni comme un nouveau Système de type FISCAL_DEVICE.

   • Un Système sera connecté à un Site spécifique de type BRANCH, créé précédemment.

   Une fois un Système créé, son état est défini à ACQUIRED par défaut. Pour créer des Enregistrements, son état doit être mis à jour à COMMISSIONED en utilisant le point de terminaison updateSystem.

   📘Remarque sur la facturation

   Pour la plupart des contrats, les System sont les unités utilisées pour la facturation chez fiskaly. Un System devient pertinent pour la facturation dès que son état passe de ACQUIRED à COMMISSIONED dans l’environnement LIVE. Les ressources de l’environnement TEST ne sont pas facturées. Pour connaître les conditions de facturation exactes, veuillez vous référer à votre contrat avec fiskaly.

4. Créer un Enregistrement

   Pour chaque opération commerciale effectuée dans le Système, le point de terminaison createRecord doit être appelé deux fois en séquence : d’abord pour enregistrer l’intention de démarrer une transaction, puis pour fournir les données de la transaction.

   Partie A) Intention

   Un Record de type INTENTION contient l’association avec le Système qui effectuera la transaction et une Opération de type TRANSACTION, représentant l’intention du Système d’enregistrer une transaction.

   Partie B) Transaction

   Un Record de type TRANSACTION est associé à l’INTENTION créée précédemment et contient les données de la transaction, qui sont ensuite signées et transmises conformément à la réglementation applicable au contribuable (Verifactu, SII ou TicketBAI).

   📘Note

   Tous les Records créés dans l’environnement LIVE représentent des documents fiscalement pertinents et doivent toujours refléter des transactions réelles. Utilisez l’environnement TEST désigné pour les tests d’intégration.