Modalità offline

⚠️ Stai visualizzando la documentazione per la versione API 2025-08-12. La versione più recente è 2026-05-04. Le modifiche principali includono la terminologia aggiornata (Asset → Organization, Entity → Taxpayer/Location).

Questa guida mostra come mantenere il sistema di cassa operativo durante interruzioni temporanee della rete (perdita di connettività tra il sistema di cassa e l’API di SIGN FR) e come memorizzare in modo sicuro i record offline per la riproduzione successiva.

In modalità online, conservare due valori da ogni risposta riuscita di createRecord: l’ID dell’ultimo record online e l’ultima firma di giornalizzazione online. Questi ancorano i dati offline al giornale del server e forniscono il seme crittografico iniziale.

Quando la connettività si interrompe, passare alla modalità offline. Scrivere ogni nuovo record in un buffer locale duraturo nell’ordine originale. È possibile operare offline per un massimo di 24 ore dal primo record non inviato. Dopo di che, interrompere l’elaborazione di nuove transazioni, mettere fuori servizio il sistema di cassa e ripristinarlo.

Al ripristino della connessione, riprodurre il buffer. Avvolgere ogni record in una “Replay Intention” che include il timestamp originale, un ID di record di ancoraggio e un seme. Per le transazioni, aggiungere un offset che colleghi la transazione alla corrispondente intention nel buffer.

Garantire l’integrità eseguendo l’hashing del contenuto canonizzato (esclusi i metadati) con SHA-256. Inizializzare il primo record offline con l’ultima firma di giornalizzazione online come seme, quindi concatenare ogni voce successiva all’hash del record precedente.

Il diagramma illustra il flusso di lavoro e mette in evidenza i passaggi essenziali necessari per gestire correttamente la modalità offline e il processo di riproduzione.

Diagramma di implementazione della modalità offline e riproduzione

PASSO 1: Modalità online

Durante la normale connettività, due campi specifici di ogni risposta riuscita di createRecord devono essere tracciati nel sistema di cassa: l’ID dell’ultimo record online (content.id) e la firma di giornalizzazione dell’ultimo record online (content.journal.signature). Questi valori sono essenziali per ancorare i record offline e fornire il seme crittografico iniziale per l’hashing.

PASSO 2: Interruzione – Buffering locale (archiviazione)

Quando la connettività viene persa, passare alla modalità offline e scrivere ogni nuovo record in un buffer locale duraturo, mantenendo l’ordine originale. Un sistema di cassa può operare offline per un massimo di 24 ore dal primo record non inviato; se l’interruzione supera questo limite, interrompere l’accettazione di nuove transazioni, mettere fuori servizio il sistema di cassa e ripristinarlo. Quando la connessione viene ripristinata (passo 4), avvolgere ogni record memorizzato nel buffer in una busta “Replay Intention” che include il timestamp originale, l’ID del record di ancoraggio e un seme. Per i record di transazione, includere anche un offset che colleghi la transazione all’indice di intention corretto nel buffer. Riprodurre i record in ordine.

PASSO 3: Sicurezza – Hashing e semi

Per garantire l’integrità dei dati, calcolare un hash SHA-256 per il contenuto canonizzato di ogni record, escludendo i metadati originali. Il primo record offline utilizza l’ultima firma di giornalizzazione online come seme, mentre tutti i record successivi utilizzano l’hash del record precedente come seme. Questo crea una catena sicura che il server può verificare durante il processo di riproduzione.

PASSO 4: Ripristino – Riproduzione dei record

Una volta ripristinata la connettività, riprodurre tutti i record nel buffer nella loro sequenza originale utilizzando l’endpoint createRecord di tipo INTENTION e operation.type REPLAY. Ogni richiesta deve includere due parametri header obbligatori: X-Replay-Hash (l’hash Base64 creato offline) e X-Replay-Remaining (il conteggio dei record ancora nel buffer). I record devono essere eliminati dall’archivio locale solo dopo che il server li ha riconosciuti con successo.

PASSO 5: Completamento – Ritorno alla modalità online

Se l’ultimo record nel buffer è una intention, il commerciante deve acquisire l’ID risolto dalla risposta del server da utilizzare come ancoraggio per la prima nuova transazione online. Se la connettività si interrompe nuovamente durante la riproduzione, tornare semplicemente alla fase offline e continuare a utilizzare i dati di ancoraggio originali finché l’intero buffer non viene svuotato e viene ricevuta una nuova risposta online.

Esempi minimi di riproduzione:

Parametri header

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

Intention → Transaction (incapsulata per la riproduzione)

{
  "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" }
      }
    }
  }
}