Mode hors ligne

⚠️ Vous consultez la documentation de la version d’API 2025-08-12. La dernière version est 2026-05-04. Les changements clés incluent une terminologie mise à jour (Asset → Organization, Entity → Taxpayer/Location).

Ce guide explique comment maintenir le système de caisse opérationnel lors de coupures réseau temporaires (perte de connectivité entre le système de caisse et l’API SIGN FR) et comment mettre en mémoire tampon les enregistrements hors ligne de manière sécurisée en vue d’une relecture ultérieure.

En mode en ligne, conserver deux valeurs de chaque réponse réussie de createRecord : l’ID du dernier enregistrement en ligne et la dernière signature de journalisation en ligne. Ces valeurs ancrent les données hors ligne au journal du serveur et fournissent la graine cryptographique initiale.

Lorsque la connectivité est interrompue, passer en mode hors ligne. Écrire chaque nouvel enregistrement dans un tampon local durable dans l’ordre d’origine. Il est possible d’opérer hors ligne pendant 24 heures maximum à partir du premier enregistrement non envoyé. Passé ce délai, cesser de traiter de nouvelles transactions, mettre hors service le système de caisse et le réinitialiser.

Lors de la reconnexion, rejouer le tampon. Envelopper chaque enregistrement dans une « Replay Intention » incluant l’horodatage d’origine, un ID d’enregistrement d’ancrage et une graine. Pour les transactions, ajouter un décalage qui relie la transaction à l’intention correspondante dans le tampon.

Garantir l’intégrité en hachant le contenu canonisé (hors métadonnées) avec SHA-256. Initialiser le premier enregistrement hors ligne avec la dernière signature de journalisation en ligne comme graine, puis chaîner chaque entrée suivante au hachage de l’enregistrement précédent.

Le diagramme illustre le flux de travail et met en évidence les étapes essentielles pour gérer correctement le mode hors ligne et le processus de relecture.

Diagramme d’implémentation du mode hors ligne et de relecture

ÉTAPE 1 : Mode en ligne

En connectivité normale, deux champs spécifiques de chaque réponse réussie de createRecord doivent être suivis dans le système de caisse : l’ID du dernier enregistrement en ligne (content.id) et la signature de journalisation du dernier enregistrement en ligne (content.journal.signature). Ces valeurs sont essentielles pour ancrer les enregistrements hors ligne et fournir la graine cryptographique initiale pour le hachage.

ÉTAPE 2 : Panne – Mise en tampon locale (stockage)

Lorsque la connectivité est perdue, passer en mode hors ligne et écrire chaque nouvel enregistrement dans un tampon local durable, en conservant l’ordre d’origine. Un système de caisse peut fonctionner hors ligne pendant au maximum 24 heures à partir du premier enregistrement non envoyé ; si la panne dépasse cette limite, cesser d’accepter de nouvelles transactions, mettre hors service le système de caisse et le réinitialiser. Lorsque la connexion est rétablie (étape 4), envelopper chaque enregistrement mis en tampon dans une enveloppe « Replay Intention » incluant l’horodatage d’origine, l’ID d’enregistrement d’ancrage et une graine. Pour les enregistrements de transaction, inclure également un décalage qui relie la transaction à l’index d’intention correct dans le tampon. Rejouer les enregistrements dans l’ordre.

ÉTAPE 3 : Sécurité – Hachage et graines

Pour garantir l’intégrité des données, calculer un hachage SHA-256 pour le contenu canonisé de chaque enregistrement, en excluant les métadonnées d’origine. Le premier enregistrement hors ligne utilise la dernière signature de journalisation en ligne comme graine, tandis que tous les enregistrements suivants utilisent le hachage de l’enregistrement précédent comme graine. Cela crée une chaîne sécurisée que le serveur peut vérifier lors du processus de relecture.

ÉTAPE 4 : Restauration – Relecture des enregistrements

Une fois la connectivité rétablie, rejouer tous les enregistrements mis en tampon dans leur séquence d’origine via l’endpoint createRecord de type INTENTION et operation.type REPLAY. Chaque requête doit inclure deux paramètres d’en-tête obligatoires : X-Replay-Hash (le hachage Base64 créé hors ligne) et X-Replay-Remaining (le nombre d’enregistrements encore dans le tampon). Les enregistrements ne doivent être supprimés du stockage local qu’après confirmation réussie par le serveur.

ÉTAPE 5 : Finalisation – Retour au mode en ligne

Si le dernier enregistrement dans le tampon est une intention, le commerçant doit capturer l’ID résolu de la réponse du serveur pour l’utiliser comme ancre pour sa première nouvelle transaction en ligne. Si la connectivité est à nouveau interrompue pendant la relecture, revenir simplement à la phase hors ligne et continuer à utiliser les données d’ancrage d’origine jusqu’à ce que l’intégralité du tampon soit vidée et qu’une nouvelle réponse en ligne soit reçue.

Exemples minimaux de relecture :

Paramètres d’en-tête

X-Replay-Hash: <offline computed SHA-256 hash, base64-encoded>
X-Replay-Remaining: <remaining after this one>

Intention → Transaction (encapsulée pour relecture)

{
  "content": {
    "type": "INTENTION",
    "system": { "id": "0199147a-8627-7101-aecc-d2149aa99ea7" },
    "operation": {
      "type": "REPLAY",
      "recorded_at": "2025-11-14T10:30:00+01:00",
      "record": { "id": "01695553-c90c-745a-b76f-770d7b3dcb6d" },
      "seed": "<base64 seed>",
      "content": {
        "type": "TRANSACTION",
        "record": {
          "id": "019a7e09-1590-738f-aa21-8ca7b58d9ccc",
          "offset": "0"
        },
        "operation": { "type": "RECEIPT" }
      }
    }
  }
}