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

{
  "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.

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.

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.

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

{
  "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}. 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

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

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.

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_BEST_IMAGE	Mejor imagen de la captura de selfie del titular.	Opcional

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.

La selfie es la captura del momento. El rostro recortado del propio documento (TOKEN_FACE_IMAGE) no se admite en este servicio: la comparación facial se haría contra el anverso del que se recortó y aprobaría siempre.

Si no se aporta TOKEN_BEST_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.

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).

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.

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). En estos casos, repetir la captura con mejor calidad suele resolver la incidencia.