Gestión de usuarios (1:N)

/users (enroll, search, unenroll)

Esta API permite la generación de una colección de rostros sobre la cual realizar búsquedas de reconocimiento facial 1:N:

• Inventario de rostros de usuarios.

• Lista negra de rostros.

• Lista blanca de rostros.

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/{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 o tokenizada del rostro del usuario. Para imágenes abiertas, 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/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 o tokenizada del rostro del usuario. Para imágenes abiertas, 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/{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