XamiLib Python — Referencia de clases

Paquete: xamisdk_client. El punto de entrada es la clase XamiSDK. Los métodos siguen la convención Python (snake_case). La interfaz es equivalente a la de PHP.

`XamiSDK`

Punto de entrada de la librería.

Constructor

XamiSDK(config: dict)

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).

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() -> dict`	resumen	Recarga credenciales y diseños desde Xami sin reiniciar. (xamiSDK ≥ 0.2.0)

`Pades`

Firma de documentos PDF (PAdES).

Métodos

`sign(pdf_bytes: bytes, opts: dict) -> str`

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

`result(request_id: str) -> dict`

Consulta el estado. Cuando está DONE, incluye el PDF firmado en la clave pdf.

`wait(request_id: str, timeout_seconds: int = 60, poll_seconds: float = 1.0) -> bytes`

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

`sign_and_wait(pdf_bytes: bytes, opts: dict, timeout_seconds: int = 60) -> bytes`

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

Ejemplo

pdf_firmado = xami.pades().sign_and_wait(
    open("documento.pdf", "rb").read(),
    {
        "credential_key": "TU_CREDENCIAL",
        "signer_name": "Tu Nombre",
        "reason": "Aprobación",
        "variables": {"name": "Tu Nombre"},
    },
)
open("documento_firmado.pdf", "wb").write(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 web3.

Métodos

`sign(tx_hash: str, opts: dict) -> str`

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

`result(request_id: str) -> dict`

Consulta el estado.

`wait(request_id: str, timeout_seconds: int = 60, poll_seconds: float = 1.0) -> dict`

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

`sign_and_wait(tx_hash: str, opts: dict, timeout_seconds: int = 60) -> dict`

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() -> list`	lista	Todas las credenciales disponibles.
`get(key: str)`	credencial o `None`	Una credencial por su `credential_key`.

`Designs`

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

Método	Devuelve	Descripción
`all() -> list`	lista	Todos los diseños disponibles.
`get(key: str)`	diseño o `None`	Un diseño por su `design_key`.

`Health`

Método	Devuelve	Descripción
`self() -> dict`	estado	Estado del servicio local (pareado, tenant, versión, etc.).
`version()`	versión	Versión del xamiSDK local. `None` si es anterior a 0.2.0.
`api_version() -> 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 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) -> list`	lista	Últimos resultados (`PENDING` / `DONE` / `ERROR`).
`pending(limit=50) -> list`	lista	Solo los que siguen esperando la firma del chip.

for r in xami.results().pending():
    print(r["request_id"], "esperando desde", 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.

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

fallos = xami.errors().for_request(request_id)
if fallos:
    print("No se pudo firmar:", fallos[0]["short"])
    print("Menciona", fallos[0]["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().api_version() >= 2:
    xami.sync()

Manejo de errores

Todos los métodos lanzan xamisdk_client.XamiException ante un fallo (credencial inválida, servicio caído, timeout). Envuélvelos en try/except.

from xamisdk_client import XamiException

try:
    pdf = xami.pades().sign_and_wait(pdf_bytes, {"credential_key": "..."})
except XamiException as e:
    print("Error al firmar:", e)

Descargar este manual (.md)