3. Recursos

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 | update-enroll | delete-enroll.
• deviceRequestInfo*: Informações criptografadas do dispositivo que originou o evento.
• 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 | update-enroll | delete-enroll | capture>",
    "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

1. O device fingerprint é criptografado e extraído do “deviceRequestInfoNaN” e, em seguida, é descriptografado.

2. 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.

3. 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	V1	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	V1	search
Backoffice	liveness	POST	V1	liveness
Backoffice	capture	POST	v1	capture
Backoffice	photo	GET	V1	N/A
Backoffice	log session	GET	V1	N/A

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).

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).

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

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).

Request (Exemplo)

context: sdk ou backoffice

curl --request POST \
  --url 'https://api-sandbox.fortface.ai/{context}/v1/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": [
    {
      "encodingId": "string",
      "externalUserId": "string",
      "matchLevel": 15
    },
    {
      "encodingId": "string",
      "externalUserId": "string",
      "matchLevel": 15
    },
    {
      "encodingId": "string",
      "externalUserId": "string",
      "matchLevel": 15
    },
    {
      "encodingId": "string",
      "externalUserId": "string",
      "matchLevel": 13
    },
    {
      "encodingId": "string",
      "externalUserId": "string",
      "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).

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
• /enroll
• /identify
• /capture

Payload

• Nenhuma alteração é necessária na estrutura da request.
• A feature é habilitada diretamente na galeria do cliente.
• 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, contendo os resultados da análise.

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

1. 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.
2. 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.
3. 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.
4. 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.
5. Ó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.
6. 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 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-1781016472881. 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"
    }
}

Validação da Foto por sessionId

O cliente pode utilizar o end-point de validação para confirmar se uma foto específica pertence à sessão (sessionId) informada. A requisição deve incluir o sessionId e os dados da imagem em formato Base64.

curl --location 'https://api-sandbox.fortface.ai/backoffice/v1/sessions/photo/validate' \
--header 'x-api-key: your-api-key' \
--header 'Content-Type: application/json' \
--data '{
    "sessionId": "08996501-5e34-485c-a1ea-56f3f68a9c42",
    "imageData": "BASE64 DA IMAGEM"
}'

A resposta será um booleano, indicando se a foto pertence ou não àquela sessão.

3.11 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
• 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 = 0
• Document final 1 - Score = 1
• Document final 2 - Score = 2
• Document final 3 - Score = 2
• Document final 4 - Score = 2
• Document final 6 - Score = 3
• Document final 7 - Score = 4
• Document final 8 - Score = 4
• Document final 9 - Score = 5

3.12 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

3.12.1 Análises x Endpoints Suportados

Análise	Endpoints Suportados
Liveness Calibration	/liveness, /capture
Face Occlusion	/liveness, /capture, /search, /identify, /enroll
NSFW Detection	/liveness, /capture, /identify

---

3.12.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.12.3 Estrutura do Request

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

Descrição dos campos

Campo	Tipo	Descrição
livenessCalibration	string	Define o modo de calibração (ex.: enhanced).
nsfw	boolean	Ativa a análise de conteúdo impróprio.
faceOcclusion (opcional)	boolean	Ativa a análise de oclusão facial.

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

---

3.12.4 Retornos das Análises

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

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

---

3.12.5 Exemplos de Uso

SDK – Handshake

{
  "apiKey": "SUA_API_KEY",
  "analysis": {
    "livenessCalibration": "enhanced",
    "nsfw": true,
    "faceOcclusion": true
  }
}

Backoffice – Exemplo em /liveness

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