XamiLib Rust — Referencia de clases

Crate: xamisdk_client. El punto de entrada es XamiSDK, creado con XamiSDK::new(config). Cada llamada a xami.pades(), xami.health(), etc. devuelve un valor nuevo que envuelve un Client clonado (barato — internamente comparte el agente HTTP), en vez de cachear una instancia perezosa como en el resto de SDKs de la suite; es el patrón más idiomático en Rust para este caso. Como self es palabra reservada, Health::self() se llama get_self().

XamiSDK

Punto de entrada de la librería.

Constructor

XamiSDK::new(config: Config) -> XamiSDK

Config acepta:

Métodos

Pades

Firma de documentos PDF (PAdES).

Métodos

sign(&self, pdf_bytes: &[u8], opts: &PadesSignOptions) -> Result<String, XamiException>

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

result(&self, request_id: &str) -> Result<Value, XamiException>

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

wait(&self, request_id: &str, timeout_seconds: u64, poll_seconds: f64) -> Result<Vec<u8>, XamiException>

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

sign_and_wait(&self, pdf_bytes: &[u8], opts: &PadesSignOptions, timeout_seconds: u64) -> Result<Vec<u8>, XamiException>

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

Ejemplo

use xamisdk_client::PadesSignOptions;

let pdf_bytes = std::fs::read("documento.pdf")?;
let firmado = xami.pades().sign_and_wait(
    &pdf_bytes,
    &PadesSignOptions {
        credential_key: "TU_CREDENCIAL".to_string(),
        signer_name: Some("Tu Nombre".to_string()),
        reason: Some("Aprobación".to_string()),
        ..Default::default()
    },
    60,
)?;
std::fs::write("documento_firmado.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(&self, tx_hash: &str, opts: &BlockchainSignOptions) -> Result<String, XamiException>

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

result(&self, request_id: &str) -> Result<Value, XamiException>

Consulta el estado.

wait(&self, request_id: &str, timeout_seconds: u64, poll_seconds: f64) -> Result<Value, XamiException>

Bloquea hasta tener la firma. Devuelve el objeto con r/s/v/signature.

sign_and_wait(&self, tx_hash: &str, opts: &BlockchainSignOptions, timeout_seconds: u64) -> Result<Value, XamiException>

Atajo: sign() + wait().

Ejemplo

use xamisdk_client::BlockchainSignOptions;

let firma = xami.blockchain().sign_and_wait(
    "0xHASH_DE_LA_TX",
    &BlockchainSignOptions { credential_key: "TU_CREDENCIAL_EVM".to_string(), chain_id: Some(648541) },
    60,
)?;
// firma["r"], firma["s"], firma["v"]

Credentials

Consulta de credenciales en la caché local.

Designs

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

Health

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.

for r in xami.results().pending(50)? {
    println!("{} lleva esperando desde {}", r["request_id"], r["created_at"]);
}

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.

let fallos = xami.errors().for_request(&request_id)?;
if let Some(f) = fallos.first() {
    println!("No se pudo firmar: {}", f["short"]);
    println!("Menciona {} al pedir soporte.", f["error_id"]);
}

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:

if xami.health().api_version()? >= 2 {
    xami.sync()?;
}

Manejo de errores

Todos los métodos devuelven Result<_, XamiException>. XamiException implementa std::error::Error y Display, con campos message: String y code: Option<u16> (None en errores de red o de serialización).

match xami.pades().sign_and_wait(&pdf_bytes, &opts, 60) {
    Ok(pdf) => std::fs::write("documento_firmado.pdf", pdf)?,
    Err(e) => eprintln!("Error al firmar: {} ({:?})", e.message, e.code),
}