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:

1. O SDK gera um requestBlob
2. A aplicação envia esse dado para o Server FaceTec
3. O Server FaceTec retorna o responseBlobpara a aplicação
4. A aplicação repassa o retorno ao SDK
5. 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

Payload da Requisição

O payload é sempre o mesmo em todas as chamadas:

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

Primeira Chamada

Responsável por iniciar o processo.

Endpoint

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

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

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

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:

Tratamento de respostas

Sessão Expirada

Quando um usuário inicia uma sessão, mas não conclui o processo antes da expiração da appkey, o endpoint /process-request retorna o seguinte:

HTTP 401 Unauthorized

{
  "error": "SESSAO EXPIRADA"
}

⚠️

Observação!

Esse retorno ocorre apenas quando o usuário já iniciou uma tentativa de validação.

Caso a appkey expire sem nenhuma tentativa do usuário, o comportamento permanece o mesmo já existente, retornando apenas:

JSON

HTTP 401 Unauthorized

/result

O endpoint /result também possui tratamento específico para sessões expiradas.

Quando a sessão expirar sem execução da prova de vida, será retornado:

HTTP 200 OK

{
  "error": "SESSAO EXPIRADA - PROVA DE VIDA NAO EXECUTADA"
}

Caso a appkey expire sem nenhuma tentativa do usuário, o comportamento atual permanece o mesmo, retornando:

HTTP 500 Internal Server Error

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.