Planification de l'intégration

Cette page est destinée aux chefs de produit et responsables techniques qui planifient une intégration fiskaly. Elle couvre les estimations d’effort, les exigences d’équipe, les dépendances entre produits, les jalons de conformité et un modèle de calendrier de déploiement.

💡Pour les développeurs

Si vous souhaitez écrire du code, commencez par le Démarrage rapide.

Étape 1 : Choisissez votre architecture API

fiskaly propose deux architectures API. Votre choix dépend des pays dont vous avez besoin :

Si vous avez besoin de…	Utilisez…	Pourquoi
Uniquement l’Allemagne, l’Autriche ou l’Espagne	API Spécialisée pour ce pays	Conçue sur mesure, support le plus approfondi pour ce pays
Uniquement la France ou l’Italie	API Unifiée	Architecture multi-pays — ajouter l’autre prend ~1 semaine
France + Italie (ou + Suède)	API Unifiée	Intégrez une fois, étendez en changeant le schéma payload
Allemagne + France/Italie	Les deux	API Spécialisée pour DE + API Unifiée pour FR/IT. Même schéma auth, modèles de ressources différents.
3+ pays dont FR/IT	Commencez par API Unifiée	Puis ajoutez les API Spécialisées pour DE/AT/ES selon les besoins

Consultez L’API Unifiée pour la comparaison complète de l’architecture, le modèle de ressources et la correspondance des terminologies.

Étape 2 : Déterminez la portée de vos produits

Les produits fiskaly dont vous avez besoin dépendent de l’endroit où vous opérez et des réglementations applicables. Utilisez cet arbre de décision :

Gérez-vous des systèmes POS dans l’un de ces pays ?

• Allemagne -> SIGN DE + DSFinV-K + SUBMIT DE (les trois obligatoires)
• Autriche -> SIGN AT
• France -> SIGN FR (certification NF525 obligatoire)
• Espagne -> SIGN ES (TicketBAI ou Verifactu, selon la région)
• Italie -> SIGN IT
• Suède -> SIGN SE (InfraSec TCS)
• Belgique -> E-Invoice (B2B uniquement, via Peppol)

Avez-vous besoin d’un archivage longue durée conforme ? -> Ajoutez SAFE ou SAFE flex

Souhaitez-vous remplacer les reçus papier ? -> Ajoutez eReceipt (optionnel, tout pays UE)

L’Allemagne est la plus complexe

L’Allemagne nécessite trois produits fonctionnant ensemble. Voici comment ils s’articulent :

SIGN DE (signature des transactions)
  |
  +--> DSFinV-K (génération d'export fiscal, référence les données SIGN DE)
  |
  +--> SUBMIT DE (déclaration ELSTER, référence les clients et TSS SIGN DE)
  |
  +--> SAFE (archivage optionnel des exports)

Pour les autres pays, SIGN est typiquement la seule intégration obligatoire.

Étape 3 : Estimez l’effort d’intégration

Ces calendriers sont typiques pour une équipe de 1 à 2 développeurs backend avec une expérience du domaine POS. Votre calendrier réel dépend de l’architecture de votre POS, de votre cadence de release et de vos exigences de test.

API Spécialisées (SIGN DE, SIGN AT, SIGN ES)

Produit	Première intégration	Depuis SIGN DE	Notes
SIGN DE	4-8 semaines	—	Provisionnement TSS, signature de transactions, QR code reçu, gestion erreurs
SIGN AT	3-5 semaines	1-2 semaines	Le plus proche de SIGN DE. SCU au lieu de TSS, enregistrement FinanzOnline.
SIGN ES	5-7 semaines	2-4 semaines	Gestion des certificats, 6 types de facture, envoi en temps réel

API Unifiée (SIGN FR, SIGN IT, SIGN SE)

Produit	Premier pays API Unifiée	Chaque pays suivant	Depuis SIGN DE	Notes
SIGN FR	4-6 semaines	—	1-3 semaines	La certification NF525 ajoute 4-8 semaines séparément
SIGN IT	4-6 semaines	—	1-3 semaines	Loterie des reçus, gestion des pertes de connexion
FR + IT	4-6 semaines (premier)	~1 semaine (second)	—	Même modèle de ressources — seuls le payload et la fiscalisation du Taxpayer diffèrent
SIGN SE	2-4 semaines	—	—	Actuellement InfraSec TCS (XML, X.509) ; API Unifiée à venir

Produits complémentaires

Produit	Durée	Notes
DSFinV-K	2-4 semaines	Allemagne uniquement. Mappage du modèle de données POS à la taxonomie DSFinV-K.
SUBMIT DE	1-2 semaines	Allemagne uniquement. Simple si SIGN DE est déjà intégré.
SAFE	1 semaine (SAFE) / 2 semaines (flex)	SAFE se lie automatiquement à SIGN ; SAFE flex nécessite une logique d’upload manuelle.
E-Invoice	2-4 semaines	Belgique en production ; autres à venir. Séparé de SIGN.
eReceipt	1-2 semaines	Indépendant du pays. Principalement du travail frontend (affichage QR).

Calendrier typique Allemagne uniquement

Semaines 1-2 :  Configuration du compte, accès sandbox, auth SIGN DE + provisionnement TSS
Semaines 3-5 :  Signature de transactions, génération de reçus, gestion des erreurs
Semaines 5-6 :  Mappage DSFinV-K et génération d'exports
Semaines 6-7 :  Intégration SUBMIT DE
Semaines 7-8 :  Tests end-to-end en sandbox
Semaines 8-9 :  Préparation go-live, provisionnement environnement LIVE
Semaines 9-10 : Déploiement en production, monitoring

Total : ~10 semaines du démarrage à la production pour l’Allemagne (SIGN DE + DSFinV-K + SUBMIT DE).

Calendrier de déploiement multi-pays

Si vous étendez depuis une intégration SIGN DE existante :

Semaine 1 :    Revue de la documentation du pays cible, identification des différences de payload
Semaine 2 :    Implémentation de l'adaptateur spécifique au pays, tests en sandbox
Semaine 3 :    QA, validation de la conformité des reçus, go-live

Total : ~3 semaines par pays supplémentaire (AT, FR, IT, ES).

Étape 4 : Planifiez votre équipe

Rôle	Responsabilité	Quand nécessaire
Développeur backend (1-2)	Intégration API, signature de transactions, gestion des erreurs, logique de retry	Toute la période d’intégration
Développeur frontend (0-1)	Rendu des reçus, affichage QR code, interface eReceipt	Après que la signature backend fonctionne
Ingénieur QA (1)	Tests end-to-end, validation de la conformité, cas limites (timeouts, hors ligne)	Semaines 5+
Chef de produit	Décisions de portée, collecte des exigences de conformité, checklist go-live	Tout au long
DevOps / Infra (0-1)	Gestion des secrets, monitoring, alertes pour les échecs de signature	Préparation go-live

Étape 5 : Comprenez la liste de contrôle de conformité

Avant de passer en production dans n’importe quel pays, vérifiez ces éléments :

Liste de contrôle universelle (tous les pays)

• Identifiants API stockés dans un gestionnaire de secrets (pas dans le code source)
• Mise en cache des tokens implémentée (ne pas se ré-authentifier par transaction)
• Logique de retry avec backoff exponentiel pour les erreurs 5xx et les timeouts
• Timeout de signature configuré (3-5 secondes) et ne bloque pas le paiement
• Le reçu inclut tous les champs obligatoires pour le pays cible
• La gestion des erreurs couvre l’indisponibilité du TSS (voir guide de gestion des erreurs)
• Les tests d’intégration dans l’environnement TEST passent
• Environnement LIVE provisionné via HUB
• Monitoring/alertes configurés pour les échecs de signature et la latence

Liste de contrôle spécifique à l’Allemagne

• TSS créé, PIN Admin défini et TSS initialisé
• Client créé pour chaque terminal POS
• Le reçu inclut le QR code KassenSichV (voir données reçu)
• Le QR code se valide correctement (voir validation QR code)
• L’export DSFinV-K génère et se valide
• La déclaration SUBMIT DE est déposée avec succès auprès d’ELSTER
• Déconnexion Admin après le provisionnement

Liste de contrôle spécifique à la France

• Processus de certification NF525 lancé avec le support fiskaly
• Clôtures de période implémentées (journalières, mensuelles, annuelles)
• Génération des archives automatisée
• Mode replay hors ligne testé

Liste de contrôle spécifique à l’Italie

• Champs de la loterie des reçus (Lotteria degli Scontrini) inclus
• Gestion des pertes de connexion testée
• États de localisation et de système du Taxpayer gérés correctement

Étape 6 : Préparation au go-live

1. Compléter les tests en sandbox

   Exécutez votre suite de tests complète sur l’environnement TEST. Vérifiez tous les types de transactions, les scénarios d’erreur et la génération des exports.

2. Demander l'accès LIVE

   Basculez votre organisation vers l’environnement LIVE via HUB. Contactez votre account manager si vous avez besoin d’assistance.

3. Provisionner les ressources LIVE

   Les ressources de TEST ne sont pas transférées. Réexécutez votre flux de provisionnement (création TSS, enregistrement des clients) dans l’environnement LIVE.

4. Déploiement progressif

   Commencez par un seul emplacement ou terminal. Surveillez la latence de signature, les taux d’erreur et la conformité des reçus pendant 1-2 semaines avant de vous étendre.

5. Configurer le monitoring

   Suivez : taux de succès de signature, latence moyenne de signature, taux d’erreurs 401 (problèmes de rafraîchissement de token) et taux d’erreurs 5xx (problèmes de service). Alertez si le taux d’échec de signature dépasse 1%.

⚠️TEST et LIVE sont complètement séparés

Les TSS, clients, transactions et exports créés en TEST n’existent pas en LIVE. Votre déploiement de go-live doit inclure une étape de provisionnement.

Liens clés pour les PM

Vue d'ensemble des produits

Ce que fait chaque produit et quand vous en avez besoin

Couverture pays (E-Invoice)

Quand les nouveaux modules pays deviennent disponibles

SAFE vs SAFE flex

Quelle option d'archivage convient à votre cas d'usage

Référence des codes d'erreur

Chaque erreur que votre équipe rencontrera et comment la résoudre

HUB (tableau de bord)

Gérez les organisations, les clés API et les exports de conformité sans code

Changelog

Modifications d'API, nouvelles fonctionnalités et avis de dépréciation