XamiLib Java — Referencia de clases

Paquete: run.xami.sdk. El punto de entrada es la clase XamiSDK. Los métodos siguen la convención camelCase de Java. La opción sign() usa un builder fluido (new Pades.SignOptions().credentialKey(...).reason(...)). Como wait es palabra reservada en Java, ese método se llama await.

`XamiSDK`

Punto de entrada de la librería.

Constructor

new XamiSDK(XamiConfig config)

XamiConfig acepta (vía setters fluidos):

Setter	Descripción
`setEndpoint(String)`	URL del servicio local (por defecto `http://127.0.0.1:8300`).
`setWrapperKey(String)`	Credencial de aplicación (`wrp_...`).
`setWrapperSecret(String)`	Secret de la credencial (`wsec_...`).
`setTimeoutSeconds(int)`	Timeout HTTP en segundos (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(): Map<String,Object>`	resumen	Recarga credenciales y diseños desde Xami sin reiniciar. (xamiSDK ≥ 0.2.0)

`Pades`

Firma de documentos PDF (PAdES).

Métodos

`sign(byte[] pdfBytes, Pades.SignOptions opts): String`

Envía un PDF a firmar. Devuelve el request_id. SignOptions: credentialKey (requerido), designKey, variables, reason, location, signerName.

`result(String requestId): Map<String,Object>`

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

`await(String requestId, int timeoutSeconds, double pollSeconds): byte[]`

Bloquea hasta que la firma esté lista y devuelve el PDF firmado. Sobrecarga await(requestId) usa 60s / 1.0s por defecto.

`signAndWait(byte[] pdfBytes, Pades.SignOptions opts, int timeoutSeconds): byte[]`

Atajo: sign() + await(). Devuelve el PDF firmado. Sobrecarga sin timeoutSeconds usa 60s.

Ejemplo

byte[] pdfBytes = Files.readAllBytes(Path.of("documento.pdf"));
byte[] firmado = xami.pades().signAndWait(pdfBytes, new Pades.SignOptions()
        .credentialKey("TU_CREDENCIAL")
        .signerName("Tu Nombre")
        .reason("Aprobación")
        .variables(Map.of("name", "Tu Nombre")));
Files.write(Path.of("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(String txHash, Blockchain.SignOptions opts): String`

Envía el hash a firmar. Devuelve el request_id. SignOptions: credentialKey (requerido, credencial EVM), chainId.

`result(String requestId): Map<String,Object>`

Consulta el estado.

`await(String requestId, int timeoutSeconds, double pollSeconds): Map<String,Object>`

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

`signAndWait(String txHash, Blockchain.SignOptions opts, int timeoutSeconds): Map<String,Object>`

Atajo: sign() + await().

Ejemplo

Map<String, Object> firma = xami.blockchain().signAndWait("0xHASH_DE_LA_TX",
        new Blockchain.SignOptions().credentialKey("TU_CREDENCIAL_EVM").chainId(648541));
// firma.get("r"), firma.get("s"), firma.get("v")

`Credentials`

Consulta de credenciales en la caché local.

Método	Devuelve	Descripción
`all(): List<Map<String,Object>>`	lista	Todas las credenciales disponibles.
`get(String key): Map<String,Object>`	credencial o `null`	Una credencial por su `credential_key`.

`Designs`

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

Método	Devuelve	Descripción
`all(): List<Map<String,Object>>`	lista	Todos los diseños disponibles.
`get(String key): Map<String,Object>`	diseño o `null`	Un diseño por su `design_key`.

`Health`

Método	Devuelve	Descripción
`self(): Map<String,Object>`	estado	Estado del servicio local (pareado, tenant, versión, etc.).
`version(): String`	versión	Versión del xamiSDK local. `null` si es anterior a 0.2.0.
`apiVersion(): int`	entero	Versión del contrato local. `1` = sin `sync()`, `results()` ni `errors()`.

`Results`

Requiere xamiSDK ≥ 0.2.0.

Pades.result() necesita que conserves el requestId. 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(int limit): List<Map<String,Object>>`	lista	Últimos resultados (`PENDING` / `DONE` / `ERROR`). Sobrecarga sin argumentos usa 50.
`pending(int limit): List<Map<String,Object>>`	lista	Solo los que siguen esperando la firma del chip. Sobrecarga sin argumentos usa 50.

for (Map<String, Object> r : xami.results().pending()) {
    System.out.println(r.get("request_id") + " lleva esperando desde " + r.get("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.

Método	Devuelve	Descripción
`recent(int limit): List<Map<String,Object>>`	lista	Últimos errores registrados. Sobrecarga sin argumentos usa 20.
`forRequest(String requestId): List<Map<String,Object>>`	lista	Errores de un request concreto.

List<Map<String, Object>> fallos = xami.errors().forRequest(requestId);
if (!fallos.isEmpty()) {
    System.out.println("No se pudo firmar: " + fallos.get(0).get("short"));
    System.out.println("Menciona " + fallos.get(0).get("error_id") + " al pedir soporte.");
}

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().apiVersion() >= 2) {
    xami.sync();
}

Manejo de errores

Todos los métodos lanzan run.xami.sdk.XamiException (extiende RuntimeException) ante un fallo (credencial inválida, servicio caído, timeout). Expone getMessage() y getCode() (-1 cuando no aplica, p. ej. error de red).

try {
    byte[] pdf = xami.pades().signAndWait(bytes, new Pades.SignOptions().credentialKey("..."));
} catch (XamiException e) {
    System.err.println("Error al firmar: " + e.getMessage() + " (" + e.getCode() + ")");
}

Descargar este manual (.md)