Guia de Integração V10

Visão Geral

A versão 10 do SDK FaceTec utiliza um fluxo cíclico baseado em requestBlob e responseBlob, onde o SDK controla toda a execução do Liveness 3D.

Como Funciona

O processo segue um ciclo controlado pelo SDK:

O SDK gera um requestBlob
A aplicação envia esse dado para o Server FaceTec
O Server FaceTec retorna o responseBlobpara a aplicação
A aplicação repassa o retorno ao SDK
O SDK decide se continua ou finaliza

Esse ciclo se repete até o resultado final.

⚠️
Observação!
Em um fluxo bem-sucedido, normalmente ocorrem cerca de 3 requisições. No entanto, a quantidade de chamadas é totalmente controlada pelo SDK.

O SDK é o único responsável por controlar o fluxo.
A aplicação e o backend não possuem controle sobre a quantidade de chamadas.

Fluxo do Processo

Endpoint

POST https://hml.certiface.com.br/facecaptcha/service/captcha/3d/process-request

Headers	Descrição
Content-Type	application/json

Payload da Requisição

O payload é sempre o mesmo em todas as chamadas:

{
  "appkey": "string",
  "requestBlob": "string",
  "userAgent": "string"
}

Campo	Descrição
appkey	Chave de autenticação da aplicação
requestBlob	Gerado pelo SDK FaceTec (contém dados da sessão)
userAgent	Identificador do navegador/dispositivo

Primeira Chamada

Responsável por iniciar o processo.

Endpoint

POST https://hml.certiface.com.br/facecaptcha/service/captcha/3d/process-request

Headers	Descrição
Content-Type	application/json

Response:

{
  "responseBlob": "string",
  "didError": false
}

Segunda Chamada

Processamento intermediário e geração do launchId.

Endpoint

POST https://hml.certiface.com.br/facecaptcha/service/captcha/3d/process-request

Headers	Descrição
Content-Type	application/json

Response:

{
  "responseBlob": "string",
  "launchId": "uuid",
  "didError": false
}

Terceira Chamada (Resultado Final)

Equivalente ao retorno final do Liveness 3D tradicional.

Endpoint

POST https://hml.certiface.com.br/facecaptcha/service/captcha/3d/process-request

Headers	Descrição
Content-Type	application/json

Response:

{
  "valid": true,
  "codID": 200.0,
  "hash": "string",
  "protocol": "string",
  "retry": false,
  "responseBlob": "string",
  "launchId": "uuid"
}

❗️
Importante!

Para quem utiliza API Global (Certiface - V1.2) Considere o response dessa documentação.

Para quem utiliza API Global (Certiface) com Classe se Risco

Campos importantes:

Campo	Descrição
valid	Indica se o liveness foi aprovado
codID	Código de status
hash	Identificador da validação
protocol	Número do protocolo gerado
retry	Indica se precisa refazer
launchId	ID da sessão

Regras do fluxo

O fluxo só é considerado válido quando o retorno final possuir valid = true.
Chamadas de retentativas não impactam o backend.
O launchId é retornado pelo serviço e reutilizado ao longo da sessão.
O responseBlob deve ser utilizado pelo SDK FaceTec para continuidade do fluxo.

Fluxo de Retentativa

Em caso de falha, o SDK reinicia o processo chamando novamente o endpoint.

O retorno será equivalente ao da segunda chamada, contendo um responseBlob e o mesmo launchId.

Considerações Técnicas

❌ Não gera validação de liveness;
❌ Não gera protocolo;
❌ Não persiste registro;
✅ Apenas reinicia tentativa no SDK.

❗️
É bom saber!
O backend não deve interpretar ou modificar o responseBlob.
Toda a orquestração do fluxo é responsabilidade exclusiva do SDK FaceTec.