# 🧠 Validar Imagen (DNI / Selfie)

> Valida por API la selfie y el DNI/CI de un firmante con reconocimiento facial: la selfie debe mostrar su cara y la del documento, y ambas coincidir.

Este endpoint te permite **subir una imagen** (selfie o DNI/CI) de un firmante y validarla con reconocimiento facial.

La validación se hace en **dos pasos**:

1. **Selfie** — el firmante toma una foto sosteniendo su DNI/CI. La imagen debe contener **dos caras**: la del firmante y la del DNI. Ambas deben coincidir.
2. **DNI/CI** — el firmante toma una foto **solo del DNI/CI**. Wapi verifica que se vea un documento real y compara la cara del DNI con la selfie previa.

> ⚠️ **Importante**: hay que validar la **selfie primero**. La validación de documento requiere una selfie previa.

> 🚫 **Límite**: hasta **3 intentos** por tipo (`selfie` y `document`) por firmante. Después del tercero el endpoint responde `429` y no procesa más imágenes para ese `id_custom`.

**Endpoint:** `/api/validateImage`
**Método:** `POST`

---

## Headers

```
x-api-key: tu-api-key
Content-Type: application/json
```

---

## Body

- **id_custom** `(string, required)` — El `id_custom` del firmante (lo recibís en la respuesta de [Solicitar Documento](https://wapifirma.com/docs/api/solicitar/)).
- **type** `(string, required)` — `selfie` o `document`.
- **image** `(string, required)` — URL pública de la imagen **o** la imagen en Base64 (JPEG). Tamaño máximo: 10 MB.

### Ejemplo

```json
{
  "id_custom": "F5384BECE0574D809CC129F90C90253B",
  "type": "selfie",
  "image": "https://midominio.com/selfie.jpg"
}
```

---

## Respuesta exitosa (200)

```json
{
  "verified": true,
  "attempts_left": 2
}
```

> `attempts_left` indica cuántos intentos quedan **para ese tipo** (`selfie` o `document`) después de la llamada actual.

---

## Respuesta no verificada (200)

Cuando la validación corre pero la imagen no pasa los chequeos, devolvemos `verified: false` con un mensaje:

```json
{
  "verified": false,
  "error": "Las dos caras de la foto no coinciden.",
  "attempts_left": 1
}
```

Errores típicos:

- `No se detectaron las dos caras (selfie + DNI/CI) en la imagen.` — la selfie no tiene exactamente 2 caras (o 2-3 para MX/CL).
- `Las dos caras de la foto no coinciden.` — la cara del firmante y la del DNI en la selfie son distintas.
- `La imagen no contiene únicamente el DNI/CI con una sola cara.` — la foto del documento tiene 0 o más de 1 cara (más de 2 para MX/CL).
- `No se reconoció un documento válido en la imagen.`
- `No se encontró una selfie previa para este id_custom. Validá primero la selfie.` — pediste validar el documento sin haber validado la selfie antes.
- `La cara del DNI/CI no coincide con la selfie.` — el documento es válido pero la persona no es la misma.

---

## Errores

### 400 — Bad Request
```json
{ "error": "id_custom requerido" }
{ "error": "type debe ser \"selfie\" o \"document\"" }
{ "error": "image (URL o base64) requerido" }
{ "error": "No se pudo leer la imagen: <razón>" }
{ "error": "La imagen está vacía" }
```

### 401 — Unauthorized
```json
{ "error": "x-api-key requerido" }
```

### 404 — Not Found
```json
{ "error": "id_custom no encontrado para esta api_key" }
```

### 413 — Payload Too Large
```json
{ "error": "Imagen demasiado grande (máx 10 MB)" }
```

### 429 — Too Many Attempts
Después de 3 intentos para ese tipo (`selfie` o `document`):
```json
{
  "verified": false,
  "attempts_left": 0,
  "error": "Se alcanzó el límite de 3 intentos para selfie."
}
```

### 500 — Internal Server Error
```json
{ "error": "Error interno" }
```