MIDAPI v2

MIDAPI v2 es la API REST síncrona del ecosistema de APIs de Facephi. Expone los servicios de verificación de identidad y antifraude mediante endpoints REST autenticados con OAuth2, pensados para integradores y desarrolladores backend.

Conceptos: plataforma del cliente y consumer

Antes de integrar cualquier servicio de MIDAPI v2 conviene conocer los dos conceptos sobre los que se organiza el acceso:

• Plataforma del cliente: representa la relación única entre el cliente y Facephi. Se identifica con la cabecera platform-id y tiene asociada una API key. Existe una única plataforma por cliente.

• Consumer: representa un canal o vertical de negocio del cliente (por ejemplo, el canal web y la app móvil, o verticales como seguros e inversiones). Se identifica con la cabecera consumer-id. Cada consumer tiene habilitados únicamente los servicios contratados para ese canal, con límites de uso y trazabilidad independientes.

Como parte del alta del servicio, se proveerá al cliente la URL base de la API, las credenciales de la plataforma y al menos un consumer (uno por cada canal o vertical que necesite integrar). Todas las rutas de esta guía son relativas a esa URL base (por ejemplo, POST <URL base>/consumer/token). Este modelo permite gestionar permisos, límites y trazabilidad de forma independiente por canal, manteniendo una única plataforma por cliente.

Con estos dos conceptos se obtiene el token de acceso: la plataforma emite tokens para sus consumers, y cada llamada operativa se hace en nombre de un consumer. El detalle está en Autenticación.

Autorizaciones

Todas las llamadas a los endpoints operativos deben incluir las siguientes claves en el encabezado de la solicitud:

Clave	Valor	Requerido
Authorization	Token de consumer en formato Bearer <token>	Sí
consumer-id	Identificador del consumer	Sí
operation-id	Identificador de la operación de los assets referenciados	Condicional

La cabecera operation-id es obligatoria cuando la petición referencia algún asset por clave. Ver Storage.

Respuestas de error

Todos los endpoints devuelven los errores con la misma estructura:

Parámetro	Tipo	Descripción
message	string	Descripción del error.
statusCode	integer	Código HTTP de la respuesta.

{
  "message": "Missing operation-id header, required when the request references stored assets",
  "statusCode": 400
}

El modelo de assets

Los servicios de validación de MIDAPI v2 trabajan sobre assets: las capturas del usuario final. Un asset puede aportarse con el contenido en línea en la propia llamada, o por referencia a un asset previamente almacenado.

La referencia por clave está disponible en todos los servicios de validación de identidad. Las excepciones son explícitas: Form OCR y los servicios de voz son exclusivamente en línea, y Document Validation es exclusivamente por referencia.

El flujo por referencia es: crear la operación, almacenar cada asset, y enviar las claves obtenidas al servicio de validación junto con la cabecera operation-id. Está desarrollado paso a paso, con su diagrama, en Flujo común. Los servicios que admiten los dos modos identifican la referencia con source: FILE_KEY; los que solo admiten referencia no llevan ese campo. El modo de asset, los contextos disponibles y el formato de la clave están en Storage.

Servicios disponibles

• Operations: ciclo de vida de la operación que agrupa los assets de una sesión y fija su caducidad.

• Storage: almacenamiento de los assets que después referencian los servicios de validación, con el modo de asset, los contextos y el formato de la clave.

• Document Services: validación de autenticidad del documento de identidad, OCR de identidad y OCR de impresos.

• Biometric Services: prueba de vida y comparación de rostros.

• Face Collections: registro y búsqueda 1:N de rostros en colecciones.

• Security & Compliance: detección de ataques de inyección sobre la captura facial.

• Validation Services: riesgo de fraude de IP, correo y teléfono.

• Voice Services: enrolamiento y autenticación de voz.