API REST de FACEIO

Llama a la API REST de FACEIO desde tu backend privado para gestionar Facial IDs, comparar imágenes faciales, estimar edad y género, actualizar payloads y PIN Codes, obtener estadísticas y consultar el estado de la API.

ABRIR CONSOLA FACEIO

Crea una aplicación en FACEIO Console y obtén su clave de API privada desde el Administrador de aplicaciones. Mantén la clave en tu backend.

La API REST de FACEIO

Endpoints HTTP de backend para la gestión de Facial ID, verificación facial y operaciones de la aplicación

Cada aplicación FACEIO tiene asignada automáticamente una clave de API. Puedes obtenerla desde el Application Manager de FACEIO Console ↗. Esta clave privada permite que tu backend llame a la API REST de FACEIO desde cualquier lenguaje de programación compatible con HTTPS.

  • Utiliza las capacidades HTTP estándar para pasar parámetros y autenticar con una clave de API.
  • Devuelve códigos de respuesta HTTP estándar para indicar estados de éxito y error.
  • Siempre devuelve JSON en cada solicitud, independientemente del resultado.

Aviso importante

Las llamadas a la API y la instanciación del widget mediante la biblioteca JavaScript fio.js son flujos separados. El registro y la autenticación ocurren en el cliente, dentro del navegador del usuario. Las llamadas a la API REST deben originarse en el backend privado de tu aplicación y pueden estar sujetas a cuotas o límites de frecuencia según tu plan. Si estás empezando con FACEIO, comienza con Primeros pasos y después utiliza la Guía de integración. Consulta la tabla de precios para conocer los límites de cuota de la API REST.

URL base de la API REST

  • El endpoint base de la API de FACEIO se encuentra en https://api.faceio.net/.
  • El esquema de URL de la solicitud es https://api.faceio.net/cmd?param=val&param2=val2, donde cmd es el endpoint de la API y los valores param=val son sus parámetros. Cada sección indica el método HTTP compatible.
  • Supervisa la salud y el estado de la API en tiempo real en status.faceio.net ↗.
Resumen de la API
URL base api.faceio.net
Endpoint de comprobación de estado api.faceio.net/status ↗
Arquitectura RESTful
Versiones de HTTP y TLS HTTP/1.1, HTTP/2, HTTP/3; TLS 1.2 y 1.3
Autenticación Basada en clave ↓
Red Cloudflare
Tipo MIME de respuesta HTTP application/json
Códigos de estado HTTP Ver abajo ↓

Obtén tu clave de API

Al crear una nueva aplicación FACEIO, se te asigna automáticamente una clave de API. Sigue estos pasos para obtener y administrar tu clave:

  1. 1 Inicia sesión en FACEIO Console ↗.
  2. 2 Ve a Administrador de aplicaciones.
  3. 3 Selecciona la aplicación que quieres administrar.
  4. 4 Haz clic en la pestaña Clave de API .
  5. ✓ Copia la clave de API para las llamadas HTTP de tu servidor. La misma pestaña muestra las estadísticas y la información de cuota de la API.

Autenticación

Autentica las solicitudes al endpoint de la API FACEIO incluyendo tu clave de API en la solicitud HTTP. Consulta la sección anterior para saber cómo obtener y administrar esta clave.

Métodos de autenticación

Envía la clave de API mediante uno de los siguientes métodos compatibles:

Encabezado HTTP

Incluye tu clave de API en el encabezado HTTP WWW-Authenticate:

WWW-Authenticate: Bearer API_KEY
Parámetro de consulta

O añade la clave a tu POST o GET URL de solicitud:

https://api.faceio.net/endpoint?param=val&key=API_KEY

Advertencia de seguridad: Mantén tus claves de API seguras. Nunca las expongas en código del cliente, repositorios públicos, JavaScript del navegador, paquetes de aplicaciones móviles, registros ni herramientas de analítica. Usa únicamente scripts autorizados del servidor y revisa la guía de buenas prácticas de seguridad antes de usarla en producción.

Respuestas, estados y códigos de error HTTP

Los siguientes códigos de estado HTTP se devuelven en cada solicitud. Todos los endpoints de la API devuelven application/json independientemente del éxito o del fallo. Gestiona los fallos explícitamente en tu backend antes de conceder acceso, actualizar registros de usuarios o confiar en el estado de un Facial ID.

200 Éxito. El endpoint de la API ejecutó la operación correctamente.
400 Solicitud incorrecta. Normalmente indica que falta un parámetro obligatorio.
401 No autorizado. Falta la clave de API o no es válida.
404 No encontrado. El elemento solicitado, por ejemplo Facial ID) no existe.
405 Método no permitido. Este endpoint no admite el método HTTP indicado.
429 Demasiadas solicitudes. Se superó el límite de velocidad. Consulta la tabla de precios para consultar los límites de cuota.
500 Error interno del servidor o mantenimiento en curso.

Documentación de endpoints

DELETEFACIALID

GET
URL de acceso del endpoint https://api.faceio.net/deletefacialid
Descripción

Elimina un Facial ID y sus datos de payload vinculados de tu aplicación FACEIO. La operación también indica al motor de reconocimiento facial seleccionado que purgue el hash biométrico asociado.

El Facial ID es un identificador único (UUID) asignado de forma anónima a cada usuario registrado. El registro se realiza mediante una llamada al método enroll() de la biblioteca fio.js del lado del cliente.

Disponibilidad Todos los planes
Método HTTP GET

Parámetros HTTP

Campo Tipo Obligatorio Descripción
key HEX String SÍ La clave de API REST de tu aplicación.
fid String SÍ El Facial ID que quieres eliminar (purgar).

Respuesta HTTP

application/json

Este endpoint de la API siempre devuelve un objeto JSON. Se devuelven los siguientes campos:

Campo Tipo Descripción
status Integer Código de estado HTTP estándar: 200 si la operación tiene éxito; de lo contrario, un estado de error como 401.
payload Boolean TRUE si el Facial ID y sus datos se eliminaron por completo. FALSE en caso contrario.
Ejemplo de código para eliminar un Facial ID (Python)

CHECKFACIALID

GET
URL de acceso del endpoint https://api.faceio.net/checkfacialid
Descripción

Comprueba si un Facial ID está registrado en la aplicación FACEIO asociada con la clave de API proporcionada.
Disponibilidad Solo planes de pago o actualizados. Consulta la página de precios para obtener más información.
Método HTTP GET

Parámetros HTTP

Campo Tipo Obligatorio Descripción
key HEX String SÍ La clave de API REST de tu aplicación.
fid String SÍ El Facial ID que se va a verificar.

Respuesta HTTP

application/json

Este endpoint de la API siempre devuelve un objeto JSON. Se devuelven los siguientes campos:

Campo Tipo Descripción
status Integer Código de estado HTTP estándar: 200 si la operación tiene éxito; de lo contrario, un estado de error.
valid Boolean TRUE si el Facial ID es válido y está registrado. FALSE en caso contrario.
Ejemplo de código para validar un Facial ID (Python)

FACE-VERIFY

POST
URL de acceso del endpoint https://api.faceio.net/faceverify
Descripción

Compara dos imágenes faciales

El endpoint faceverify compara los rostros de dos imágenes y devuelve el resultado de coincidencia y las puntuaciones de similitud.

Envía una imagen Source y otra Target, cada una con un solo rostro. No se requiere un registro previo en FACEIO. Tu backend debe decidir cómo interpretar las puntuaciones devueltas dentro de su propio flujo.

Nota de privacidad: El procesamiento se realiza en memoria (RAM). Las imágenes se eliminan inmediatamente después del análisis. No se registran ni almacenan datos. Consulta las buenas prácticas de privacidad antes de añadir la verificación facial a los flujos de producción.
Disponibilidad Solo planes de pago o actualizados. Consulta la página de precios para obtener más información.
Método HTTP POST

Parámetros HTTP

Campo Tipo Obligatorio Descripción
key HEX String SÍ La clave de API REST de tu aplicación.
src Base64 | URL SÍ La persona de origen imagen. Debe ser una cadena codificada en Base64, en formato data URI, o una URL accesible públicamente. Asegúrate de que solo haya un solo rostro esté presente.
target Base64 | URL SÍ La persona de destino imagen que se comparará con la de origen. Debe ser una cadena codificada en Base64, en formato data URI, o una URL accesible públicamente.

Respuesta HTTP

application/json

Este endpoint de la API siempre devuelve un objeto JSON. Se devuelven los siguientes campos:

Campo Tipo Descripción
status Integer Código de estado HTTP estándar: 200 si la operación tiene éxito; de lo contrario, un estado de error.
same_person Boolean TRUE si los rostros de origen y destino pertenecen a la misma persona. FALSE en caso contrario.
dist Float Puntuación de similitud por distancia de 0 a 1. Un valor más cercano a 1 indica una mayor probabilidad de que los rostros pertenezcan a la misma persona.
sim Float Puntuación de similitud coseno (de 0 a 1). Cuanto más cerca de 1, mayor es la similitud.
Ejemplo de código de Face Verify (Python)

AGE-CHECK

POST
URL de acceso del endpoint https://api.faceio.net/agecheck
Descripción

Estimación de edad y género

El endpoint agecheck devuelve estimaciones de edad y género para el rostro de una imagen. No se requiere un registro previo en FACEIO. Trata la edad como una aproximación, no como prueba de identidad, edad exacta o decisión de elegibilidad legal.

Nota de privacidad: El procesamiento se realiza en memoria (RAM). Las imágenes se eliminan inmediatamente después del análisis. No se registran ni almacenan datos. Consulta las buenas prácticas de privacidad antes de añadir la estimación de edad y género a un flujo de producción.
Disponibilidad Solo planes de pago o actualizados. Consulta la página de precios para obtener más información.
Método HTTP POST

Parámetros HTTP

Campo Tipo Obligatorio Descripción
key HEX String SÍ La clave de API REST de tu aplicación.
img Base64 | URL SÍ La imagen de entrada que contiene el rostro que se analizará. Formato: data:{MIME_type};base64,{data} o una URL accesible públicamente.

Respuesta HTTP

application/json

Este endpoint de la API siempre devuelve un objeto JSON. Se devuelven los siguientes campos:

Campo Tipo Descripción
status Integer Código de estado HTTP estándar: 200 si la operación tiene éxito; de lo contrario, un estado de error.
age Integer Edad estimada de la persona de la imagen.
gender String Estimación del género de la persona de la imagen.
Ejemplo de estimación de edad y género (Python)

SETFACIALIDPAYLOAD

POST
URL de acceso del endpoint https://api.faceio.net/setfacialidpayload
Descripción

Establece o modifica los datos del payload asociados a un usuario inscrito específico mediante su Facial ID.

El payload almacenado se devuelve a tu sitio o aplicación web mediante fio.js después de la siguiente autenticación correcta del usuario. Úsalo para datos mínimos de la aplicación, como un ID interno de usuario. No incluyas secretos ni decisiones de autorización en el payload.
Disponibilidad Solo planes de pago o actualizados. Consulta la página de precios para obtener más información.
Método HTTP POST

Parámetros HTTP

Campo Tipo Obligatorio Descripción
key HEX String SÍ La clave de API REST de tu aplicación.
fid String SÍ El Facial ID que se actualizará.
payload Cadena/Datos sin procesar SÍ Los nuevos datos del payload que se asociarán al Facial ID. Estos datos se devolverán durante futuras autenticaciones. Usa cadenas, JSON u otro formato de payload administrado por el backend.

Respuesta HTTP

application/json
Campo Tipo Descripción
status Integer Código de estado HTTP estándar: 200 si la operación tiene éxito; de lo contrario, un estado de error.
payload Boolean TRUE si el payload se actualizó correctamente. FALSE en caso contrario.

SETFACIALIDPINCODE

POST
URL de acceso del endpoint https://api.faceio.net/setfacialidpincode
Descripción

Establece o cambia el código PIN asociado a un usuario inscrito concreto en tu aplicación FACEIO.
Disponibilidad Solo planes de pago o actualizados. Consulta la página de precios para obtener más información.
Método HTTP POST

Parámetros HTTP

Campo Tipo Obligatorio Descripción
key HEX String SÍ La clave de API REST de tu aplicación.
fid String SÍ El Facial ID que se actualizará.
pin Number SÍ El nuevo código PIN que se asociará al Facial ID. El usuario deberá confirmar este PIN cuando se le solicite durante una autenticación futura. El PIN debe contener entre 4 y 16 dígitos.

Respuesta HTTP

application/json

Este endpoint de la API siempre devuelve un objeto JSON. Se devuelven los siguientes campos:

Campo Tipo Descripción
status Integer Código de estado HTTP estándar. 200 indica éxito.
payload Boolean TRUE si el código PIN se actualizó correctamente. FALSE en caso contrario.
Ejemplo de código para cambiar el PIN (Python)

STAT

GET
URL de acceso del endpoint https://api.faceio.net/stat
Descripción

Recopila datos analíticos y estadísticas de tu aplicación FACEIO, incluidos los rostros indexados, las llamadas a la API y los registros recientes. Nota: las estadísticas se almacenan en caché y se actualizan cada 5 minutos.
Disponibilidad Solo planes de pago o actualizados. Consulta la página de precios para obtener más información.
Método HTTP GET

Parámetros HTTP

Campo Tipo Obligatorio Descripción
key HEX String SÍ La clave de API REST de tu aplicación.

Respuesta HTTP

application/json

Este endpoint de la API siempre devuelve un objeto JSON. Se devuelven los siguientes campos:

Campo Tipo Descripción
status Integer Código de estado HTTP estándar: 200 si la operación tiene éxito; de lo contrario, un estado de error como 401.
total_api_calls Integer Número acumulado de llamadas a la API realizadas por esta aplicación.
total_indexed_faces Integer Número total de rostros únicos inscritos/indexados actualmente.
last_indexed_faces Array Una lista con los Facial IDs de los usuarios inscritos más recientemente.

ABOUT

GET
URL de acceso del endpoint https://api.faceio.net/about
Descripción

Obtén la información de versión y el aviso de copyright de la instancia de la API FACEIO en ejecución.
Disponibilidad Todos los planes
Método HTTP GET

Parámetros HTTP

No se requieren parámetros.

Respuesta HTTP

application/json
Campo Tipo Descripción
status Integer Código de estado HTTP estándar: 200 si la operación tiene éxito; de lo contrario, un estado de error.
payload String Cadena de versión del servidor y aviso de copyright.

STATUS

GET
URL de acceso del endpoint https://api.faceio.net/status
Descripción

Comprueba el estado de salud de los servidores de la API FACEIO. El historial de estado en tiempo real también está disponible en status.faceio.net ↗.
Disponibilidad Todos los planes
Método HTTP GET

Parámetros HTTP

No se requieren parámetros.

Respuesta HTTP

application/json
Campo Tipo Descripción
status Integer 200 indica un estado operativo (System OK). 500 indica mantenimiento o una interrupción del servicio.
error String Mensaje de error, si el estado no es 200.
payload String Mensaje de estado, por ejemplo, "System OK".

Conecta tu backend a la API REST

Crea una aplicación FACEIO, obtén su clave privada de REST API desde FACEIO Console y llama a los endpoints documentados desde tu backend. Nunca expongas la clave de API en el navegador ni en el código de una aplicación móvil.

Lee la guía de primeros pasos → Abrir FACEIO Console
Precisión LFW del 99,7%