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

# Middleware API v2

**Middleware API 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 Middleware API 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](/api-rest/midapi-v2/autenticacion.md).

#### 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](/api-rest/midapi-v2/storage.md).

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

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

### El modelo de assets

Los servicios de validación de Middleware API 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](/api-rest/midapi-v2/document-services/form-ocr.md) y los servicios de [voz](/api-rest/midapi-v2/voice-services.md) son exclusivamente en línea, y [Document Validation](/api-rest/midapi-v2/document-services/document-validation.md) es exclusivamente por referencia.

El flujo por referencia es: crear la [operación](/api-rest/midapi-v2/operations/create-operation.md), [almacenar](/api-rest/midapi-v2/storage/save-asset.md) 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](/api-rest/midapi-v2/flujo-comun.md). 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](/api-rest/midapi-v2/storage.md).

### Servicios disponibles

* [**Operations**](/api-rest/midapi-v2/operations.md): ciclo de vida de la operación que agrupa los assets de una sesión y fija su caducidad.
* [**Storage**](/api-rest/midapi-v2/storage.md): 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**](/api-rest/midapi-v2/document-services.md): validación de autenticidad del documento de identidad, OCR de identidad y OCR de impresos.
* [**Biometric Services**](/api-rest/midapi-v2/biometric-services.md): prueba de vida y comparación de rostros.
* [**Face Collections**](/api-rest/midapi-v2/face-collections.md): registro y búsqueda 1:N de rostros en colecciones.
* [**Injection Attack Defence**](/api-rest/midapi-v2/security-compliance.md): detección de ataques de inyección sobre la captura facial.
* [**Validation Services**](/api-rest/midapi-v2/validation-services.md): riesgo de fraude de IP, correo y teléfono.
* [**Voice Services**](/api-rest/midapi-v2/voice-services.md): enrolamiento y autenticación de voz.