Referencia de la API TIR

El TIR API (isbe-identity-tir-api) es el servicio que expone las operaciones del Trusted Issuers Registry de ISBE. Proporciona dos tipos de endpoints:

• JSON-RPC (POST /trusted-issuers-registry/v1/jsonrpc) — operaciones de escritura en blockchain. Requiere autenticación con API Key.
• REST (GET /trusted-issuers-registry/v1/issuers/{did}/attributes/{attributeId}) — lectura de acreditaciones. Sin autenticación requerida.

Base URLs

Entorno	Base URL
Producción	https://tir.portal.redisbe.com/trusted-issuers-registry
Preproducción	https://tir.pre.portal.redisbe.com/trusted-issuers-registry

Documentación interactiva OpenAPI: GET <base-url>/api-docs

Autenticación

El endpoint JSON-RPC requiere una API Key en el header HTTP:

x-api-key: <TU_API_KEY>

La API Key se valida contra el servicio de gestión de API Keys de ISBE. Contacta con el equipo de ISBE para obtener una.

El endpoint REST de lectura no requiere autenticación.

Protocolo JSON-RPC

La API sigue la especificación JSON-RPC 2.0. Todas las peticiones van a POST /trusted-issuers-registry/v1/jsonrpc con Content-Type application/json:

{
  "jsonrpc": "2.0",
  "method": "<nombre_del_método>",
  "params": [{ ... }],
  "id": <identificador_numérico_o_string>
}

Las respuestas exitosas tienen la forma:

{
  "jsonrpc": "2.0",
  "id": <mismo_id_de_la_petición>,
  "result": { ... }
}

Los errores tienen la forma:

{
  "jsonrpc": "2.0",
  "id": <mismo_id_de_la_petición>,
  "error": {
    "code": <código_numérico>,
    "message": "<descripción>"
  }
}

Códigos de error estándar JSON-RPC

Código	Significado
-32700	Parse error — JSON inválido
-32600	Invalid Request — petición no válida o no autorizada
-32601	Method not found — método desconocido
-32602	Invalid params — parámetros incorrectos o faltantes
-32603	Internal error — error interno del servidor

Flujo de publicación de una acreditación

Publicar una acreditación en el TIR requiere cuatro pasos. Los tres primeros son llamadas a la API; el cuarto es una verificación:

Verificar el recibo antes de continuar

sendSignedTransaction devuelve el hash de la transacción, pero la transacción puede no estar incluida aún en un bloque. Antes de dar la publicación por completada, consulta el recibo con eth_getTransactionReceipt y verifica que status = 0x1. Si status = 0x0, la transacción falló: revisa el campo revertReason.

Métodos disponibles

Método	Descripción
setAttributeMetadata	Construye una transacción no firmada para registrar los metadatos del rol de un emisor.
setAttributeData	Construye una transacción no firmada para registrar el JWT de la acreditación.
sendSignedTransaction	Envía una transacción firmada a la blockchain.

Endpoint REST de lectura

Método	Path	Descripción
GET	/v1/issuers/{did}/attributes/{attributeId}	Devuelve el JSON de la acreditación para un DID y attributeId dados.
GET	/health	Estado de salud del servicio.
GET	/metrics	Métricas en formato Prometheus.