🔗 SoWasIt - Documentación Técnica

Conceptos Técnicos y Garantías

SoWasIt es una infraestructura de anclaje criptográfico diseñada para garantizar la integridad absoluta de sus datos mediante pruebas de existencia inmutables y matemáticamente verificables.

Mecanismo de Anclaje

La singularidad de SoWasIt radica en su arquitectura de doble capa:

[ Votre App ] -> [ Chaîne Privée ] -> [ Chaîne d'Ancrage Publique ]
      |               |                       |
   Données      Ordre & Contexte        Preuve Globale

Cada evento de su aplicación se registra primero en su cadena privada (para mantener la confidencialidad de sus datos) y luego se ancla inmediatamente en la cadena pública compartida.

Atomicidad y Fiabilidad

Para garantizar que existe una prueba tan pronto como se confirma una operación, SoWasIt utiliza mecanismos de transacción avanzados.

Transacciones Atómicas

La escritura en su cadena y el anclaje público ocurren dentro de una única transacción atómica.

Gestión de Bloqueos

El uso de bloqueos a nivel de sistema garantiza una secuencia perfecta de sucesión de bloques, evitando cualquier condición de carrera incluso bajo alta concurrencia.

Seguridad e Aislamiento

Aunque la infraestructura es compartida (Multi-tenant), el aislamiento es hermético.

• Aislamiento Lógico : Cada solicitud se filtra mediante un tenant_id a nivel del motor de base de datos. Un usuario del inquilino A nunca puede, por diseño, dirigirse a una cadena del inquilino B.
• Secretos Hasheados : Las claves API y los tokens de sesión nunca se almacenan en texto plano. Solo se conserva su hash SHA-256.
• Idempotencia : El sistema admite claves de idempotencia. Si vuelve a enviar la misma solicitud, SoWasIt detecta el duplicado y devuelve la prueba original.

Referencia de la API

La API es RESTful y se comunica exclusivamente en JSON a través de HTTPS.

Autenticación

Utilice el encabezado X-API-Key para sus llamadas al servidor.

GET /v1/chains
Host: api.sowasit.io
X-API-Key: your_api_key_here

Gestión de Cadenas

Una cadena es un contenedor lógico para sus pruebas.

Anclaje de Bloques

Esta es la operación principal para crear una prueba.

POST /v1/chains/{chainId}/blocks
{
  "data": {
    "event": "document_signed",
    "hash": "e3b0c442...",
    "user_id": "user_42"
  }
}

Respuesta : Recibirá inmediatamente el hash del bloque y su prev_hash, lo que constituye su prueba de existencia.

Búsqueda JSONPath

Filtre y recupere sus bloques de manera eficiente utilizando expresiones JSONPath. Ideal para gestionar grandes cadenas o ignorar bloques mal formados.

POST /v1/chains/{chainId}/blocks/search
{
  "path": "$.content.type == \"invoice\" && $.content.amount > 100"
}

Ejemplos de expresiones

• $.content.user == "Alice" : Filtrer par valeur
• $.content.status != "draft" : Exclusion
• $.content.tags[*] == "urgent" : Recherche dans un tableau

Versionado de Bloques

Actualice los datos existentes manteniendo un historial inmutable. Cree nuevas versiones de bloques que se enlacen con las versiones anteriores a través de los campos prevState/nextState.

Cómo Funciona

Cuando actualiza un bloque (PUT /chains/{chainId}/blocks/{blockId}), se crea un nuevo bloque con el contenido actualizado. El campo prevState del nuevo bloque apunta al ID del bloque antiguo, y el nextState del bloque antiguo se actualiza para apuntar al nuevo bloque. Esto crea una cadena de versiones inquebrantable.

PUT /v1/chains/{chainId}/blocks/{blockId}
{
  "content": {
    "event": "document_updated",
    "version": 2
  }
}

Navegar por las versiones

Cada bloque devuelto por la API contiene metadata.prevState (ID del bloque anterior) y metadata.nextState (ID del bloque siguiente). Un bloque con nextState igual a null es la versión más reciente. Para recorrer el historial, siga la cadena prevState de bloque en bloque. Se planean SDKs para simplificar esta navegación.

Webhooks (Callbacks)

Automatice sus flujos de trabajo recibiendo notificaciones en tiempo real cuando se añadan nuevos bloques a sus cadenas.

Paso 1 — Crear el webhook

Llame a POST /v1/chains/{chainId}/callbacks con su URL. La API devuelve un secret (guárdelo de forma segura — no se mostrará de nuevo) y un validation_challenge (ej: "tomato").

POST /v1/chains/{chainId}/callbacks
{
  "url": "https://yourapp.com/webhook"
}

// Response
{
  "data": {
    "secret": "a3f8c2d1...",
    "validation_challenge": "tomato"
  }
}

Paso 2 — Preparar su endpoint

Su servidor debe responder a las solicitudes GET en su URL con el parámetro ?check=true devolviendo exactamente: {"challenge": "tomato"} (reemplace con su challenge real).

// GET https://yourapp.com/webhook?check=true
{ "challenge": "tomato" }

Paso 3 — Validar el webhook

Llame a POST /v1/chains/{chainId}/callbacks/{id}/validate. SoWasIt contacta su endpoint, verifica la respuesta y activa el webhook si todo es correcto.

Verificar las notificaciones recibidas

Cada notificación incluye dos encabezados: X-Callback-Secret (su secreto bruto) y X-Callback-Signature (HMAC-SHA256 del cuerpo firmado con su secreto). Recalcule el HMAC en su servidor y compárelo con el encabezado para asegurarse de que la notificación proviene realmente de SoWasIt.

// Node.js example
const crypto = require('crypto');
const sig = req.headers['x-callback-signature'];
const expected = crypto
  .createHmac('sha256', YOUR_SECRET)
  .update(req.rawBody)
  .digest('hex');
if (sig !== expected) return res.status(401).send('Invalid signature');

Idempotencia : Cada notificación contiene una idempotency_key única. Guárdela e ignore las notificaciones con una clave ya procesada — SoWasIt reintenta en caso de fallo (3 intentos: 30s, 2min, 10min).

Logs & Debugging

SoWasIt realiza un seguimiento de las operaciones técnicas para ayudarle a diagnosticar sus integraciones.

Modo Depuración

Por defecto, solo se conservan los eventos importantes (INFO) y los errores (ERROR). Para un análisis más profundo, puede activar temporalmente el 'Modo Depuración' desde su panel de control. Esto registrará todos los detalles técnicos durante la duración elegida (hasta 48h).