3. Recursos - Biometria

Campos sinalizados com * são de caráter obrigatório para utilizar corretamente as APIs.

IMPORTANTE:

Todos os exemplos de chamadas nas APIs abaixo estão apontando para as URL do ambiente de SANDBOX. Para maiores detalhes em relação as URLs dos ambientes consultar API Reference.
Existem URLs que estão disponíveis para o contexto SDK e também para o Backoffice. Atentar-se para isso quando houver o placeholder sdk na URL, pois o mesmo deve ser substituído de acordo com o caso de uso, podendo assumir os valores "sdk" ou "backoffice".

Fluxo recomendado para Backoffice

Para rotas /backoffice/*, utilize x-api-key diretamente em cada requisição.
O endpoint /backoffice/v1/handshake é legado, permanece por compatibilidade e está em processo de depreciação.
Quando houver exemplos com Authorization: Bearer <SessionToken> nesta página, considere-os como fluxo legado para Backoffice.
No fluxo direto do backoffice, o sessionId operacional é retornado no payload da resposta (sucesso e erro).

Exemplo (fluxo direto por API key):

curl --request POST \
  --url https://api-sandbox.fortface.ai/backoffice/v1/identify \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: string' \
  --data '{
    "externalUserId": "string",
    "imgData": "base64"
  }'

3.1 Handshake

Descrição

A API do Fortface possui um sistema proprietário de criação de sessões. Após o usuário passar pela etapa de credenciamento, ele pode criar sessões temporárias de acesso restrito às ações previamente determinadas pelo sistema, construídas a partir do Handshake.

Antes de detalhar os campos do header do Handshake e as etapas de processamento, é importante abordar o processo de criptografia e descriptografia do device fingerprint.

A manipulação de dados vinculados a qualquer processo interno ao Fortface segue um rigoroso processo de segurança. Um dos dados mais utilizados durante todos os processos é o device fingerprint, e um contrato específico foi utilizado para encapsulá-lo de forma segura na requisição.

Agora, com o processo de criptografia e descriptografia explicado, vamos voltar a falar sobre os campos de consulta do header do Handshake, que são:

Content-Type: Informando a natureza de leitura do campo application/json
x-api-key: Chave de segurança configurada para o cliente cliente.

Abaixo segue o corpo (body) necessário para o Handshake, e o campo X-API-KEY no header se torna necessário para identificar o cliente requisitante, bem como suas devidas permissões.

Endpoint: /handshake

Method: POST

Payload:

galleryId*: Identificador da galeria do usuário.
accountName*: Identificador da conta do usuário.
action*: Ação a ser executada: enroll | identify | search | liveness | capture | document | update-enroll | delete-enroll.
deviceRequestInfo: Informações criptografadas do dispositivo que originou o evento. Obrigatório apenas no contexto SDK (/sdk/v1/handshake); o handshake de Backoffice não recebe esse campo.
externalTransactionId: Transação externa utilizada para agrupamento das sessões. (opcional) O identificador forte do usuário é o externalUserId (usado nos endpoints de enroll, identify, capture).

Request (Exemplo)

context: sdk ou backoffice

sdk/handshake : Gera uma sessão valida para uma action via SDK

backoffice/handshake : Gera uma sessão valida para uma action via Backoffice

Exemplo: Uma sessão gerada sdk/handshake não será válida para o endpoint backoffice/liveness, mas sim para o sdk/liveness

curl --request POST \
  --url https://api-sandbox.fortface.ai/{context}/v1/handshake \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: string' \
  --data '{
    "galleryId": "string",
    "accountName": "string",
    "action": "String<enroll | identify | search | liveness | capture | document | update-enroll | delete-enroll>",
    "deviceRequestInfo": "string",
    "externalTransactionId": "string"
  }'

Response (Exemplo)

  "body": {
    "sessionToken": "TOKEN DE SESSÃO PARA ACESSO AOS RECURSOS DA API",
    "sessionKey": "CHAVE DA SESSÃO UTILIZADA NO SDK",
    "sessionId": "IDENTIFICADOR DA SESSÃO GERADA PELO HANDSHAKE"
  }

Etapas de Processamento

O device fingerprint é criptografado e extraído do “deviceRequestInfoNaN” e, em seguida, é descriptografado.
Nesta etapa, é realizada uma verificação do hash do device fingerprint. O hash é gerado por uma função que associa um hash a cada campo do deviceInfo. A API Fortface utiliza o mesmo sistema do SDK para gerar o hash local com base nos dados do campo deviceInfo que o “deviceRequestInfoNaN” descriptografado possui. Essa abordagem permite criar uma camada de verificação de confiabilidade e integridade estrutural dos dados em cada requisição ao Handshake.
Uma sessão é criada mediante a existência de uma galeria, conforme informado no propriedade galleryId. A api-key associada à essa galeria deve ter a permissão para realizar o Handshake.

Contexto	API	HTTP Methods	Version	Handshake Action
SDK	handshake	POST	V1	N/A
SDK	enroll	POST	V1	enroll
SDK	identify	POST	V1	identify
SDK	search	POST	V2	search
SDK	liveness	POST	V1	liveness
SDK	capture	POST	v1	capture
Backoffice	handshake	POST	V1	N/A
Backoffice	enroll	POST, PUT, DELETE	V1	enroll, update-enroll, delete-enroll
Backoffice	identify	POST	V1	identify
Backoffice	search	POST	V2	search
Backoffice	liveness	POST	V1	liveness
Backoffice	capture	POST	v1	capture
Backoffice	photo	GET	V1	N/A
Backoffice	photo 3x4	GET	V1	N/A
Backoffice	log session	GET	V1	N/A

O recurso de search está na versão v2 (/sdk/v2/search e /backoffice/v2/search). A permissão da API-KEY deve ser concedida para esse path.

3.2 Enroll

A API Fortface tem como serviço o cadastro do rosto do usuário. A requisição para o recurso precisa ter os seguintes campos validos.

Handshake Action: enroll

Endpoint: /enroll

method: POST

Headers

Content-Type: Informando a natureza de leitura do campo application/json
Authorization: Bearer token de seção gerado através do endpoint /handshake (SessionToken do Handshake) para SDK e fluxo legado do Backoffice.
x-api-key: Header recomendado para chamadas diretas do Backoffice (sem handshake).

Payload:

externalUserId*: CPF do Usuário
key*: Chave gerada pelo SDK Fortface.(🔓 SDK ).
data*: Dados criptografados do usuário.(🔓 SDK ).
imgData*: Dados de imagem (SDK/Criptografados ou BackOficce/Base64).
returnPhoto: Flag opcional, indicando o retorno do foto no reponse (🔓 SDK).
document: Identificador do documento do usuário (opcional).
documentType: Tipo do documento informado em document (opcional). Ex.: CPF

Request (Exemplo)

context: sdk ou backoffice

curl --request POST \
  --url https://api-sandbox.fortface.ai/{context}/v1/enroll \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer (SessionToken do handshake) \
  --data '{
    "imgData": "String <Retorna do SDK> ou <Base64 no Backofice>",
    "externalUserId": "String",
    "key": "String <Retorna do SDK>",
    "data": "String <Retorna do SDK>",
    "returnPhoto": "Boolean"
  }'

Response (exemplo)

   "photo":{
      "liveness":{
         "value":false,
         "confidence":100
      },
      "eyesOpen":{
         "left":{
            "value":true,
            "confidence":0
         },
         "right":{
            "value":true,
            "confidence":0
         }
      }
   },
   "api":{
      "version":"string",
      "timestamp":"string",
      "env":"string"
   },
   "sdk":{
      "appId":"string",
      "brand":"string",
      "model":"string",
      "platform":"string",
      "sdkVersion":"string",
      "soVersion":"string"
   }

Etapas de processamento

Nesta etapa o Enroll valida a sessão do usuário e traz os dados da sessão para serem utilizados pelos casos de uso.
Realizamos a decriptografia do payload e processamos o enroll da imagem em nossas galerias.

3.3 Identify

Outra funcionalidade da API do Fortface é realizar a identificação 1:1 onde recebemos um identificador e uma foto e retornamos se a foto é realmente desse identificador.

Handshake Action: identify

Endpoint: /identify

Method: POST

Headers:

Content-Type: Informando a natureza de leitura do campo application/json
Authorization: Bearer token gerado através do endpoint de /handshake (SessionToken do Handshake)

Payload:

externalUserId*: CPF do Usuário
key*: Chave gerada pelo SDK Fortface.(🔓 SDK ).
data*: Dados criptografados do usuário.(🔓 SDK ).
imgData*: Dados de imagem (SDK/Criptografados ou BackOficce/Base64).
returnPhoto: Flag opcional, indicando o retorno do foto no reponse (🔓 SDK).
document: Identificador do documento do usuário (opcional).
documentType: Tipo do documento informado em document (opcional). Ex.: CPF

Request (Exemplo)

context: sdk ou backoffice

curl --request POST \
  --url 'https://api-sandbox.fortface.ai/{context}/v1/identify' \
  --header 'Authorization: Bearer (SessionToken do handshake)' \
  --header 'Content-Type: application/json' \
 --data '{
    "imgData": "String <Retorna do SDK> ou <Base64 no Backofice>",
    "externalUserId": "String",
    "key": "String <Retorna do SDK>",
    "data": "String <Retorna do SDK>",
    "returnPhoto": "Boolean"
  }'

Response (Exemplo)

{
  {
    "matchLevel": {
      "value": 0
    },
    "photo": {
      "liveness": {},
      "eyesOpen": {}
    },
    "api": {
      "version": "string",
      "timestamp": "string",
      "env": "string"
    },
    "sdk": {
      "appId": "string",
      "brand": "string",
      "model": "string",
      "platform": "string",
      "sdkVersion": "string",
      "soVersion": "string"
    }
  }
}

3.4 Search

Outra funcionalidade da API do Fortface é realizar a identificação 1:N onde recebemos uma foto e retornamos possíveis matches que essa foto tem dentro da galeria informada.

Handshake Action: search

Endpoint: /search

Version: v2 — o path completo é /{context}/v2/search

Method: POST

Headers:

Content-Type: Informando a natureza de leitura do campo application/json
Authorization: Bearer token gerado através do endpoint de /handshake (SessionToken do Handshake)

Payload:

key*: Chave gerada pelo SDK Fortface.(🔓 SDK ).
data*: Dados criptografados do usuário.(🔓 SDK ).
imgData*: Dados de imagem (SDK/Criptografados ou BackOficce/Base64).
returnPhoto: Flag opcional, indicando o retorno do foto no reponse (🔓 SDK).
document: Identificador do documento do usuário (opcional).
documentType: Tipo do documento informado em document (opcional). Ex.: CPF

Request (Exemplo)

context: sdk ou backoffice

curl --request POST \
  --url 'https://api-sandbox.fortface.ai/{context}/v2/search' \
  --header 'Authorization: Bearer (SessionToken do handshake)' \
  --header 'Content-Type: application/json' \
 --data '{
    "imgData": "String <Retorna do SDK> ou <Base64 no Backofice>",
    "key": "String <Retorna do SDK>",
    "data": "String <Retorna do SDK>",
    "returnPhoto": "Boolean"
  }'

Response (Exemplo)

{
  "matches": [
    {
      "id": "user-001",
      "matchLevel": 16
    },
    {
      "id": "user-004",
      "matchLevel": 16
    },
    {
      "id": "user-002",
      "matchLevel": 0
    },
    {
      "id": "user-003",
      "matchLevel": 0
    },
    {
      "id": "user-005",
      "matchLevel": 0
    }
  ],
  "photo": {
    "liveness": {
      "value": true,
      "confidence": 100
    },
    "eyesOpen": {
      "left": {
        "value": true,
        "confidence": 0.0
      },
      "right": {
        "value": true,
        "confidence": 0.0
      }
    },
    "api": {
      "version": "string",
      "timestamp": "string",
      "env": "string"
    },
    "sdk": {
      "appId": "string",
      "brand": "string",
      "model": "string",
      "platform": "string",
      "sdkVersion": "string",
      "soVersion": "string"
    }
  }
}

3.5 Update Enroll

Outra funcionalidade da API do Fortface é realizar a o update do encoding onde recebemos o id da sessão legado e o id do usuário. Assim é efetuado o update do encoding atrávés das informações/imagem relacionadas a sessão e ao id de usuário.

Handshake Action: update-enroll

Endpoint: /enroll

Method: PUT

Headers:

Content-Type: Informando a natureza de leitura do campo application/json
Authorization: Bearer token gerado através do endpoint de /handshake (SessionToken do Handshake)

Payload:

sessionId*: Id da Sessão legada, qual foi feito o enroll.
externalUserId*: CPF do usuário relacionado ao Enroll efetuado.

Request (Exemplo)

curl --request PUT \
  --url 'https://api-sandbox.fortface.ai/backoffice/v1/enroll' \
  --header 'Authorization: Bearer (SessionToken do handshake)' \
  --header 'Content-Type: application/json' \
 --data '{
    "sessionId": "Identificador da sessão",
    "externalUserId": "CPF do Usuário",
  }'

Response (Exemplo)

{
  {
    "api": {
      "version": "string",
      "timestamp": "string",
      "env": "string"
    }
  }
}

Etapas de processamento

Nesta etapa é feita a validação do ID da sessão legada, se foi executada com sucesso(isSuccess), se ID de usuário é o mesmo que o enviado no payload.
Após o processamento anterior, é feita a busca ela imagem pelo ID da sessão, extraido o encoding da imagem, e efetuado o update.
Após o update do encoding, é criado um log da sessão, que armazena as informações do processamento.

3.6 Delete Enroll

Outra funcionalidade da API do Fortface é realizar a o delete do encoding onde recebemos o id do usuário. Atráves da sessão gerada pelo handshake obtermos o restante das informações. Assim é efetuado a remoção do encoding do usuário.

Handshake Action: delete-enroll

Endpoint: /enroll

Method: DELETE

Headers:

Content-Type: Informando a natureza de leitura do campo application/json
Authorization: Bearer token gerado através do endpoint de /handshake (SessionToken do Handshake)

Payload:

externalUserId*: CPF do usuário relacionado ao Enroll efetuado.

Request (Exemplo)

curl --request DELETE \
  --url 'https://api-sandbox.fortface.ai/backoffice/v1/enroll' \
  --header 'Authorization: Bearer (SessionToken do handshake)' \
  --header 'Content-Type: application/json' \
 --data '{
    "externalUserId": "CPF do Usuário",
  }'

Response (Exemplo)

{
  {
    "api": {
      "version": "string",
      "timestamp": "string",
      "env": "string"
    }
  }
}

3.7 Liveness

Outra funcionalidade da API do Fortface é realizar o liveness (ou prova de vida), onde recebemos uma foto e realizamos uma análise minuciosa para garantir a assertividade de se a pessoa de fato que está enviando uma foto, não está usando máscara, dentre outras possíveis formas de fraude para prova de vida.

Handshake Action: liveness

Endpoint: /liveness

Method: POST

Headers:

Content-Type: Informando a natureza de leitura do campo application/json
Authorization: Bearer token gerado através do endpoint de /handshake (SessionToken do Handshake)

Payload:

key*: Chave gerada pelo SDK Fortface.(🔓 SDK ).
data*: Dados criptografados do usuário.(🔓 SDK ).
imgData*: Dados de imagem (SDK/Criptografados ou BackOficce/Base64).
externalUserId:CPF do Usuário.
externalTransactionId: Transação externa utilizada para agrupamento das sessões.
returnPhoto: Flag opcional, indicando o retorno do foto no reponse (🔓 SDK).
document: Identificador do documento do usuário (opcional).
documentType: Tipo do documento informado em document (opcional). Ex.: CPF

Request (Exemplo)

context: sdk ou backoffice

curl --request POST \
  --url 'https://api-sandbox.fortface.ai/{context}/v1/liveness' \
  --header 'Authorization: Bearer (SessionToken do handshake)' \
  --header 'Content-Type: application/json' \
 --data '{
    "imgData": "String <Retorna do SDK> ou <Base64 no Backofice>",
    "key": "String <Retorna do SDK>",
    "data": "String <Retorna do SDK>",
    "externalUserId": "String",
    "externalTransactionId": "String",
    "returnPhoto": "Boolean"
  }'

Response (Exemplo)

{
  "photo": {
    "liveness": {
      "value": true,
      "confidence": 0
    }
  },
  "api": {
    "env": "string",
    "timestamp": 0,
    "version": "string"
  }
}

3.8 Face Occlusion (Oclusão de Face)

O Fortface permite avaliar a oclusão de um rosto por mãos, braços, objetos, óculos escuros nos seguintes serviços:

/liveness (SDK e Backoffice)
/enroll (SDK e Backoffice)
/identify (SDK e Backoffice)
/search (SDK e Backoffice)
/capture (apenas SDK — a resposta do /backoffice/v1/capture não inclui a análise)

Payload

A feature é habilitada na galeria do cliente, que define o comportamento padrão.
O campo analysis.faceOcclusion sobrepõe esse padrão por requisição (ver seção 3.13).
A análise de oclusão é independente das análises de Liveness e MatchLevel.
Pode haver um tempo de processamento ligeiramente maior devido à complexidade adicional.
O campo faceOcclusion será adicionado na resposta dentro do bloco photo; em /capture ele vem na raiz da resposta.

Response (Exemplo - Sem oclusão)

(...)
"faceOcclusion":
{
"status": "done",
"occlusion": false,
"reason": null,
"additionalReason": null
}

Response (Exemplos - Com oclusão)

Com Oclusão – Óculos Escuros:

"faceOcclusion":
{
"status": "done",
"occlusion": true,
"reason": "SUNGLASSES"
}

Com Oclusão – Mãos/Braços:

"faceOcclusion":
{
"status": "done",
"occlusion": true,
"reason": "HANDS_ARMS"
}

Com Oclusão – Objetos:

"faceOcclusion":
{
"status": "done",
"occlusion": true,
"reason": "OBJECT",
"additionalReason": "hat"
}

Com Oclusão – Região dos Olhos:

"faceOcclusion":
{
"status": "done",
"occlusion": true,
"reason": "EYE_REGION"
}

Informações Adicionais

Apenas um tipo de oclusão é retornado por análise, mesmo que existam múltiplas obstruções. Por esse motivo, é essencial utilizar o campo occlusion = true como parte da lógica de decisão. A oclusão retornada será aquela considerada mais significativa pelo modelo.
Objetos são detectados, mas não classificados. O sistema apenas indicará que há uma oclusão causada por um objeto, sem especificar se é, por exemplo, uma xícara, um celular ou outro item.
Se houver zero ou múltiplos rostos, a análise não será realizada. Nesses casos, o sistema retornará um erro ao cliente indicando a impossibilidade da verificação.
A presença de oclusão não impede as análises de Liveness e MatchLevel, mas pode reduzir a acurácia. Rostos significativamente oclusos têm maior chance de gerar falsos negativos, especialmente nas validações de vivacidade e correspondência facial.
Óculos de grau não são classificados como oclusão, exceto se cobrirem regiões críticas como olhos/nariz. Portanto, usuários utilizando óculos de grau não terão impacto negativo na análise de oclusão.
Quando reason = OBJECT, o campo additionalReason pode retornar: hat, headcover, helmet, object, reflex, synthetic, toobright (no futuro pode ter mais).

3.9 Get Image

O fortface oferece uma API do para resgatar uma foto utilizada em alguma ação (enroll, identify, etc) através do sessionId. Não há necessidade de realizar handshake para esse end-point.

Endpoint: /backoffice/v1/sessions/photo/{sessionId}

Path Param: :sessionId - Identificador da sessão

Method: GET

Headers:

Content-Type: Informando a natureza de leitura do campo application/json
x-api-key: Chave de segurança configurada para o cliente cliente.

Request (Exemplo)

curl --request GET \
  --url 'https://api-sandbox.fortface.ai/backoffice/v1/sessions/photo/{sessionId}' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: string'

Response (Exemplo)

{
  "photoUrl": "string",
  "content": "string<Base64>"
}

3.10 Get Image 3x4

O Fortface oferece uma API para resgatar a foto de uma sessão já recortada no formato 3:4, utilizando o sessionId. Não há necessidade de realizar handshake para esse endpoint.

Diferente do endpoint de recuperação de foto por sessão (seção 3.9), este retorna apenas o conteúdo da imagem processada em base64, sem link temporário (photoUrl).

Endpoint: /backoffice/v1/sessions/photo/3x4/{sessionId}

Path Param: :sessionId — Identificador da sessão

Method: GET

Headers:

Content-Type: Informando a natureza de leitura do campo application/json
x-api-key: Chave de segurança configurada para o cliente.

Request (Exemplo)

curl --request GET \
  --url 'https://api-sandbox.fortface.ai/backoffice/v1/sessions/photo/3x4/{sessionId}' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: string'

Response (Exemplo)

{
  "content": "string<Base64>"
}

Tratamento de erros

Quando a sessão não possui foto recuperável, o endpoint retorna erro conforme o fluxo de obtenção de imagem da sessão (ex.: 404).
Quando o processamento do recorte 3:4 falha, o endpoint retorna o mesmo status code observado no serviço de processamento, sem fallback para a imagem original.
A API key deve possuir permissão para o recurso /backoffice/v1/sessions/photo/3x4/{sessionId}.

3.11 Armazenamento das Fotos de Transações

Armazenamento da Foto pelo Fortface

O Fortface oferece a opção de armazenar as fotos capturadas durante a biometria facial, seguindo rigorosamente as melhores práticas de proteção de dados, criptografia e segurança. A escolha de qual abordagem seguir deve ser informada durante o processo de implantação para configuração interna. Caso o cliente escolha essa abordagem, é importante estar ciente dos seguintes pontos:

Resgate das imagens pelo `SessionID`

As fotos armazenadas pelo Fortface podem ser recuperadas usando o endpoint /sessions/photo/web-doc-1788899468515. O resgate é feito por meio do sessionId gerado durante o processo de autenticação inicial (handshake). É altamente recomendável que o cliente armazene localmente o sessionId de cada transação para facilitar o acesso futuro às imagens.

curl --location 'https://api-sandbox.fortface.ai/backoffice/v1/sessions/photo/{sessionId}' \
--header 'x-api-key: your-api-key' \
--header 'Content-Type: application/json'

Substitua {sessionId} pelo ID da sessão e 'your-api-key' pela sua chave de API.

Remoção das imagens

Caso o cliente deseje remover uma ou mais fotos da base de dados, ou solicitar a exclusão completa das imagens, isso pode ser feito entrando em contato com o suporte Fortface através do e-mail suporte@fortface.com.br.

Armazenamento da Foto pelo Cliente

O Fortface oferece a opção de descartar todas as fotos após a biometria facial, armazenando apenas um Hash da imagem para auditorias futuras. Caso o cliente opte por essa abordagem, recomendamos implementar os seguintes controles:

Utilizar o recurso `ReturnPhoto = True`

Nos end-points do SDK (Enroll, Liveness, Identify e Search), o cliente pode solicitar o retorno da foto capturada na requisição. Ao configurar o parâmetro ReturnPhoto = True, a imagem será devolvida em formato Base64 no corpo da resposta. Para garantir a integridade da imagem, é recomendável assinar o payload da resposta e armazenar a imagem sem qualquer tipo de compressão.

Hash Retornado no Payload

Nos end-points do SDK, a resposta incluirá um Hash da foto gerado a partir do Base64 da imagem, utilizando o algoritmo SHA-256. Este Hash permite verificar que a foto corresponde exatamente àquela gerada na requisição. Embora o Hash seja fornecido no payload, o cliente não precisa armazená-lo localmente.

[...]
    "hash": "dqWBmESjR4+Cu6W5Oo64wMsn0J5hi9hfuQmOTFS3hSmpvkoIn6IZpGv6rBt4M7fMmFMU5uc/kGWwtiSuTOrz1g==",
    "api": {
        "env": "dev",
        "timestamp": 1726755603473,
        "version": "v1 - 0.15.1"
    }
}

3.12 Hubface - Validação de Rosto e Documento em Provedores de Identidade

O Hubface permite validar a identidade de uma pessoa utilizando uma selfie e o documento (CPF). Para essa validação, utiliza-se o endpoint /capture.

Configuração

O Hubface pode ser utilizado em configurações que garantem entre 92% e 95% de cobertura na validação de rosto e documento, aproximadamente. A configuração deve ser discutida junto ao time comercial do Fortface previamente ao uso.

Utilização

Ação de Handshake: capture
Endpoint: /capture
Método: POST

Headers

Content-Type: application/json (especifica o tipo de conteúdo no campo)
Authorization: Bearer token gerado através do endpoint /handshake (SessionToken do Handshake)

Payload

externalUserId*: CPF do usuário
document*: CPF do usuário que o cliente deseja validar
documentType: Tipo do documento informado em document (opcional). Ex.: CPF
imgData*: Dados de imagem (criptografados pelo SDK ou Base64 no BackOffice)
key*: Chave gerada pelo SDK Fortface.(🔓 SDK ).
data*: Dados criptografados do usuário (🔓 SDK)
returnPhoto: Flag opcional para retornar a foto no response (🔓 SDK)

Exemplo de Request

Contexto: SDK ou BackOffice

curl --request POST \
  --url 'https://api-sandbox.fortface.ai/{context}/v1/capture' \
  --header 'Authorization: Bearer (SessionToken do handshake)' \
  --header 'Content-Type: application/json' \
 --data '{
    "imgData": "String <Retorna do SDK> ou <Base64 no BackOffice>",
    "externalUserId": "String",
    "document": "String <CPF somente números>",
    "key": "String <Retorna do SDK>",
    "data": "String <Retorna do SDK>"
  }'

Response (Exemplo)

{
  "providers": {
    "identity": {
      "id": "dac98d50-1997-4d78-b270-d487fd795821",
      "score": 5
    }
  },
  "photo": {
    "liveness": {
      "value": true,
      "confidence": 100
    }
  }
}

Importante: Retorno do liveness apenas para SDK

Interpretação do Rank

Score	Resposta Tabela Hubface	Recomendação
NULL	Não foi possível analisar	Solicitar nova captura biométrica
0	Sem informações sobre rosto/CPF	Complementar validação com fontes externas
5	Risco Baixíssimo	Aprovação automática
4	Risco Baixo	Aprovação com acompanhamento/monitoramento
3	Risco Neutro	Encaminhamento para mesa da análise
2	Risco Médio	Reprovação preventiva com possibilidade de revisão
1	Risco Alto	Reprovação automática por alto risco

Testes em Sandbox

Para os testes em Sandbox, retornaremos scores pré definidos a partir do último dígito do CPF (0 a 9) enviado no campo de “document”:

Document final 0 - Score = 0
Document final 5 - Score = 1
Document final 1 - Score = 1
Document final 2 - Score = 2
Document final 3 - Score = 2
Document final 4 - Score = 4
Document final 6 - Score = 4
Document final 7 - Score = 5
Document final 8 - Score = 5
Document final 9 - Score = 4

3.13 Analises Adicionais

O FortFace permite a execução de análises complementares durante as operações biométricas.
Essas análises aumentam a segurança, validam a qualidade da imagem e evitam o processamento de conteúdos indevidos ou inválidos.

As análises disponíveis são:

Liveness Calibration
Face Occlusion
NSFW Detection
Quality Assessment

3.13.1 Análises x Endpoints Suportados

Análise	SDK e Backoffice	Apenas SDK
Liveness Calibration	`/liveness`, `/enroll`, `/identify`, `/search`	`/capture`
Face Occlusion	`/liveness`, `/enroll`, `/identify`, `/search`	`/capture`
NSFW Detection	`/liveness`, `/identify`	`/capture`
Quality Assessment	`/enroll`	—

A resposta do /backoffice/v1/capture retorna apenas os dados do provedor de identidade; nenhuma análise adicional é incluída nesse contexto.

3.13.2 Como habilitar análises adicionais

A forma de ativação depende do contexto:

SDK

As análises devem ser configuradas no handshake, aplicando-se a todas as chamadas subsequentes.

Backoffice

As análises são configuradas diretamente na requisição, como em /liveness, /identify, /search, etc.

3.13.3 Estrutura do Request

"analysis": {
    "liveness": true,
    "livenessCalibration": "enhanced",
    "nsfw": true,
    "faceOcclusion": true
}

Descrição dos campos

Campo	Tipo	Descrição
`liveness`	boolean	Quando `false`, a análise de vivacidade não é executada. Padrão: `true`.
`livenessCalibration`	string	Modo de calibração: `optimal`, `enhanced` ou `supreme`. Valor inválido retorna erro `400`. Padrão: `supreme`.
`nsfw`	boolean	Ativa a análise de conteúdo impróprio. Padrão: `false`.
`faceOcclusion`	boolean	Ativa ou desativa a análise de oclusão facial. Se omitido, vale a configuração da galeria.
`qualityAssessment`	boolean	Ativa a análise de qualidade da imagem (exposição, nitidez, iluminação). Disponível apenas em `/enroll`. Padrão: `false`.

Observação: Caso alguma análise não seja suportada no endpoint utilizado, ela será ignorada.

Importante sobre qualityAssessment: A ativação depende apenas da requisição: enviar qualityAssessment: true (no handshake, no SDK, ou no body, no backoffice) já executa a análise, sem configuração prévia na galeria. A análise roda apenas em /enroll; em qualquer outro endpoint a flag é ignorada.

3.13.4 Retornos das Análises

Cada análise ativada adicionará um bloco de retorno próprio no response do FortFace, dentro do objeto photo.

Exceção: em /capture, o bloco faceOcclusion é retornado na raiz da resposta, e não dentro de photo.

Abaixo, exemplos dos retornos possíveis:

NSFW Detection – Exemplo de Retorno

"nsfw": {
  "isSafe": true,
  "confidence": 0
}

Campos:

Campo	Tipo	Descrição
`isSafe`	boolean	Indica se a imagem foi classificada como segura.
`confidence`	number	Grau de confiança do classificador (0–100).

Face Occlusion – Exemplo de Retorno

"faceOcclusion": {
  "status": "done",
  "occlusion": false,
  "reason": null
}

Campos:

Campo	Tipo	Descrição
`status`	string	Status da análise (`done`, `error`, etc.).
`occlusion`	boolean	Indica se há oclusão no rosto detectado.
`reason`	string	null
`additionalReason`	string	null

Quality Assessment – Exemplo de Retorno

Disponível em /enroll. O resultado é retornado dentro do bloco photo, junto com liveness:

"photo": {
  "qualityAssessment": {
    "value": true,
    "confidence": 100
  }
}

Campos:

Campo	Tipo	Descrição
`value`	boolean	`true` quando a foto atende ao critério de qualidade; `false` quando é reprovada.
`confidence`	number	`100` quando o serviço de qualidade respondeu (aprovado, reprovado, ou sem conseguir avaliar a imagem); `0` quando o serviço não pôde ser acessado (timeout, indisponibilidade).

Combinações possíveis:

Situação	`value`	`confidence`
Foto aprovada	`true`	`100`
Reprovação limítrofe (margem pequena)	`true`	`100`
Foto reprovada	`false`	`100`
Serviço respondeu mas não conseguiu avaliar (sem rosto etc.)	`false`	`100`
Serviço de qualidade inacessível (timeout, indisponibilidade)	`false`	`0`
Análise não executada	(bloco `qualityAssessment` ausente da resposta)	—

Observação: reprovações limítrofes são aceitas pelo Fortface (value: true) — a foto ficou fora dos limites por margem pequena e ainda é utilizável para enrollment. Apenas reprovações claras retornam value: false.

Observação: o algoritmo e os thresholds de aprovação/reprovação ainda estão em processo de calibração e podem ser ajustados sem aviso prévio nesta fase inicial.

3.13.5 Exemplos de Uso

SDK – Handshake

A API-KEY vai no header x-api-key; o bloco analysis acompanha o corpo do handshake.

{
  "galleryId": "string",
  "accountName": "string",
  "action": "liveness",
  "deviceRequestInfo": "string",
  "analysis": {
    "livenessCalibration": "enhanced",
    "nsfw": true,
    "faceOcclusion": true
  }
}

Backoffice – Exemplo em `/liveness`

{
  "imgData": "base64-da-imagem",
  "analysis": {
    "livenessCalibration": "enhanced",
    "faceOcclusion": true,
    "nsfw": true
  }
}

Backoffice – Exemplo em `/enroll` (Quality Assessment)

{
  "imgData": "base64-da-imagem",
  "externalUserId": "String",
  "analysis": {
    "qualityAssessment": true
  }
}

Fluxo recomendado para Backoffice​

3.1 Handshake​

Descrição​

Request (Exemplo)​

Response (Exemplo)​

Etapas de Processamento​

3.2 Enroll​

Request (Exemplo)​

Response (exemplo)​

3.3 Identify​

Request (Exemplo)​

Response (Exemplo)​

3.4 Search​

Request (Exemplo)​

Response (Exemplo)​

3.5 Update Enroll​

Request (Exemplo)​

Response (Exemplo)​

3.6 Delete Enroll​

Request (Exemplo)​

Response (Exemplo)​

3.7 Liveness​

Request (Exemplo)​

Response (Exemplo)​

3.8 Face Occlusion (Oclusão de Face)​

Payload​

Response (Exemplo - Sem oclusão)​

Response (Exemplos - Com oclusão)​

Informações Adicionais​

3.9 Get Image​

Request (Exemplo)​

Response (Exemplo)​

3.10 Get Image 3x4​

Request (Exemplo)​

Response (Exemplo)​

Tratamento de erros​

3.11 Armazenamento das Fotos de Transações​

Armazenamento da Foto pelo Fortface​

Resgate das imagens pelo SessionID​

Remoção das imagens​

Armazenamento da Foto pelo Cliente​

Utilizar o recurso ReturnPhoto = True​

Hash Retornado no Payload​

3.12 Hubface - Validação de Rosto e Documento em Provedores de Identidade​

Configuração​

Utilização​

Headers​

Payload​

Exemplo de Request​

Response (Exemplo)​

Interpretação do Rank​

Testes em Sandbox​

3.13 Analises Adicionais​

3.13.1 Análises x Endpoints Suportados​

3.13.2 Como habilitar análises adicionais​

SDK​

Backoffice​

3.13.3 Estrutura do Request​

Descrição dos campos​

3.13.4 Retornos das Análises​

NSFW Detection – Exemplo de Retorno​

Face Occlusion – Exemplo de Retorno​

Quality Assessment – Exemplo de Retorno​

3.13.5 Exemplos de Uso​

SDK – Handshake​

Backoffice – Exemplo em /liveness​

Backoffice – Exemplo em /enroll (Quality Assessment)​

Fluxo recomendado para Backoffice

3.1 Handshake

Descrição

Request (Exemplo)

Response (Exemplo)

Etapas de Processamento

3.2 Enroll

Request (Exemplo)

Response (exemplo)

3.3 Identify

Request (Exemplo)

Response (Exemplo)

3.4 Search

Request (Exemplo)

Response (Exemplo)

3.5 Update Enroll

Request (Exemplo)

Response (Exemplo)

3.6 Delete Enroll

Request (Exemplo)

Response (Exemplo)

3.7 Liveness

Request (Exemplo)

Response (Exemplo)

3.8 Face Occlusion (Oclusão de Face)

Payload

Response (Exemplo - Sem oclusão)

Response (Exemplos - Com oclusão)

Informações Adicionais

3.9 Get Image

Request (Exemplo)

Response (Exemplo)

3.10 Get Image 3x4

Request (Exemplo)

Response (Exemplo)

Tratamento de erros

3.11 Armazenamento das Fotos de Transações

Armazenamento da Foto pelo Fortface

Resgate das imagens pelo `SessionID`

Remoção das imagens

Armazenamento da Foto pelo Cliente

Utilizar o recurso `ReturnPhoto = True`

Hash Retornado no Payload

3.12 Hubface - Validação de Rosto e Documento em Provedores de Identidade

Configuração

Utilização

Headers

Payload

Exemplo de Request

Response (Exemplo)

Interpretação do Rank

Testes em Sandbox

3.13 Analises Adicionais

3.13.1 Análises x Endpoints Suportados

3.13.2 Como habilitar análises adicionais

SDK

Backoffice

3.13.3 Estrutura do Request

Descrição dos campos

3.13.4 Retornos das Análises

NSFW Detection – Exemplo de Retorno

Face Occlusion – Exemplo de Retorno

Quality Assessment – Exemplo de Retorno

3.13.5 Exemplos de Uso

SDK – Handshake

Backoffice – Exemplo em `/liveness`

Backoffice – Exemplo em `/enroll` (Quality Assessment)