Pour les clients externes

Ce guide fournit un aperçu des étapes nécessaires pour soumettre les données requises aux autorités fiscales conformément aux obligations légales (§146a (4) AO - Code fiscal allemand). Il est destiné aux clients qui n’ont pas implémenté l’API fiskaly SIGN DE.

Cette API a été créée en coopération avec l’administration fiscale de l’État de Hessen.

Le guide se compose de deux parties : Configuration de base et Partie principale - Endpoints SIGN DE x Submission.

Partie 1 : Configuration de base

Création d’un compte

Pour utiliser les services fiskaly, vous devez créer un compte via le fiskaly HUB. Une fois le compte créé, vous êtes invité à créer votre première organisation principale.

Création de la première organisation

La première organisation (principale), représentant le fournisseur de POS, doit être créée via le fiskaly HUB. Une fois créée, vous pouvez procéder à l’ajout d’organisations gérées représentant les emplacements individuels du contribuable. Il est possible d’ajouter un niveau supplémentaire à la structure, vous pouvez trouver un guide ici.

💡tutoriel vidéo

Regardez notre vidéo pour une explication étape par étape sur la configuration de votre compte et de votre première organisation.

📘Organisations principales et gérées : Différences

Une organisation principale (organization) représente un fournisseur de POS ou un détaillant avec son propre système POS, tandis qu’une organisation gérée (managed_ organization) représente l’emplacement d’un commerçant ou d’un point de vente d’un détaillant.

Exemples :

• Si l’organisation principale est un fournisseur de POS, les organisations gérées représentent l’emplacement de chaque client (contribuable).
• Si l’organisation principale est un détaillant avec son propre système POS, les organisations gérées représentent chaque magasin.

Création de la première clé API

Après avoir créé un compte et votre première organisation via HUB, vous devez générer une clé API dans HUB (Paramètres -> Clés API -> CRÉER UNE CLÉ API).

La clé API et le secret sont nécessaires pour générer un token d’accès via l’endpoint authenticate. Ce token est utilisé pour tous les appels API.

POST : Créer une organisation

Utilisez cet endpoint pour créer une organisation gérée. Utilisez l’ID de l’ organisation principale pour le champ managed_by_organization_id dans votre corps de requête. Nous recommandons vivement de configurer une organisation gérée distincte pour chaque emplacement. Ainsi, une structure peut être créée où une organisation gérée correspond à un Établissement.

Partie 2 : Endpoints SIGN DE x Submission

POST : Authentification API

Pour accéder à l’API SIGN DE x Submission, vous avez besoin d’un token JWT valide. Cet endpoint crée le token avec votre api_key et api_secret. Si vous ne disposez pas d’api_key, vous pouvez en créer une via l’endpoint de la Management API createApiKey ou via le fiskaly HUB. L’api_secret sera généré pour vous après la création de l’api_key. Le token doit être envoyé avec chaque requête suivante dans le champ d’en-tête Authorization en utilisant le schéma d’authentification Bearer.

PUT : Créer ou mettre à jour un contribuable

Le Contribuable représente soit une personne physique, soit une entité juridique telle qu’une société. Les informations générales sur le contribuable doivent être fournies ici. Il est créé une seule fois et peut être mis à jour sans déclencher une nouvelle Soumission.

Au sein de chaque (managed_)organization, un seul Contribuable peut et doit être créé.

PUT : Créer ou mettre à jour un établissement

L’Établissement représente chaque lieu d’exploitation physique (Betriebsstätte) et doit être créé même si les données de l’Établissement sont identiques à celles du Contribuable.

Pour les clients qui ont créé une managed_organization distincte pour chaque emplacement, la managed_organization correspond toujours à un Établissement spécifique. Il s’agit de l’approche recommandée.

Si une managed_organization représente plus d’un emplacement d’un même Contribuable, un Établissement distinct doit être créé pour chacun de ces emplacements.

Chaque Contribuable peut posséder plusieurs Établissements, mais chaque Établissement ne peut appartenir qu’à un seul Contribuable et avoir une seule adresse.

📘Note

La création et les mises à jour des TSS et des Clients affectés à un Établissement nécessitent toujours une nouvelle Soumission de l’Établissement concerné dans son ensemble. Les autres Établissements ne nécessitent pas de nouvelle Soumission dans ce cas.

PUT : Créer ou mettre à jour un TSS externe (c.-à-d. un TSS d’un fabricant autre que fiskaly)

Un TSS désigne un Système de Sécurité Technique. Il s’agit d’un ensemble de composants utilisés pour sécuriser, stocker et gérer les données fiscales.

Les TSS externes doivent être ajoutés via cet endpoint.

📘Note

Cet endpoint n’est pas obligatoire pour les clients qui ont implémenté l’API fiskaly SIGN DE et qui n’utilisent pas de TSS externes.

PUT : Créer ou mettre à jour un client externe (c.-à-d. utilisant un TSS d’un fabricant autre que fiskaly)

Un Client représente un appareil POS en utilisation. Les Clients connectés à des instances TSS externes sont ajoutés via cet endpoint.

La mise hors service d’un Client doit être signalée une seule fois, en définissant les paramètres correspondants et en déclenchant une nouvelle Soumission pour l’Établissement concerné. Ensuite, le Client peut être désaffecté de l’Établissement et/ou réaffecté à un autre Établissement en tant que Client mis en service, suivi à nouveau d’une nouvelle Soumission pour l’Établissement concerné.

📘Note

Cet endpoint n’est pas obligatoire pour les clients qui ont implémenté l’API fiskaly SIGN DE et qui n’utilisent pas de TSS externes.

PUT : Créer une soumission

Une Soumission est l’ensemble des informations sur un Établissement spécifique avec tous ses Clients. Elle n’est pas envoyée automatiquement aux autorités fiscales — une requête supplémentaire doit être effectuée via l’endpoint TriggerTransmission.

Afin de transmettre une Soumission, il est nécessaire de télécharger et de consulter le PDF d’aperçu au préalable via l’endpoint GetValidationSuccessfulFile.

📘Note

Les intégrateurs API doivent s’assurer que les contribuables réels ont vérifié que les données de Soumission générées sont correctes avant qu’elles soient envoyées aux autorités fiscales.

PUT : Déclencher la transmission

La Transmission est le processus par lequel les données de la Soumission sont transférées vers le serveur ELSTER (ELektronische STeuer ERklärung). Une seule Transmission peut être déclenchée par Soumission.

Une fois déclenchée, une Transmission peut être annulée, tant qu’elle est en cours de traitement dans l’API SIGN DE x Submission, et qu’elle n’a pas encore été transmise à ELSTER. Comme la Transmission a généralement lieu en quelques secondes, la fenêtre pour une annulation réussie est courte. Après une annulation réussie, une Transmission pour la Soumission spécifique peut être déclenchée à nouveau.

Utilisez cet endpoint pour déclencher une Transmission d’une Soumission spécifique vers les autorités fiscales. Veuillez noter que cela n’est possible que si la Soumission est dans l’état READY_FOR_TRANSMISSION, ce qui indique que les données contenues dans la Soumission ont été vérifiées pour leur validité syntaxique et leur exhaustivité. Cependant, ce n’est pas une confirmation de l’exactitude factuelle.

📘Note

Le Contribuable est légalement tenu de vérifier les données de la Soumission pour leur exactitude avant de déclencher la Transmission. Le fait de déclencher la Soumission indique le consentement du Contribuable et l’assomption de responsabilité pour l’exactitude des données transmises. Dans le cas où des données erronées auraient été incluses dans une Soumission transmise, cela peut être rectifié en créant simplement et en transmettant une nouvelle Soumission avec les données correctes.