Autenticação facial

Esta API está obsoleta.

A Core API não é mais recomendada para novas integrações. Ela permanecerá funcional exclusivamente para clientes existentes. A migração para a Connect API é fortemente recomendada.

Para mais detalhes, consulte a Política de descontinuação.

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.

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

Parâmetros de cabeçalho

AuthorizationstringObrigatório

Bearer token

Corpo

application/json

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

400

Invalid request data

application/json

401

Invalid authentication token

application/json

422

Unsupported image format

application/json

500

Internal server error

application/json

post/faces

HTTPcURLJavaScriptPython

POST /v1/faces HTTP/1.1
Host: api.combateafraude.com
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

Parâmetros de rota

attemptIdstringObrigatório

Unique identifier of the authentication attempt.

Example: 01K1XDD6W98M5QM9B8EAZZDV49

Parâmetros de cabeçalho

AuthorizationstringObrigatório

Bearer token

Respostas

200

Attempt found successfully

application/json

requestIdstringObrigatório

Unique identifier of request

Example: bb1ce1fd-5d0d-42af-bb0e-16f56b230a20

400

attemptId not provided

application/json

401

Invalid authentication token

application/json

404

Attempt not found

application/json

500

Internal server error

application/json

get/faces/attempts/{attemptId}

HTTPcURLJavaScriptPython

GET /v1/faces/attempts/{attemptId} HTTP/1.1
Host: api.combateafraude.com
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=...",
    "isAlive": true,
    "isMatch": true,
    "similarity": 0.95
  }
}

Aviso Importante sobre Integrações

Para garantir a estabilidade e a segurança dos nossos serviços, é obrigatório implementar integrações com as APIs da Caf exclusivamente via backend/lado do servidor, pois chamadas pelo front-end (via navegador ou lado do cliente) podem ser bloqueadas pelos nossos sistemas quando múltiplos IPs ou user agents de navegador são detectados. Além disso, integrações no lado do cliente expõem as chaves de autenticação ao risco de vazamento e uso malicioso, o que pode levar ao consumo não autorizado de recursos e cobranças adicionais. As chaves de autenticação encontradas em uso em implementações incorretas serão desativadas imediatamente.

Sempre recomendamos: (1) implementar no backend, (2) usar cabeçalhos e autenticação adequados e (3) nunca expor credenciais no lado do cliente. Consulte nossa documentação para mais detalhes ou entre em contato com nossa equipe de suporte técnico.