Servidor xamiSDK — Comandos (CLI)

Todos los comandos del CLI xamisdk. Ejecuta xamisdk <comando> --help para ver la ayuda de cada uno.

Pareo y estado

`init`

Ceremonia de pareo con Xami (única). Establece el canal seguro.

xamisdk init --sdk-key xsdk_live_... --secret ...

Opción	Descripción
`--sdk-key`	Matrícula (`xsdk_live_...`).
`--secret`	Secret de la matrícula.
`--receive-url`	URL donde Xami empujará los resultados (modo push). Por defecto `http://127.0.0.1:8300/receive`. En modo pull no se usa.
`--endpoint`	Endpoint de Xami (por defecto `https://api.xami.run`).
`--force`	Rehace la ceremonia aunque ya esté pareado.

`status`

Muestra el estado del pareo: matrícula, tenant, endpoint, versión y estado de las llaves.

xamisdk status

Caché local

El SDK guarda una copia local de tus credenciales y diseños de firma para firmar sin consultar a Xami en cada operación. La caché se sincroniza automáticamente al levantar serve; si editas algo en la consola, ejecuta xamisdk sync para tomar el cambio sin reiniciar el servicio. (El detalle de esta sincronización está en Instalar.)

`cache:show`

Resumen de la caché local (cuántas credenciales y diseños hay sincronizados).

xamisdk cache:show

`credentials:list`

Lista las credenciales que el SDK tiene en caché, con su credential_key. Útil para confirmar con qué puedes firmar. Si sale vacío, levanta serve para sincronizar.

xamisdk credentials:list

`designs:list`

Lista los diseños de sello en caché, con su design_key. Si el sello no aparece al firmar, verifica aquí que el diseño esté presente (si no, reinicia serve).

xamisdk designs:list

`designs:show`

Detalle de un diseño concreto.

xamisdk designs:show <design_key>

`sync`

Vuelve a descargar las credenciales y los diseños desde Xami y reemplaza la caché local con esa información fresca, sin reiniciar el servicio. Es una sincronización real: lo que ya no existe en el servidor (por ejemplo, credenciales de un chip dado de baja) también se elimina de la caché local. Úsalo cuando cambiaste un diseño o una credencial en la consola de Xami y quieres que el SDK lo tome de inmediato.

xamisdk sync

`reinstall`

Actualiza el SDK a la última versión publicada. Comprueba si hay una versión más reciente; si la hay, lanza una ventana nueva que hace todo el ciclo por ti: detiene el servicio, reinstala el paquete, lo vuelve a levantar y abre la consola. Si ya estás al día no hace nada (usa --force para reinstalar igual). Como un programa no puede reemplazarse a sí mismo mientras corre, la consola actual se cierra y la actualización continúa en la ventana nueva.

xamisdk reinstall
xamisdk reinstall --force

Es un subcomando: se escribe xamisdk reinstall, no reinstall a secas. La primera vez (cuando tu versión aún no trae el comando) actualiza a mano con python -m pip install --force-reinstall --no-cache-dir <url-del-wheel>. Ver la guía de instalación para el detalle.

Firma de documentos (PAdES)

`pades:sign`

Firma un PDF. El documento no sale de tu red.

xamisdk pades:sign --credential-key TU_CREDENCIAL --wait documento.pdf

Opción	Descripción
`pdf`	Ruta del PDF a firmar (posicional, requerido).
`--credential-key`	Credencial a usar (requerido).
`--design`	`design_key` (si no, se usa el diseño por defecto de la credencial).
`--var clave=valor`	Variable del sello. Repetible.
`--reason`	Razón de la firma.
`--location`	Lugar de la firma.
`--signer-name`	Nombre del firmante.
`--out`	Ruta de salida del PDF firmado.
`--wait`	Espera el resultado y guarda el PDF.
`--timeout`	Segundos de espera en modo `--wait` (por defecto 60).

Firma blockchain (EVM)

`blockchain:sign`

Firma el hash (keccak256) de una transacción EVM. El chip actúa como wallet y devuelve la firma r/s/v; tú ensamblas la transacción con tu web3.

xamisdk blockchain:sign <hash> --credential-key TU_CREDENCIAL_EVM --chain-id 648541 --wait

Opción	Descripción
`hash`	keccak256 de la tx (64 hex, con o sin `0x`) (posicional, requerido).
`--credential-key`	Credencial EVM / wallet (requerido).
`--chain-id`	Chain id (EIP-155).
`--wait`	Espera `r`/`s`/`v`.
`--timeout`	Segundos de espera (por defecto 60).

Resultados por push

`callbacks:list`

Lista los resultados de firma recibidos por push.

xamisdk callbacks:list

`callbacks:show`

Detalle de un resultado de firma por su id.

xamisdk callbacks:show <request_id>

Credenciales de librería (wrapper)

Para que una aplicación externa firme a través del servicio HTTP local, necesita una credencial de acceso. Estos comandos la gestionan.

`wrapper:create`

Emite una credencial para una aplicación. Devuelve wrapper_key y wrapper_secret.

xamisdk wrapper:create --name mi-aplicacion

Opción	Descripción
`--name`	Nombre de la aplicación (requerido).

`wrapper:list`

Lista las credenciales de aplicación emitidas.

xamisdk wrapper:list

`wrapper:revoke`

Revoca una credencial de aplicación.

xamisdk wrapper:revoke <wrapper_key>

Servicio HTTP

`serve`

Levanta el servicio HTTP local del xamiSDK, para que tus aplicaciones firmen a través de una librería (XamiLib). Al arrancar, sincroniza tu configuración (credenciales y diseños) desde Xami y registra un log con fecha y nivel (INFO/WARN/ERROR).

xamisdk serve --port 8300

Modo pull (recomendado para probar desde una PC detrás de NAT): Xami no te empuja los resultados; el SDK los recoge por polling. Añade --polling con el intervalo en segundos:

xamisdk serve --port 8300 --polling 2

Opción	Descripción
`--host`	Host de escucha (por defecto `127.0.0.1`).
`--port`	Puerto (por defecto `8300`).
`--polling`	Intervalo en segundos para recoger resultados de Xami (modo pull). `-1` (por defecto) = inactivo (modo push, Xami empuja al `receive_url`).

Sesión y token (automático)

El SDK mantiene la sesión con Xami por su cuenta: el token de acceso se renueva automáticamente cuando caduca, sin que tengas que volver a parear. Solo necesitas ejecutar init una vez; a partir de ahí el servicio puede correr durante días sin interrupciones por expiración del token.

Si en algún momento la licencia fue revocada o el secret ya no es válido, el SDK te lo dirá con un mensaje claro y te pedirá volver a parear con init --force.

Registro de actividad y errores

Toda la actividad se registra con fecha y nivel (INFO / WARN / ERROR) en un log unificado (activity.log, en la carpeta del SDK), que reúne lo que ocurre en el servicio y en los comandos que ejecutas.

Cada comando que ejecutas deja un evento en el log; si un comando falla, queda registrado como ERROR.
Una firma deja su traza paso a paso (petición creada, hash calculado, hash enviado, resultado recibido, ensamblado, entregado), identificada por su request_id.
Cuando una operación falla, su traza completa se guarda además en errors.log, para poder revisar exactamente hasta dónde llegó. Las operaciones que terminan bien no se guardan ahí (el archivo solo contiene los casos con error).

Desde la consola interactiva puedes seguir este log en vivo con logs -f (ver Console).

Soporte y diagnóstico

`report`

Cuando una firma no sale como esperabas y necesitas ayuda, este comando arma un reporte técnico de ese request y lo envía a Xami para dar soporte. Antes de enviar nada, te muestra exactamente qué información se incluirá y te pide confirmación.

xamisdk report <requestId>

El requestId es el identificador que aparece (en verde) al firmar y en el log de actividad. El reporte incluye solo información no confidencial útil para el diagnóstico:

La versión y el build exacto del SDK que estás ejecutando.
El endpoint de Xami y el estado de tu caché (cuántas credenciales y diseños, con sus identificadores y dispositivos — sin secretos).
El resultado y el registro detallado de ese request.

No se envía tu llave privada, tu token de acceso ni el contenido de tus documentos.

Al recibirlo, Xami genera un número de incidente (por ejemplo INC-20260808-4A1B2C) que se muestra en pantalla. Menciónalo al pedir soporte: con él, el equipo de Xami puede ver exactamente qué build corre tu SDK y qué ocurrió en ese request, y ayudarte más rápido.

Descargar este manual (.md)