XamiLib Ruby — Referencia de clases

Módulo: XamiSDKClient. El punto de entrada es la clase XamiSDK. Los métodos siguen la convención snake_case de Ruby. Health#self está expuesto como self_status, con el alias self (por compatibilidad con el resto de SDKs de esta suite).

`XamiSDK`

Punto de entrada de la librería.

Constructor

XamiSDKClient::XamiSDK.new(config = {})

config acepta:

Clave	Descripción
`:endpoint`	URL del servicio local (por defecto `http://127.0.0.1:8300`).
`:wrapper_key`	Credencial de aplicación (`wrp_...`).
`:wrapper_secret`	Secret de la credencial (`wsec_...`).
`:timeout`	Timeout HTTP en segundos (opcional, 30 por defecto).

Métodos

Método	Devuelve	Descripción
`pades`	`Pades`	Servicio de firma de documentos PDF.
`blockchain`	`Blockchain`	Servicio de firma de transacciones EVM.
`credentials`	`Credentials`	Consulta de credenciales.
`designs`	`Designs`	Consulta de diseños de sello.
`health`	`Health`	Estado del servicio local.
`results`	`Results`	Resultados de firma recientes. (xamiSDK ≥ 0.2.0)
`errors`	`Errors`	Errores registrados por el servicio local. (xamiSDK ≥ 0.2.0)
`sync`	`Hash`	Recarga credenciales y diseños desde Xami sin reiniciar. (xamiSDK ≥ 0.2.0)

`Pades`

Firma de documentos PDF (PAdES).

Métodos

`sign(pdf_bytes, opts = {})`

Envía un PDF a firmar. Devuelve el request_id. opts: credential_key (requerido), design_key, variables, reason, location, signer_name.

`result(request_id)`

Consulta el estado. Cuando está DONE, incluye el PDF firmado (pdf_base64).

`wait(request_id, timeout_seconds: 60, poll_seconds: 1.0)`

Bloquea hasta que la firma esté lista y devuelve el PDF firmado (bytes).

`sign_and_wait(pdf_bytes, opts = {}, timeout_seconds: 60)`

Atajo: sign() + wait(). Devuelve el PDF firmado.

Ejemplo

pdf_firmado = xami.pades.sign_and_wait(
  File.binread('documento.pdf'),
  {
    credential_key: 'TU_CREDENCIAL',
    signer_name: 'Tu Nombre',
    reason: 'Aprobación',
    variables: { name: 'Tu Nombre' }
  }
)
File.binwrite('documento_firmado.pdf', pdf_firmado)

`Blockchain`

Firma de transacciones / mensajes EVM. El chip actúa como wallet y devuelve r/s/v; tú ensamblas la transacción con tu librería EVM.

Métodos

`sign(tx_hash, opts = {})`

Envía el hash a firmar. Devuelve el request_id. opts: credential_key (requerido, credencial EVM), chain_id.

`result(request_id)`

Consulta el estado.

`wait(request_id, timeout_seconds: 60, poll_seconds: 1.0)`

Bloquea hasta tener la firma. Devuelve {"r"=>..., "s"=>..., "v"=>..., "signature"=>...}.

`sign_and_wait(tx_hash, opts = {}, timeout_seconds: 60)`

Atajo: sign() + wait().

Ejemplo

firma = xami.blockchain.sign_and_wait('0xHASH_DE_LA_TX', {
  credential_key: 'TU_CREDENCIAL_EVM',
  chain_id: 648541
})
# firma['r'], firma['s'], firma['v']

`Credentials`

Consulta de credenciales en la caché local.

Método	Devuelve	Descripción
`all`	`Array`	Todas las credenciales disponibles.
`get(key)`	credencial o `nil`	Una credencial por su `credential_key`.

`Designs`

Consulta de diseños de sello en la caché local.

Método	Devuelve	Descripción
`all`	`Array`	Todos los diseños disponibles.
`get(key)`	diseño o `nil`	Un diseño por su `design_key`.

`Health`

Método	Devuelve	Descripción
`self` (alias de `self_status`)	`Hash`	Estado del servicio local (pareado, tenant, versión, etc.).
`version`	versión	Versión del xamiSDK local. `nil` si es anterior a 0.2.0.
`api_version`	entero	Versión del contrato local. `1` = sin `sync`, `results` ni `errors`.

`Results`

Requiere xamiSDK ≥ 0.2.0.

Pades#result necesita que conserves el request_id. Si tu proceso se reinició o el push no llegó, ese documento quedaba inalcanzable desde la librería. Con Results puedes recuperar lo firmado sin depender de tu propio almacenamiento.

Método	Devuelve	Descripción
`recent(limit = 50)`	`Array`	Últimos resultados (`PENDING` / `DONE` / `ERROR`).
`pending(limit = 50)`	`Array`	Solo los que siguen esperando la firma del chip.

xami.results.pending.each do |r|
  puts "#{r['request_id']} lleva esperando desde #{r['created_at']}"
end

`Errors`

Requiere xamiSDK ≥ 0.2.0.

Devuelve el mensaje corto y el error_id de cada fallo. Nunca devuelve el traceback: el detalle técnico solo sale del equipo del cliente cuando alguien ejecuta xamisdk report. Está pensado para que tu aplicación pueda decirle al usuario qué falló y con qué identificador pedir soporte.

Método	Devuelve	Descripción
`recent(limit = 20)`	`Array`	Últimos errores registrados.
`for_request(request_id)`	`Array`	Errores de un request concreto.

fallos = xami.errors.for_request(request_id)
if fallos.any?
  puts "No se pudo firmar: #{fallos.first['short']}"
  puts "Menciona #{fallos.first['error_id']} al pedir soporte."
end

Compatibilidad de versiones

Los métodos marcados con xamiSDK ≥ 0.2.0 devuelven 404 contra un servicio anterior. Compruébalo antes si no controlas la versión instalada:

xami.sync if xami.health.api_version >= 2

Manejo de errores

Todos los métodos lanzan XamiSDKClient::XamiException ante un fallo (credencial inválida, servicio caído, timeout). Expone message y code.

begin
  pdf = xami.pades.sign_and_wait(bytes, { credential_key: '...' })
rescue XamiSDKClient::XamiException => e
  puts "Error al firmar: #{e.message} (#{e.code})"
end

Descargar este manual (.md)