Referencia de la API de Transactions

:::warning Enviada no es aceptada Un 200 de cualquier endpoint de escritura de esta página significa que la transaction se entregó a un node, aunque no significa que la red la aceptó. Se debe confirmar con Obtener Transaction hasta que blockHeight esté definido y output sea SUCCESS, porque una transaction que nunca aparece ahí no fue aceptada. Ver Confirmar siempre para la explicación completa. :::

Registrar Billetera

Registra una billetera en un blockchain para que pueda firmar y enviar transactions. Esto se hace una vez por billetera por blockchain antes de enviar cualquier transaction.

Solicitud

POST /api/v1/transactions/register-wallet

Encabezados

X-AccessKey — La clave de acceso de entidad
Content-Type: application/json

Cuerpo

walletAddress (requerido) — La dirección de la billetera a registrar
blockchain (requerido) — El ID del blockchain en el que registrar
passphrase (opcional) — Solo necesario si la billetera fue creada con una passphrase

Respuesta

Devuelve el resultado de la transaction del node en caso de éxito.

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/transactions/register-wallet' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"walletAddress": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"blockchain": "08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2"
}'

const res = await fetch('https://your-tms-url/api/v1/transactions/register-wallet', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  walletAddress: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  blockchain: '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2',
}),
});

const data = await res.json();
console.log(data);

Crear Transaction

Envía una transaction a un blockchain. La billetera debe estar ya registrada en el blockchain de destino antes de llamar a este endpoint. El TMS elige un node disponible de los nodes permitidos por la clave de acceso y reenvía la transaction.

Solicitud

POST /api/v1/transactions

Encabezados

X-AccessKey — La clave de acceso de entidad
Content-Type: application/json

Cuerpo

blockchainId (requerido) — ID del blockchain de destino
to (requerido) — Dirección de la billetera destinataria
walletAddress — Dirección de la billetera firmante
from — Dirección de la billetera remitente
payload — Los datos a almacenar
payloadType — text o json
passphrase — Solo si la billetera fue creada con una
metadata — Pares clave-valor opcionales

Respuesta

Devuelve el objeto de transaction incluyendo transactionId en caso de éxito.

Ejemplo de respuesta

{
"transactionId": "a1b2c3d4e5f6...",
"blockchainId": "08c28f29...",
"status": "pending",
"payload": "hello blockchain",
"payloadType": "text",
"from": "54677be3...",
"to": "54677be3..."
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/transactions' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"blockchainId": "08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2",
"from": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"to": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"walletAddress": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"payload": "hello blockchain",
"payloadType": "text"
}'

const res = await fetch('https://your-tms-url/api/v1/transactions', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  blockchainId: '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2',
  from: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  to: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  walletAddress: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  payload: 'hello blockchain',
  payloadType: 'text',
}),
});

const tx = await res.json();
console.log('Transaction ID:', tx.transactionId);

Obtener Transaction

:::note Cómo leer el resultado output es el resultado: SUCCESS significa confirmada, un valor de error significa que se registró pero falló, y un output vacío significa pendiente. status sigue en ACCEPTED en ambos casos. Si esta llamada no devuelve la transaction después de una espera razonable, no fue aceptada, así que no se debe tratar como pendiente. :::

Recupera el payload y los metadatos de una transaction específica por su ID y blockchain. Útil para verificar que una transaction se registró correctamente.

Solicitud

GET /api/v1/transactions/{blockchainId}/{transactionId}

Encabezados

X-AccessKey — La clave de acceso de entidad

Parámetros de ruta

blockchainId — El blockchain al que se envió la transaction
transactionId — El ID devuelto cuando se creó la transaction

Respuesta

Devuelve el objeto completo de la transaction incluyendo payload, estado, altura de bloque y marcas de tiempo.

Ejemplo de respuesta

{
"transactionId": "a1b2c3d4e5f6...",
"blockchainId": "08c28f29...",
"payload": "hello blockchain",
"payloadType": "text",
"status": "confirmed",
"blockHeight": 2301,
"from": "54677be3...",
"to": "54677be3...",
"timestamp": {
  "exactTime": "2026-05-25T19:00:00Z"
}
}

cURL
TypeScript

curl -X GET \
'https://your-tms-url/api/v1/transactions/{blockchainId}/{transactionId}' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Accept: application/json'

const blockchainId = '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2';
const transactionId = 'your-transaction-id';

const res = await fetch(
`https://your-tms-url/api/v1/transactions/${blockchainId}/${transactionId}`,
{
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Accept': 'application/json',
  },
}
);

const tx = await res.json();
console.log('Status:', tx.status);
console.log('Block height:', tx.blockHeight);
console.log('Payload:', tx.payload);

Crear Transaction JSON

Envía una transaction cuyo payload es un objeto JSON estructurado. El TMS serializa el objeto en el blockchain. Se usa cuando se quieren almacenar registros legibles por máquina en lugar de texto plano.

Solicitud

POST /api/v1/transactions/json

Encabezados

X-AccessKey — La clave de acceso de entidad
Content-Type: application/json

Cuerpo

blockchainId (requerido) — ID del blockchain de destino
to (requerido) — Dirección de la billetera destinataria
payload (requerido) — Un objeto JSON para almacenar en la chain, los escalares y los arrays se rechazan
walletAddress (opcional) — Billetera firmante (por defecto igual a from)
from (opcional) — Dirección de la billetera remitente
passphrase (opcional) — Solo si la billetera fue creada con una
metadata (opcional) — Pares clave-valor de cadena

Restricciones del payload

El payload debe ser un objeto JSON, por lo que un valor como 42,"text", true, null o [1, 2, 3] se rechaza con un 400, porque este endpoint almacena registros estructurados y las formas escalar y array quedan fuera de su alcance. El cuerpo del error dice{"error": "invalid request body"}, lo cual se refiere al payload aunque suene como si toda la solicitud estuviera mal formada, así que se debe verificar primero el tipo del payload cuando aparezca.

Los números se manejan como doubles IEEE-754, por lo que cualquier entero mayor que 2^53 − 1 (9007199254740991) se redondea al almacenarse, pero la escritura igualmente tiene éxito con un 200, lo que significa que solo se nota al leer la transaction de vuelta. Se deben enviar esos valores como cadenas, {"orderId": "1234567890123456789"}, y se conservan exactamente, ya sea un id de 19 dígitos, un timestamp en nanosegundos o un monto de tokens en unidades base.

El payload también se vuelve a serializar al ingresar, por lo que 100.0 se almacena como 100 y caracteres como <, > y& pueden almacenarse en su forma escapada. Los valores siguen siendo equivalentes como JSON, pero no se garantiza que los bytes almacenados coincidan con lo que se envió.

Respuesta

{
"transactionId": "a1b2c3d4e5f6...",
"blockchainId": "08c28f29...",
"status": "pending",
"payloadType": "json"
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/transactions/json' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"blockchainId": "08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2",
"to": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"walletAddress": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"payload": { "event": "invoice_paid", "amount": 1500, "currency": "USD" }
}'

const res = await fetch('https://your-tms-url/api/v1/transactions/json', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  blockchainId: '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2',
  to: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  walletAddress: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  payload: { event: 'invoice_paid', amount: 1500, currency: 'USD' },
}),
});

const tx = await res.json();
console.log('Transaction ID:', tx.transactionId);

Crear Transaction de Texto

Envía una transaction cuyo payload es una cadena de texto plano. Idéntico aPOST /api/v1/transactions pero con tipo explícito — se usa cuando se quiere dejar claro en el código que el payload es texto.

Solicitud

POST /api/v1/transactions/text

Encabezados

X-AccessKey — La clave de acceso de entidad
Content-Type: application/json

Cuerpo

blockchainId (requerido) — ID del blockchain de destino
to (requerido) — Dirección de la billetera destinataria
walletAddress (requerido) — Dirección de la billetera firmante
from — Dirección de la billetera remitente
payload — La cadena de texto a almacenar
payloadType — Debe ser "text"
passphrase (opcional) — Solo si la billetera fue creada con una
metadata (opcional) — Pares clave-valor de cadena

Respuesta

{
"transactionId": "a1b2c3d4e5f6...",
"blockchainId": "08c28f29...",
"status": "pending",
"payload": "hello blockchain",
"payloadType": "text"
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/transactions/text' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"blockchainId": "08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2",
"from": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"to": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"walletAddress": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"payload": "hello blockchain",
"payloadType": "text"
}'

const res = await fetch('https://your-tms-url/api/v1/transactions/text', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  blockchainId: '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2',
  from: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  to: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  walletAddress: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  payload: 'hello blockchain',
  payloadType: 'text',
}),
});

const tx = await res.json();
console.log('Transaction ID:', tx.transactionId);

Obtener Historial de Transactions

Devuelve una lista paginada de transactions enviadas por la entidad a través del TMS. Admite filtrado por estado, tipo de flujo, blockchain, remitente y destinatario.

Solicitud

GET /api/v1/transactions/history

Encabezados

X-AccessKey — La clave de acceso de entidad

Parámetros de consulta

status (opcional) — Filtrar por estado, p. ej. pending, confirmed
flow_type (opcional) — Filtrar por tipo de flujo
blockchain_id (opcional) — Filtrar por blockchain específico
from (opcional) — Filtrar por dirección de la billetera remitente
to (opcional) — Filtrar por dirección de la billetera destinataria
page (opcional) — Número de página (por defecto: 0)
pageSize (opcional) — Resultados por página (por defecto: 20)

Respuesta

{
"items": [
  {
    "id": 1,
    "transactionId": "a1b2c3...",
    "blockchainId": "08c28f29...",
    "status": "confirmed",
    "payloadType": "text",
    "from": "54677be3...",
    "to": "54677be3...",
    "createdAt": "2026-05-25T19:00:00Z"
  }
],
"total": 1,
"page": 0,
"pageSize": 20
}

cURL
TypeScript

curl -X GET \
'https://your-tms-url/api/v1/transactions/history?status=confirmed&pageSize=10' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Accept: application/json'

const params = new URLSearchParams({
status: 'confirmed',
blockchain_id: '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2',
page: '0',
pageSize: '20',
});

const res = await fetch(
`https://your-tms-url/api/v1/transactions/history?${params}`,
{
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Accept': 'application/json',
  },
}
);

const history = await res.json();
console.log('Total:', history.total);
history.items.forEach(tx => console.log(tx.transactionId, tx.status));

Obtener Entrada del Historial por ID

Recupera un único registro del historial de transactions por su ID interno del TMS (el campo id devuelto en la lista del historial). Es distinto deltransactionId en la cadena.

Solicitud

GET /api/v1/transactions/history/{id}

Encabezados

X-AccessKey — La clave de acceso de entidad

Parámetros de ruta

id — El ID interno del registro de historial del TMS

Respuesta

{
"id": 42,
"transactionId": "a1b2c3...",
"blockchainId": "08c28f29...",
"status": "confirmed",
"payloadType": "text",
"from": "54677be3...",
"to": "54677be3...",
"createdAt": "2026-05-25T19:00:00Z"
}

cURL
TypeScript

curl -X GET \
'https://your-tms-url/api/v1/transactions/history/42' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Accept: application/json'

const id = 42;

const res = await fetch(
`https://your-tms-url/api/v1/transactions/history/${id}`,
{
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Accept': 'application/json',
  },
}
);

const entry = await res.json();
console.log('Transaction ID:', entry.transactionId);
console.log('Status:', entry.status);

Obtener Estado de Transaction en Cola

Verifica el estado de una transaction en la cola de envío para un blockchain dado. Se usa para hacer polling cuando el TMS devuelve un ID de mensaje en lugar de un ID de transaction finalizado.

Solicitud

GET /api/v1/transactions/{blockchainId}/queue/{msgId}

Encabezados

X-AccessKey — La clave de acceso de entidad

Parámetros de ruta

blockchainId — El blockchain al que se envió la transaction
msgId — El ID del mensaje en cola devuelto durante el envío

Respuesta

{
"msgId": "msg-abc123",
"status": "pending",
"transactionId": "a1b2c3...",
"blockchainId": "08c28f29..."
}

cURL
TypeScript

curl -X GET \
'https://your-tms-url/api/v1/transactions/08c28f29.../queue/msg-abc123' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Accept: application/json'

const blockchainId = '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2';
const msgId = 'msg-abc123';

const res = await fetch(
`https://your-tms-url/api/v1/transactions/${blockchainId}/queue/${msgId}`,
{
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Accept': 'application/json',
  },
}
);

const queueEntry = await res.json();
console.log('Status:', queueEntry.status);
console.log('Transaction ID:', queueEntry.transactionId);

Registrar Billetera​

Solicitud

Encabezados

Cuerpo

Respuesta

Crear Transaction​

Solicitud

Encabezados

Cuerpo

Respuesta

Ejemplo de respuesta

Obtener Transaction​

Solicitud

Encabezados

Parámetros de ruta

Respuesta

Ejemplo de respuesta

Crear Transaction JSON​

Solicitud

Encabezados

Cuerpo

Restricciones del payload

Respuesta

Crear Transaction de Texto​

Solicitud

Encabezados

Cuerpo

Respuesta

Obtener Historial de Transactions​

Solicitud

Encabezados

Parámetros de consulta

Respuesta

Obtener Entrada del Historial por ID​

Solicitud

Encabezados

Parámetros de ruta

Respuesta

Obtener Estado de Transaction en Cola​

Solicitud

Encabezados

Parámetros de ruta

Respuesta

Registrar Billetera

Crear Transaction

Obtener Transaction

Crear Transaction JSON

Crear Transaction de Texto

Obtener Historial de Transactions

Obtener Entrada del Historial por ID

Obtener Estado de Transaction en Cola