# Servidor xamiSDK — Servicios (HTTP)

Cuando levantas el servicio con `xamisdk serve`, el xamiSDK expone una API HTTP **local**
(por defecto en `http://127.0.0.1:8300`) para que tus aplicaciones firmen a través de
ella. Es la API que consumen las librerías XamiLib (PHP, Python).

## Autenticación

Todas las rutas `/v1/*` requieren una credencial de aplicación (emitida con
`xamisdk wrapper:create`), enviada en cada petición mediante cabeceras:

```
X-Wrapper-Key: wrp_...
X-Wrapper-Secret: wsec_...
```

## Endpoints

### `POST /v1/pades/sign`
Firma un PDF. Devuelve un `request_id`; el resultado se consulta luego en
`/v1/results/{request_id}`.

Cuerpo (JSON):

| Campo | Tipo | Descripción |
|---|---|---|
| `pdf_base64` | string | PDF en base64 (**requerido**). |
| `credential_key` | string | Credencial a usar (**requerido**). |
| `design_key` | string | Diseño del sello (opcional; usa el por defecto). |
| `variables` | objeto | Valores de las variables del sello. |
| `reason` | string | Razón de la firma. |
| `location` | string | Lugar de la firma. |
| `signer_name` | string | Nombre del firmante. |

Respuesta: `{ "request_id": "...", "status": "PENDING" }`

### `POST /v1/blockchain/sign`
Firma el hash de una transacción EVM. Devuelve un `request_id`.

Cuerpo (JSON):

| Campo | Tipo | Descripción |
|---|---|---|
| `tx_hash` | string | keccak256 de la tx (**requerido**). |
| `credential_key` | string | Credencial EVM / wallet (**requerido**). |
| `chain_id` | entero | Chain id (EIP-155). |

Respuesta: `{ "request_id": "...", "status": "PENDING" }`

### `GET /v1/results/{request_id}`
Consulta el resultado de una operación de firma. Mientras esté pendiente devuelve
`status: PENDING`; al completarse, `status: DONE`. Para PAdES, cuando está `DONE`
incluye el PDF firmado en `pdf_base64`. Para blockchain, incluye `r`, `s`, `v`.

Respuesta (ejemplo PAdES): `{ "status": "DONE", "pdf_base64": "..." }`

### `GET /v1/credentials`
Lista las credenciales disponibles en la caché local.

Respuesta: `{ "credentials": [ ... ] }`

### `GET /v1/designs`
Lista los diseños de sello disponibles en la caché local.

Respuesta: `{ "designs": [ ... ] }`

### `GET /health`
Estado del servicio. No requiere autenticación de aplicación.

Respuesta: `{ "ok": true, "paired": true, "tenant_id": ... }`

### `POST /receive`
Endpoint interno por el que Xami empuja los resultados de firma al SDK. **No lo llames
directamente**; lo usa Xami durante el ciclo de firma.