Biometric ID - API

En este documento encontrará una explicación de cómo se realiza la integración con el API BiometricID

Pre requisitos

Para hacer uso del API debe contar con un API Key válido.

Toda petición que se realice al api debe contener el siguiente header

ApiKey: {{ apiKey }}

Nota

Según el endpoint que se use se solicitarán headers adicionales.

Flujo de uso

El api está diseñado para utilizarse de manera secuencial, el flujo es el siguiente:

flowchart LR
    A([Consulta de documento]) --> B([Verificación biometrica])
    B --> C([Consulta de información adicional])

Endpoints expuestos

DocumentQuery

Este endpoint permite consultar si un documento está disponible para su verificación biométrica.

Nota

Se debe enviar el correo del usuario que está realizando la petición {{ USUARIO_SELFSERVICE }}, solo serán válidos correos de usuarios creados en el selfservice por el cliente dueño del ApiKey

Headers requeridos:

ApiKey: {{ apiKey }}
Authorization: ApiKey {{ apiKey }}
Content-Type: application/json

Ejemplo de request:

curl --location --request POST 'https://apibiometricid.racsa.go.cr/bioapi/api/DocumentQuery' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'ApiKey: {{ APIKEYVALID }}' \
--header 'Authorization: ApiKey {{ APIKEYVALID }}' \
--data-raw '{
  "documentType": "Foreigner",
  "documentNumber": "1234566",
  "userEmail": "{{ USUARIO_SELFSERVICE }}"
}'

Ejemplo de respuesta para un documento disponible:

{
    "biometricAvailable": true,
    "token": "{{ JWTVALIDTOKEN }}",
    "availableFingers": [
        "RightThumb",
        "RightIndex"
    ],
    "facialRecognitionAvailable": false,
    "name": "Pepito",
    "surname": "Peréz",
    "secondSurname": "HIT",
    "transactionId": "c3717a3c-32d5-b62b-b5d4-3a092a3dcb84"
}

Nota

En este caso la respuesta nos entrega un token que será requerido para hacer la verificación biométrica

Ejemplo de respuesta para un documento no disponible:

{
    "transactionId": "ab57808b-b6cd-c8db-5485-3a092a1ffc54",
    "biometricAvailable": false
}

BiometricVerification

Este endpoint permite realizar la verificación biométrica de una persona dada la imagen de su rostro o la imagen de una huella en formato wsq.

Headers requeridos:

ApiKey: {{ apiKey }}
Authorization: Bearer {{ JWTVALIDTOKEN }}
Content-Type: application/json

JWTVALIDTOKEN

Este token es entregado por la respuesta de DocumentQuery

Ejemplo de request verificación facial:

curl --location --request POST 'https://apibiometricid.racsa.go.cr/bioapi/api/BiometricVerification' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{ JWTVALIDTOKEN }}' \
--header 'ApiKey: {{ APIKEYVALID }}' \
--data-raw '{
  "fullFacePhoto": "BASE64ENCODEDJPEGIMAGE"
}'

Formato de la fotografía

El campo fullFacePhoto debe ser la fotografía del rostro de la persona codificada en Base64, en formato JPEG.

Ejemplo de request verificación por huella:

curl --location --request POST 'https://apibiometricid.racsa.go.cr/bioapi/api/BiometricVerification' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{ JWTVALIDTOKEN }}' \
--header 'ApiKey: {{ APIKEYVALID }}' \
--data-raw '{
  "finger": "RightThumb",
  "fingerPrint": "BASE64ENCODEDWSQFINGER"
}'

Dedos disponibles

Los valores válidos para el campo finger son: RightThumb, RightIndex, RightMiddle, RightRing, RightLittle, LeftThumb, LeftIndex, LeftMiddle, LeftRing, LeftLittle. Los dedos disponibles para un documento en particular se retornan en el campo availableFingers de la respuesta de DocumentQuery.

Ejemplo de respuesta para una verificación exitosa:

{
    "hit": true,
    "documentImage": "BASE64ENCODEDDOCUMENTIMAGE",
    "documentExpirationDate": "2024-10-25T00:00:00",
    "token": "JWTVALIDTOKEN",
    "externalDataSources": [],
    "transactionId": "c3717a3c-32d5-b62b-b5d4-3a092a3dcb84",
    "remainingTries": 1,
    "scoreResult": 0,
    "scoreLimit": 0,
    "documentNumber": "123456789",
    "oldDocumentNumber": "2223333444",
    "lastName": "Carter",
    "secondLastName": "Doo",
    "name": "John",
    "category": "CATEGORY",
    "birthDay": "2023-06-09T15:07:11.978Z",
    "dateIssue": "2023-06-09T15:07:11.978Z",
    "nationality": "Colombian",
    "gender": "M",
    "status": "STATUS"
}

Nota

En este caso la respuesta nos entrega un token que será requerido para consultar las fuentes de información externas a través del endpoint ExternalSourceQuery.

Ejemplo de respuesta para una verificación fallida:

{
    "transactionId": "c3717a3c-32d5-b62b-b5d4-3a092a3dcb84",
    "remainingTries": 1,
    "hit": false,
    "scoreResult": 0,
    "scoreLimit": 0
}

Códigos de respuesta

DocumentQuery

Código HTTP	Mensaje	Descripción
200	—	Consulta exitosa. El campo biometricAvailable indica si el documento está disponible para verificación biométrica.
400	(detalle de validación)	La solicitud no pudo ser procesada con la información provista. Revisar los campos enviados.
404	—	No se encontró el documento consultado.
500	An error occurred when querying document types	No se lograron obtener los tipos de documentos habilitados desde el backoffice.
500	Document type {documentType} is not available for the query	Se intentó consultar con un tipo de documento que no está habilitado para el cliente.
500	The {userEmail} is required	No se envió el correo del usuario en la solicitud.
500	Ocurrio un error al consultar el usuario	No se logró consultar el usuario en el backoffice.
500	Error de autenticación	No se logró obtener el identificador del cliente.
500	No se encontró una sucursal válida dentro de la sesión	No se encontró una sucursal válida asociada al usuario o ApiKey (documentos nacionales, TSE).
500	Ocurrio un error con la respuesta de TSE	El servicio de TSE no respondió con éxito al consultar el documento (documentos nacionales).
500	Ocurrio un error al conectarse con el servicio de nacionales	Excepción al comunicarse con TSE (documentos nacionales).
500	Error en la conexión con el servicio	Error de conexión con el proveedor del documento (documentos de extranjería).

BiometricVerification

Código HTTP	Mensaje	Descripción
200	—	Verificación biométrica exitosa. hit: true. Incluye datos del documento y un token para consultar fuentes externas.
400	(detalle de validación)	La solicitud no pudo ser procesada con la información provista. Revisar los campos enviados.
404	—	La biometría no coincide con el registro del documento. hit: false. El campo remainingTries indica los intentos restantes.
500	Debe enviar huella o foto	La solicitud no incluyó ni fotografía (fullFacePhoto) ni huella (finger + fingerPrint).
500	Intentos máximos alcanzados	Se agotaron los intentos de verificación permitidos (remainingTries llegó a 0).
500	Ocurrio un error al verificar el liveness	El servicio de liveness no respondió con éxito al procesar la fotografía.
500	Ocurrio un error con el servicio de liveness	Excepción al procesar la respuesta del servicio de liveness.
500	Error en la conexión con el servicio	Error de conexión con el servicio biométrico (Innovatrics o DGME).
500	Ocurrio un error con la verificación facial	Error interno al procesar la verificación facial (DGME).
500	No se encontró una sucursal válida dentro de la sesión	No se encontró una sucursal válida asociada al usuario o ApiKey.
500	Ocurrio un error con el servicio de TSE, código: {código}, mensaje: {mensaje}	TSE no respondió con éxito o devolvió una respuesta inválida durante la verificación de huella.
500	No se encontró al menos una huella de la persona en TSE	TSE no devolvió huellas disponibles para el documento consultado.
500	Ocurrio un error al conectarse con el servicio de nacionales	Excepción al comunicarse con TSE durante la verificación de huella (documentos nacionales).

ExternalSourceQuery

Código HTTP	Mensaje	Descripción
200	—	Consulta exitosa a la fuente externa.
400	(detalle de validación)	La solicitud no pudo ser procesada con la información provista.
401	—	El token de la sesión ha expirado o se intentó consultar una fuente externa no autorizada para el token. Se debe realizar una nueva verificación biométrica.
404	La persona no fue encontrada	No se encontró información en la fuente externa consultada.
500	No coinciden los datos con la transacción de origen	El número de documento, tipo o número de transacción no coincide con la solicitud biométrica original.
500	Ocurrio un error con el servicio	Error de conexión con la fuente externa (CCSS o CST).

Estructura de error

Los errores devuelven una estructura ProblemDetails con el siguiente formato:

{
    "title": "La solicitud fue recibida pero no pudo ser procesada",
    "status": 500,
    "detail": "Mensaje con el detalle del error"
}

Los errores de validación devuelven una estructura ValidationProblemDetails:

{
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "Campo": ["Descripción del error de validación"]
    }
}

Más información:

Puede ver la documentación actualizada del enpoint en el swagger