Save Asset

Servicio que almacena un asset en un contexto de una operación y devuelve la clave con la que se referencia después.

Endpoint

POST /storage

Headers

Nombre	Tipo	Requerido	Descripción
Authorization	string	Sí	Token de consumer en formato Bearer <token>. Ver Autenticación.
consumer-id	string	Sí	Identificador del consumer.

Cuerpo de la solicitud

Content-Type: application/json

Parámetros

Parámetro	Tipo	Requerido	Descripción
operationId	string	Sí	Identificador de la operación a la que pertenece el asset, tal como lo devolvió Create Operation.
asset	object	Sí	Asset a almacenar.
asset.context	string	Sí	Contexto del asset. Admite TOKEN_FRONT_DOCUMENT, TOKEN_BACK_DOCUMENT, TOKEN_FACE_IMAGE, TOKEN_BEST_IMAGE, TOKEN_BIN_IAD y RAW_IMAGE. TOKEN_RAW_IMAGE no se admite aquí: es el contexto con el que queda almacenada una subida RAW_IMAGE, y declararlo se rechaza con 400. Ver Contextos de asset.
asset.file	string	Sí	Contenido del asset codificado en Base64, con el formato que exige su contexto.

Cada contexto exige un formato concreto. Los cuatro contextos tokenizados, TOKEN_FRONT_DOCUMENT, TOKEN_BACK_DOCUMENT, TOKEN_FACE_IMAGE y TOKEN_BEST_IMAGE, exigen el buffer tokenizado generado por el SDK de captura, y en ellos una imagen JPEG o PNG en Base64 se rechaza con 400. TOKEN_BIN_IAD acepta el binario de la captura. RAW_IMAGE es el único contexto que toma una imagen en abierto, JPEG o PNG en Base64.

El tamaño máximo por asset es de 10 MiB, aplicado al contenido codificado.

Ejemplo de solicitud

{
  "operationId": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04",
  "asset": {
    "context": "TOKEN_FRONT_DOCUMENT",
    "file": "<base64>"
  }
}

Respuestas

200 Éxito

Parámetros de respuesta

Parámetro	Tipo	Descripción
fileKey	string	Clave del asset, con la forma {operationId}/{CONTEXTO}. Se reenvía sin modificar al referenciar el asset.
derivedFileKey	string	Clave del asset derivado por esta subida, con la misma forma. Solo aparece en una subida TOKEN_BIN_IAD de la que se derivó la mejor imagen. Ver Contextos derivados.
timestamp	string	Marca de tiempo de la respuesta en formato ISO 8601.

Ejemplo de respuesta

{
  "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FRONT_DOCUMENT",
  "timestamp": "2026-06-26T12:00:03.000Z"
}

En una subida RAW_IMAGE el contexto de la clave no es el declarado: la imagen en abierto se tokeniza al recibirla y la respuesta devuelve TOKEN_RAW_IMAGE, que es el contexto con el que se referencia el asset a partir de ese momento.

{
  "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_RAW_IMAGE",
  "timestamp": "2026-06-26T12:00:03.000Z"
}

Contextos derivados

Al almacenar un asset TOKEN_BIN_IAD queda disponible además el contexto TOKEN_BEST_IMAGE de la misma operación, con la mejor imagen de esa captura. Puede almacenarse un TOKEN_BEST_IMAGE propio después; si ya hay uno almacenado, se conserva ese.

La respuesta devuelve la clave de esa mejor imagen en derivedFileKey, lista para usarse en las validaciones que la aceptan, como prueba de vida o comparación facial:

{
  "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BIN_IAD",
  "derivedFileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BEST_IMAGE",
  "timestamp": "2026-06-26T12:00:03.000Z"
}

derivedFileKey nombra lo que derivó esa subida, así que no aparece cuando la operación ya tenía almacenado un TOKEN_BEST_IMAGE propio: ahí no se deriva nada y se conserva el que ya estaba. Tampoco aparece en la subida de cualquier otro contexto.

Consulta Get File Keys para confirmar qué contextos hay disponibles en la operación.

Otras respuestas

Código	Descripción
400	El operationId no tiene el formato esperado, el contenido no corresponde al contexto declarado, el contexto declarado no se admite en la subida (TOKEN_RAW_IMAGE, que solo se obtiene subiendo RAW_IMAGE), o el asset está vacío o excede el tamaño máximo.
403	El consumer no está aprovisionado con el servicio STORAGE.
404	La operación no existe o pertenece a otro consumer.
409	Ya existe un asset de ese contexto en la operación.
410	La operación ha caducado.
429	El consumer ha superado su límite de tasa de peticiones. La respuesta incluye Retry-After con los segundos de espera, y X-RateLimit-Limit y X-RateLimit-Burst con los umbrales vigentes.
503	La imagen en abierto de una subida RAW_IMAGE no se pudo tokenizar. No se almacena nada.

El cuerpo de una respuesta de error tiene la forma descrita en Middleware API v2.