Ctrlk
Useful links
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Autenticação facial

Autenticação Facial é um serviço biométrico que permite o registro facial e a autenticação por meio de comparação facial. Este recurso disponibiliza endpoints para registrar faces de pessoas e consultar tentativas de autenticação facial.

Requisitos de autenticação:

  • Endpoints regulares usam OAuth2 autenticação com URL base: https://api.us.prd.caf.io

  • Para maior segurança, alguns endpoints também podem suportar mTLS autenticação com URL base: https://mtls.us.prd.caf.io

  • Para informações sobre a implementação de mTLS, acesse Usando mTLS

Registro Facial

O endpoint de registro permite associar uma imagem facial a um identificador de pessoa (personId), criando uma referência biométrica que será usada posteriormente para autenticação.

As faces registradas por este endpoint serão usadas para comparação facial por meio do CafSdk ou CafFaceLiveness SDKs. As SDKs documentadas como obsoletas não necessariamente usarão esses registros faciais.

Register Face

post
/

Register a facial image for a person identifier, creating a biometric reference for future authentication.

Permission required: Create Face Authentication

Parâmetros de cabeçalho
AuthorizationstringObrigatório

Your access token. See more in the 'Authentication' topic of this section.

Example: Bearer YOUR_TOKEN
Corpo
personIdstringObrigatório

Unique person identifier (CPF, external ID, etc). Must be between 5 and 254 characters and contain only letters, numbers and special characters "@", ".", "_", "-". If personId contains only numbers and the symbols ".", "-", "/", these special characters are removed, as the value is interpreted as a document mask.

Example: 12345678901
imageUrlstringObrigatório

URL of the facial image to be registered. Must be a valid and accessible .jpg or .png URL

Example: https://example.com/face-image.png
Respostas
200

Face registered successfully

application/json
requestIdstringObrigatório

Unique identifier of request

Example: bb1ce1fd-5d0d-42af-bb0e-16f56b230a20
messagestringObrigatório

Status message

Example: Face registration in progress
personIdstringObrigatório

Person identifier

Example: 12345678901
post/
POST /v1/faces/ HTTP/1.1
Host: api.us.prd.caf.io
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "personId": "12345678901",
  "imageUrl": "https://example.com/face-image.png"
}
{
  "requestId": "bb1ce1fd-5d0d-42af-bb0e-16f56b230a20",
  "message": "Face registration in progress",
  "personId": "12345678901"
}

Consulta de Tentativa de Autenticação Facial

O endpoint de consulta permite recuperar informações sobre uma tentativa específica de autenticação facial, incluindo as URLs das imagens usadas.

Query Attempt

get
/attempts/{attemptId}

Retrieve information about a specific facial authentication attempt, including URLs of the images used.

Permission required: Read Face Authentication Attempts

Parâmetros de rota
attemptIdstringObrigatório

Unique identifier of the authentication attempt.

Example: 01K1XDD6W98M5QM9B8EAZZDV49
Parâmetros de cabeçalho
AuthorizationstringObrigatório

Your access token. See more in the 'Authentication' topic of this section.

Example: Bearer YOUR_TOKEN
Respostas
200

Attempt found successfully

application/json
requestIdstringObrigatório

Unique identifier of request

Example: bb1ce1fd-5d0d-42af-bb0e-16f56b230a20
get/attempts/{attemptId}
GET /v1/faces/attempts/{attemptId} HTTP/1.1
Host: api.us.prd.caf.io
Authorization: text
Accept: */*

{
  "requestId": "bb1ce1fd-5d0d-42af-bb0e-16f56b230a20",
  "data": {
    "id": "01K1XDD6W98M5QM9B8EAZZDV49",
    "createdAt": "2025-07-15T10:30:00.000Z",
    "personId": "12345678901",
    "sourceIp": "192.168.1.100",
    "registeredFaceImageUrl": "https://s3.amazonaws.com/bucket/registered-face.jpg?signature=...",
    "capturedFaceImageUrl": "https://s3.amazonaws.com/bucket/captured-face.jpg?signature=...",
    "isMatch": true,
    "similarity": 0.95
  }
}

Atualizado