Intégration étape par étape

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 réussir votre intégration.

Pour l’intégration, vous devrez utiliser le fiskaly HUB, la Management API et la SIGN AT API.

Avant de plonger dans la configuration, voici ce que vous allez configurer :

🏢

Organisation

Votre entité de niveau supérieur dans fiskaly. Les organisations gérées représentent des commerçants individuels.

🔑

Clé API et Secret

Identifiants générés dans HUB, utilisés pour authentifier toutes les requêtes ultérieures de l'API SIGN AT.

🇦🇹

Authentification FON

Identifiants FinanzOnline fournis par le contribuable pour activer la synchronisation avec l'autorité fiscale autrichienne.

🛡️

SCU (Signature Creation Unit)

Le composant central de signature. Une SCU par organisation gérée se charge de la signature cryptographique des reçus.

💻

Caisse enregistreuse

Représente une caisse enregistreuse physique ou virtuelle. Doit être enregistrée auprès de FinanzOnline et initialisée.

🧾

Reçu

Un document fiscal signé conforme à la RKSV contenant les données du code QR et les métadonnées du reçu.

Prérequis

📘Avant de commencer

Vous avez besoin d’un compte fiskaly et d’un accès au fiskaly HUB. Si vous n’avez pas encore de compte, inscrivez-vous ici.

Vous aurez également besoin d’un outil pour effectuer des requêtes HTTP — par exemple cURL (ligne de commande), Postman ou le code de votre propre application. Vous pouvez télécharger notre collection Postman, qui peut faciliter votre intégration.

Flux de travail d’intégration

Le diagramme ci-dessous illustre le flux de travail et met en évidence les étapes essentielles nécessaires pour réussir votre intégration. Chaque vignette renvoie directement à l’étape de configuration correspondante ci-dessous.

Configuration étape par étape

1. S'inscrire sur le Dashboard

   Commencez par vous inscrire sur le fiskaly HUB. La création d’un compte est la première étape, après quoi vous pouvez procéder à la mise en place de la structure organisationnelle de votre entreprise dans notre système.

   💡Démarrez rapidement

   HUB propose un flux d’intégration guidé qui vous accompagne tout au long de la création du compte et de la configuration initiale.

2. Créer la première organisation

   Continuez en créant votre première organisation à l’aide de HUB. Cette organisation représentera le fournisseur de TPV ou le commerçant avec son propre système TPV. Il est nécessaire d’inclure l’adresse de facturation à cette étape. Cette adresse sera uniquement utilisée à des fins de facturation par fiskaly.

   💡Pas encore prêt pour la production ?

   À des fins de test, vous n’avez pas besoin de remplir tous les champs. Vous pouvez laisser l’adresse de facturation vide et la compléter ultérieurement.

3. Créer des organisations gérées

   Après avoir établi votre première organisation, vous procéderez à la création d’organisations gérées. Chaque organisation gérée représente un commerçant, vous permettant de les gérer séparément. Si vous envisagez d’automatiser votre processus, nous recommandons d’utiliser l’endpoint createOrganization de la Management API.

   💡Automatisez à grande échelle

   Si vous gérez de nombreux commerçants, utilisez la Management API pour créer des organisations gérées de manière programmatique plutôt que manuellement via HUB.

4. Créer une clé API

   L’étape suivante consiste à générer une clé API au sein de chaque organisation gérée. Cela peut être fait via HUB ou l’endpoint createApiKey de la Management API. Cette paire clé API et secret est nécessaire pour générer un token d’accès, utilisé pour tous les appels API ultérieurs.

   ⚠️Conservez vos identifiants en sécurité

   L’API Secret n’est affiché qu’une seule fois. Assurez-vous de le copier et de le stocker dans un endroit sécurisé avant de fermer la boîte de dialogue.

   📘TEST vs. LIVE

   Les clés API générées dans l’environnement TEST créeront des ressources TEST, tandis que celles de l’environnement LIVE créeront des ressources LIVE. Pour plus de détails, consultez notre article sur les environnements TEST et LIVE.

   À partir de l’étape suivante, vous utiliserez la SIGN AT API.

   S’authentifier avec l’API

   Utilisez votre clé API et votre secret pour obtenir un token d’accès. Ce token est requis pour toutes les requêtes ultérieures.

   cURLJavaScript

   curl -X POST https://rksv.fiskaly.com/api/v1/auth \
     -H "Content-Type: application/json" \
     -d '{
       "api_key": "your_api_key",
       "api_secret": "your_api_secret"
     }'

   const response = await fetch(
     "https://rksv.fiskaly.com/api/v1/auth",
     {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         api_key: "your_api_key",
         api_secret: "your_api_secret",
       }),
     }
   );
   
   const { access_token } = await response.json();

   La réponse contient un access_token que vous devez inclure en tant que token Bearer dans l’en-tête Authorization de toutes les requêtes suivantes.

5. Authentifier FON

   Après vous être authentifié avec la paire clé API et secret générée précédemment, il est nécessaire d’appeler l’endpoint authenticateFon une fois par contribuable.

   Pour activer la synchronisation avec FinanzOnline, le contribuable doit d’abord créer l‘“Utilisateur du Service Web de Caisse Enregistreuse” directement dans FinanzOnline et vous fournir les identifiants de cet utilisateur.

   📘Les identifiants FON sont distincts

   Les identifiants ne correspondent pas aux identifiants généraux de FinanzOnline. Ils correspondent aux identifiants de l’Utilisateur du Service Web de Caisse Enregistreuse dédié créé par le contribuable.

   cURLJavaScript

   curl -X POST https://rksv.fiskaly.com/api/v1/fon/auth \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "fon_participant_id": "your_fon_participant_id",
       "fon_user_id": "your_fon_user_id",
       "fon_user_pin": "your_fon_user_pin"
     }'

   const fonResponse = await fetch(
     "https://rksv.fiskaly.com/api/v1/fon/auth",
     {
       method: "POST",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         fon_participant_id: "your_fon_participant_id",
         fon_user_id: "your_fon_user_id",
         fon_user_pin: "your_fon_user_pin",
       }),
     }
   );

6. Créer la SCU

   Continuez en créant une SCU via l’endpoint createSignatureCreationUnit. Par organisation gérée, une seule SCU doit être créée. Une fois créée, l’état d’une SCU sera CREATED.

   cURLJavaScript

   SCU_ID=$(uuidgen)
   
   curl -X PUT "https://rksv.fiskaly.com/api/v1/signature-creation-unit/${SCU_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "legal_entity_id": {
         "vat_id": "ATU12345678"
       }
     }'

   const scuId = crypto.randomUUID();
   
   const scuResponse = await fetch(
     `https://rksv.fiskaly.com/api/v1/signature-creation-unit/${scuId}`,
     {
       method: "PUT",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         legal_entity_id: {
           vat_id: "ATU12345678",
         },
       }),
     }
   );

   📘Note

   Remplacez ATU12345678 par le numéro de TVA réel du contribuable.
7. Créer la/les caisse(s) enregistreuse(s)

   Continuez en créant au moins une caisse enregistreuse via l’endpoint createCashRegister. Le nombre de caisses enregistreuses doit correspondre au nombre de caisses enregistreuses utilisées dans un magasin ou un établissement particulier. La création d’une caisse enregistreuse définit l’état à CREATED.

   cURLJavaScript

   CASH_REGISTER_ID=$(uuidgen)
   
   curl -X PUT "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "description": "Main POS Terminal"
     }'

   const cashRegisterId = crypto.randomUUID();
   
   const crResponse = await fetch(
     `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}`,
     {
       method: "PUT",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         description: "Main POS Terminal",
       }),
     }
   );

8. Mettre à jour la SCU à INITIALIZED

   Pour signer des reçus, la SCU et la/les caisse(s) enregistreuse(s) doivent être mises à jour à INITIALIZED. Appelez l’endpoint updateSignatureCreationUnit et faites-la transitionner à l’état INITIALIZED. Cette transition d’état enregistre automatiquement la SCU dans le portail FinanzOnline.

   cURLJavaScript

   curl -X PATCH "https://rksv.fiskaly.com/api/v1/signature-creation-unit/${SCU_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "state": "INITIALIZED"
     }'

   await fetch(
     `https://rksv.fiskaly.com/api/v1/signature-creation-unit/${scuId}`,
     {
       method: "PATCH",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         state: "INITIALIZED",
       }),
     }
   );

9. Mettre à jour la/les caisse(s) enregistreuse(s)

   Contrairement à la mise à jour de la SCU, la/les caisse(s) enregistreuse(s) doit/doivent être mise(s) à jour deux fois via updateCashRegister :

   a) Enregistrer la caisse enregistreuse

   Premièrement, changez l’état de la caisse enregistreuse à REGISTERED. Cette transition d’état enregistre automatiquement la caisse enregistreuse dans le portail FinanzOnline.

   cURLJavaScript

   curl -X PATCH "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "state": "REGISTERED"
     }'

   await fetch(
     `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}`,
     {
       method: "PATCH",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         state: "REGISTERED",
       }),
     }
   );

   b) Initialiser la caisse enregistreuse

   Ensuite, dans un deuxième appel, changez l’état à INITIALIZED. Cette transition d’état déclenche la création et la validation du reçu initial dans le portail FinanzOnline.

   cURLJavaScript

   curl -X PATCH "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "state": "INITIALIZED"
     }'

   await fetch(
     `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}`,
     {
       method: "PATCH",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         state: "INITIALIZED",
       }),
     }
   );

   La SCU et la caisse enregistreuse sont maintenant prêtes à signer des reçus.

10. Signer les reçus

    Avec toutes les étapes précédentes terminées, vous êtes maintenant prêt à signer des reçus via l’endpoint signReceipt.

    cURLJavaScript

    RECEIPT_ID=$(uuidgen)
    
    curl -X PUT "https://rksv.fiskaly.com/api/v1/cash-register/${CASH_REGISTER_ID}/receipt/${RECEIPT_ID}" \
      -H "Authorization: Bearer ${ACCESS_TOKEN}" \
      -H "Content-Type: application/json" \
      -d '{
        "receipt_type": "NORMAL",
        "schema": {
          "standard_v1": {
            "receipt": {
              "amounts_per_vat_rate": [
                {
                  "vat_rate": "STANDARD",
                  "amount": "12.00"
                }
              ],
              "amounts_per_payment_type": [
                {
                  "payment_type": "CASH",
                  "amount": "12.00"
                }
              ]
            }
          }
        }
      }'

    const receiptId = crypto.randomUUID();
    
    const receiptResponse = await fetch(
      `https://rksv.fiskaly.com/api/v1/cash-register/${cashRegisterId}/receipt/${receiptId}`,
      {
        method: "PUT",
        headers: {
          "Authorization": `Bearer ${accessToken}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          receipt_type: "NORMAL",
          schema: {
            standard_v1: {
              receipt: {
                amounts_per_vat_rate: [
                  { vat_rate: "STANDARD", amount: "12.00" },
                ],
                amounts_per_payment_type: [
                  { payment_type: "CASH", amount: "12.00" },
                ],
              },
            },
          },
        }),
      }
    );
    
    const signedReceipt = await receiptResponse.json();

    SIGN AT garantit que tous les reçus sont conformes à la RKSV. La réponse contient toutes les informations nécessaires pour compléter le reçu final remis au client :

    • qr_code_data — contient les données pour le code QR RKSV à afficher sous forme graphique
    • receipt_number, time_signature et cash_register_serial_number — informations à afficher sous forme textuelle
    • Tous les montants bruts bruts

    💡Automatiser la configuration

    Cette séquence complète de requêtes peut être intégrée dans une solution de provisionnement “en un clic” ne nécessitant aucune interaction manuelle de l’utilisateur. Les détails d’implémentation vous appartiennent.

Prochaines étapes

Documentation API SIGN AT

Documentation complète de l'API pour l'endpoint RKSV v1 — toutes les ressources, paramètres et réponses.

Données du reçu

Référence détaillée pour les champs du reçu, les taux de TVA et les types de paiement pris en charge par SIGN AT.

Glossaire

Termes clés et définitions pour le système de conformité fiscale autrichien RKSV.

Guide HUB

Apprenez à gérer les organisations, les clés API et les ressources via fiskaly HUB.