Transacciones

Una transacción es una lista de operaciones que se ejecutan de manera atómica. Esta referencia describe la estructura JSON de las solicitudes de confirmación. Úsala junto con la referencia de operaciones para construir cargas útiles correctas y reproducibles.

Resumen

Todos los cambios de estado fluyen a través del endpoint /v1/write/namespaces/{namespace_id}/commit como transacciones. El daemon de escritura valida, ejecuta y añade operaciones al backend del registro de confirmaciones antes de devolver una respuesta de éxito. Esto significa que cada mutación es auditable y reproducible por diseño.

Estructura

Solicitud de Compromiso

{
  "actor_id": "lab-operator-17",
  "policy_id": null,
  "operations": [
    { "op": "OperationName", "args": { ... } },
    { "op": "AnotherOperation", "args": { ... } }
  ],
  "idempotency_key": "optional-unique-key",
  "metadata": {
    "custom_field": "optional user metadata"
  },
  "origin": {
    "client": "assetcore-sdk",
    "source": "batch-import"
  }
}

Operación Sobre.

Cada operación tiene la misma estructura de sobre. Esta uniformidad es lo que hace que la validación y las herramientas sean confiables en todos los dominios.

{
  "op": "OperationName",
  "args": {
    "field1": "value1",
    "field2": 123
  }
}

Campos

Campos de Solicitud

Campo	Tipo	Requerido	Descripción
operations	array	Sí	Lista de operaciones a ejecutar
actor_id	string	No	Identificador del actor para auditorías
policy_id	string	No	Identificador de la política (uso futuro)
idempotency_key	string	No	Clave única para deduplicación
metadata	object	No	Metadatos definidos por el usuario reflejados en la respuesta
origin	object	No	Metadatos de origen opcionales reflejados en la respuesta

Campos del Sobre de Operación

Campo	Tipo	Requerido	Descripción
op	cadena	Sí	Identificador de operación
args	objeto	Sí	Argumentos específicos de la operación

Campos de Respuesta

Campo	Tipo	Descripción
namespace	entero	Espacio de nombres en el que se ejecutó la transacción
commit_id	cadena	Identificador de commit opaco utilizado para commits reversos
outcome	cadena	Committed o RolledBack
world_seq_start	entero	Primer número de secuencia mundial en el commit
world_seq_end	entero	Número de secuencia mundial final en el commit
event_count	entero	Número de eventos emitidos
start_time_ms	entero	Hora de inicio de la transacción (milisegundos desde la época)
commit_time_ms	entero	Hora de commit de la transacción (milisegundos desde la época)
server_correlation_id	cadena	ID de correlación asignado por el servidor para rastreo
client_correlation_id	cadena	ID de correlación proporcionado por el cliente cuando se suministra
origin	objeto	Eco de los metadatos de origen proporcionados por el llamador
echo	objeto	Eco de los metadatos de la solicitud incluyendo idempotency_key
created_entities	objeto	Resumen de las entidades creadas durante el commit

Ejemplos

Transacción Mínima

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 1001,
        "kind": { "type": "balance" },
        "owner": null,
        "policies": null
      }
    }
  ]
}

Transacción con Idempotencia

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 1002,
        "kind": { "type": "balance" },
        "owner": null,
        "policies": null
      }
    }
  ],
  "idempotency_key": "create-container-2026-01-15-001"
}

Transacción de Múltiples Operaciones

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 2001,
        "kind": { "type": "slots", "count": 8 },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "RegisterClass",
      "args": {
        "request": {
          "class_id": 200,
          "flags": 2,
          "name": "SampleClass"
        }
      }
    },
    {
      "op": "AddInstance",
      "args": {
        "class_id": 200,
        "key": 1,
        "location": {
          "container_id": 2001,
          "kind": "slot",
          "slot_index": 1
        }
      }
    }
  ],
  "metadata": {
    "experiment_id": "exp-001",
    "operator": "system"
  }
}

Respuesta:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 5,
  "world_seq_end": 5,
  "event_count": 3,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "echo": {
    "metadata": {
      "experiment_id": "exp-001",
      "operator": "system"
    }
  },
  "created_entities": {
    "classes": [200],
    "containers": [2001],
    "instances": [9001]
  }
}

Respuesta de Reintento Idempotente

Cuando se envía nuevamente la misma clave de idempotencia:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 5,
  "world_seq_end": 5,
  "event_count": 3,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "echo": {
    "idempotency_key": "create-sample-2026-01-15-001",
    "metadata": {
      "experiment_id": "exp-001",
      "operator": "system"
    }
  },
  "created_entities": {
    "classes": [200],
    "containers": [2001],
    "instances": [9001]
  }
}

El encabezado x-asset-idempotency: hit indica una respuesta en caché.

Referencias relacionadas

• Referencia de Acción - Referencia completa de operaciones
• Recetas - Patrones comunes de múltiples operaciones
• Modelo de Error - Manejo de fallos en transacciones