Modo fuera de línea

Esta guía muestra cómo mantener el sistema de caja en funcionamiento durante interrupciones de red temporales (pérdida de conectividad entre el sistema de caja y la API de SIGN FR) y cómo almacenar de forma segura los registros sin conexión para su reproducción posterior.

En modo en línea, conservar dos valores de cada respuesta exitosa de createRecord: el ID del último registro en línea y la última firma de diario en línea. Estos anclan los datos sin conexión al diario del servidor y proporcionan la semilla criptográfica inicial.

Cuando se pierde la conectividad, cambiar al modo fuera de línea. Escribir cada nuevo registro en un búfer local duradero en el orden original. Se puede operar sin conexión hasta 24 horas desde el primer registro no enviado. Después de eso, dejar de procesar nuevas transacciones, retirar el sistema de caja del servicio y restablecerlo.

Al reconectarse, reproducir el búfer. Envolver cada registro en una “Replay Intention” que incluye la marca de tiempo original, un ID de registro de anclaje y una semilla. Para las transacciones, añadir un desplazamiento que vincula la transacción con su intención correspondiente en el búfer.

Garantizar la integridad mediante el hash del contenido canonizado (excluyendo metadatos) con SHA-256. Inicializar el primer registro sin conexión con la última firma de diario en línea como semilla, luego encadenar cada entrada posterior al hash del registro anterior.

El diagrama ilustra el flujo de trabajo y destaca los pasos esenciales necesarios para manejar correctamente el modo fuera de línea y el proceso de reproducción.

Diagrama de implementación de modo fuera de línea y reproducción

PASO 1: Modo en línea

Durante la conectividad normal, dos campos específicos de cada respuesta exitosa de createRecord deben rastrearse en el sistema de caja: el ID del último registro en línea (content.id) y la firma de diario del último registro en línea (content.journal.signature). Estos valores son esenciales para anclar los registros sin conexión y proporcionar la semilla criptográfica inicial para el hash.

PASO 2: Interrupción – Almacenamiento en búfer local (almacenamiento)

Cuando se pierde la conectividad, cambiar al modo fuera de línea y escribir cada nuevo registro en un búfer local duradero, manteniendo el orden original. Un sistema de caja puede operar sin conexión durante un máximo de 24 horas desde el primer registro no enviado; si la interrupción supera este límite, dejar de aceptar nuevas transacciones, retirar el sistema de caja del servicio y restablecerlo. Cuando se restaure la conexión (paso 4), envolver cada registro almacenado en un sobre “Replay Intention” que incluye la marca de tiempo original, el ID de registro de anclaje y una semilla. Para los registros de transacciones, incluir también un desplazamiento que vincula la transacción con el índice de intención correcto en el búfer. Reproducir los registros en orden.

PASO 3: Seguridad – Hashing y semillas

Para garantizar la integridad de los datos, calcular un hash SHA-256 para el contenido canonizado de cada registro, excluyendo los metadatos originales. El primer registro sin conexión utiliza la última firma de diario en línea como semilla, mientras que todos los registros posteriores utilizan el hash del registro anterior como semilla. Esto crea una cadena segura que el servidor puede verificar durante el proceso de reproducción.

PASO 4: Restauración – Reproducción de registros

Una vez restaurada la conectividad, reproducir todos los registros almacenados en su secuencia original utilizando el endpoint createRecord de tipo INTENTION y operation.type REPLAY. Cada solicitud debe incluir dos parámetros de encabezado obligatorios: X-Replay-Hash (el hash Base64 creado sin conexión) y X-Replay-Remaining (el recuento de registros que aún están en el búfer). Los registros solo deben eliminarse del almacenamiento local después de que el servidor los reconozca correctamente.

PASO 5: Finalización – Retorno al modo en línea

Si el último registro en el búfer es una intención, el comerciante debe capturar el ID resuelto de la respuesta del servidor para usarlo como ancla para tu primera nueva transacción en línea. Si la conectividad se interrumpe nuevamente durante la reproducción, simplemente volver a la fase sin conexión y continuar utilizando los datos de anclaje originales hasta que todo el búfer se haya vaciado y se reciba una nueva respuesta en línea.

Ejemplos mínimos de reproducción:

Parámetros de encabezado

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

Intention → Transaction (envuelta para reproducción)

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