> 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/biometric-services/facial-matching.md).

# Facial Matching

Servicio que compara dos rostros y devuelve el resultado de la coincidencia con su confianza.

El orden de los huecos es significativo: `sourceImage` es la selfie y `targetImage` el rostro del documento.

### Endpoint

```
POST /biometric/face/matching
```

### Headers

| Nombre            | Tipo   | Requerido   | Descripción                                                                                                                                                         |
| ----------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | **Sí**      | Token de consumer en formato `Bearer <token>`. Ver [Autenticación](/api-rest/midapi-v2/autenticacion.md).                                                           |
| **consumer-id**   | string | **Sí**      | Identificador del consumer.                                                                                                                                         |
| **operation-id**  | string | Condicional | Identificador de la operación a la que pertenecen los assets referenciados. Requerido cuando `source` es `FILE_KEY`. Ver [Storage](/api-rest/midapi-v2/storage.md). |

### Cuerpo de la solicitud

**Content-Type:** `application/json`

#### Parámetros

| Parámetro     | Tipo   | Requerido | Descripción                                                                                                                                                      |
| ------------- | ------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`      | string | **Sí**    | Modo en que se aportan los assets: `FILE_KEY` para claves de assets almacenados, `FILE` para contenido en Base64. Ver [Storage](/api-rest/midapi-v2/storage.md). |
| `sourceImage` | string | **Sí**    | Selfie que se compara: clave del asset `TOKEN_BEST_IMAGE` o su contenido en Base64.                                                                              |
| `targetImage` | string | **Sí**    | Rostro contra el que se compara: rostro recortado del documento (`TOKEN_FACE_IMAGE`) o token de su anverso (`TOKEN_FRONT_DOCUMENT`), o su contenido en Base64.   |

#### Ejemplo de solicitud

```json
{
  "source": "FILE_KEY",
  "sourceImage": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_BEST_IMAGE",
  "targetImage": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FACE_IMAGE"
}
```

### Respuestas

#### `200` Éxito

#### Parámetros de respuesta

| Parámetro                  | Tipo   | Descripción                                                            |
| -------------------------- | ------ | ---------------------------------------------------------------------- |
| `consumerId`               | string | Identificador del consumer que realizó la llamada.                     |
| `transactionId`            | string | Identificador de la transacción.                                       |
| `timestamp`                | string | Marca de tiempo de la respuesta en formato **ISO 8601**.               |
| `message`                  | string | Campo descriptivo del resultado de la ejecución del servicio.          |
| `facialMatchingResult`     | string | Resultado de la coincidencia facial: `POSITIVE`, `NEGATIVE` o `ERROR`. |
| `facialMatchingConfidence` | number | Confianza de la coincidencia. **1.0 = 100%**                           |

#### Ejemplo de respuesta

```json
{
  "consumerId": "consumer-web",
  "transactionId": "e96e85a4-3f94-4000-b639-15c4f18c345b",
  "timestamp": "2026-06-26T12:00:06.000Z",
  "message": "Service executed ok",
  "facialMatchingResult": "POSITIVE",
  "facialMatchingConfidence": 0.99153554
}
```

#### Otras respuestas

| Código | Descripción                                                                                                                                                                                                                                                                                                                                         |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Campo obligatorio ausente o valor no admitido; falta la cabecera `operation-id` habiendo referencias; o una clave no tiene la forma `{operationId}/{CONTEXTO}` o declara un contexto que el hueco no admite.                                                                                                                                        |
| `403`  | El consumer no está aprovisionado con el servicio `FACIAL_MATCHING`.                                                                                                                                                                                                                                                                                |
| `404`  | La operación declarada en `operation-id` no existe o pertenece a otro consumer.                                                                                                                                                                                                                                                                     |
| `409`  | Un asset referenciado contiene un contenido ya procesado en otra operación.                                                                                                                                                                                                                                                                         |
| `410`  | La operación declarada en `operation-id` ha caducado.                                                                                                                                                                                                                                                                                               |
| `422`  | Una clave nombra una operación distinta de la declarada en `operation-id`, o el contexto no tiene ningún asset almacenado.                                                                                                                                                                                                                          |
| `429`  | El consumer ha superado su límite de tasa de peticiones, o un asset referenciado ha agotado su presupuesto de invocaciones en este endpoint. En el primer caso la respuesta incluye `Retry-After`, `X-RateLimit-Limit` y `X-RateLimit-Burst`, y esperar resuelve; en el segundo no. El servicio subyacente no se invoca y la llamada no se factura. |

El cuerpo de una respuesta de error tiene la forma descrita en [Middleware API v2](/api-rest/midapi-v2.md#respuestas-de-error).