> 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/identity-api/identity-api-reference/onboarding/civil-validation/ecuador.md).

# Ecuador

Servicio de validación civil para Ecuador. Realiza la verificación de identidad contra los datos del Registro Civil de Ecuador.

{% hint style="info" %}
Para Ecuador, el parámetro `documentCode` (fingerprintCode) es requerido en todas las operaciones.
{% endhint %}

### Endpoint

```
POST /services/civilValidation
```

### Headers

| Nombre        | Tipo   | Requerido | Descripción                                                   |
| ------------- | ------ | --------- | ------------------------------------------------------------- |
| **x-api-key** | string | **Sí**    | API key de autorización de acceso.                            |
| **family**    | string | No        | Valor: **OnBoarding**. Requerido con el servicio de tracking. |

{% hint style="info" %}
Todas las llamadas a los Endpoints para tracking con **Identity Platform** deben contener el header `family`.
{% endhint %}

## Full Validation Mobile

Realiza la validación de datos y coincidencia facial contra el Registro Civil de Ecuador utilizando plataforma móvil.

### Cuerpo de la solicitud

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

#### Parámetros

| Parámetro              | Tipo    | Requerido | Descripción                                                                                                                                                                       |
| ---------------------- | ------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operation`            | string  | **Sí**    | Operación de validación a realizar. Valor: `"FULL"`.                                                                                                                              |
| `platform`             | string  | **Sí**    | Plataforma desde la que se realiza la solicitud. Valor: `"MOBILE"`.                                                                                                               |
| `tokenOcr`             | string  | **Sí**    | Token generado por el widget SelphID nativo o híbrido, cifrado en AES256 y tokenizado, enviado en formato Base64. Contiene el resultado OCR del documento de identidad capturado. |
| `templateRaw`          | string  | **Sí**    | Plantilla biométrica generada por el widget Selphi. Requerida para operaciones FACIAL o FULL.                                                                                     |
| `documentCode`         | string  | **Sí**    | Código del documento (fingerprintCode), necesario para la validación en Ecuador.                                                                                                  |
| `documentNumber`       | string  | No        | Número de documento del usuario.                                                                                                                                                  |
| `countryCode`          | string  | **Sí**    | Código de país en formato ISO 3166-1 alfa-3. Valor: `"ECU"`.                                                                                                                      |
| `returnPII`            | boolean | No        | Indica si se desean recibir los datos personales generados por el servicio OCR y la respuesta del Registro Civil.                                                                 |
| `documentValidation`   | boolean | No        | Indica si se desea iniciar la validación del documento, retornando `scanReference` y `type`.                                                                                      |
| `tracking`             | object  | No        | Objeto que representa la información de seguimiento necesaria.                                                                                                                    |
| `tracking.extraData`   | string  | No        | Token generado por el SDK Mobile/Web. Contiene información de seguimiento tokenizada con la Plataforma.                                                                           |
| `tracking.operationId` | string  | No        | Identificador de operación generado por el SDK Mobile/Web.                                                                                                                        |

#### Ejemplo de solicitud

```json
{
  "operation": "FULL",
  "platform": "MOBILE",
  "tokenOcr": "base64TokenOcrString",
  "templateRaw": "base64TemplateRawString",
  "documentCode": "E1234V",
  "documentNumber": "1234567890",
  "countryCode": "ECU",
  "returnPII": true,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}
```

### Respuestas

#### `200` Éxito

#### Parámetros de respuesta

| Parámetro                           | Tipo    | Descripción                                                                                                                                  |
| ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`                 | integer | Código que indica el resultado general de la ejecución del servicio. Ver [Service Result Code](#service-result-code).                        |
| `serviceTime`                       | string  | Tiempo total de procesamiento (milisegundos).                                                                                                |
| `serviceResultLog`                  | string  | Campo descriptivo del resultado de la ejecución del servicio. Incluye detalles cuando hay un error o excepción.                              |
| `serviceTransactionId`              | string  | Identificador de transacción asociado a la solicitud procesada por la API.                                                                   |
| `civilDataValidation`               | array   | Array que representa las validaciones OCR contra los datos obtenidos del Registro Civil. Su presencia depende del Registro Civil consultado. |
| `civilDataValidation[].field`       | string  | Nombre del campo validado (ej. `firstName`, `lastName`, `dateOfBirth`).                                                                      |
| `civilDataValidation[].code`        | string  | Código de resultado de la validación. `"0"`: Validado correctamente. `"-99"`: Posiblemente adulterado.                                       |
| `civilDataValidation[].message`     | string  | Mensaje descriptivo del resultado de la validación.                                                                                          |
| `serviceFacialAuthenticationResult` | integer | Código que indica el resultado de la coincidencia facial. Ver [Service Facial Authentication Result](#service-facial-authentication-result). |
| `serviceFacialSimilarityResult`     | number  | Valor que indica la similitud facial entre el rostro en la foto del documento y el selfie del usuario. **1.0 = 100%**.                       |
| `serviceFacialAuthenticationHash`   | string  | Hash de integridad de la plantilla biométrica utilizada en una autenticación facial positiva o incierta.                                     |
| `serviceDocument`                   | string  | Cadena JSON que representa el documento capturado. Sus propiedades son todos los campos extraídos por el proceso OCR.                        |
| `civilServiceData`                  | string  | Cadena JSON con los datos personales obtenidos del Registro Civil (solo se retorna si `returnPII` fue enviado como `true` en la solicitud).  |

#### Ejemplo de respuesta

```json
{
  "serviceResultCode": 0,
  "serviceTime": "2500",
  "serviceResultLog": "Positive | Service executed ok",
  "serviceTransactionId": "12345678-1234-1234-1234-123456789012",
  "civilDataValidation": [
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "firstName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.98,
  "serviceFacialAuthenticationHash": "ABC123DEF456GHI789JKL012MNO345PQR678STU901VWX234YZ567",
  "serviceDocument": "{\"DocumentNumber\":\"1234567890\",\"FirstName\":\"JUAN CARLOS\",\"LastName\":\"RODRIGUEZ LOPEZ\",\"DateOfBirth\":\"15/03/1985\",\"Gender\":\"M\",\"Nationality\":\"ECUATORIANA\"}",
  "civilServiceData": "{\"apellidos\":\"RODRIGUEZ LOPEZ\",\"nombres\":\"JUAN CARLOS\",\"fechaNacimiento\":\"15/03/1985\",\"sexo\":\"HOMBRE\",\"nacionalidad\":\"ECUATORIANA\",\"estadoCivil\":\"SOLTERO\"}"
}
```

## Full Validation Web

Realiza la validación de datos y coincidencia facial contra el Registro Civil de Ecuador utilizando plataforma web.

### Cuerpo de la solicitud

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

#### Parámetros

| Parámetro              | Tipo    | Requerido | Descripción                                                                                                       |
| ---------------------- | ------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `operation`            | string  | **Sí**    | Operación de validación a realizar. Valor: `"FULL"`.                                                              |
| `platform`             | string  | **Sí**    | Plataforma desde la que se realiza la solicitud. Valor: `"WEB"`.                                                  |
| `imageFrontDocument`   | string  | **Sí**    | Captura frontal del documento, imagen en Base64 sin el encabezado de tipo MIME. Requerido para plataforma WEB.    |
| `imageBackDocument`    | string  | **Sí**    | Captura trasera del documento, imagen en Base64 sin el encabezado de tipo MIME. Requerido para plataforma WEB.    |
| `templateRaw`          | string  | **Sí**    | Plantilla biométrica generada por el widget Selphi. Requerida para operaciones FACIAL o FULL.                     |
| `documentCode`         | string  | **Sí**    | Código del documento (fingerprintCode), necesario para la validación en Ecuador.                                  |
| `documentNumber`       | string  | No        | Número de documento del usuario.                                                                                  |
| `countryCode`          | string  | **Sí**    | Código de país en formato ISO 3166-1 alfa-3. Valor: `"ECU"`.                                                      |
| `returnPII`            | boolean | No        | Indica si se desean recibir los datos personales generados por el servicio OCR y la respuesta del Registro Civil. |
| `documentValidation`   | boolean | No        | Indica si se desea iniciar la validación del documento, retornando `scanReference` y `type`.                      |
| `tracking`             | object  | No        | Objeto que representa la información de seguimiento necesaria.                                                    |
| `tracking.extraData`   | string  | No        | Token generado por el SDK Mobile/Web. Contiene información de seguimiento tokenizada con la Plataforma.           |
| `tracking.operationId` | string  | No        | Identificador de operación generado por el SDK Mobile/Web.                                                        |

#### Ejemplo de solicitud

```json
{
  "operation": "FULL",
  "platform": "WEB",
  "imageFrontDocument": "base64ImageFrontString",
  "imageBackDocument": "base64ImageBackString",
  "templateRaw": "base64TemplateRawString",
  "documentNumber": "0987654321",
  "documentCode": "V5678V",
  "countryCode": "ECU",
  "returnPII": true,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}
```

### Respuestas

#### `200` Éxito

#### Parámetros de respuesta

| Parámetro                           | Tipo    | Descripción                                                                                                                                  |
| ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`                 | integer | Código que indica el resultado general de la ejecución del servicio. Ver [Service Result Code](#service-result-code).                        |
| `serviceTime`                       | string  | Tiempo total de procesamiento (milisegundos).                                                                                                |
| `serviceResultLog`                  | string  | Campo descriptivo del resultado de la ejecución del servicio. Incluye detalles cuando hay un error o excepción.                              |
| `serviceTransactionId`              | string  | Identificador de transacción asociado a la solicitud procesada por la API.                                                                   |
| `civilDataValidation`               | array   | Array que representa las validaciones OCR contra los datos obtenidos del Registro Civil. Su presencia depende del Registro Civil consultado. |
| `civilDataValidation[].field`       | string  | Nombre del campo validado (ej. `firstName`, `lastName`, `dateOfBirth`).                                                                      |
| `civilDataValidation[].code`        | string  | Código de resultado de la validación. `"0"`: Validado correctamente. `"-99"`: Posiblemente adulterado.                                       |
| `civilDataValidation[].message`     | string  | Mensaje descriptivo del resultado de la validación.                                                                                          |
| `serviceFacialAuthenticationResult` | integer | Código que indica el resultado de la coincidencia facial. Ver [Service Facial Authentication Result](#service-facial-authentication-result). |
| `serviceFacialSimilarityResult`     | number  | Valor que indica la similitud facial entre el rostro en la foto del documento y el selfie del usuario. **1.0 = 100%**.                       |
| `serviceFacialAuthenticationHash`   | string  | Hash de integridad de la plantilla biométrica utilizada en una autenticación facial positiva o incierta.                                     |
| `serviceDocument`                   | string  | Cadena JSON que representa el documento capturado. Sus propiedades son todos los campos extraídos por el proceso OCR.                        |
| `civilServiceData`                  | string  | Cadena JSON con los datos personales obtenidos del Registro Civil (solo se retorna si `returnPII` fue enviado como `true` en la solicitud).  |

#### Ejemplo de respuesta

```json
{
  "serviceResultCode": 0,
  "serviceTime": "3200",
  "serviceResultLog": "Negative | Service executed ok",
  "serviceTransactionId": "87654321-4321-4321-4321-210987654321",
  "civilDataValidation": [],
  "serviceFacialAuthenticationResult": 1,
  "serviceFacialSimilarityResult": 0.15,
  "serviceFacialAuthenticationHash": "ZYX987WVU654TSR321PON098MLK765JIH432GFE109DCB876A543",
  "serviceDocument": "{\"DocumentNumber\":\"0987654321\",\"FirstName\":\"MARIA ELENA\",\"LastName\":\"GONZALEZ TORRES\",\"DateOfBirth\":\"28/11/1992\",\"Gender\":\"F\",\"Nationality\":\"ECUATORIANA\"}",
  "civilServiceData": "{\"apellidos\":\"GONZALEZ TORRES\",\"nombres\":\"MARIA ELENA\",\"fechaNacimiento\":\"28/11/1992\",\"sexo\":\"MUJER\",\"nacionalidad\":\"ECUATORIANA\",\"estadoCivil\":\"CASADO\"}"
}
```

## Data Validation Mobile

Realiza la validación de datos contra el Registro Civil de Ecuador utilizando plataforma móvil. No incluye coincidencia facial.

### Cuerpo de la solicitud

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

#### Parámetros

| Parámetro              | Tipo    | Requerido | Descripción                                                                                                                                                                       |
| ---------------------- | ------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operation`            | string  | **Sí**    | Operación de validación a realizar. Valor: `"DATA"`.                                                                                                                              |
| `platform`             | string  | **Sí**    | Plataforma desde la que se realiza la solicitud. Valor: `"MOBILE"`.                                                                                                               |
| `tokenOcr`             | string  | **Sí**    | Token generado por el widget SelphID nativo o híbrido, cifrado en AES256 y tokenizado, enviado en formato Base64. Contiene el resultado OCR del documento de identidad capturado. |
| `documentCode`         | string  | **Sí**    | Código del documento (fingerprintCode), necesario para la validación en Ecuador.                                                                                                  |
| `documentNumber`       | string  | No        | Número de documento del usuario.                                                                                                                                                  |
| `countryCode`          | string  | **Sí**    | Código de país en formato ISO 3166-1 alfa-3. Valor: `"ECU"`.                                                                                                                      |
| `returnPII`            | boolean | No        | Indica si se desean recibir los datos personales generados por el servicio OCR y la respuesta del Registro Civil.                                                                 |
| `documentValidation`   | boolean | No        | Indica si se desea iniciar la validación del documento, retornando `scanReference` y `type`.                                                                                      |
| `tracking`             | object  | No        | Objeto que representa la información de seguimiento necesaria.                                                                                                                    |
| `tracking.extraData`   | string  | No        | Token generado por el SDK Mobile/Web. Contiene información de seguimiento tokenizada con la Plataforma.                                                                           |
| `tracking.operationId` | string  | No        | Identificador de operación generado por el SDK Mobile/Web.                                                                                                                        |

#### Ejemplo de solicitud

```json
{
  "operation": "DATA",
  "platform": "MOBILE",
  "tokenOcr": "base64TokenOcrString",
  "documentCode": "E9876V",
  "documentNumber": "1122334455",
  "countryCode": "ECU",
  "returnPII": true,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}
```

### Respuestas

#### `200` Éxito

#### Parámetros de respuesta

| Parámetro                       | Tipo    | Descripción                                                                                                                                  |
| ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`             | integer | Código que indica el resultado general de la ejecución del servicio. Ver [Service Result Code](#service-result-code).                        |
| `serviceTime`                   | string  | Tiempo total de procesamiento (milisegundos).                                                                                                |
| `serviceResultLog`              | string  | Campo descriptivo del resultado de la ejecución del servicio. Incluye detalles cuando hay un error o excepción.                              |
| `serviceTransactionId`          | string  | Identificador de transacción asociado a la solicitud procesada por la API.                                                                   |
| `civilDataValidation`           | array   | Array que representa las validaciones OCR contra los datos obtenidos del Registro Civil. Su presencia depende del Registro Civil consultado. |
| `civilDataValidation[].field`   | string  | Nombre del campo validado (ej. `firstName`, `lastName`, `dateOfBirth`).                                                                      |
| `civilDataValidation[].code`    | string  | Código de resultado de la validación. `"0"`: Validado correctamente. `"-99"`: Posiblemente adulterado.                                       |
| `civilDataValidation[].message` | string  | Mensaje descriptivo del resultado de la validación.                                                                                          |
| `serviceDocument`               | string  | Cadena JSON que representa el documento capturado. Sus propiedades son todos los campos extraídos por el proceso OCR.                        |
| `civilServiceData`              | string  | Cadena JSON con los datos personales obtenidos del Registro Civil (solo se retorna si `returnPII` fue enviado como `true` en la solicitud).  |

#### Ejemplo de respuesta

```json
{
  "serviceResultCode": 0,
  "serviceTime": "1800",
  "serviceResultLog": "Service executed ok",
  "serviceTransactionId": "55443322-5544-3322-1100-554433221100",
  "civilDataValidation": [
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "firstName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceDocument": "{\"DocumentNumber\":\"1122334455\",\"FirstName\":\"CARLOS ALBERTO\",\"LastName\":\"MARTINEZ SILVA\",\"DateOfBirth\":\"10/07/1978\",\"Gender\":\"M\",\"Nationality\":\"ECUATORIANA\"}",
  "civilServiceData": "{\"apellidos\":\"MARTINEZ SILVA\",\"nombres\":\"CARLOS ALBERTO\",\"fechaNacimiento\":\"10/07/1978\",\"sexo\":\"HOMBRE\",\"nacionalidad\":\"ECUATORIANA\",\"estadoCivil\":\"DIVORCIADO\"}"
}
```

## Data Validation Web

Realiza la validación de datos contra el Registro Civil de Ecuador utilizando plataforma web. No incluye coincidencia facial.

### Cuerpo de la solicitud

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

#### Parámetros

| Parámetro              | Tipo    | Requerido | Descripción                                                                                                       |
| ---------------------- | ------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `operation`            | string  | **Sí**    | Operación de validación a realizar. Valor: `"DATA"`.                                                              |
| `platform`             | string  | **Sí**    | Plataforma desde la que se realiza la solicitud. Valor: `"WEB"`.                                                  |
| `imageFrontDocument`   | string  | **Sí**    | Captura frontal del documento, imagen en Base64 sin el encabezado de tipo MIME. Requerido para plataforma WEB.    |
| `imageBackDocument`    | string  | **Sí**    | Captura trasera del documento, imagen en Base64 sin el encabezado de tipo MIME. Requerido para plataforma WEB.    |
| `documentCode`         | string  | **Sí**    | Código del documento (fingerprintCode), necesario para la validación en Ecuador.                                  |
| `countryCode`          | string  | **Sí**    | Código de país en formato ISO 3166-1 alfa-3. Valor: `"ECU"`.                                                      |
| `returnPII`            | boolean | No        | Indica si se desean recibir los datos personales generados por el servicio OCR y la respuesta del Registro Civil. |
| `documentValidation`   | boolean | No        | Indica si se desea iniciar la validación del documento, retornando `scanReference` y `type`.                      |
| `tracking`             | object  | No        | Objeto que representa la información de seguimiento necesaria.                                                    |
| `tracking.extraData`   | string  | No        | Token generado por el SDK Mobile/Web. Contiene información de seguimiento tokenizada con la Plataforma.           |
| `tracking.operationId` | string  | No        | Identificador de operación generado por el SDK Mobile/Web.                                                        |

#### Ejemplo de solicitud

```json
{
  "operation": "DATA",
  "platform": "WEB",
  "documentCode": "V1357V",
  "imageFrontDocument": "base64ImageFrontString",
  "imageBackDocument": "base64ImageBackString",
  "countryCode": "ECU",
  "returnPII": true,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}
```

### Respuestas

#### `200` Éxito

#### Parámetros de respuesta

| Parámetro                       | Tipo    | Descripción                                                                                                                                  |
| ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`             | integer | Código que indica el resultado general de la ejecución del servicio. Ver [Service Result Code](#service-result-code).                        |
| `serviceTime`                   | string  | Tiempo total de procesamiento (milisegundos).                                                                                                |
| `serviceResultLog`              | string  | Campo descriptivo del resultado de la ejecución del servicio. Incluye detalles cuando hay un error o excepción.                              |
| `serviceTransactionId`          | string  | Identificador de transacción asociado a la solicitud procesada por la API.                                                                   |
| `civilDataValidation`           | array   | Array que representa las validaciones OCR contra los datos obtenidos del Registro Civil. Su presencia depende del Registro Civil consultado. |
| `civilDataValidation[].field`   | string  | Nombre del campo validado (ej. `firstName`, `lastName`, `dateOfBirth`).                                                                      |
| `civilDataValidation[].code`    | string  | Código de resultado de la validación. `"0"`: Validado correctamente. `"-99"`: Posiblemente adulterado.                                       |
| `civilDataValidation[].message` | string  | Mensaje descriptivo del resultado de la validación.                                                                                          |
| `serviceDocument`               | string  | Cadena JSON que representa el documento capturado. Sus propiedades son todos los campos extraídos por el proceso OCR.                        |
| `civilServiceData`              | string  | Cadena JSON con los datos personales obtenidos del Registro Civil (solo se retorna si `returnPII` fue enviado como `true` en la solicitud).  |

#### Ejemplo de respuesta

```json
{
  "serviceResultCode": 0,
  "serviceTime": "2100",
  "serviceResultLog": "Service executed ok",
  "serviceTransactionId": "13579246-1357-9246-8024-135792468024",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "-99",
      "message": "Possibly adulterated"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceDocument": "{\"DocumentNumber\":\"2468135790\",\"FirstName\":\"ANA PATRICIA\",\"LastName\":\"LOPEZ HERRERA\",\"DateOfBirth\":\"22/09/1990\",\"Gender\":\"F\",\"Nationality\":\"ECUATORIANA\"}"
}
```

## Facial Validation Mobile

Realiza la coincidencia facial contra las imágenes oficiales del Registro Civil de Ecuador utilizando plataforma móvil. No incluye validación de datos.

### Cuerpo de la solicitud

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

#### Parámetros

| Parámetro              | Tipo   | Requerido | Descripción                                                                                             |
| ---------------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------- |
| `operation`            | string | **Sí**    | Operación de validación a realizar. Valor: `"FACIAL"`.                                                  |
| `platform`             | string | **Sí**    | Plataforma desde la que se realiza la solicitud. Valor: `"MOBILE"`.                                     |
| `templateRaw`          | string | **Sí**    | Plantilla biométrica generada por el widget Selphi. Requerida para operaciones FACIAL o FULL.           |
| `documentNumber`       | string | No        | Número de documento del usuario. Requerido para operaciones FACIAL.                                     |
| `documentCode`         | string | **Sí**    | Código del documento (fingerprintCode), necesario para la validación en Ecuador.                        |
| `countryCode`          | string | **Sí**    | Código de país en formato ISO 3166-1 alfa-3. Valor: `"ECU"`.                                            |
| `tracking`             | object | No        | Objeto que representa la información de seguimiento necesaria.                                          |
| `tracking.extraData`   | string | No        | Token generado por el SDK Mobile/Web. Contiene información de seguimiento tokenizada con la Plataforma. |
| `tracking.operationId` | string | No        | Identificador de operación generado por el SDK Mobile/Web.                                              |

#### Ejemplo de solicitud

```json
{
  "operation": "FACIAL",
  "platform": "MOBILE",
  "documentNumber": "9876543210",
  "documentCode": "V2468V",
  "templateRaw": "base64TemplateRawString",
  "countryCode": "ECU",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}
```

### Respuestas

#### `200` Éxito

#### Parámetros de respuesta

| Parámetro                           | Tipo    | Descripción                                                                                                                                  |
| ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`                 | integer | Código que indica el resultado general de la ejecución del servicio. Ver [Service Result Code](#service-result-code).                        |
| `serviceTime`                       | string  | Tiempo total de procesamiento (milisegundos).                                                                                                |
| `serviceResultLog`                  | string  | Campo descriptivo del resultado de la ejecución del servicio. Incluye detalles cuando hay un error o excepción.                              |
| `serviceTransactionId`              | string  | Identificador de transacción asociado a la solicitud procesada por la API.                                                                   |
| `civilDataValidation`               | array   | Array que representa las validaciones OCR contra los datos obtenidos del Registro Civil. Su presencia depende del Registro Civil consultado. |
| `civilDataValidation[].field`       | string  | Nombre del campo validado (ej. `firstName`, `lastName`, `dateOfBirth`).                                                                      |
| `civilDataValidation[].code`        | string  | Código de resultado de la validación. `"0"`: Validado correctamente. `"-99"`: Posiblemente adulterado.                                       |
| `civilDataValidation[].message`     | string  | Mensaje descriptivo del resultado de la validación.                                                                                          |
| `serviceFacialAuthenticationResult` | integer | Código que indica el resultado de la coincidencia facial. Ver [Service Facial Authentication Result](#service-facial-authentication-result). |
| `serviceFacialSimilarityResult`     | number  | Valor que indica la similitud facial entre el rostro en la foto del documento y el selfie del usuario. **1.0 = 100%**.                       |
| `serviceFacialAuthenticationHash`   | string  | Hash de integridad de la plantilla biométrica utilizada en una autenticación facial positiva o incierta.                                     |
| `serviceDocument`                   | string  | Cadena JSON que representa el documento capturado. Sus propiedades son todos los campos extraídos por el proceso OCR.                        |

#### Ejemplo de respuesta

```json
{
  "serviceResultCode": 0,
  "serviceTime": "2800",
  "serviceResultLog": "Positive | Service executed ok",
  "serviceTransactionId": "24681357-2468-1357-9024-246813579024",
  "civilDataValidation": [
    {
      "field": "firstName",
      "code": "-99",
      "message": "Possibly adulterated"
    },
    {
      "field": "lastName",
      "code": "0",
      "message": "Validated ok"
    },
    {
      "field": "dateOfBirth",
      "code": "0",
      "message": "Validated ok"
    }
  ],
  "serviceFacialAuthenticationResult": 3,
  "serviceFacialSimilarityResult": 0.94,
  "serviceFacialAuthenticationHash": "DEF789GHI012JKL345MNO678PQR901STU234VWX567YZA890BCD123",
  "serviceDocument": "{\"DocumentNumber\":\"9876543210\",\"FirstName\":\"LUIS FERNANDO\",\"LastName\":\"PEREZ CASTRO\",\"DateOfBirth\":\"05/12/1986\",\"Gender\":\"M\",\"Nationality\":\"ECUATORIANA\"}"
}
```

## Facial Validation Web

Realiza la coincidencia facial contra las imágenes oficiales del Registro Civil de Ecuador utilizando plataforma web. No incluye validación de datos.

### Cuerpo de la solicitud

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

#### Parámetros

| Parámetro              | Tipo    | Requerido | Descripción                                                                                             |
| ---------------------- | ------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `operation`            | string  | **Sí**    | Operación de validación a realizar. Valor: `"FACIAL"`.                                                  |
| `platform`             | string  | **Sí**    | Plataforma desde la que se realiza la solicitud. Valor: `"WEB"`.                                        |
| `templateRaw`          | string  | **Sí**    | Plantilla biométrica generada por el widget Selphi. Requerida para operaciones FACIAL o FULL.           |
| `documentCode`         | string  | **Sí**    | Código del documento (fingerprintCode), necesario para la validación en Ecuador.                        |
| `documentNumber`       | string  | **Sí**    | Número de documento del usuario. Requerido para operaciones FACIAL.                                     |
| `countryCode`          | string  | **Sí**    | Código de país en formato ISO 3166-1 alfa-3. Valor: `"ECU"`.                                            |
| `returnPII`            | boolean | No        | Indica si se desean recibir los datos personales generados por la respuesta del Registro Civil.         |
| `tracking`             | object  | No        | Objeto que representa la información de seguimiento necesaria.                                          |
| `tracking.extraData`   | string  | No        | Token generado por el SDK Mobile/Web. Contiene información de seguimiento tokenizada con la Plataforma. |
| `tracking.operationId` | string  | No        | Identificador de operación generado por el SDK Mobile/Web.                                              |

#### Ejemplo de solicitud

```json
{
  "operation": "FACIAL",
  "platform": "WEB",
  "templateRaw": "base64TemplateRawString",
  "documentCode": "E8642I",
  "documentNumber": "5678901234",
  "countryCode": "ECU",
  "returnPII": true,
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
  }
}
```

### Respuestas

#### `200` Éxito

#### Parámetros de respuesta

| Parámetro                           | Tipo    | Descripción                                                                                                                                  |
| ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`                 | integer | Código que indica el resultado general de la ejecución del servicio. Ver [Service Result Code](#service-result-code).                        |
| `serviceTime`                       | string  | Tiempo total de procesamiento (milisegundos).                                                                                                |
| `serviceResultLog`                  | string  | Campo descriptivo del resultado de la ejecución del servicio. Incluye detalles cuando hay un error o excepción.                              |
| `serviceTransactionId`              | string  | Identificador de transacción asociado a la solicitud procesada por la API.                                                                   |
| `civilDataValidation`               | array   | Array que representa las validaciones OCR contra los datos obtenidos del Registro Civil. Su presencia depende del Registro Civil consultado. |
| `civilDataValidation[].field`       | string  | Nombre del campo validado (ej. `firstName`, `lastName`, `dateOfBirth`).                                                                      |
| `civilDataValidation[].code`        | string  | Código de resultado de la validación. `"0"`: Validado correctamente. `"-99"`: Posiblemente adulterado.                                       |
| `civilDataValidation[].message`     | string  | Mensaje descriptivo del resultado de la validación.                                                                                          |
| `serviceFacialAuthenticationResult` | integer | Código que indica el resultado de la coincidencia facial. Ver [Service Facial Authentication Result](#service-facial-authentication-result). |
| `serviceFacialSimilarityResult`     | number  | Valor que indica la similitud facial entre el rostro en la foto del documento y el selfie del usuario. **1.0 = 100%**.                       |
| `serviceFacialAuthenticationHash`   | string  | Hash de integridad de la plantilla biométrica utilizada en una autenticación facial positiva o incierta.                                     |
| `serviceDocument`                   | string  | Cadena JSON que representa el documento capturado. Sus propiedades son todos los campos extraídos por el proceso OCR.                        |
| `civilServiceData`                  | string  | Cadena JSON con los datos personales obtenidos del Registro Civil (solo se retorna si `returnPII` fue enviado como `true` en la solicitud).  |

#### Ejemplo de respuesta

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "NoneBecausePoseExceed",
  "serviceTime": "1900",
  "serviceFacialAuthenticationResult": 4,
  "serviceFacialAuthenticationHash": "GHI456JKL789MNO012PQR345STU678VWX901YZA234BCD567EFG890",
  "serviceFacialSimilarityResult": 0.0,
  "serviceTransactionId": "86420135-8642-0135-7913-864201357913",
  "civilServiceData": "{\"apellidos\":\"RAMIREZ MORENO\",\"nombres\":\"SOFIA ALEXANDRA\",\"fechaNacimiento\":\"13/04/1995\",\"sexo\":\"MUJER\",\"nacionalidad\":\"ECUATORIANA\",\"estadoCivil\":\"SOLTERO\"}"
}
```

## Tablas de referencia

#### Service Result Code

El `serviceResultCode` indica el resultado general de la ejecución del servicio:

| serviceResultCode | Descripción                                                                          | Código HTTP |
| ----------------- | ------------------------------------------------------------------------------------ | ----------- |
| 0                 | La ejecución del servicio fue exitosa, el módulo procesó la solicitud correctamente. | 200         |

#### Service Facial Authentication Result

El `serviceFacialAuthenticationResult` indica el resultado de las operaciones de coincidencia facial (solo para operaciones FULL y FACIAL):

| Código | Resultado                        | Descripción                                                                                                                                                                                           |
| ------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0      | NONE                             | No se pudo realizar la verificación facial.                                                                                                                                                           |
| 1      | NEGATIVE                         | El proceso se ejecutó correctamente. La comparación del patrón facial de los rostros no coincide.                                                                                                     |
| 3      | POSITIVE                         | El proceso se ejecutó correctamente. La comparación del patrón facial de los rostros es positiva. El valor de `serviceFacialSimilarityResult` indica el % de similitud entre las imágenes comparadas. |
| 4      | NONE BECAUSE POSE EXCEED         | No se pudo realizar la verificación facial debido a la posición del rostro.                                                                                                                           |
| 5      | NONE BECAUSE INVALID EXTRACTIONS | No se pudo realizar la verificación facial debido a problemas en la extracción del patrón facial.                                                                                                     |

## Errores comunes

#### `400` Bad Request

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Unauthorized

```json
{
  "message": "Unauthorized"
}
```

#### `403` Forbidden

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `502` Bad Gateway

```json
{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Gateway Timeout

```json
{
  "message": "Endpoint request timed out"
}
```