Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Descripción de los objetos que puede encontrar en el sistema de Oz Forensics.
Los objetos del sistema en los productos de Oz Forensics tiene la estructura jerárquica que se muestra en la siguiente imagen.
En el nivel superior, hay una Empresa. Puede utilizar una copia de Oz API para trabajar con varias empresas.
El siguiente nivel es un Usuario. Una empresa puede contener cualquier cantidad de usuarios. Hay varios roles de usuarios con diferentes permisos. Para más información, consulte Roles de usuario.
Un usuario puede crear cualquier número de carpetas. Cada carpeta puede contener cualquier cantidad de medios. Un usuario aplica análisis a uno o varios medios dentro de una carpeta.
Además de estos parámetros, cada tipo de objeto tiene otros parámetros específicos.
Parámetro
Tipo
Descripción
time_created
Timestamp
tiempo de creación del objeto (excepto usuario y empresa)
time_updated
Timestamp
tiempo de actualización del objeto (excepto usuario y empresa)
meta_data
Json
cualquier parámetro del usuario
technical_meta_data
Json
parámetros requeridos por el módulo; reservados para necesidades internas
Parámetro
Tipo
Descripción
company_id
UUID
el id. de la empresa en el sistema
name
String
el nombre de la empresa en el sistema
Parámetro
Tipo
Descripción
user_id
UUID
el id. del usuario dentro del sistema
user_type
String
first_name
String
nombre
last_name
String
apellido
middle_name
String
segundo nombre
String
email del usuario = login
password
String
contraseña del usuario (sólo se requiere para los nuevos usuarios o para cambiarla)
can_start_analyze_*
String
depende de los roles de los usuarios.
company_id
UUID
id. de la empresa del usuario actual dentro del sistema
is_admin
Boolean
si este usuario es un admin o no
is_service
Boolean
si esta cuenta de usuario es de servicio o no
Parámetro
Tipo
Descripción
folder_id
UUID
el id. de la carpeta dentro del sistema
resolution_status
ResolutionStatus
el último estado del análisis
Parámetro
Tipo
Descripción
media_id
UUID
el id. de los medios
original_name
String
the original filename (how el nombre original del archivo (cómo se llamaba el archivo en la máquina del cliente)
original_url
Url
el enlace HTTP a este archivo en el servidor de la API
tags
Array(String)
una lista de etiquetas para este archivo
Parámetro
Tipo
Descripción
analyse_id
UUID
id. del análisis
folder_id
UUID
id id. de la carpeta
type
String
el tipo de análisis (BIOMETRY\QUALITY\DOCUMENTS)
results_data
JSON
resultados del análisis
Oz API es el componente más importante del sistema. Su función es garantizar que todos los demás componentes estén conectados entre sí. Oz API:
proporciona la interfaz Rest API unificada para ejecutar análisis de Liveness y Biometry
procesa la autorización y administración de los permisos de los usuarios
sigue y registra las solicitudes y análisis enviados a la base de datos
archiva los archivos multimedia entrantes
recoge la telemetría de las app móviles conectadas
proporciona ajustes para modelos de dispositivos específicos
genera informes con los resultados de los análisis
Descripción del esquema de API Rest:
Una guía sobre cómo obtener y ampliar las tokens.
Para obtener los tokens de acceso, haga una solicitud POST a/authorize/auth/
con el correo electrónico y la contraseña necesarios en el cuerpo de la solicitud. La respuesta correcta devolverá un par de tokens:access_token
y expire_token
.
access_token es una clave que le da acceso a los recursos del sistema. Para acceder a un recurso, debe agregar su access_token
al encabezado.
headers = {‘ X-Forensic-Access-Token’: <access_token>}
access_token funciona por un tiempo limitado, los límites dependen del tipo de cuenta.
cuentas de servicio: – OZ_SESSION_LONGLIVE_TTL
(5 años por defecto),
otras cuentas: – OZ_SESSION_TTL
(15 minutos por defecto).
expire_token es el token que se utiliza para obtener un nuevo par de tokens.
Si el valor de expire_date
> fecha actual, el valor de expire_date
de la sesión actual se establece en la fecha actual + el período de tiempo definido como se muestra arriba (dependiendo del tipo de cuenta).
Para renovar access_token
y expire_token
, haga una petición POST a authorize/refresh/
. Agregue expire_token
al cuerpo de la petición y X-Forensic-Access-Token
al encabezado. En caso de éxito, recibirá un nuevo par de access_token
y expire_token
. El par "antiguo" se eliminará durante la primera autentificación con los tokens renovados.
Los códigos de respuesta 2 XX indican una solicitud correctamente procesada (por ejemplo, el código 200 para recuperar datos, el código 201 para agregar una nueva entidad, el código 204 para una eliminación correcta, etc.)
Los códigos de respuesta 4 XX indican que una solicitud no se pudo procesar correctamente debido a algunos problemas con los datos del cliente (por ejemplo, 404 al dirigirse a un recurso inexistente).
Los códigos de respuesta 5 XX indican que se ha producido un error del lado del SI durante el procesamiento de la solicitud (por ejemplo, cuando una BD no está disponible temporalmente).
Cada error de respuesta incluye el código HTTP y los datos JSON con la descripción del error. Tiene la siguiente estructura:
error_code
– número del código de error;
error_message
– texto con la descripción del error;
details
– detalles adicionales del error (el formato se especifica para cada caso). Puede estar vacío.
Ejemplo de respuesta de error:
Códigos de error:
0 – UNKNOWN
Error de servidor desconocido.
1 - NOT ALLOWED
Se llamó un método no permitido. Por lo general, le sigue el estado de respuesta HTTP 405. Por ejemplo, al intentar solicitar el método PATCH, cuando sólo se admiten los métodos GET/POST.
2 - NOT REALIZED
El método está documentado pero no realizado, por ninguna razón temporal o permanente.
3 - INVALID STRUCTURE
Estructura incorrecta de la solicitud. Faltan algunos campos obligatorios o se ha producido un error de validación de formato.
4 - INVALID VALUE
Valor incorrecto del parámetro dentro del cuerpo de la solicitud o de la consulta.
5 - INVALID TYPE
Tipo de datos no válido del parámetro de la solicitud.
6 - AUTH NOT PROVIDED
No se especificó el token de acceso.
7 - AUTH INVALID
El token de acceso no existe en la base de datos.
8 - AUTH EXPIRED
El token de autentificación caducó.
9 - AUTH FORBIDDEN
Acceso denegado para el usuario actual.
10 - NOT EXIST
No se encuentra el recurso solicitado (alternativa de HTTP status_code = 404).
11 - EXTERNAL SERVICE
Error en el sistema de información externo.
12 – DATABASE
Error crítico de la base de datos en el servidor.
Los ajustes de configuración están contenidos en el archivo config.py
. Su ubicación depende del método de instalación:
máquina host o contenedor Docker oz-api: /opt/gateway/configs
Todos los archivos multimedia entrantes se guardan en el directorio local montado en uno de los posibles puntos finales dependiendo del método de instalación:
servidor anfitrión o contenedor Docker: /opt/gateway/static
en el caso del instalador autónomo: /var/lib/docker/volumes/api_oz-api-static-vol/_data
cualquier ruta especificada a través de la configuración
En la mayoría de los casos de integración, se puede acceder a los archivos multimedia en la web mediante enlaces directos a nombres de archivo generados aleatoriamente.
Para acceder a los medios, es necesario especificar en el archivo de configuración el nombre de su host o dirección IP externos, el puerto y el protocolo de conexión.
Para su correcto funcionamiento, los algoritmos de resolución necesitan que cada medio cargado esté marcado con etiquetas especiales. Las etiquetas del video y de las imágenes son diferentes. Su función es ayudar a los algoritmos a identificar lo que debe aparecer en la foto o el video y a analizar el contenido.
Los siguientes tipos de etiquetas deben especificarse en el sistema para los archivos de video.
Para identificar el tipo de datos del video:
video_selfie
Para identificar la orientación del video:
orientation_portrait
– orientación vertical;
orientation_landscape
– orientación horizontal.
Para identificar la acción en el video:
video_selfie_left
– giro de cabeza a la izquierda;
video_selfie_right
– giro de cabeza a la derecha;
video_selfie_down
– inclinación de la cabeza hacia abajo;
video_selfie_high
– cabeza levantada;
video_selfie_smile
- sonrisa;
video_selfie_eyes
- parpadeo;
video_selfie_scan
- escaneo.
Ejemplo del conjunto de etiquetas correctas para un archivo de video con la acción "parpadeo":
Los siguientes tipos de etiquetas deben especificarse en el sistema para los archivos de video:
Una etiqueta para selfies:
photo_selfie
– para identificar el tipo de imagen como "selfie".
Etiquetas para fotos/escaneos de tarjetas de identidad:
photo_id
– para identificar el tipo de imagen como "ID";
photo_id_front
– para la foto del anverso del DNI;
photo_id_back
– para la foto del reverso del DNI.
Ejemplo del conjunto de etiquetas correcto para un archivo de fotos "selfie":
Example of the correct tag set for a photo file with the face side of an ID card:
Ejemplo del conjunto de etiquetas correcto para un archivo de foto con el anverso de un documento de identificación:
: /var/lib/docker/volumes/api_oz-api-config-vol/_data
Código de error
Mensaje de error
¿Qué provocó el error?
400
No se pudo localizar el campo de key_path
expire_token
de los datos dict proporcionados
expire_token
no se encontró en el cuerpo de la solicitud
401
Sesión no encontrada
La sesión con expire_token
que ha pasado no existe.
403
No tiene acceso para actualizar esta sesión
El usuario que realiza la solicitud no es el propietario de esta sesión de expire_token
.
Cada uno de los nuevos usuarios de la API obtiene un rol que define las restricciones de acceso de las conexiones directas a la API.
Cada rol se combina con las banderas is_admin
y is_service
, lo que implica restricciones adicionales.
is_service
es una bandera que marca la cuenta de usuario como cuenta de servicio a efectos de conexión automática. Esta autenticación de usuario crea un token de acceso de larga duración (5 años por defecto). El tiempo de vida del token para usos regulares es de 15 minutos por defecto (parametrizado) y, por defecto, el tiempo de vida de un token se extiende con cada solicitud (parametrizado).
ADMIN
es un administrador del sistema. Tiene acceso completo sin restricciones a todos los objetos del sistema;
OPERATOR
es un operador del sistema. Tiene acceso ilimitado a todos los objetos y permisos para cambiar el estado de los análisis;
CLIENT
es una cuenta de cliente normal. Puede cargar archivos multimedia, procesar análisis, mostrar resultados en carpetas personales, generar informes y otras funciones habituales;
is_admin
– si está establecida, el usuario obtiene acceso a los datos de otros usuarios dentro de su propia empresa;
can_start_analyse_biometry
– bandera adicional para restringir el acceso a los análisis BIOMETRY (activada por defecto);
can_start_analyse_quality
– bandera adicional para restringir el acceso a los análisis LIVENESS (QUALITY) (activada por defecto);
CLIENT ADMIN
es un administrador de la empresa que puede administrar su cuenta de empresa y los usuarios dentro de ella. Además, CLIENT ADMIN
puede modificar los estados de los análisis, los veredictos de los operadores, ver los datos de todos los usuarios de su empresa, eliminar los archivos de las carpetas, las plantillas de informes con o sin archivos adjuntos, los propios informes y los análisis individuales. El rol está presente sólo en WebUI. Fuera de WebUI, CLIENT ADMIN
es reemplazado por el rol CLIENT
con la bandera is_admin
con el valor true establecido.
CLIENT OPERATOR
es similar a CLIENT ADMIN
, pero sin permisos para administrar la cuenta de la empresa y de los usuarios.
Para probar Oz API, puede utilizar el software gratuito llamado Postman. Descargue e instale Postman Client desde esta página.
Descargue el archivo .JSON actual que contiene la colección Postman de Oz API:
Inicie el cliente e importe la colección actual de Oz API para Postman haciendo clic en el botón Import:
Arrastre y suelte el archivo de la colección desde su explorador de archivos a la ventana de importación:
La colección se importará y aparecerá en la interfaz de Postman con todos los métodos de interacción de Oz API:
Para la mayoría de los objetos del sistema, se pueden almacenar metadatos: cualquier campo y sus valores creados por los usuarios. Aquí está la lista de estos objetos:
usuarios/api/users/{{user_id}}/meta_data
compañías /api/companies/{{company_id}}/meta_data
carpetas/api/folders/{{folder_id}}/meta_data
medios /api/media/{{media_id}}/meta_data
analisis /api/analyses/{{analyse_id}}/meta_data
Para procesar los metadatos, puede utilizar los métodos de la API Rest:
GET
https://apidoc.ozforensics.com/api/.../metadata
POST
https://apidoc.ozforensics.com/api/.../metadata
PATCH
https://apidoc.ozforensics.com/api/.../metadata
DELETE
https://apidoc.ozforensics.com/api/.../metadata
A continuación se explica cómo agregar el id. de cliente client_iin
a un objeto de carpeta:
PATCH
https://apidoc.ozforensics.com/api/folders/9f864721-6c4b-4d0a-b31b-cee5136234c0/meta_data
{ "client_iin": "418974987" }
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
object
un objeto .JSON con los valores de todos los campos
object
un objeto .JSON con campos nuevos o modificados
object
Aquí se familiarizará con los tipos de análisis que ofrece Oz API.
Utilizando Oz API, puede realizar uno de los siguientes análisis:
biometry
quality (liveness, best shot)
documents
blacklist
El algoritmo permite comparar varios medios y comprobar si las personas que aparecen en ellos se parecen. Como fuentes, puede utilizar imágenes, videos y escaneos de documentos (con foto). Para realizar el análisis, el algoritmo necesita al menos dos medios.
Tras la comparación, el algoritmo proporciona un número que representa el nivel de similitud. El número varía del 100 al 0%, donde
100%: los rostros son similares
0%: los rostros no son similares y pertenecen a diferentes personas
El algoritmo de detección de Liveness tiene como objetivo comprobar si la persona que aparece en un video es un ser humano real que actúa de buena fe, y no una falsificación.
El algoritmo "Best Shot" comprueba la mejor toma de un video (el fotograma de mejor calidad en el que mejor se vea el rostro). Es una adición a liveness.
Tras la comprobación, el análisis muestra la posibilidad de un ataque de spoofing en porcentajes.
100%: se detectó un ataque, la persona del video no es una persona viva real
0%: la persona en el video es una persona viva real
*Spoofing en biometría es un tipo de estafa cuando una persona se disfraza de otra utilizando herramientas tanto de software, como no de software como deepfake, máscaras, fotos ya hechas y videos.
El análisis de los documentos tiene como objetivo reconocer el documento y comprobar si sus campos son correctos según su tipo.
Oz API utiliza un servicio de análisis OCR de terceros prestado por nuestro socio. Si quiere cambiar este servicio por otro, póngase en contacto con nosotros.
Como salida, obtendrá una lista de campos del documento con resultados de reconocimiento para cada campo y un resultado de comprobación que puede ser:
Los documentos pasaron la comprobación con éxito
Los documentos no pasaron el control
El algoritmo de comprobación de la lista negra se utiliza para determinar si la persona que aparece en una foto o video está presente en la base de datos de imágenes precargadas. Esta base puede utilizarse como lista negra o lista blanca. En el primer caso, se compara el rostro de la persona con el de estafadores conocidos; en el segundo, puede tratarse de una lista de VIP.
Tras la comparación, el algoritmo proporciona un número que representa el nivel de similitud. El número varía del 100 al 0%, donde
100%: la persona de una imagen o video coincide con alguien de la lista negra
0%: la persona no se encuentra en la lista negra
Aquí puede encontrar las descripciones de los casos de uso más comunes de Oz Forensics Liveness and Face Biometric System.
El algoritmo biométrico le permite comparar varias fotos y evaluar el nivel de similitud de las personas representadas en ellas. Como fuente los algoritmos de medios se toman fotos, videos y documentos (con fotos).
Pasos de procesamiento:
En source_media
se indica uno o varios media_id
de la respuesta anterior. Es opcional y depende de si necesita comprobar uno o varios videos cargados.
Guardar elanalyse_id
de la respuesta.
How to compare a photo or video with ones from your database.
El algoritmo de búsqueda en la lista negra está diseñado para determinar si una persona está en una base de datos de fotos precargadas. Se puede utilizar un fragmento de video o una foto como fuente de comparación.
Procedimiento:
source_media
especifica el media_id
de la respuesta de la solicitud anterior. Esto es opcional y se utiliza cuando se quiere comprobar uno de los dos videos precargados en la carpeta.
Guardar elanalyse_id
de la respuesta.
.
el archivo de video en una nueva carpeta.
3. el análisis.
4. los resultados depués de unos instantes. Repita la operación hasta que los campos resolution_status
y resolution
cambien de estado a cualquier otro excepto PROCESSING
y trátelo como resultado.
.
el archivo en una nueva carpeta.
3. el análisis.
4. los resultados depués de unos instantes. Repita la operación hasta que los campos resolution_status
y resolution
cambien de estado a cualquier otro excepto PROCESSING
y trátelo como resultado.
El algoritmo "Best shot" tiene por objeto elegir de una grabación de video el fotograma de mayor calidad y mejor ajustado con un rostro. Este algoritmo funciona como parte del análisis de Liveness.
Nota: Best Shot requiere el uso de la etiqueta video_selfie_scan
.
Pasos de procesamiento:
Ponga el archivo de video en una nueva carpeta.
3. Inicie el análisis.
En source_media
se indica uno o varios media_id
de la respuesta anterior. Es opcional y depende de si necesita comprobar uno o varios videos cargados.
Guardar elanalyse_id
de la respuesta.
4. Comprueba los resultados depués de unos instantes. Repita la operación hasta que los campos resolution_status
y resolution
cambien de estado a cualquier otro excepto PROCESSING
y trátelo como resultado.
5. La URL de la mejor toma se establece en la respuesta results_media
-> output_images
-> original_url
.
Este artículo describe cómo obtener las puntuaciones del análisis.
Cuando se realiza un análisis, el resultado que se obtiene es un número. En el caso de la biometría, refleja la posibilidad de que las dos o más personas representadas en sus medios sean la misma persona. En el caso de Liveness, muestra una posibilidad de deepfake o un ataque de spoofing: que la persona que aparece en los medios cargados no es real. Puede obtener estos números mediante una respuesta JSONa de la API.
Envíe una petición a la carpeta o lista de carpetas para obtener una respuesta JSON. Establezca el parámetro with_analyses en True
.
Para el análisis Biometry, busque el valor del parámetro min_confidence
:
Este valor es un resultado cuantitativo de la coincidencia de las personas en los medios de comunicación cargados.
4. Para el análisis de Liveness, busque el valor de confidence_spoofing
relacionado con el video que necesita:
Este valor es la posibilidad de que una persona no sea real.
Para procesar un grupo de resultados de análisis, puede analizar la respuesta JSON correspondiente.
El algoritmo de detección Liveness detecta una persona viva real en un fragmento de video.
Pasos de procesamiento:
Ponga el archivo de video en una nueva carpeta.
3. Inicie el análisis.
En source_media
se indica uno o varios media_id
de la respuesta anterior. Es opcional y depende de si necesita comprobar uno o varios videos cargados.
Guardar elanalyse_id
de la respuesta.
4. Comprueba los resultados depués de unos instantes. Repita la operación hasta que los campos resolution_status
y resolution
cambien de estado a cualquier otro excepto PROCESSING
y trátelo como resultado.