Certiface

Passo a passo para integrar com a Oiti

Este guia de integração se destina aos clientes que desejam integrar com a Oiti por meio das nossas APIs, utilizando a Classe de Risco.

A Integração Certiface ID requer oito etapas:

Credencial
Appkey
Liveness 2D
3.1. Challenge
3.2. Captcha
Liveness 3D
4.1. Facetec
4.2. 3D Session
4.3. 3D Liveness
4.4. Iproov
4.5. 3D Session
4.6. 3D Liveness
Document
Webhook
Result
Status Updater

Abaixo está um diagrama do processo de integração com todos os passos:

1. Credencial

Antes de iniciar será necessário gerar as credenciais que vão ser utilizadas para gerar uma appkey. Você precisa informar o login e senha de acesso à integração e o serviço deve retornar as credenciais de acesso ao Certiface ID.

Request

POST https://hml.certiface.com.br/facecaptcha/service/captcha/credencial

Headers	Descrição
Content-Type	application/x-www-form-urlencoded

Body Params

Parâmetro	Descrição
user	Login do operador do Certiface.
pass	Senha criptografada em MD5.

Request example

user: login
pass: 3355a3973f54a008c642ee94fd0313d7

Response

Headers	Descrição
Content-Type	application/json

Body Params

Body	Descrição
token	Token de autorização para gerar Appkeys.
expires	Horário de expiração do token UTC-0.

Responses

Status Code	Descrição
200	OK.
400	Requisição mal formada ou os dados não foram informados corretamente.
401	Não autorizado ou credenciais expiradas.
500	Erro genérico.

Response example

{
    "token": "QjBlFoPJZYjSry-H5G3UU_BPSJST1zy8uMSPTtOgr7Y",
    "expires": "27/09/2019 19:09:00" 
}

📘
É bom saber!

O tipo do conteúdo da requisição deve ser "application/x-www-form-urlencoded". O token gerado por este método possui uma expiração configurável. O padrão são 3 horas. Enquanto o token não expirar, é possível gerar novas Appkeys.

O endereço https://hml.certiface.com.br./ deve ser utilizado apenas para o desenvolvimento e homologação da integração. Para acesso ao ambiente de produção, deve-se substituí-lo por https://www.certiface.com.br/.

2. Appkey

Para acessar o serviço do Certiface ID deve ser criada uma Appkey informando os dados do cliente (cpf, nome e data de nascimento), o login do operador e o Token gerado no passo anterior. O Certiface gera uma appkey global que deve ser utilizada no front-end, pelo cliente que solicitou o processo para realizar a validação biométrica.

Request

POST https://hml.certiface.com.br/facecaptcha/service/captcha/appkey

Headers	Descrição
Content-Type	application/x-www-form-urlencoded

Body Params

Parâmetro	Descrição
user	Login do operador que gerou as credenciais de acesso.
token	JSON gerado na resposta do método /credencial.
cpf	CPF do usuário que realizará a prova de vida.
nome	Nome e sobrenome do usuário que realizará a prova de vida.
nascimento	Data de nascimento do usuário, no formato `dd/mm/yyyy` .
idExternoCliente	Campo de referência da identificação da proposta/jornada/transação/contrato do cliente. Este id deve ser escrito alfanumérico e conter até 255 caracteres.

Request example

user: opelogin
token: {"token": "QjBlFoPJZYjSry-H5G3UU_BPSJST1zy8uMSPTtOgr7Y","expires": "27/09/2019 19:09:00"}
cpf: 00000014141
nome: Nome sobrenome
nascimento: 15/11/2001
idExternoCliente: 4561645657446457-651A.SDRFEN

Responses

Headers	Descrição
Content-Type	application/json

Body Params

Body	Descrição
appkey	Chave de acesso para validação biométrica com prova de vida.

Responses

Status Code	Descrição
200	OK.
401	Não autorizado ou credenciais expiradas.
422	Requisição mal formada ou dados não foram informados corretamente.
500	Erro genérico.

Response example

{												            			      
 		 "appkey":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EaiHfZC9VdEVBNiPqfNVpS38iw"
}

📘
É bom saber!
A appkey gerada por este método possui tempo de expiração configurável. O padrão é de 5 minutos. Ela pode ser utilizada para obter mais informações da transação da prova de vida e dos documentos, chamando o método "/result".

3. Liveness 2D

3.1 Challenge

Este método cria os desafios que o usuário deverá realizar com a appkey gerada no passo anterior.

Uma appkey pode criar diversos desafios, porém, após a chamada ao /captcha, ela estará vinculada à uma prova de vida, não podendo ser utilizada novamente para gerar desafios.
Após a geração dos desafios há um intervalo de 60 segundos, ao qual os desafios devem ser executados. Caso esta condição não seja cumprida, será necessário gerar novos desafios.

Request

POST https://hml.certiface.com.br/facecaptcha/service/captcha/challenge

Headers	Descrição
Content-Type	application/x-www-form-urlencoded

Body Params

Body	Descrição
appkey	Chave de acesso para validação biométrica com prova de vida.

Request example

appkey: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EaiHfZC9VdEVBNiPqfNVnPzDill2E5YyYdSpS38iw

Responses

Headers	Descrição
Content-Type	application/json

Body Params

Body	Descrição
chkey	Chave da requisição.
snapFrequenceInMillis	Tempo para cada foto em milissegundos.
snapNumber	Quantidade de fotos por Desafio.
totalTime	Tempo total de todos os desafios (seg).
numberOfChallenges	Número de Desafios.
challenges	Desafios da requisição.

Chalenges

Chalenges são os desafios(posições da face) que devem ser realizados para validação da biometria facial.

Challenges	Descrição
mensagem	Imagem do texto do desafio em base64.
tempoEmSegundos	Tempo do desafio em segundos.
tipoFace.codigo	Código do tipo do desafio.
tipoFace.imagem	Imagem do emoji do desafio em base64.

Responses

Status Code	Descrição
200	OK
401	Não autorizado ou credenciais expiradas.

Response example

{
    chkey: "BlG6fiiDMy0_LFP_5ku1F3HmTfBJwSx9VrMGGtVQcb",
    snapFrequenceInMillis: 1990,
    snapNumber: 2,
    totalTime: 8,
    numberOfChallenges: 1,
    challenges:[{
        mensagem: "img_base64",
        tempoEmSegundos: 4,
        tipoFace: {
            codigo: "E5XG6ZJBqr5yZy4bku1F3Xsx7k_HmTfBJwSGGtVQcb4x9VrMpGah0RISjKVG56aZ",
            imagem: "img_base64"
        }
    },{
        mensagem: "img_base64",
        tempoEmSegundos: 4,
        tipoFace: {
            codigo: "yZy4bE5XG6ZJBqrXsx7k_5ku1F3HmTfBJwSx9VrMGGtVQcb4pGah0RIG56aZSjKV",
            imagem: "img_base64"
        }
    }]
}

📘
É bom saber!
O conteúdo do Body estará criptografado. Exemplo: YtyB6DGov4NNVGskJnxwKtA4QKmQnZDmPxFJSSfC...JZbNyTWD171A==

3.2 Captcha

Este método envia as imagens dos desafios executados para validações biométricas.

Ao chamar este método, a appkey gerada anteriormente estará associada a esta prova de vida.

Request

POST https://hml.certiface.com.br/facecaptcha/service/captcha

Headers	Descrição
Content-Type	application/x-www-form-urlencoded

Body Params

Body	Descrição
appkey	Appkey gerada pelo método "/appkey".
chkey	Chave do desafio que está no body do "/challenge".
images	Imagens dos desafios, devidamente formatadas.

Request example

appkey: "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EiPqfNVnPzDill2E5YyYdSpS38iw",
chkey: "BlG6fiiDMy0_LFP_5ku1F3HmTfBJwSx9VrMGGtVQcb",
images: "xtT3IrjV77MIl61899E...FvXXsnDd38%3D"

Response

Headers	Descrição
Content-Type	application/json

Response Body

Body	Descrição
valid	Indica Acesso Negativo ou Acesso Positivo (true or false).
codID	Código identificador do tipo da transação (detalhes mais abaixo).
cause	Indica por qual motivo o processo finalizou sem sucesso (Biometria ou Prova de Vida).
protocol	Protocolo da transação de prova de vida. Ex: "201900039067".

codID

codID	Descrição
200.0	Prova de vida válida.
300.1	Prova de vida inválida.
300.2	Usuário bloqueado.

Responses

Status Code	Descrição
200	OK
401	Não autorizado ou credenciais expiradas.
500	Erro genérico.

Response example

{
    "valid":false,
    "codID":300.1,
    "cause":"PROVA DE VIDA",
    "protocol":"201900039067"
}

4. Liveness 3D

4.1 Facetec

4.2 3D Session

Este método cria um session token para habilitar o SDK Front-end 3D Liveness para execução da validação. Esse token está associado a appkey gerada no segundo passo.

Após a chamada ao /liveness-3d, tanto o session token quanto a appkey são finalizados. Ou seja, para gerar uma nova sessão é necessário retornar ao segundo passo e gerar uma nova appkey.

Request

POST https://hml.certiface.com.br/facecaptcha/service/captcha/3d/session-token

Headers	Descrição
Content-Type	application/json

Body Params

Body	Descrição
appkey	Chave de acesso para validação.
userAgent	String do userAgent fornecida pelo SDK 3D Liveness , opcional.

Request example

{  
  "appkey" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EaiHfZC9VdEVBNiPqfNVnPzDill2E5YyYdSpS38iw",  
 "userAgent" : "fornecido pelo dispositivo"  
}

Response

Headers	Descrição
Content-Type	application/json

Response Body

Body	Descrição
sessionToken	Token de sessão gerado pelo API do 3D Liveness para habilitar a validação biométrica.

Responses

Status Code	Descrição
200	OK
401	Não autorizado ou credenciais expiradas.
500	Erro interno na geração do Token.

Response example

{  
		"sessionToken" : "AJyC3MiVXTgxC8bj3CJFopEPQyrFG8smzdd71ohQ8kTCbDAgRYyd6Uz"  
}

📘
É bom saber!

O conteúdo do Body estará criptografado;

Os métodos para a execução de cada módulo são exclusivos para o fluxo ao qual pertence;

As URLs podem ser atualizadas de acordo as propriedades internas.

4.3 3D Liveness

Este método envia os mapas tridimensionais da face gerados pelo SDK front-end 3D Liveness para validação.

Ao chamar este método, a appkey gerada no passo 2 estará associada a esta prova de vida e não poderá ser reutilizada.

Request

POST https://hml.certiface.com.br/facecaptcha/service/captcha/3d/liveness

Headers	Descrição
Content-Type	application/json

Body Params

Body	Descrição
appkey	Chave de acesso para validação.
userAgent	String do userAgent fornecida pelo SDK 3D Liveness.
faceScan	Blob do mapa tridimensional da face, conforme fornecido pelo SDK 3D Liveness.
auditTrailImage	Imagem frontal do usuário fornecida pelo SDK 3D Liveness, encodada e criptografada.
lowQualityAuditTrailImage	Imagem de baixa qualidade do usuário fornecida pelo SDK 3D Liveness, encodada e criptografada.
sessionId	O UUID da sessão gerada pelo 3D Liveness no front-end.

Request Body

{
   " appkey" :"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UiLC.utzIZMCVqe_wNjNSxJw",
    "userAgent" : "fornecido pelo SDK",
    "faceScan":"BAFsr1Sp2eCWZEibLqKEloBX/gDpeC6RxJprf/N1thdyESSYKKOeQGTKuw8bDkw=" ,
    "auditTrailImage":"AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQofseZMTbR",
    "lowQualityAuditTrailImage":"AAQSkZJRgABAQAAD/2wBDAAAwMBQofseZMTbR",
    "sessionId":"5dc67a9d-f8a4-44cc-b159-fbaa9ea222b3"
}

📘
É bom saber!

As URLs podem ser atualizadas de acordo as propriedades internas.

Response

Headers	Descrição
Content-Type	application/json

Response Body

Body	Descrição
valid	Indica Acesso Negativo ou Acesso Positivo (true or false).
codID	Código identificador do tipo da transação (detalhes mais abaixo).
cause	Indica por qual motivo o processo finalizou sem sucesso (Biometria ou Prova de Vida).
protocol	Protocolo da transação de prova de vida. Ex: "201900039067".
scanResultBlob	É um blob criptografado para uso do SDK 3D Liveness para tratar o retorno.

codID

codID	Descrição
200.0	Prova de vida válida.
300.1	Prova de vida inválida.
300.2	Usuário bloqueado.

Responses

Status Code	Descrição
200	OK.
401	Não autorizado ou credenciais expiradas.
500	Erro genérico.

Response example

{
    "valid":false ,
    "codID":300.1 ,
    "cause":"PROVA DE VIDA" ,
    "protocol":"201900039067" ,
    "scanResultBlob":"AAAAAaaaaa123456zzzzzzz"
}

4.4 Iproov

4.5 3D Session

Para esta etapa deve-se executar o método: Session Token.

Este método cria um token para habilitar o SDK Front-end 3D Liveness para execução da validação. Esse token está associado a appkey que será gerada no próximo passo.

❗️
Após a chamada ao /liveness-3d, tanto o token quanto a appkey são finalizados. Ou seja, para gerar uma nova sessão é necessário retornar ao segundo passo e gerar uma nova appkey.

Aqui é onde você faz a chamada para o endpoint da API, enviando as informações necessárias para iniciar o processo.

❗️
É importante garantir que os headers e os dados do body estejam corretamente preenchidos para que tudo funcione como esperado.

Basta seguir o exemplo abaixo de como a URL e os headers devem ser configurados para realizar o processo corretamente.

POST https://hml.certiface.com.br/facecaptcha/service/captcha/3d/session-token

Headers	Descrição
Content-Type	application/json

Body Params

Esses são os parâmetros que você precisa incluir no body do request. Certifique-se de preencher corretamente para que a API consiga processar a solicitação.

Body	Descrição
appkey	Chave de acesso para validação.
userAgent	String do userAgent.

Request example

Aqui está um exemplo de como o body do request deve ser estruturado. Use esse exemplo como referência para montar a sua requisição, substituindo os valores necessários.


{  
  "appkey" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EaiHfZC9VdEVBNiPqfNVnPzDill2E5YyYdSpS38iw",  
 "userAgent" : "fornecido pelo dispositivo"  
}

Headers	Descrição
Content-Type	application/json

Após enviar a requisição, essa é a parte em que você recebe a resposta da API. Ela trará informações importantes como o token de sessão, o nome do provedor responsável e a URL que será usada para realizar a validação biométrica.

👍
Fique atento também ao código de status para identificar se a operação foi bem-sucedida ou se ocorreu algum erro.

Response Body

Este é o formato do body que você receberá na resposta da API. Ele traz informações como se a requisição foi processada com sucesso e outros detalhes importantes como o isContingency, token, vendor, e url.

Body	Descrição
isContingency	Indicador de contingência da API
token	Token de sessão gerado pelo API do 3D Liveness para habilitar a validação biométrica.
vendor	Nome do provedor de serviço do Liveness 3D
url	URL do provedor de serviço do Liveness 3D

Responses

Aqui você encontra os possíveis status codes que a API pode retornar. Eles indicam se a requisição foi bem-sucedida ou se houve algum problema, como credenciais expiradas ou erro interno no servidor.

Status Code	Descrição
200	OK
401	Não autorizado ou credenciais expiradas.
500	Erro interno na geração do Token.

Response example

Este é um exemplo de como a resposta da API pode se parecer. Ele mostra o formato dos dados que você receberá após o processamento da requisição.


{  

    "isContingency": false,
    "token": "891450a09ee434e2534ce3fbd36bdb0049a09d466ef26b6f059a75371801vi18",
    "vendor": "IPROOV",
    "url": "latam.rp.secure.iproov.me"

}

4.6 3D Liveness

Agora que o token foi gerado, é hora de validar a autenticidade biométrica com o método Liveness. Esta etapa realiza a verificação do liveness do usuário, garantindo que o processo seja feito de forma segura.

👍
Esse é o momento em que a validação biométrica realmente acontece. Utilizando o sessionToken gerado anteriormente e a appkey, o sistema realiza uma verificação em tempo real para garantir que há uma pessoa viva na frente da câmera. O resultado dessa etapa vai indicar se a prova de vida foi bem-sucedida ou não, além de fornecer um protocolo de referência para acompanhamento.

Request

Aqui você verá como fazer a requisição para realizar a validação de liveness. Como na etapa anterior, você precisará configurar corretamente a URL e o body para enviar o appkey e o sessionToken obtidos.

POST https://hml.certiface.com.br/facecaptcha/service/captcha/3d/liveness

Headers	Descrição
Content-Type	application/json

Body Params

São os parâmetros necessários para o body da requisição. O sessionToken é o principal dado, pois é ele que vai identificar a sessão em que a validação biométrica está sendo realizada.

Body	Descrição
appkey	Chave de acesso para validação.
sessionToken	Token de sessão gerado pelo API do 3D Liveness para habilitar a validação biométrica.

Request Body

Esse é o formato correto para o body do request. Ele precisa incluir tanto o appkey quanto o sessionToken para que o processo de validação funcione corretamente.

{
   " appkey" :"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UiLC.utzIZMCVqe_wNjNSxJw",
    "sessionToken":"891450a09ee434e2534ce3fbd36bdb0049a09d466ef26b6f059a75371801vi18"
}

Response

Após o request de validação de liveness, você vai receber uma resposta com o status do processo. Ela indica se o acesso foi aprovado ou não, e pode fornecer mais detalhes sobre o motivo do sucesso ou falha.

Headers	Descrição
Content-Type	application/json

Response Body

O body da resposta irá indicar se a validação foi bem-sucedida ou não, juntamente com o código identificador da transação. Além disso, ele vai fornecer o motivo da falha, caso tenha ocorrido, seja por Biometria ou Prova de Vida.

Body	Descrição
valid	Indica Acesso Negativo ou Acesso Positivo (true or false).
codID	Código identificador do tipo da transação (detalhes mais abaixo).
cause	Indica por qual motivo o processo finalizou sem sucesso (Biometria ou Prova de Vida).
protocol	Protocolo da transação de prova de vida. Ex: "201900039067".

codID

Esse campo traz o código de identificação do tipo de transação realizada. Ele pode ser útil para entender o resultado da validação, como "Prova de vida válida" ou "Usuário bloqueado".

codID	Descrição
200.0	Prova de vida válida.
300.1	Prova de vida inválida.
300.2	Usuário bloqueado.

Responses

Aqui estão os status codes possíveis que a API pode retornar, informando sobre o sucesso ou falha do processo. Os códigos ajudam a identificar se o problema é devido a credenciais inválidas, erro interno, ou outro tipo de falha.

Descrição	Status Code
OK.	200
Não autorizado ou credenciais expiradas.	401
Erro genérico.	500

Response example

Esse é um exemplo de como a resposta pode se parecer. Ela irá mostrar, entre outras coisas, o resultado da validação e o código que descreve o tipo de acesso concedido ou negado.

{
    "valid":false ,
    "codID":300.1 ,
    "cause":"PROVA DE VIDA" ,
    "protocol":"202500012345" ,
}

5. Document

Este método envia as imagens dos documentos para a validação.

Ao chamar este método, a appkey gerada anteriormente estará associada ao OCR e documentoscopia.

Request

POST https://hml.certiface.com.br/facecaptcha/service/captcha/document

Headers	Descrição
Content-Type	application/json

Body Params

Body	Descrição
appkey	Appkey gerada pelo método "/appkey".
images	Array de Imagens do documento, em base64. (Suporta uma ou duas imagens, separado por vírgula).

Request example

{
    "appkey": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EiPqfNVnPzDill2E5YyYdSpS38iw",
    "images": [
        "xtT3IrjV77MIl61899E...",
        "FvXXsnDd38%3D..."
    ]
}

Response

Headers	Descrição
Content-Type	application/json

Response Body

Body	Descrição
appkey	Appkey gerada pelo método "/appkey".
id	Identificação interna.

Responses

Status Code	Descrição
200	OK
400	Imagem sem documento, pode ser enviado outra imagem utilizando a mesma appkey. (alerta de documento não encontrado, voltar para captura de documentos).
401	Não autorizado ou credenciais expiradas.
500	Erro genérico.

Response example

{
	"appkey": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EiPqfNVnPzDill2E5YyYdSpS38iw",
    "id": 55
}

📘
É bom saber!
Em todo retorno status code 400, a aplicação deve enviar novas imagens de documento. O procedimento se repetirá até que o retorno seja igual a status code 200 (OK), ou status code 401(Appkey expirada). O tempo de expiração é de 5 minutos.

6. Webhook

A Certiface ID notificará a conclusão da jornada do cliente assim que o processo for finalizado. Esta notificação será enviada para um endpoint especificado pela empresa através do método Webhook configurável POST, conforme definido a seguir:

🚧
Importante
A empresa deve manter este endpoint ativo para receber a notificação de conclusão.

Request

POST https://host/servername/*/

Headers	Descrição
Content-Type	application/json

Body Params

Body	Descrição
Status	Comportamento esperado do status: "Completo". ou "Error"
Appkey	Appkey gerada pelo método "/appkey".

Request example Status "Completo"

{
    "Status" : "Completo",
    "Appkey" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EiPqfNVnPzDill2E5YyYdSpS38iw"
}

7. Result

Este método retorna o detalhe de toda a jornada do cliente (Prova de Vida, Bureau de Face, Facematch, Serpro, OCR, e Documentoscopia). Ele pode ser chamado a qualquer momento, de preferência após o recebimento da finalização por meio do Webhook.

Para realizar a chamada é necessário ter a appkey gerada no passo 2.

POST https://hml.certiface.com.br:8443/facecaptcha/service/captcha/document/result

Headers	Descrição
Content-Type	application/x-www-form-urlencoded

Body Params

Body	Descrição
appkey	Appkey gerada pelo método "/appkey".

Request example

{
  appkey: "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EiPqfNVnPzDill2E5YyYdSpS38iw"
}

Response

Headers	Descrição
Content-Type	application/json

Response Body

Body	Descrição
status	Status do processamento da jornada: "Completo"; "Em processamento"; "Não processado"; "Erro".
idExternoCliente	Campo de referência da identificação da proposta do cliente, conforme enviado na etapa 2. Appkey.
dataCriacaoAppkey	Data em que foi gerada a appkey pelo método do passo 2.
analiseDocumento	Análise do documento. (OCR e Documentoscopia). Conforme tabela a seguir.
certifaceID	Retorno do objeto CertifaceID. (Bureau de Faces). Ver tabela certifaceID abaixo.
facecaptcha	Retorno do objeto Facecaptcha. (Prova de Vida). Ver tabela facecaptcha abaixo.
fotos	Retorno do objeto das fotos enviadas. (Prova de Vida e Documentos).

analiseDocumento

analiseDocumento	Descrição
id	Identificação interna.
idExterno	Código de identificação interna do cliente.
ticket	Ticket do(s) documento(s) em processamento.
dtCriacao	Data de criação do ticket.
idCliente	Código de identificação do cliente no sistema de Documentoscopia.
idSubcliente	Código de identificação do subcliente no sistema de Documentoscopia.
idUsuario	Código de identificação do usuário.
statusProcessamento	Identificador de status de processamento. Vide tabela abaixo.
dtStatusProcessamento	Data e hora do status de processamento finalizado.
idTipoProcessamento	Código do tipo de processamento realizado. Código interno.
score	Valor 0 à 100% da possibilidade do documento ser verdadeiro, onde 100% quer dizer que o documento passou com sucesso por todas as regras cadastradas no sistema e padrões do estado emissor.
urlRetornoTicket	Endereço web onde será postado o resultado do processamento.
dtRetornoTicket	Data e hora de retorno do ticket.
responseClientDadosOcrDTO	Todos os dados extraídos do documento; tendo ou não duas partes, a primeira sendo RG, a segunda CNH.
biometriaCertiface	Resultado do Facematch do documento.
documentos	Lista de todos os status dos documentos processados pela API.

statusProcessamento

statusProcessamento	Descrição
2	Aguardando Processamento.
3	Em Processamento.
4	Processado.
5	Cancelado.
6	Falha no Processamento.
70	Upload Incorreto.

responseClientDadosOcrDTO

Trata-se do conjunto de dados retornados conforme o documento enviado para análise; classificação do documento (RG; CNH; DNI; CIN).

responseClientRGOcrDTO

responseClientRGOcrDTO	Descrição
estado	Estado onde foi emitido o documento.
documento	Identificação do tipo do documento.
dtExpedicao	Data da expedição do documento (formato: dd/mm/yyyy).
dtExpedicaoFormatada	Data da expedição do documento (formato: yyyy-mm-dd).
dtNascimentoFormatada	Data de nascimento (formato: yyyy-mm-dd).
nrRg	Número do documento RG.
nome	Nome e sobrenome do titular do documento.
filiacao	Nome do pai e nome da mãe.
nomePai	Nome do Pai.
nomeMae	Nome da Mãe.
docOrigem	Origem do Documento.
dtNascimento	Data de nascimento (formato: dd/mm/aaaa).
cpf	Número do CPF (formato: "999999999/99").
naturalidade	Naturalidade.
nomenclatura	Nome do órgão emissor.
dtCriacao	Data de criação do processo (formato: "yyyy-mm-dd hh:mm:ss").
flAnalfabeto	Identificação de assinatura do usuário no documento para leitura no OCR. Enviado de acordo com o tipo de documento (DNI; RG; ou CIN). True = documento não assinado; False: documento assinado.

ResponseClientCNHcrDTO

ResponseClientCNHOcrDTO	Descrição
estado	Sigla do estado da emissão do documento CNH.
estadoNome	Nome do estado da emissão do documento CNH.
documento	Tipo do documento (CNH).
nome	Nome e sobrenome do titular do documento.
docOrigem	Dados do documento de origem: número de identificação e emissor de origem.
documentoOrigem	Número de identificação do documento de origem.
emissorOrigem	Emissor de Origem.
ufOrigem	UF de Origem.
cpf	Número do CPF (formato "999.999.999-99").
dtNascimento	Data de Nascimento (formato: dd/mm/aaaa).
dtNascimentoFormatada	Data de Nascimento (formato: yyyy-mm-aa).
filiacao	Nome do pai e nome da mãe.
nomePai	Nome do Pai.
nomeMae	Nome da Mãe.
permissao	"PERMISSÃO" ou NULL.
acc	Autorização para conduzir ciclomotores.
categoria	Categoria ("ABCDE" ou individual).
numeroRegistro	Número do registro do documento.
validade	Data de validade do documento (formato: "dd/mm/aaaa").
primeiraHabilitacao	Data da primeira habilitação (formato: "dd/mm/aaaa").
local	Cidade e estado onde foi emitido o documento ("SÃO PAULO, SP").
dtExpedicao	Data da expedição do documento (formato: "dd/mm/aaaa").
dtExpedicaoFormatada	Data da expedição do documento (formato: yyyy-mm-dd).
codSeguranca	Código de segurança.
espelho	Número de controle do documento (papel documento).
renach	Numeração do Renach.
dtCriacao	Data de criação do processo (formato: "yyyy-mm-dd hh:mm:ss").

ResponseClientDNIOcrDTO

ResponseClientDNIOcrDTO	Descrição
estado	Estado de emissão do Documento Nacional de Identidade (DNI).
nomenclatura	Nome do orgão emissor.
naturalidade	Naturalidade.
filiacao	Nome do pai e nome da mãe.
nomePai	Nome do pai.
nomeMae	Nome da mãe.
dtNascimento	Data de Nascimento (formato: dd/mm/aaaa).
dtNascimentoFormatada	Data de Nascimento (formato: yyyy-mm-aa).
nome	Nome e sobrenome do titular do documento.
observacaoFront	Observação.
outroRG	Número de outro RG caso possua.
orgao	Órgão Emissor.
fator	Tipo sanguíneo com fator Rh.
registroCivil	Informação de origem do Registro civil.
cnh	Número do CNH.
cns	Cartão Nacional de Saúde.
cpf	Número do CPF.
ctps	Número da Carteira de Trabalho Previdência Social.
serieCTPS	Série da Carteira de Trabalho Previdência Social.
ufctps	UF de emissão da Carteira de Trabalho Previdência Social.
dni	Número do DNI.
tituloEleitor	Número do Título de Eleitor.
dtExpedicao	Data da expedição do DNI (formato: "dd/mm/aaaa").
dtExpedicaoFormatada	Data da expedição do DNI (formato: yyyy-mm-dd).
local	Posto onde o DNI foi emitido.
certMilitar	Número da Certidão Militar.
nomeSocial	Nome Social.
pis	Número do PIS.
profissional	Identidade Profissional ou CIP.
rg	Número do RG.
dtCriacao	Data de criação do processo (formato: "yyyy-mm-dd hh:mm:ss").
flAnalfabeto	Identificação de assinatura do usuário no documento para leitura no OCR. Enviado de acordo com o tipo de documento (DNI; RG; ou CIN). True = documento não assinado; False: documento assinado.

ResponseClientCINOcrDTO

ResponseClientCINOcrDTO	Descrição
documento	Tipo do documento (neste caso, CIN).
estado	Estado de emissão do documento CIN.
nomenclatura	Nome do orgão emissor.
nome	Nome e sobrenome do titular do documento.
cpf	Número do CPF.
sexo	Gênero do titular do documento.
dtNascimento	Data de Nascimento (formato: dd/mm/yyyy).
nacionalidade	Nacionalidade.
naturalidade	Naturalidade.
dtValidade	Data validade documento (sem definição de formato).
posto	Local de emissão.
filiacao	Nome do pai e nome da mãe.
nomePai	Nome do Pai.
nomeMae	Nome da Mãe.
orgaoEmissor	Órgão Emissor.
local	Estado onde foi emitido o documento ("SÃO PAULO").
dtExpedicao	Data da expedição do documento (formato: dd/mm/yyyy).
analfabeto	Identificação de assinatura do usuário no documento para leitura no OCR. Enviado de acordo com o tipo de documento (CNH; DNI; RG; ou CIN). True = documento não assinado; False: documento assinado.
dtExpedicaoFormatada	Data da expedição do documento (formato: yyyy-mm-dd).
dtNascimentoFormatada	Data de nascimento (formato: yyyy-mm-dd).
dtCriacao	Data e hora do envio do documento para análise (formato: yyyy-mm-dd hh:mm:ss).

biometriaDocumento

biometriaDocumento	Descrição
protocolo	Protocolo da Requisição da validação de biometria do documento.
facematch.codigo	Código da resposta do Facematch. Vide tabela abaixo.
facematch.causa	Mensagem referente ao código da resposta.
facematch.score	Pontuação da validação da foto-documento versus foto-usuário (selfie) enviada de 0.0 a 1.0, retornado apenas quando executado.
serpro.codigo	Código da resposta do Facematch. Vide tabela abaixo.
serpro.causa	Mensagem referente ao código da resposta.
serpro.score	Pontuação da validação da foto-documento versus base-Serpro de 0.0 a 1.0, retornado apenas quando executado.

facematch.codigo / serpro.codigo

facematch.codigo / serpro.codigo	Descrição
1	Erros gerais na validação da entrada, itens obrigatórios nulos ou com dados descritos inválidos.
2	Operador ativo não encontrado.
3	CPF inválido, formatação ou número.
4	CPF não cadastrado na base interna.
5	Arquivo da imagem com formato ou extensão não suportada.
101	Falha na configuração. Contate o Suporte.
102	Falha na configuração. Contate o Suporte.
103	Operador não possui acesso.
200	Validação Positiva. Biometria validada corretamente com o documento (faces similares).
300	Validação Negativa. Biometria não validada corretamente com o documento (similaridade baixa).
400	Face não encontrada no documento.
401	Falha na validação documento-biometria. Falha interna na validação do documento.
402	Documento ilegível. Falta de legibilidade/qualidade da imagem. Recomenda-se nova captura de imagem.
500	Erro interno.

documentos

documentos	Descrição
arquivo	Número serial, gerado a partir da ordem dos recebimentos dos arquivos que existem no ticket.
statusArquivo	Identificador de status de processamento; possui as seguintes codificações apresentadas na tabela "statusArquivo" a seguir.
arquivosProcessado.tipo	Tipo do documento identificado; possui as seguintes codificações apresentadas na tabela "tipo" a seguir.
arquivosProcessado.statusArquivoProcessado	Identificador de status do tipo de documento processado da imagem; possui as seguintes codificações apresentadas na tabela "statusArquivoProcessado" a seguir.

statusArquivo

statusArquivo	Descrição
7	Aguardando Identificação.
8	Falha Identificação.
9	Sucesso Identificação.
21	Cancelado.
22	Processado.

tipo

tipo	Descrição
1	RG[FRONT]
2	RG[BACK]
4	CNH[FRONT]
5	CNH[BACK]
6	DNI[FRONT]
7	DNI[BACK]
10	CNH2022[FRONT]
11	CNH2022[BACK]
13	CIN[FRONT]
14	CIN[BACK]

statusArquivoProcessado

statusArquivoProcessado	Descrição
10	Aguardando Leitura.
11	Falha Leitura.
12	Sucesso Leitura.
19	Processado.
20	Cancelado.

certifaceID

certifaceID	Descrição
codigo	Código referente ao resultado do processo. Vide tabela abaixo.
protocolo	Protocolo da transação CertifaceID.
score	Retorno da classe de risco.

codigo

codigo	Descrição
200	Processamento com sucesso.
401	Falha na qualidade da imagem da face.
402	Cadastro desabilitado.
501	Falha ao cadastrar.

score

Classe de Risco	Descrição
000	Sem informação
100	Baixíssimo Risco
200	Baixíssimo Risco
300	Baixo Risco
400	Médio Risco
500	Médio Risco
600	Médio Risco
700	Alto Risco
800	Alto Risco
900	Altíssimo Risco
1000	Altíssimo Risco

facecaptcha

facecaptcha	Descrição
causa	Indica a etapa em que o processo terminou.
codID	Código identificador do tipo da transação. Vide tabela abaixo.
protocolo	Protocolo da transação de Prova de Vida.
valid	True acesso positivo; False indica acesso negativo ou erro no processo de Prova de Vida.

codID

codID	Descrição
200.0	Prova de vida válida.
300.1	Prova de vida inválida.
300.2	Usuário bloqueado.

Fotos

Fotos	Descrição
facecaptcha.frontal	Imagem frontal em base64.
documento.descrição	Descrição da imagem do documento (face A; fac B).
documento.imagem	Imagem do documento em base64.

Response example

{
    "status": "Completo",
    "idExternoCliente": "4561645657446457-651A.SDRFEN",
    "dataCriacaoAppkey": "2021-07-30 21:44:16",
    "analiseDocumento": {
        "id": 180931,
        "idExterno": "90e9ef2f-b9a1-46c4-ac73-fca2fad755ae",
        "ticket": "da748b1a-abf0-4bff-b359-56b84f928ff3",
        "dtCriacao": "2021-07-30T18:45:05",
        "idCliente": "08d90425-ce53-474a-8f26-0ea646d3152a",
        "idSubcliente": "00000000-0000-0000-0000-000000000000",
        "idUsuario": "08d905c9-c8da-46dc-8682-e32437639638",
        "statusProcessamento": 4,
        "dtStatusProcessamento": "2021-07-30T18:45:37.5926823-03:00",
        "idTipoProcessamento": 2,
      	"score": 100, 
        "urlRetornoTicket": "https://hml.certiface.com.br/facecaptcha/service/captcha/document/processed",
        "dtRetornoTicket": "2021-07-30T18:45:38.4401041-03:00",
        "responseClientDadosOcrDTO": {
            "responseClientRGOcrDTO": {
                "estado": "SP",
                "documento": "RG",
                "dtExpedicao": "18/07/2019",
                "dtExpedicaoFormatada": "2019-07-18",
                "nrRg": "99.999.999-9",
                "nome": "NOME SOBRENOME",
                "filiacao": "NOME DO PAI\nNOME DA MAE",
                "nomePai": "NOME DO PAI",
                "nomeMae": "NOME DA MAE",
                "dtNascimento": "27/05/1984",
                "dtNascimentoFormatada": "1984-05-27",
                "cpf": "999999999/99",
                "naturalidade": "SAO PAULO - SP",
                "nomenclatura": "ESTADO DE SAO PAULO\nSECRETARIA DA SEGURANÇA PÚBLICA",
                "dtCriacao": "2021-07-30 21:45:20" ,
                "flAnalfabeto": "True"  
            },
            "ResponseClientCNHOcrDTO": {
                "estado": "SP",
                "documento": "CNH",
                "nome": "NOME SOBRENOME",
                "docOrigem": "99999999 XX/XX",
                "documentoOrigem": "99999999",
                "emissorOrigem": "SSP",
                "ufOrigem": "SP",
                "cpf": "XXX.XXX.XXX-XX",
                "dtNascimento": "20/01/1990",
                "dtNascimentoFormatada": "1990-01-20",
                "filiacao": "NOME DO PAI\nNOME DA MAE",
                "nomePai": "NOME DO PAI",
                "nomeMae": "NOME DA MAE",
                "permissao": "NULL",
                "acc": "NULL",
                "categoria": "XXXXX",
                "numeroRegistro": "99999999999",
                "validade": "20/03/1990",
                "primeiraHabilitacao": "20/01/1990",
                "local": "SÃO PAULO, SP",
                "dtExpedicao": "20/01/1990",
                "dtExpedicaoFormatada": "1990-01-20",
                "codSeguranca": "9999999999",
                "espelho": "9999999999",
                "estadoNome": "ESTADO",
                "renach": "XX999999999",
                "dtCriacao": "1990-01-20 21:45:20" ,               
            },
            "ResponseClientDNIOcrDTO": {
                "estado": "SP",
                "nomenclatura": "ESTADO DE SAO PAULO\nSECRETARIA DA SEGURANÇA PÚBLICA",
                "naturalidade": "SAO PAULO - SP",
                "filiacao": "NOME DO PAI\nNOME DA MAE",
                "nomePai": "NOME DO PAI",
                "nomeMae": "NOME DA MAE",
                "dtNascimento": "20/01/1990",
                "dtNascimentoFormatada": "1990-01-20",
                "nome": "NOME SOBRENOME",
                "observacaoFront": "XXXXXXXXXXXXXXX",
                "outroRG": "99.999.999-9",
                "orgao": "XXXXXX-XX",
                "fator": "XXX",
                "registroCivil": "CERTIDÃO DE CASAMENTO TESTE",
                "cnh": "99999999999",
                "cns": "99999999999",
                "cpf": "XXX.XXX.XXX-XX",
                "ctps": "XXXXXXXX",
                "serieCTPS": "XXX",
                "ufctps": "XX",
                "dni": "XXXXXXXXXXXXXXX",
                "tituloEleitor": "XXXX.XXXX.XXXX",
                "dtExpedicao": "20/01/1990",
                "dtExpedicaoFormatada": "1990-01-20",
                "local": "P.:49",
                "certMilitar": "XXXXXXXXXXXXXX",
                "nomeSocial": "NOME SOCIAL",
                "pis": "XXXXXXXXXX-X",
                "profissional": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                "rg": "99.999.999-9",
                "dtCriacao": "1990-01-20 21:45:20" ,
                "flAnalfabeto": "True"  
            },
            "ResponseClientCINOcrDTO": {
                "documento": "CIN",
                "nomenclatura": "REPUBLICA FEDERATIVA DO BRASIL",
                "nome": "NOME SOBRENOME",
                "cpf": "XXX.XXX.XXX-XX",
                "sexo": "F",
                "dtNascimento": "24/09/1956",
                "nacionalidade": "BRA", 
                "naturalidade":"ALEGRETE/RS",
                "dtValidade": "INDETERMINADA",       
                "nrEspelho":"000000000",       
                "posto": "00050000",       
                "filiacao": "PAI\nMAE",       
                "orgaoEmissor": "INSTITUTO GERAL DE TESTE",       
                "local": "PORTO ALEGRE",       
                "dtExpedicao": "06/04/2023",       
                "analfabeto": false,       
                "dtExpedicaoFormatada": "2023-04-06",       
                "dtNascimentoFormatada": "1956-09-24",       
                "dtCriacao": "2023-08-25 12:30:35"
             }
        },
        "biometriaDocumento": {
            "protocolo": "202100045840",
            "facematch": {
                "codigo": "200",
                "causa": "Validacao positiva",
                "score": "0.56069"
            },
            "serpro": {
                "codigo": "200",
                "causa": "Validacao positiva",
                "score": "0.9667247"
            }
        },
        "documentos": [
            {
                "arquivo": 2,
                "statusArquivo": 22,
                "arquivosProcessado": [
                    {
                        "tipo": 2,
                        "statusArquivoProcessado": 19
                    }
                ]
            },
            {
                "arquivo": 1,
                "statusArquivo": 22,
                "arquivosProcessado": [
                    {
                        "tipo": 1,
                        "statusArquivoProcessado": 19
                    }
                ]
            }
        ]
    },
    "certifaceID": {
        "codigo": 203,
        "protocolo": 202101420655,
        "score": 400
    },    
    "facecaptcha": {
        "causa": "CERTIFACE",
        "codID": 1.2,
        "protocolo": 202100094411,
        "validado": true
    },
    "fotos": {
        "facecaptcha": {
            "frontal": "base64"
        },
        "documento": [
            {
                "descricao": "FACE A",
                "imagem": "base64"
            },
            {
                "descricao": "FACE B",
                "imagem": "base64"
            }
        ]
    }
}

HTTP Status Code

Status Code	Descrição
200	OK.
400	Requisição mal formada ou os dados não foram informados corretamente.
401	Não autorizado ou credenciais expiradas.
404	Appkey não encontrada ou não realizada a Prova de Vida.
500	Erro genérico.

📘
É bom saber!

Exemplo do retorno da Certiface ID completa. O OCR pode ser de quatro tipos: RG, CNH, DNI ou CIN quando enviado qualquer um desses tipos, os outros objetos referente a esse tipo serão suprimidos;

O serviço do Facematch e Serpro podem ser habilitados ou desabilitado. Quando um dos serviços estiver desabilitado o objeto referente a esse serviço será suprimido do retorno.

Outros Retornos

Nome Inválido

{
    "status": "ERR",
    "resultado": "ERR",
    "protocolo": "202001138311",
    "msg": "NOME"
}

CPF Inválido

{
    "status": "ERR",
    "resultado": "ERR",
    "protocolo": "202001138315",
    "msg": "INVALID CPF"
}

Nascimento Inválido

{
    "status": "ERR",
    "resultado": "ERR",
    "protocolo": "202001138317",
    "msg": "INVALID DATE"
}

8. Status Updater

Este método retorna notificações de suspeita de fraude baseado na captura da movimentação do status do usuário, no Bureu da Oiti.

Detalhes importantes:

A notificação ocorre a cada alteração do status do usuário no Bureau de Faces.
Autenticação: Whitelist IP.
Utilizamos o método Webhook para gerar as notificações.
O processo ocorre em até 10 dias a partir da transação.

📘
É bom saber!
O cliente deve criar a API para recebimento do Webhook e o link deve ser compartilhado com a Oiti para realizar a integração.

Body Params

Body	Descrição
protocolo	Protocolo da Transação
cpf	CPF do usuário que realizará a transação
novoStatus	Novo status da suspeita de fraude.
descricao	Descrição do novo status da notificação.

Request example

{
  "protocolo": "202200998977",
  "cpf": 00011122233,
  "novoStatus": "RES" ,
  "descricao": "Suspeita Fraude"
}