Intégration étape par étape

📘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 peut-être déjà terminées. Dans ce cas, vous pouvez passer directement à l’Étape 10 pour examiner les étapes supplémentaires requises.

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 API SIGN PT.

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 l’API SIGN PT.

   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.

   Les tokens sont des JWT de courte durée qui authentifient chaque appel SIGN PT ultérieur. Ils sont obtenus par portée de Compte ou d’Organisation.

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 au Portugal.

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

   • Définissez le contribuable comme type Company (personne morale) ou Individual (personne physique). Dans les deux cas, le nom et l’adresse doivent être fournis.
   • Dans les informations de fiscalisation portugaises, au minimum les données suivantes du contribuable doivent être fournies :
     • tax_id_number : le NIF (Número de Identificação Fiscal) portugais du contribuable. 9 chiffres, sans espaces ni séparateurs (par ex. 501234567).
     • credentials : les identifiants du sous-utilisateur AT que SIGN PT utilisera pour appeler les services web AT au nom de ce contribuable :
       • Nom d’utilisateur : l’identifiant du sous-utilisateur au format <NIF>/<subuser-id> (par ex. 501234567/5), tel qu’émis par le Portal das Finanças.
       • Mot de passe : le mot de passe défini pour ce sous-utilisateur.

   Ce ne sont pas les identifiants principaux du Portal das Finanças du commerçant. Il doit s’agir d’un sous-utilisateur dédié créé spécifiquement pour l’accès au service web — voir la note Importante ci-dessous.

   ⚠️Important

   L’utilisation des Services Web AT via SIGN PT nécessite une configuration préalable sur le Portal das Finanças par le contribuable ou son représentant légal : un sous-utilisateur dédié au Service Web doit être créé, doté des permissions requises (par ex. WSE, WFA, WDT) et les conditions générales AT applicables doivent être acceptées.

   Pour des instructions étape par étape sur la création du sous-utilisateur, consultez Création du sous-utilisateur sur le Portal das Finanças.

   Une fois que vous créez un Taxpayer, qu’il soit de type Company ou Individual, 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éé avec le contribuable. 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 (ERS) 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.

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 peut effectuer l’une des opérations suivantes :

   • INVOICE/RECEIPT : Représente la vente d’un bien ou d’un service, incluant les détails du document (numéro de document, code d’activité, date de transaction, montants totaux TTC et HT) et les lignes d’articles (chaque ligne a un entries[].type tel que SALE, description, s’il s’agit d’un GOOD ou SERVICE, etc.).
   • CORRECTION : Émet un document correctif (NC pour crédit / ND pour débit) référençant un INVOICE/RECEIPT créé précédemment. Contient les lignes corrigées et un reference_id vers le document original.
   • CANCELLATION : Utilisé pour invalider une transaction entière. Nécessite l’id d’un enregistrement créé précédemment.

   Après la soumission du Record TRANSACTION, SIGN PT effectue les étapes d’émission conformes pour l’opération sélectionnée : il attribue le prochain numéro séquentiel de la série (les numéros ne sont pas pré-attribués), signe et enchaîne le document, et génère les données nécessaires pour la représentation finale orientée client.

   Selon la configuration de déclaration du Contribuable, les mêmes données de transaction sont ensuite soit :

   • incluses dans la déclaration/exportation SAF-T (PT) (pour soumission mensuelle), et/ou
   • déclarées à AT via des services web (par ex., factures via WFA ; documents de transport via WDT, si applicable et si les permissions ont été accordées).

   Une fois le traitement terminé, SIGN PT renvoie (via la réponse du Record et/ou les artefacts récupérables du Record) :

   • le payload de conformité requis pour l’impression (par ex., ATCUD, contenu du code QR, l’extrait de hachage et le numéro de certificat logiciel)
   • les données du document signé/enchaîné nécessaires pour construire la représentation finale du reçu/de la facture, et
   • les informations de statut de traitement du Record (succès/échec et détails d’erreur pertinents).

   📘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.