> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/api-rest/midapi-v2/document-services/document-validation/subida-de-assets.md). # Subida de assets Document Validation no recibe archivos directamente: consume los assets ya cargados en el servicio de almacenamiento de Facephi, referenciados por su `fileKey`. Antes de iniciar una validación, sube cada asset (documento y, opcionalmente, selfie) con el endpoint de almacenamiento. ### Antes de subir: crear la operación Los assets pertenecen a una **operación**, que es su contenedor y su ciclo de vida. El identificador de operación **no es un dato de negocio libre**: es el que emite `POST /operation`, y es el primer segmento de toda clave de asset. ``` POST /operation ``` ```json { "operationId": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04", "timestamp": "2026-06-26T12:00:00Z", "expiresAt": "2026-06-26T12:15:00Z" } ``` La operación **caduca** en el momento que indica `expiresAt`. Al caducar, ni se pueden subir assets bajo ella ni referenciarlos: hay que crear una operación nueva y volver a subir los assets. Ver [Operations](/api-rest/midapi-v2/operations.md). {% hint style="warning" %} Si tu integración venía usando un identificador de operación propio (del tipo `consumerX/op-123`) tiene que pasar a usar el que devuelve `POST /operation`. Un identificador con otro formato se rechaza con `400`. {% endhint %} ### Endpoint ``` POST /storage ``` ### Headers | Nombre | Tipo | Requerido | Descripción | | ----------------- | ------ | --------- | ---------------------------------------------------------------------------------------------------------- | | **Authorization** | string | **Sí** | Token de consumer en formato `Bearer ` (ver [Autenticación](/api-rest/midapi-v2/autenticacion.md)). | | **consumer-id** | string | **Sí** | Identificador del consumer. | Este endpoint no lleva cabecera `operation-id`: la operación va en el cuerpo, en `operationId`. ### 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ó `POST /operation`. | | `asset` | object | **Sí** | Asset a guardar. | | `asset.context` | string | **Sí** | Tipo de asset (ver tabla de tipos más abajo). | | `asset.file` | string | **Sí** | Contenido del asset (token del documento o selfie), codificado en **Base64**. Para `TOKEN_FRONT_DOCUMENT` y `TOKEN_BACK_DOCUMENT` debe ser el **token RAW** del documento generado por el SDK de captura. | #### Ejemplo de solicitud ```json { "operationId": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04", "asset": { "context": "TOKEN_FRONT_DOCUMENT", "file": "" } } ``` ### Respuestas #### `200` Éxito #### Parámetros de respuesta | Parámetro | Tipo | Descripción | | ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- | | `fileKey` | string | Clave del asset, con la forma `{operationId}/{CONTEXTO}`. Es el valor que se reenvía **sin modificar** al iniciar la validación. | | `timestamp` | string | Marca de tiempo de la respuesta en formato **ISO 8601**. | #### Ejemplo de respuesta ```json { "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FRONT_DOCUMENT", "timestamp": "2026-06-26T12:00:03.000Z" } ``` {% hint style="warning" %} Reenvía la `fileKey` **tal cual**. No le añadas el contexto (la clave ya lo lleva, y concatenarlo otra vez deja una clave que no resuelve), no le pongas ningún prefijo delante y no la partas. Si necesitas recuperar las claves de una operación, pídelas con `GET /operation/{operationId}/file-keys`, que las devuelve indexadas por contexto. {% endhint %} #### Otras respuestas | Código | Significado | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `operationId` no tiene el formato esperado, el contenido no corresponde al contexto declarado, 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: no puede haber más de uno por contexto y operación. | | `410` | La operación ha caducado. | ### Contextos de asset relevantes para el servicio | Contexto | Contenido | Obligatoriedad | | ---------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------- | | `TOKEN_FRONT_DOCUMENT` | **Token RAW** del anverso del documento de identidad (p. ej. `tokenRawFrontDocument` generado por el SDK de captura). | **Requerido** | | `TOKEN_BACK_DOCUMENT` | **Token RAW** del reverso del documento de identidad (p. ej. `tokenRawBackDocument` generado por el SDK de captura). | Opcional | | `TOKEN_FACE_IMAGE` | Selfie del titular. | Opcional | {% hint style="warning" %} **Importante:** los assets del documento deben ser los tokens **RAW** del anverso/reverso, no los tokens procesados. Si se sube un token no RAW, la validación no puede ejecutarse y la transacción finaliza en `FAILED`. {% endhint %} {% hint style="info" %} Si no se aporta `TOKEN_FACE_IMAGE`, el servicio valida únicamente el documento: se pierden las señales derivadas de la selfie (comparación facial) y el diagnóstico se basa solo en las validaciones documentales. {% endhint %} ### Documentos soportados * Document Validation valida **documentos de identidad (ID)** y **pasaportes**. * En pasaportes no se requiere el reverso: basta con el anverso (`TOKEN_FRONT_DOCUMENT`). * El conjunto concreto de **tipos de documento y países/emisores soportados** se define en el **alta del servicio**; consúltalo con Facephi para tu integración. * Si el documento no está soportado o su versión no puede validarse, la transacción se resuelve como `DECLINED` con el código de razón correspondiente (ver [Respuesta de resultado](/api-rest/midapi-v2/document-services/document-validation/respuesta-de-resultado.md)). ### Requisitos y calidad de imagen La calidad de la captura determina si el documento puede validarse. Para maximizar la tasa de aprobación: * **Resolución** mínima recomendada: HD (≥ 720×1080 px). * **Tamaño** máximo por archivo: 10 MB. Evitar compresión agresiva; usar los valores por defecto de un flujo de captura guiada. * **Encuadre**: el documento debe aparecer **completo y sin recortes**, ocupando la mayor parte del encuadre y con una relación de aspecto de tarjeta estándar. * **Nitidez e iluminación**: sin desenfoque, sin reflejos ni brillos que oculten datos, y sin rotación excesiva. * No puede existir más de un asset del mismo contexto para la misma operación (una segunda subida del mismo contexto devuelve `409 Conflict`). Si hay que repetir una captura ya subida, crea una operación nueva. {% hint style="info" %} Si una captura no cumple estos requisitos, la validación la señala como un **problema de calidad/captura** (no como fraude): son los códigos de las categorías `input` e `integrity` (p. ej. 100/101/104/105 y 102/103/106-111/500/501, ver [Respuesta de resultado](/api-rest/midapi-v2/document-services/document-validation/respuesta-de-resultado.md#rechazo-por-calidad-vs-deteccion-de-fraude)). En estos casos, repetir la captura con mejor calidad suele resolver la incidencia. {% endhint %}