SDK · Manuales
Descargas

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) que consumen tus aplicaciones y las librerías XamiLib. Los documentos se firman en tu propia red.

Descargar colección Postman Descargar (.md)

Autenticación

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_...
POST /v1/pades/sign

Firmar documento PDF

Firma un PDF en formato PAdES. Devuelve un request_id; el PDF firmado se recupera después en GET /v1/results/{request_id}. El documento se procesa localmente y nunca sale de tu red.

Cuerpo de la petición

CampoTipoRequeridoDescripción
pdf_base64 string sí El PDF a firmar, codificado en base64.
credential_key string sí Credencial con la que se firma.
design_key string no Diseño del sello visible. Si se omite, se usa el diseño por defecto de la credencial.
variables object no Valores de las variables del sello (por ejemplo el nombre a estampar).
reason string no Razón de la firma.
location string no Lugar de la firma.
signer_name string no Nombre del firmante.
Petición
{
  "pdf_base64": "JVBERi0xLjQK...",
  "credential_key": "b52c2ec0-07b5-4da4-a93f-22227f344fc6",
  "variables": { "name": "Jose Zárate" },
  "reason": "Aprobación",
  "signer_name": "Jose Zárate"
}
Respuesta
{
  "request_id": "req_ee2140824f855efb",
  "status": "PENDING"
}
POST /v1/blockchain/sign

Firmar transacción (EVM)

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. Devuelve un request_id.

Cuerpo de la petición

CampoTipoRequeridoDescripción
tx_hash string sí Hash keccak256 de la transacción (64 hex, con o sin 0x).
credential_key string sí Credencial EVM (wallet) con la que se firma.
chain_id integer no Chain id de la red (EIP-155).
Petición
{
  "tx_hash": "0x9c1f...",
  "credential_key": "e7303407-9688-497f-b32c-12aa94dea6ac",
  "chain_id": 648541
}
Respuesta
{
  "request_id": "req_a1b2c3d4",
  "status": "PENDING"
}
GET /v1/results/{request_id}

Consultar resultado

Consulta el estado de una operación de firma. Mientras se procesa devuelve status: PENDING; al completarse, status: DONE. Para PAdES, cuando está listo incluye el PDF firmado en pdf_base64. Para blockchain, incluye r, s y v.

Respuesta
{
  "status": "DONE",
  "pdf_base64": "JVBERi0xLjQK..."
}
GET /v1/credentials

Listar credenciales

Devuelve las credenciales disponibles en la caché local del SDK, con su credential_key, tipo y diseño por defecto.

Respuesta
{
  "credentials": [
    {
      "credential_key": "b52c2ec0-...",
      "type": "pades",
      "default_design_key": "531ba341-..."
    }
  ]
}
GET /v1/designs

Listar diseños

Devuelve los diseños de sello disponibles en la caché local, con las variables que cada uno necesita.

Respuesta
{
  "designs": [
    {
      "design_key": "531ba341-...",
      "name": "Firma estándar"
    }
  ]
}
GET /health público

Estado del servicio

Estado del servicio local: si está pareado con Xami y el tenant asociado. No requiere autenticación de aplicación.

Respuesta
{
  "ok": true,
  "paired": true,
  "tenant_id": 5
}
POST /receive interno

Endpoint por el que Xami empuja los resultados de firma al SDK. Lo usa Xami durante el ciclo de firma; no lo llames directamente.