Centro de desarrolladores fio.js, API y webhooks

Documentación para integrar FACEIO en una aplicación web: crea una aplicación, carga fio.js, llama a enroll() o authenticate(), y conecta endpoints de REST API y webhooks cuando tu backend los necesite.

Ir a: Inicio rápido Guía de integración REST API Webhooks
ABRIR FACEIO Console

Crea una aplicación en FACEIO Console, copia su Public ID, configura los dominios y las opciones de seguridad y añade fio.js a tu sitio web o aplicación web.

Inicio rápido - Autenticación facial

~ 5 min

1 Crea tu aplicación

Inicia sesión en FACEIO Console ↗ y usa el Application Wizard para crear una aplicación. Elige un motor de reconocimiento, añade los dominios donde puede ejecutarse el widget y copia el Public ID que aparece al final.

Un Public ID tiene este formato fioa1b2c3d4. Puedes usarlo en el navegador y es necesario para crear la instancia del SDK.

2 Importa fio.js en tu sitio

Añade el contenedor del widget y carga fio.js antes de la etiqueta de cierre </body> . Usa la CDN oficial para que las correcciones del navegador y las actualizaciones de seguridad lleguen a tu aplicación sin un nuevo despliegue.

index.html
HTML 
<div id="faceio-modal"></div>
<script src="https://cdn.faceio.net/fio.js"></script>
¿Usas un bundler? Instala el paquete NPM oficial ↗
npm i @faceio/fiojs

3 Crea una instancia de faceIO

Crea una instancia de faceIO con el Public ID de tu aplicación. Mantén esa instancia disponible para las partes de tu interfaz que necesiten registrar o autenticar a un usuario.

app.js
JavaScript 
<script type="text/javascript">
  /* Crea una instancia de fio.js con el Public ID de tu aplicación */
  const faceio = new faceIO("app-public-id");
</script>

4 Llama al widget

Cuando fio.js esté cargado y exista la instancia faceIO(), llama a uno de los dos métodos principales:

enroll()

Registra a un usuario nuevo y devuelve un Facial ID que puedes asociar al registro de su cuenta - Acceder a la documentación →

authenticate()

Verifica a un usuario recurrente frente al índice facial de tu aplicación - Acceder a la documentación →

app.js
JavaScript 
<button onclick="enrollNewUser()">Registrar nuevo usuario</button>
<button onclick="authenticateUser()">Autenticar usuario</button>

<script type="text/javascript">
  const faceio = new faceIO("app-public-id");

  function enrollNewUser() {
    // Llamar a faceio.enroll() inicia el flujo de registro
  }

  function authenticateUser() {
    // Llamar a faceio.authenticate() inicia el flujo de autenticación
  }

  function handleError(errCode) {
    // Gestiona el error aquí
  }
</script>

Siguientes pasos

Guía completa de primeros pasos

Configuración de FACEIO Console, capturas de pantalla y lista de comprobación para el lanzamiento

Guías del SDK y frameworks

Ejemplos para React, Vue, Angular y JavaScript sin framework

Seguridad y buenas prácticas

Comprobaciones antes de pasar a producción

SDK y frameworks

Icono de primeros pasos
Inicio rápido

Guía de primeros pasos

Un recorrido práctico por tu primera integración de FACEIO: configuración de FACEIO Console, autorización de dominios, selección del motor y un flujo de registro funcional, con capturas de pantalla.

  • Recorrido paso a paso por FACEIO Console con capturas de pantalla
  • Lista de comprobación de dominios, claves y permisos del navegador
  • HTML inicial que puedes adaptar a tu aplicación
Abrir guía de configuración
Icono de código para desarrolladores
Documentación de la API

Referencia de la API y boilerplate

La referencia del SDK fio.js incluye parámetros de métodos, valores devueltos, códigos de error y ejemplos de frameworks.

  • Referencia completa de los métodos enroll() y authenticate()
  • Todos los códigos de error con patrones de gestión recomendados
  • Ejemplos de frameworks para stacks JavaScript habituales
Ver guía de integración
Vanilla JavaScript

Vanilla JS

JavaScript puro
React

React

v18+ / Hooks
Vue.js

Vue.js

Vue 3 / Composition
Angular

Angular

v15+ / Standalone
Next.js

Next.js

App Router y Pages Router
Svelte

Svelte

Listo para SvelteKit
Nuxt.js

Nuxt.js

Nuxt 3 / SSR
Ember.js

Ember.js

Edición Octane
Notas de compatibilidad de frameworks
  • SDK independiente del framework
    Usa FACEIO con React, Vue, Angular, Next.js, Svelte, Nuxt.js, Ember.js o JavaScript puro.
  • Usa tus rutas existentes
    fio.js es independiente del framework. Añádelo a los flujos de registro e inicio de sesión que ya utiliza tu sitio web o aplicación web.
  • Requisitos del navegador
    Funciona en navegadores modernos con una webcam estándar. Los usuarios no necesitan hardware biométrico dedicado.
Navegadores compatibles:
Chrome Chrome
Firefox Firefox
Edge Edge
+ todos los navegadores basados en Chromium
Ver todos los ejemplos

Webhooks y API

Cuando un usuario se registra, se autentica o elimina un Facial ID, FACEIO envía un HTTP POST al endpoint configurado, con los detalles del evento en el cuerpo JSON.

Documentación completa
Icono de webhooks
Eventos en tiempo real

Webhooks y notificaciones de eventos

Mantén tu backend sincronizado cuando los usuarios se registren, se autentiquen o eliminen un Facial ID.

ENROLL AUTH DELETION
Configurar webhooks

Cómo funcionan los webhooks

  1. 1

    Un usuario completa un flujo de registro, autenticación o eliminación en el widget de FACEIO.

  2. 2

    FACEIO envía un HTTP POST a la URL de tu endpoint configurado.

  3. 3

    Valida el WWW-Authenticate bearer token antes de procesar el payload JSON.

  4. Devuelve 200 OK en un plazo de 6 segundos para que FACEIO sepa que recibió el evento.

Guía de configuración (5 pasos)
webhook-payload.json
JSON 
{
  "eventName": "AUTH",
  "facialId": "fid_a1b2c3d4e5f6...",
  "appId": "your-app-public-id",
  "clientIp": "203.0.113.42",
  "payload": "your-linked-user-data",
  "details": {
    "timestamp": "2025-12-29",
    "gender": "male",
    "age": "28"
  }
}

Campos principales

eventName
Tipo de evento: ENROLL / AUTH / DELETION
facialId
Facial ID asociado a la aplicación
payload
Tus datos de usuario vinculados (plan Business+)
clientIp
IP pública del navegador del usuario
Autenticar solicitudes entrantes

Compara siempre el WWW-Authenticate bearer token con la clave del webhook mostrada en FACEIO Console antes de confiar en el payload.

Endpoints de REST API

Icono de HTTP y red

Accede a los endpoints de REST API

Control programático

Usa endpoints HTTPS autenticados para gestionar aplicaciones FACEIO, Facial IDs y flujos de cuenta del lado del servidor. fio.js se ejecuta en el navegador y no es necesario en tu backend.

GET POST DELETE Gestiona aplicaciones y Facial IDs
Explorar REST API
DELETE
Eliminar Facial ID

Elimina el Facial ID de un usuario del índice facial de tu aplicación.
GET
Obtener detalles de la aplicación

Obtén metadatos, recuentos de registros y la configuración de una aplicación.
GET
Listar todas las aplicaciones

Lista las aplicaciones FACEIO vinculadas a tu cuenta, incluidos sus IDs, nombres y estado.
POST
Comprobar pertenencia

Comprueba si un Facial ID pertenece al índice facial de tu aplicación.
POST
Cambiar nivel del motor

Cambia mediante programación entre niveles del motor de reconocimiento facial de tu aplicación.
Ver todos los endpoints

Referencia completa de REST API

¿Quieres ejecutar FACEIO en tu propia infraestructura?

Usa la opción on-premise si tu despliegue necesita infraestructura local y control local del motor de reconocimiento seleccionado.

Más información

Códigos de error

Cuando se rechaza la Promise devuelta por enroll() o authenticate(), recibes un errCode. Gestiona explícitamente los casos comunes para ofrecer al usuario un siguiente paso claro.

Código Constante Significado Acción recomendada
1 fioErrCode.PERMISSION_REFUSED El usuario o el navegador denegó el acceso a la cámara o al micrófono. Pide al usuario que permita el acceso a la cámara y vuelve a intentarlo.
2 fioErrCode.NO_FACES_DETECTED No se detectó ningún rostro en el encuadre de la cámara durante la sesión. Pide al usuario que se coloque con buena iluminación y mire directamente a la cámara.
3 fioErrCode.UNRECOGNIZED_FACE El rostro escaneado no coincide con ningún usuario enrolled en el índice facial de tu aplicación. Muestra un error y ofrece el flujo de registro si el usuario es nuevo.
4 fioErrCode.MANY_FACES Se detectaron varios rostros al mismo tiempo en el encuadre de la cámara. Pide al usuario que se asegure de que solo se vea su rostro.
5 fioErrCode.FACE_DUPLICATION Este rostro ya está enrolled en el índice facial de tu aplicación. Redirige al usuario al flujo de inicio de sesión (authenticate).
6 fioErrCode.PAD_ATTACK La detección de vivacidad señaló un intento de spoofing (foto, vídeo o máscara). Rechaza el intento sin revelar detalles de la lógica de detección.
7 fioErrCode.MINORS_NOT_ALLOWED La estimación de edad indica que el usuario está por debajo del límite mínimo configurado en tu aplicación. Muestra un mensaje adecuado de control de edad y cancela el flujo.
10 fioErrCode.NETWORK_IO Se produjo un error de red o tiempo de espera al comunicarse con los servidores de FACEIO. Vuelve a intentarlo tras una breve espera y comprueba la conexión del usuario.

Esta tabla cubre los casos comunes. La referencia completa incluye errores de red, sesión, navegador y consentimiento.

Referencia completa de códigos de error

Buenas prácticas

Lee antes de pasar a producción

La autenticación facial requiere un despliegue cuidadoso. Empieza por las buenas prácticas de seguridad y los controles de privacidad y consentimiento antes de publicar.

Icono de seguridad
Configuración necesaria

Seguridad de la aplicación

Restringe dónde puede ejecutarse el Widget, mantén activada la validación con PIN Code predeterminada, configura la detección de vivacidad y valida los eventos del backend.

  • Autoriza dominios para los orígenes exactos de producción
  • Configura la detección de vivacidad para ayudar a detectar ataques de presentación
  • Valida los tokens de webhook antes de actualizar el estado de la cuenta
Ver guía de seguridad
Icono de privacidad
Controles de privacidad

Privacidad de la aplicación

Muestra un consentimiento claro antes de capturar, mantén los payloads pequeños, atiende las solicitudes de eliminación y conserva un registro de auditoría que tu equipo pueda revisar.

  • Muestra siempre el consentimiento antes de capturar
  • Minimiza los datos del payload a lo estrictamente necesario
  • Atiende las solicitudes de eliminación válidas conforme a las reglas de conservación aplicables
Ver guía de privacidad
Facial ID
Modelo de identidad

Identificador facial único

Después del registro, FACEIO devuelve un Facial ID que pertenece a tu aplicación. Guarda ese identificador junto a tu propio registro de usuario.

// Ejemplo de asociación
await db.users.update({
  where: { email: "user@x.com" },
  data:  { facialId: u.facialId }
});
Más información sobre Facial IDs
Trust Center
Flujo de datos

Motor de reconocimiento y flujo de datos

FACEIO, incluidos fio.js, el Widget, la REST API y Console, no almacena, gestiona ni accede a hashes biométricos. El Facial Recognition Engine seleccionado por el propietario de la aplicación gestiona la comparación facial y los hashes biométricos. Los propietarios de las aplicaciones siguen siendo responsables del consentimiento, la conservación, la eliminación y la configuración del motor.

Consentimiento
Eliminación por parte del usuario
Elección del motor
IDs asociados al ámbito
Visitar Trust Center

Lista de comprobación para producción

Haz

  • Carga fio.js exclusivamente desde cdn.faceio.net
  • Restringe el widget a tus dominios exactos de producción en FACEIO Console
  • Valida los tokens de webhook y los identificadores de aplicación esperados antes de actualizar el estado de la cuenta
  • Usa HTTPS en todas las páginas donde se cargue el widget
  • Muestra una pantalla de consentimiento antes de llamar a enroll()

No hagas

  • No cargues fio.js desde servidores espejo no oficiales; usa la CDN oficial para que las correcciones del navegador lleguen a tu aplicación
  • No guardes imágenes faciales, hashes biométricos ni payloads de autenticación sensibles en el almacenamiento del cliente o en los registros de la aplicación
  • No cargues el widget en http://; el acceso a la cámara y las APIs seguras del navegador requieren HTTPS
  • No llames a enroll() antes de mostrar el aviso requerido y obtener el consentimiento explícito del usuario final
  • Nunca expongas tu clave secreta de API en el lado del cliente

Descripción de productos

Autenticación facial

Añade autenticación facial con fio.js. Los usuarios se registran en el navegador y tu aplicación recibe un facialId asociado a la aplicación para futuros flujos de autenticación.

  • Guarda el facialId devuelto en tu backend para vincular el registro de FACEIO con tu propio registro de usuario.
  • Llama a enroll() y authenticate() desde la misma instancia de fio.js.
  • Úsalo para iniciar sesión sin contraseña, volver a autenticar la cuenta o realizar comprobaciones adicionales en tu flujo de acceso existente.
fio.js inicio de sesión con reconocimiento facial autenticación facial
Guía de integración

Meeting Shield

Una extensión de Chrome para detectar deepfakes en Google Meet, Zoom Web y Microsoft Teams Web. Úsala para alertar a los participantes sobre vídeos sospechosos, sintéticos, reproducidos o manipulados en reuniones desde el navegador.

Explorar Meeting Shield

ID Match

Un widget de navegador integrable para capturar un documento de identidad y un selfie en directo, comprobar la vivacidad y comparar el selfie con el retrato del documento. La extracción opcional de campos utiliza PixLab DOCSCAN ↗, compatible con más de 11 mil formatos de documentos de más de 197 países y territorios. ID Match no autentica el documento ni establece la identidad legal.

Explorar ID Match

Recursos y comunidad

FACEIO Console

FACEIO Console

Crea aplicaciones, revisa métricas, ajusta la configuración de seguridad y copia las claves que necesita tu integración.

Usa FACEIO Console durante el desarrollo para gestionar dominios permitidos, elegir la configuración de reconocimiento y confirmar que cada entorno utiliza el Public ID correcto.

Métricas en vivo Configuración de la aplicación Claves de API
Abrir FACEIO Console

FAQ

Preguntas frecuentes

Centro de ayuda

Solución de problemas

Estado

Disponibilidad en vivo
Configuración para desarrolladores

Añade autenticación facial a tu sitio web o aplicación web

Crea una aplicación en FACEIO Console, copia tu Public ID, carga fio.js y prueba enroll() y authenticate() con tu backend.

Integración directa en 5 minutos
Referencias de fio.js, REST API y webhooks
Integración de navegador independiente del framework
Comprobaciones de consentimiento, eliminación y seguridad
Abrir FACEIO Console Leer guía de configuración