> 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/confirmacion-de-fraude.md).

# Confirmación de fraude

Si, tras una revisión posterior, se confirma que una transacción concreta correspondía a un intento de fraude, el consumer puede notificarlo al servicio. Esta información refuerza futuras detecciones sobre el mismo documento o identidad. Este paso es opcional.

### Endpoint

```
POST /document/validate/fraud-report
```

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

### Cuerpo de la solicitud

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

#### Parámetros

| Parámetro       | Tipo   | Requerido | Descripción                                                                                                                       |
| --------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `transactionId` | string | **Sí**    | Identificador (UUID) de la transacción de validación que se confirma como fraude, tal como lo devolvió `POST /document/validate`. |
| `categories`    | array  | **Sí**    | Una o más categorías del fraude detectado. Cada valor debe ser uno de los **valores admitidos** (ver más abajo).                  |
| `comment`       | string | No        | Comentario libre, máx. 500 caracteres.                                                                                            |

#### Categorías válidas

El campo `categories` solo admite los siguientes valores:

| Valor                      | Descripción                                         |
| -------------------------- | --------------------------------------------------- |
| `DOCUMENT_MANIPULATED`     | El documento está manipulado.                       |
| `DOCUMENT_ON_SCREEN`       | El documento se muestra desde una pantalla.         |
| `DOCUMENT_PRINTED_COPY`    | El documento es una copia impresa.                  |
| `SELFIE_ON_SCREEN`         | La selfie se muestra desde una pantalla.            |
| `SELFIE_MANIPULATED`       | La selfie está manipulada.                          |
| `SELFIE_DOCUMENT_MISMATCH` | La selfie no coincide con el retrato del documento. |
| `INJECTED_MEDIA`           | El contenido (imagen/vídeo) fue inyectado.          |

{% hint style="info" %}
El campo `categories` admite exactamente los valores de esta tabla. Cualquier otro valor se rechaza con `400` y no registra ninguna acción.
{% endhint %}

#### Ejemplo de solicitud

```json
{
  "transactionId": "1c7d...e9",
  "categories": ["DOCUMENT_MANIPULATED", "SELFIE_MANIPULATED"],
  "comment": "Confirmado como fraude tras revisión interna"
}
```

### Respuestas

#### `200` Éxito

```json
{
  "accepted": true
}
```

Todas las acciones aplicables de la confirmación quedaron registradas correctamente. Esto incluye el enrolamiento del rostro en las blocklists aplicables (ver más abajo). La operación es **idempotente**: si el rostro ya estaba en una blocklist, o si la transacción ya se había reportado previamente, el reintento se considera igualmente un éxito y devuelve `200`.

#### `400` Bad Request

La solicitud no es válida: falta `transactionId` o no tiene forma de UUID, `categories` está vacío o contiene un valor no admitido (ver **Categorías válidas**), o `comment` supera los 500 caracteres. No se registra ninguna acción; corrige la solicitud y reintenta.

#### `401` Unauthorized

Token ausente, inválido o caducado.

#### `403` Forbidden

El consumer no está aprovisionado con el servicio `DOCUMENT_ANTIFRAUD`, o el consumer o su plataforma están inactivos, caducados o fuera de consumo.

#### `404` Not Found

La transacción indicada no existe o pertenece a otro consumer.

#### `422` Unprocessable Entity

La transacción no admite reporte: solo son admisibles transacciones finalizadas en estado `COMPLETED`.

#### `429` Too Many Requests

El consumer ha superado su límite de tasa de peticiones. La respuesta incluye `Retry-After` con los segundos de espera, y `X-RateLimit-Limit` y `X-RateLimit-Burst` con los umbrales vigentes. No se registra ninguna acción.

#### `503` Service Unavailable

Alguna de las acciones aplicables de la confirmación **no pudo completarse**. La confirmación no se considera plenamente registrada; el consumer debe **reintentar** más tarde. La operación es idempotente, por lo que reintentar es seguro.

No todas las causas se resuelven reintentando: algunas requieren intervención de Facephi. Si el reintento sigue devolviendo `503`, **notifícalo a soporte** indicando el `transactionId`.

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

### Blocklists de rostros

Cuando la transacción confirmada como fraude incluye selfie, su rostro se enrola en las blocklists que apliquen, de forma que futuras validaciones lo detecten (códigos `200`/`201`, ver [respuesta de resultado](/api-rest/midapi-v2/document-services/document-validation/respuesta-de-resultado.md)):

* **Blocklist de la plataforma:** el rostro se enrola siempre en la blocklist propia de la plataforma.
* **Blocklist global:** además, si la plataforma participa en la blocklist global compartida, el rostro se enrola también en ella.

{% hint style="info" %}
La participación en la **blocklist global** se acuerda con Facephi en el alta del servicio y no se controla mediante la API. **Por defecto la plataforma participa**; si no quieres participar, indícalo en el alta. Su alcance es simétrico: se aplica tanto a la **búsqueda** durante la validación como al **enrolamiento** en esta confirmación de fraude. Si la transacción se procesó sin selfie (sin `TOKEN_FACE_IMAGE`), no se enrola ningún rostro en ninguna blocklist.
{% endhint %}

{% hint style="info" %}
Se recomienda enviar un único reporte de fraude por transacción. No obstante, reintentar es **seguro**: la operación es idempotente y un reporte ya registrado devuelve `200` sin duplicar efectos.
{% endhint %}