> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Comenzar con FaceAuth

> FaceAuth verifica la identidad un paso más comparando la selfie de un usuario aprobado en el proceso de ID Check con la selfie capturada durante FaceAuth. Esta página cubre los dos modos de entrega (URL / API), la estructura de QueryString de la URL de Face Auth y las definiciones de los parámetros de solicitud.

<Info>
  **Lectura relacionada**

  * Crear un proyecto FaceAuth en el panel y configurar la política (umbrales, liveness, oclusión) y la expiración del token → [Guía de FACE AUTH](/dashboard/es/face-auth-guide)
  * Aspectos comunes a todos los complementos (emisión de la clave API, cuotas de solicitudes, códigos de estado de respuesta HTTP) → [Comenzar con complementos](/es/idcheck/add-on/overview)
</Info>

## Modos de entrega de FaceAuth — 2 opciones

FaceAuth puede entregarse de dos formas. **Recomendamos el método Face Auth URL**, que elimina la necesidad de implementar una UI de cámara propia y admite Active Liveness.

<CardGroup cols={2}>
  <Card title="A. Face Auth URL (Recomendado)" icon="link" href="/dashboard/es/face-auth-guide">
    La captura del selfie se realiza en una página alojada por ARGOS (similar a Liveform). No es necesario implementar una UI de cámara en el cliente, y la política del proyecto puede habilitar **Liveness (Pasivo/Activo)** y controles de oclusión (mascarilla/casco).
  </Card>

  <Card title="B. POST /faceauth API" icon="code" href="/es/idcheck/add-on/post-faceauth">
    Su aplicación implementa la UI de cámara y envía el archivo `faceImage` capturado al API. **Active Liveness no es compatible** — solo se compara la similitud facial.
  </Card>
</CardGroup>

<Tip>
  **Si le preocupan los intentos de suplantación (replays de pantalla, fotos impresas), utilice el método URL.** El método POST API juzga una sola imagen enviada únicamente por similitud y no puede verificar que el usuario esté físicamente presente. El método URL le permite configurar un **umbral de Liveness** en la política del proyecto para bloquear ataques de replay de pantalla y fotos estáticas.
</Tip>

Para la configuración de políticas en el dashboard (umbrales, liveness, oclusión) y casos de uso de ambos métodos, consulte la [Guía de FACE AUTH](/dashboard/es/face-auth-guide). El resto de esta página cubre los parámetros y el flujo de autenticación del **Método A (Face Auth URL)**. Para el **Método B (POST API)**, consulte la página [POST/Faceauth](/es/idcheck/add-on/post-faceauth).

## QueryString para acceder a FaceAuth

FaceAuth es un subproyecto de ID Check, y los administradores pueden crear tantos proyectos como deseen. Para entregar autenticación adicional mediante el método Face Auth URL, **utilice la URL de Face Auth dentro del proyecto Add-on.** <br />
Para hacer referencia a un submission\_Id que ha sido aprobado a través de ID document o Knowledge-based donde existe una imagen selfie, se debe agregar a la URL mediante el parámetro de consulta `encrypted`, y por motivos de seguridad, siempre debe usarse en estado cifrado.<br />
El cifrado debe utilizar la clave API dentro del proyecto FaceAuth y utiliza AES-256. <br />
Para métodos detallados, consulte [Cifrado de Cadena de Consulta](/es/idcheck/getting-started/encrypt-and-decrypt-data/overview#2-cifrado-de-cadena-de-consulta).

<Warning>
  **El texto plano que se cifra es JSON — no una cadena de consulta.**

  Si cifra una cadena formada por pares `key=value` unidos con `&` (por ejemplo `sid=...&authUserId=...`), el `sid` no se reconoce y la verificación no se inicia. **Serialice un objeto JSON (`JSON.stringify`) y cifre esa cadena**, y use el resultado como valor de `encrypted`.

  En ese caso la pantalla muestra **"Página no encontrada"** en lugar de una página con código de error, lo que dificulta identificar la causa. Para el orden de diagnóstico, consulte [Validación de la URL de Face Auth y manejo de errores](/es/idcheck/add-on/faceauth-url-errors#2-1-parámetros-obligatorios-ausentes).
</Warning>

<Warning>
  **Face Auth no se ejecuta sin cadena de consulta.**

  Una URL que solo lleve `pid` no inicia la verificación — el `sid` de referencia debe cifrarse y enviarse dentro de `encrypted`. Si falta, el usuario es redirigido a la [página de error `PV-40015`](/es/idcheck/add-on/faceauth-url-errors#2-fallos-de-validación-en-la-etapa-de-entrada).
</Warning>

### Paso 1 — Prepare el texto plano (JSON) que va a cifrar

<CodeGroup>
  ```json Básico: solo el submission_Id de referencia (forma mínima ejecutable) theme={null}
  {
    "sid": "{submission_Id}"
  }
  ```

  ```json Todos los parámetros: sid, authUserId, authCf1, authCf2, authCf3, token theme={null}
  {
    "sid": "{submission_Id}",
    "authUserId": "{user Id}",
    "authCf1": "{additional_info}",
    "authCf2": "{additional_info}",
    "authCf3": "{additional_info}",
    "token": "{any tokenId}"
  }
  ```
</CodeGroup>

### Paso 2 — Cifre con la clave API del proyecto FaceAuth (AES-256) y construya la URL

```text Estructura de la URL de Face Auth (esta forma por sí sola no se ejecuta) theme={null}
  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}
```

```text El valor cifrado enviado en encrypted (forma ejecutable) theme={null}
  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}&encrypted={encrypted}
```

<Warning>
  **El valor de `encrypted` debe estar codificado para URL.**

  El resultado del cifrado AES-256 (Base64) contiene `+`, `/` y `=`. Si lo añade a la URL sin codificar, `+` se interpreta como un espacio, por lo que **el descifrado falla** y no se puede leer el `sid`. Aplique `encodeURIComponent` (o la función de codificación de URL de su lenguaje).
</Warning>

```javascript Ejemplo completo en Node.js theme={null}
const crypto = require('crypto');

function encrypt(data, apiKey) {
  const hashedKey = crypto.createHash('sha256').update(apiKey).digest();
  const cipher = crypto.createCipheriv('aes-256-ecb', hashedKey, null);
  return cipher.update(data, 'utf8', 'base64') + cipher.final('base64');
}

// Paso 1: el texto plano es un objeto JSON serializado
const queryData = JSON.stringify({
  sid: 'submission_12345',
  authUserId: 'user123',
});

// Paso 2: cifre con la clave API del proyecto FaceAuth y codifique para URL
const encrypted = encrypt(queryData, FACEAUTH_API_KEY);
const faceAuthUrl =
  `https://form.argosidentity.com/face-auth?pid=${FACEAUTH_PROJECT_ID}` +
  `&encrypted=${encodeURIComponent(encrypted)}`;
```

<Note>
  `pid` y `lang` no están sujetos a cifrado — añádalos como texto plano fuera de `encrypted`.
</Note>

## Definición de parámetros de solicitud

<ResponseField name="pid" type="string" required>
  Número único asignado al proyecto al crear un proyecto FaceAuth (se adjunta automáticamente a la URL)
</ResponseField>

<ResponseField name="sid" type="string" required>
  submission\_Id aprobado a través de ID document o Knowledge-based (se usa sid para distinguir)
</ResponseField>

<ResponseField name="authUserId" type="string">
  ID de usuario que el administrador asignará al usuario (puede ser el ID de usuario en el servicio del administrador o el mismo userId utilizado en ID document o Knowledge-based)
</ResponseField>

<ResponseField name="authCf1" type="string">
  Información adicional que el administrador asignará al usuario (por ejemplo, dirección de correo electrónico, etc.)
</ResponseField>

<ResponseField name="authCf2" type="string">
  Información adicional que el administrador asignará al usuario (igual que authCf1)
</ResponseField>

<ResponseField name="authCf3" type="string">
  Información adicional que el administrador asignará al usuario (igual que authCf1)
</ResponseField>

<ResponseField name="token" type="string">
  Token que el administrador agregará a la URL con fines de seguridad. <br />
  **¡Nota!**: Este token opera de forma independiente del token preregistrado en modo privado.

  <Accordion title="Cómo funciona el token de FaceAuth">
    El token está diseñado para asignar una URL única a cada usuario cuando se autentican a través de FaceAuth. <br />
    Para aplicar un token, debe habilitar la opción de configuración de condición de expiración de token en el proyecto FaceAuth, y funciona de la siguiente manera:

    * Expiración basada en conteo: Cuando el token se usa una vez, el Token ID expira inmediatamente.
    * Expiración basada en tiempo: Cuando ha transcurrido el tiempo desde el momento en que el token se usó una vez, el Token ID expira.

    Este token opera de forma independiente del token de modo privado del proyecto principal o del token preregistrado. <br />
    Por ejemplo, puede especificar un tokenId arbitrario establecido por el administrador en el token, e incluso si reutiliza el token usado en el proyecto principal, funciona porque se gestiona por separado.
    Para una guía sobre cómo habilitar la opción de configuración de condición de expiración de token en el proyecto FaceAuth, consulte [Guía de FACE AUTH — Configuración de condiciones de expiración de Token](/dashboard/es/face-auth-guide#configuración-de-condiciones-de-expiración-de-token).
  </Accordion>
</ResponseField>

<ResponseField name="lang" type="string">
  Idioma de visualización de la pantalla de Face Auth. Use un código ISO 639-1 en minúsculas (por ejemplo, `en`, `ko`). **No está sujeto a cifrado — añádalo en texto plano fuera de `encrypted`** (por ejemplo, `?pid={faceAuth_projectId}&encrypted={encrypted}&lang=en`). Si se omite, en móvil se usa el idioma del dispositivo y en PC el del navegador. Para la lista de idiomas admitidos, consulte [Idiomas Soportados](/es/idcheck/getting-started/liveform-languages).
</ResponseField>

<Note>
  Para casos aprobados donde no existe imagen selfie, se utilizará en su lugar la imagen de retrato del documento de identidad.
</Note>

<Card title="Validación y manejo de errores de Face Auth URL" icon="triangle-exclamation" href="/es/idcheck/add-on/faceauth-url-errors">
  Referencia por etapas de los códigos de error generados por fallos de validación de QueryString, fallos de precarga y fallos de autenticación, junto con los mensajes que los usuarios ven realmente.
</Card>

## Endpoints de la API de FaceAuth

<CardGroup cols={2}>
  <Card title=" POST/FaceAuth" icon="person-circle-plus" href="/es/idcheck/add-on/post-faceauth">
    Envío de FaceAuth
  </Card>

  <Card title="GET/FaceAuth" icon="person-circle-check" href="/es/idcheck/add-on/get-faceauth">
    Consulta de FaceAuth
  </Card>

  <Card title="GET/FaceAuth/Image" icon="person-circle-check" href="/es/idcheck/add-on/get-faceauth_image">
    Consulta de imagen de FaceAuth
  </Card>

  <Card title="DELETE/FaceAuth" icon="person-circle-xmark" href="/es/idcheck/add-on/delete-faceauth">
    Eliminación de FaceAuth
  </Card>
</CardGroup>

## Webhooks

<CardGroup cols={2}>
  <Card title="Faceauth" icon="person-circle-plus" href="/es/idcheck/add-on/add-on-webhook">
    Webhook de FaceAuth
  </Card>

  <Card title="Expiración de Token ID" icon="clock" href="/es/idcheck/add-on/add-on-webhook-token">
    Webhook de expiración de Token ID
  </Card>
</CardGroup>