XamiLib PHP — Referencia de clases

Namespace: Xami\SDK. El punto de entrada es la clase XamiSDK, que da acceso a los distintos servicios.

`XamiSDK`

Punto de entrada de la librería.

Constructor

new XamiSDK(array $config)

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

`Pades`

Firma de documentos PDF (PAdES).

Métodos

`sign(string $pdfBytes, array $opts): string`

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

`result(string $requestId): array`

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

`wait(string $requestId, int $timeoutSeconds = 60, float $pollSeconds = 1.0): string`

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

`signAndWait(string $pdfBytes, array $opts, int $timeoutSeconds = 60): string`

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

Ejemplo

$pdfFirmado = $xami->pades()->signAndWait(
    file_get_contents('documento.pdf'),
    [
        'credential_key' => 'TU_CREDENCIAL',
        'signer_name'    => 'Tu Nombre',
        'reason'         => 'Aprobación',
        'variables'      => ['name' => 'Tu Nombre'],
    ]
);
file_put_contents('documento_firmado.pdf', $pdfFirmado);

`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(string $txHash, array $opts): string`

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

`result(string $requestId): array`

Consulta el estado.

`wait(string $requestId, int $timeoutSeconds = 60, float $pollSeconds = 1.0): array`

Bloquea hasta tener la firma. Devuelve ['r' => ..., 's' => ..., 'v' => ...].

`signAndWait(string $txHash, array $opts, int $timeoutSeconds = 60): array`

Atajo: sign() + wait().

Ejemplo

$firma = $xami->blockchain()->signAndWait('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(): array`	lista	Todas las credenciales disponibles.
`get(string $key): ?array`	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(): array`	lista	Todos los diseños disponibles.
`get(string $key): ?array`	diseño o `null`	Un diseño por su `design_key`.

`Health`

Método	Devuelve	Descripción
`self(): array`	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 = 50): array`	lista	Últimos resultados (`PENDING` / `DONE` / `ERROR`).
`pending(int $limit = 50): array`	lista	Solo los que siguen esperando la firma del chip.

foreach ($xami->results()->pending() as $r) {
    echo $r['request_id'], ' lleva esperando desde ', $r['created_at'], PHP_EOL;
}

`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 = 20): array`	lista	Últimos errores registrados.
`forRequest(string $requestId): array`	lista	Errores de un request concreto.

$fallos = $xami->errors()->forRequest($requestId);
if ($fallos) {
    echo 'No se pudo firmar: ', $fallos[0]['short'], PHP_EOL;
    echo 'Menciona ', $fallos[0]['error_id'], ' al pedir soporte.', PHP_EOL;
}

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 Xami\SDK\XamiException ante un fallo (credencial inválida, servicio caído, timeout). Envuélvelos en try/catch.

use Xami\SDK\XamiException;

try {
    $pdf = $xami->pades()->signAndWait($bytes, ['credential_key' => '...']);
} catch (XamiException $e) {
    error_log('Error al firmar: ' . $e->getMessage());
}

Descargar este manual (.md)