# Servidor xamiSDK — Comandos (CLI) Todos los comandos del CLI `xamisdk`. Ejecuta `xamisdk --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 ``` ### `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 `. 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 --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 ``` ## 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 ``` ## 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 ``` 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.