Listas negras de usuarios

/blacklist (enroll, search, unenroll)

Esta API permite la generación de una lista negra compartida de rostros de usuarios sobre la cual realizar búsquedas de reconocimiento facial 1:N.

Nota La funcionalidad de lista negra está diseñada para compartir una lista de rostros para detectar y bloquear entre un conjunto de clientes.

En caso de encontrar coincidencias para un rostro proporcionado, solo el cliente que ha registrado inicialmente ese rostro recibirá en la respuesta el identificador de usuario asignado en el registro; el resto de los clientes con acceso a esa lista solo recibirán el puntaje de similitud.

Solo el cliente que ha registrado un rostro (asociado a un ID de usuario) podrá realizar la eliminación.

Las operaciones soportadas son:

• Enroll (Registrar): nuevo registro de rostro de usuario.

• Search (Buscar): búsqueda 1:N de rostros dentro de la colección.

• Unenroll (Eliminar): desregistro de usuario.

---

Enroll (Registrar)

Solicitud de registro de usuario:

bash

curl --location '{IDENTITY_API_BASE_URL}/users/blacklist/{USER_ID}' \
--header 'x-api-key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "face": "{FACE_IMAGE}"
}'

Parámetros de la solicitud:

Campo	Requerido	Descripción
USER_ID	Sí	ID para el UserID a crear. Este ID debe ser único dentro de la colección.
FACE_IMAGE	Sí	Imagen codificada en Base64 del rostro del usuario. Los formatos admitidos son JPEG y PNG. El tamaño máximo admitido es 5MB.

Ejemplo de respuesta exitosa:

200 OK

Ejemplos de respuestas fallidas:

Escenario: ID de usuario duplicado.

400 Bad Request

Content-Type: application/json

json

{
    "status": 400,
    "title": "Bad Request",
    "detail": "Solicitud no válida.",
    "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
    "errors": [
        "el userId proporcionado ya existe"
    ]
}

Escenario: Imagen facial no válida.

400 Bad Request

Content-Type: application/json

json

{
    "status": 400,
    "title": "Bad Request",
    "detail": "Solicitud no válida.",
    "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
    "errors": [
        "no se detectó ningún rostro en la imagen proporcionada"
    ]
}

---

Search (Buscar)

Solicitud de búsqueda de usuario:

bash

curl --location '{IDENTITY_API_BASE_URL}/users/blacklist/search' \
--header 'x-api-key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "face": "{FACE_IMAGE}",
    "threshold": {THRESHOLD},
}'

Parámetros de la solicitud:

Campo	Requerido	Descripción
FACE_IMAGE	Sí	Imagen codificada en Base64 del rostro del usuario. Los formatos admitidos son JPEG y PNG. El tamaño máximo admitido es 5MB.
THRESHOLD	No	Valor opcional que especifica la confianza mínima en la coincidencia facial para devolver un resultado. Por ejemplo, no devolver coincidencias donde la confianza sea menor al 75,5%. El valor por defecto es 80%. Ejemplo de valor esperado para 75,5%: 75.5

Ejemplo de respuesta exitosa:

200 OK

Content-Type: application/json

json

{
    "matches": [
        {
            "userId": "f7eab18f-e5d3-4dac-9d4d-cfb969ef848e",
            "similarity": 99.99953
        }
    ]
}

Ejemplos de respuestas fallidas:

Escenario: usuario no encontrado.

404 Not Found

Content-Type: application/json

json

{
    "status": 404,
    "title": "Not Found",
    "detail": "El servidor no puede encontrar el recurso solicitado.",
    "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404"
}

---

Unenroll (Eliminar)

Solicitud de desregistro de usuario:

bash

curl --location --request DELETE '{IDENTITY_API_BASE_URL}/users/blacklist/{USER_ID}' \
--header 'x-api-key: {API_KEY}'

Parámetros de la solicitud:

Campo	Requerido	Descripción
USER_ID	Sí	ID para el UserID a eliminar.

Ejemplo de respuesta exitosa:

200 OK