Gestion des erreurs et des délais d'attente
La priorité absolue lors de l’implémentation de l’API fiskaly SIGN DE est de maintenir le système POS opérationnel en permanence.
Il n’y a aucune obligation que la caisse doive interrompre son fonctionnement ou être fortement perturbée à quelque moment que ce soit. Assurez-vous que votre intégration ne bloque pas les opérateurs.
Dans le cas optimal, l’API est implémentée de telle sorte que le bon fonctionnement de la caisse enregistreuse peut être garanti en permanence. Voici comment y parvenir.
Définir les délais d’attente correctement
Section intitulée « Définir les délais d’attente correctement »Dans le cas où le TSS est indisponible ou temporairement instable, le processus de paiement ne doit pas être perturbé. Les délais d’attente dépendent fortement de la fréquence du système POS. En tant que fabricant, vous devez décider quelle durée de délai d’attente vous jugez raisonnable. Aucune requête ne devrait jamais rester ouverte assez longtemps pour compromettre le bon fonctionnement de la caisse enregistreuse.
Valeurs de délai d’attente recommandées
Section intitulée « Valeurs de délai d’attente recommandées »| Endpoint | Délai d’attente recommandé | Notes |
|---|---|---|
| Endpoints de transactions | 3 - 5 secondes | Les plus critiques pour le flux de paiement |
| Création et personnalisation du TSS | 30 secondes minimum | Opération de configuration unique |
| Autorisation | 3 - 4 secondes | Renouvellement du jeton, pas à chaque requête |
| Endpoints DSFinV-K | Jusqu’à 10 minutes | Traitement intensif / exports de données |
Nous recommandons de créer la possibilité de définir les délais d’attente (p. ex. une valeur entre 1,5 - 3 secondes) par un administrateur. Ainsi, des ressources de développement précieuses peuvent être économisées et un fonctionnement fluide du POS est possible.
S’il semble y avoir un problème, vérifiez status.fiskaly.com ainsi que la page de support.
Gérer les erreurs avec élégance
Section intitulée « Gérer les erreurs avec élégance »Lorsqu’une requête échoue ou dépasse le délai d’attente, suivez cette approche :
Détecter l'échec
Définissez des délais d’attente appropriés par type d’endpoint (voir le tableau ci-dessus). Lorsqu’un délai d’attente ou une erreur HTTP se produit, interceptez-le avec élégance sans bloquer le paiement.
Continuer le paiement
Permettez à la transaction de se poursuivre même sans signature TSS. Enregistrez la transaction localement avec toutes les données disponibles.
Marquer le reçu
Ajoutez une note claire sur le reçu telle que “TSS indisponible” ou “Signature TSS échouée” comme recommandé par les autorités fiscales.
Enregistrer dans DSFinV-K
Assurez-vous que la transaction non signée apparaît dans l’export DSFinV-K en utilisant le champ
transactions.security.error_messageà la place detransactions.security.tss_tx_id.
Signatures manquantes
Section intitulée « Signatures manquantes »Une signature manquante sur le document ne signifie pas que le document n’est pas conforme à la loi (voir Punkt 7 AEAO to § 146a). Cependant, l’API fiskaly doit être implémentée de telle sorte que chaque transaction demande une signature. S’il n’est pas possible d’en obtenir une, les règles DSFinV-K s’appliquent.
Toutes les transactions, y compris celles sans signature, doivent apparaître dans l’export DSFinV-K. Pour les transactions sans signature, toutes les données connues sont transférées vers l’export DSFinV-K.
DSFinV-K et transactions
Section intitulée « DSFinV-K et transactions »Les autorités fiscales recommandent d’ajouter une note claire sur le reçu pour les transactions non signées, telle que :
“TSS indisponible” ou “Signature TSS échouée”
Lors de l’utilisation de l’API DSFinV-K de fiskaly, le champ
transactions.security.error_message doit être utilisé à la place de
transactions.security.tss_tx_id à l’endpoint insertCashPointClosing dans
le cas de transactions non signées.
Autorisation
Section intitulée « Autorisation »L’autorisation est initialement effectuée via la Clé API et le Secret API. Vous recevrez :
| Jeton | Validité |
|---|---|
access_token | 24 heures |
refresh_token | 48 heures |
Vous pouvez utiliser ces jetons pour vous réautoriser en permanence. Si vous recevez une réponse 401, réauthentifiez-vous simplement via la Clé API et le Secret.
La réautorisation ne doit pas se produire à chaque requête, car cela ajouterait une surcharge inutile à votre processus de paiement. La validité des jetons est de plusieurs heures.
- Définir des délais d’attente appropriés pour chaque type d’endpoint
- Rendre les délais d’attente configurables par un administrateur
- Ne jamais bloquer la caisse — toujours permettre au paiement de se poursuivre
- Enregistrer toutes les transactions dans l’export DSFinV-K, même celles non signées
- Ajouter une note claire sur les reçus lorsqu’une signature est manquante
- Mettre en cache les jetons d’autorisation et les réutiliser dans leur période de validité
Pages associées
Section intitulée « Pages associées »Was this page helpful?