Pour les clients SIGN ES

Guide d’intégration SIGN PT pour les clients SIGN ES

Ce guide aide les équipes qui ont déjà intégré SIGN ES à comprendre comment le même flux métier s’applique dans SIGN PT en utilisant l’approche Unified API de fiskaly.

De SIGN ES à SIGN PT

Si vous connaissez déjà SIGN ES, de nombreuses parties du flux vous sembleront familières. En même temps, SIGN PT introduit des différences importantes dans la structure des endpoints, la dénomination des ressources et la façon dont les ressources évoluent dans leur cycle de vie.

Aperçu comparatif

SIGN ES	SIGN PT / Unified API	Signification
Organisation principale	Organization::GROUP	Représente l’intégrateur (fournisseurs de logiciels ou marchands avec leur propre système de facturation).
Organisation gérée	Organization::UNIT	Représente un NIF (marchand ou contribuable).
Un contribuable par organisation gérée	Contribuable lié à une ou plusieurs ressources Location::BRANCH	Un contribuable peut opérer depuis différents sites commerciaux. Location::BRANCH représente les emplacements individuels de magasin.
signer	géré automatiquement	Le composant de signature est géré automatiquement dans le flux Unified API. L’intégrateur n’a pas besoin de créer cette ressource.
client	System::FISCAL_DEVICE	Les terminaux POS/facturation sont représentés en tant que systèmes plutôt qu’en objets client.
invoice	Record::INTENTION et Record::TRANSACTION	Les factures ou reçus sont gérés en tant que records, avec deux appels : INTENTION pour indiquer l’intention d’émettre un reçu ou une facture, et TRANSACTION avec le contenu final du reçu ou de la facture.
UUID définis par le client	UUID attribués automatiquement plus X-Idempotency-Key	Vous ne fournissez plus directement les UUID des ressources ; l’idempotence protège contre les doublons.

Avant de commencer

📘Prérequis

Vous avez besoin d’un compte fiskaly et d’un accès au fiskaly HUB. Vous aurez également besoin d’un outil pour effectuer des requêtes HTTP, tel que cURL, Postman ou votre propre code d’application.

Si vous avez déjà intégré SIGN ES, le flux métier vous semblera familier, mais la configuration est plus explicite dans SIGN PT et utilise le modèle de ressources Unified API. Avec cette intégration, vous débloquerez plusieurs pays avec une seule intégration.

Avant de commencer, il est utile de penser en termes de ressources à configurer :

• Organization — un GROUP pour la structure de niveau supérieur et une ou plusieurs organisations UNIT pour les marchands ou contribuables individuels.
• API Key et Token — des identifiants créés dans HUB puis échangés contre des tokens utilisés dans le flux Unified API.
• Taxpayer — une ressource COMPANY ou INDIVIDUAL représentant l’entité légale qui émet des documents fiscaux.
• Location — une ressource BRANCH pour chaque magasin physique ou site opérationnel.
• System — une ressource FISCAL_DEVICE représentant le POS ou l’appareil fiscal qui émet les documents.
• Record — un flux fiscal en deux étapes utilisant INTENTION et TRANSACTION au lieu de créer directement des factures.

Flux d’intégration

Étape	Ce que vous faites	Pourquoi elle existe
1. S’inscrire sur HUB	Créez votre compte fiskaly dans HUB	C’est le point d’entrée pour configurer votre organisation et vos identifiants API.
2. Créer votre première organisation	Créez votre première Organization::GROUP dans HUB	Cela représente le fournisseur POS ou le marchand au niveau supérieur. Après cette étape, créez une clé API pour cette organisation dans HUB.
3. Créer une clé API	Générez une clé API et un secret pour le groupe dans HUB	Vous avez besoin de ces identifiants pour vous authentifier et poursuivre la configuration.
4. Créer un token	Appeler createToken	Ce token est utilisé pour les prochaines requêtes API.
5. Créer une organisation UNIT	Créer une Organization::UNIT par contribuable	Cela remplace l’ancien concept d’organisation gérée.
6. Créer une clé API sujet	Appeler createSubject avec X-Scope-Identifier	Cela lie une clé API à la bonne Organization::UNIT.
7. Créer un token scopé	Créer un second token pour le scope de l’unité	Ce token est ensuite utilisé pour les ressources au niveau du contribuable et les ressources opérationnelles.
8. Créer le contribuable	Créer un Taxpayer::COMPANY ou Taxpayer::INDIVIDUAL	Cela représente l’entité légale qui émet les documents fiscaux.
9. Créer l’emplacement	Créer un Location::BRANCH pour chaque magasin ou site opérationnel	Cela rend chaque emplacement commercial explicite dans le modèle.
10. Créer le système	Créer un System::FISCAL_DEVICE et les systèmes POS associés	Cela remplace la configuration du signer et du client.
11. Créer l’enregistrement fiscal	Créer l’opération fiscale sous forme de records	Cela remplace le flux orienté facture de SIGN ES.

Traduction pratique

Pour une intégration SIGN ES existante, la façon la plus claire de traduire votre modèle est :

• managed organization devient Organization::UNIT
• taxpayer aura une ou plusieurs ressources Location::BRANCH connectées, selon le nombre de sites commerciaux
• signer est géré automatiquement par le flux Unified API
• client devient System::FISCAL_DEVICE
• invoice devient un Record

Comportement des ressources

Une différence importante par rapport à SIGN ES est la façon dont les ressources opérationnelles deviennent utilisables.

Dans SIGN ES, les ressources clés sont généralement prêtes à l’emploi immédiatement après leur création.

Dans SIGN PT, les ressources telles que Taxpayer, Location et System suivent un cycle de vie :

• elles sont d’abord créées dans l’état ACQUIRED
• elles doivent ensuite être mises à jour vers COMMISSIONED
• ce n’est qu’après cela qu’elles sont prêtes pour l’utilisation opérationnelle

Cela signifie que le flux de configuration comprend une étape d’activation explicite pour les ressources qui sont immédiatement utilisables dans SIGN ES.

États et modes du Record

Un Record traverse différents états et modes au cours de son cycle de vie. Certains changements se produisent lorsque vous appelez l’API, et d’autres se produisent automatiquement pendant que le système traite le Record.

SIGN PT

États

État UAPI	Signification	Équivalent SIGN ES
Accepted	Le Record a été reçu correctement et est en cours de traitement	Facture créée avec succès (ISSUED) et prête à être transmise — équivalent à une réponse 200 OK dans SIGN ES.
Rejected	Le Record a échoué et ne sera pas traité davantage	La création de la facture échoue, aucune facture n’est stockée — équivalent à une réponse d’erreur 400 ou 500 dans SIGN ES.
Completed	Le Record a été traité avec succès par l’autorité correspondante	Facture acceptée par l’autorité fiscale — équivalent au statut d’enregistrement REGISTERED dans SIGN ES.
Failed	Le Record n’a pas pu être traité par l’autorité correspondante	Facture envoyée mais rejetée ou acceptée avec des erreurs par l’autorité fiscale — équivalent au statut d’enregistrement REQUIRES_INSPECTION ou REQUIRES_CORRECTION dans SIGN ES.

Modes

Mode UAPI	Signification	Équivalent SIGN ES
Processing	Le Record est en cours de traitement (entre la création et tout état final)	Facture ISSUED en attente de réponse de l’agence fiscale — équivalent au statut d’enregistrement PENDING dans SIGN ES.
Finished	Le traitement est terminé ; l’état est maintenant Completed, Failed ou Rejected	La facture a un statut d’enregistrement final : REGISTERED, REQUIRES_CORRECTING ou REQUIRES_INSPECTION.