🚧 Guia de Integração API v1.3

🚧

Atualizaremos nosso domĆ­nio

GostarĆ­amos de informar que estamos substituindo o domĆ­nio comercial.certiface.com.br pelo novo domĆ­nio hml.certiface.com.br.

šŸ“… Data inicial para atualização: 10/06/2024
āš ļø Prazo limite para atualização: 10/12/2024


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:

  1. Credencial
  2. Appkey
  3. Liveness 2D
    3.1. Challenge
    3.2. Captcha
  4. Liveness 3D
    4.1. Facetec
    4.2. 3D Session
    4.3. 3D Liveness
    4.4. Iproov
    4.5. 3D Session
    4.6. 3D Liveness
  5. Document
  6. Webhook
  7. Result
  8. 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
HeadersDescrição
Content-Typeapplication/x-www-form-urlencoded

Body Params

ParâmetroDescrição
userLogin do operador do Certiface.
passSenha criptografada em MD5.

Request example

user: login
pass: 3355a3973f54a008c642ee94fd0313d7

Response

HeadersDescrição
Content-Typeapplication/json

Body Params

BodyDescrição
tokenToken de autorização para gerar Appkeys.
expiresHorÔrio de expiração do token UTC-0.

Responses

Status CodeDescrição
200OK.
400Requisição mal formada ou os dados não foram informados corretamente.
401NĆ£o autorizado ou credenciais expiradas.
500Erro genƩrico.

Response example

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

Ɖ bom saber!

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

  2. 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
HeadersDescrição
Content-Typeapplication/x-www-form-urlencoded

Body Params

ParâmetroDescrição
userLogin do operador que gerou as credenciais de acesso.
tokenJSON gerado na resposta do mƩtodo /credencial.
cpfCPF do usuƔrio que realizarƔ a prova de vida.
nomeNome e sobrenome do usuƔrio que realizarƔ a prova de vida.
nascimentoData de nascimento do usuƔrio, no formato dd/mm/yyyy .
idExternoClienteCampo 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

HeadersDescrição
Content-Typeapplication/json

Body Params

BodyDescrição
appkeyChave de acesso para validação biométrica com prova de vida.

Responses

Status CodeDescrição
200OK.
401NĆ£o autorizado ou credenciais expiradas.
422Requisição mal formada ou dados não foram informados corretamente.
500Erro 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
HeadersDescrição
Content-Typeapplication/x-www-form-urlencoded

Body Params

BodyDescrição
appkeyChave de acesso para validação biométrica com prova de vida.

Request example

appkey: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EaiHfZC9VdEVBNiPqfNVnPzDill2E5YyYdSpS38iw

Responses

HeadersDescrição
Content-Typeapplication/json

Body Params

BodyDescrição
chkeyChave da requisição.
snapFrequenceInMillisTempo para cada foto em milissegundos.
snapNumberQuantidade de fotos por Desafio.
totalTimeTempo total de todos os desafios (seg).
numberOfChallengesNĆŗmero de Desafios.
challengesDesafios da requisição.

Chalenges

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

ChallengesDescrição
mensagemImagem do texto do desafio em base64.
tempoEmSegundosTempo do desafio em segundos.
tipoFace.codigoCódigo do tipo do desafio.
tipoFace.imagemImagem do emoji do desafio em base64.

Responses

Status CodeDescrição
200OK
401NĆ£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
HeadersDescrição
Content-Typeapplication**/**x-www-form-urlencoded

Body Params

BodyDescrição
appkeyAppkey gerada pelo mƩtodo "/appkey".
chkeyChave do desafio que estĆ” no body do "/challenge".
imagesImagens dos desafios, devidamente formatadas.

Request example

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

Response

HeadersDescrição
Content-Typeapplication/json

Response Body

BodyDescrição
validIndica Acesso Negativo ou Acesso Positivo (true or false).
codIDCódigo identificador do tipo da transação (detalhes mais abaixo).
causeIndica por qual motivo o processo finalizou sem sucesso (Biometria ou Prova de Vida).
protocolProtocolo da transação de prova de vida. Ex: "201900039067".

codID

codIDDescrição
200.0Prova de vida vƔlida.
300.1Prova de vida invƔlida.
300.2UsuƔrio bloqueado.

Responses

Status CodeDescrição
200OK
401NĆ£o autorizado ou credenciais expiradas.
500Erro 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
HeadersDescrição
Content-Typeapplication/json

Body Params

BodyDescrição
appkeyChave de acesso para validação.
userAgentString do userAgent fornecida pelo SDK 3D Liveness , opcional.

Request example

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

Response

HeadersDescrição
Content-Typeapplication/json

Response Body

BodyDescrição
sessionTokenToken de sessão gerado pelo API do 3D Liveness para habilitar a validação biométrica.

Responses

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

Response example

{  
		"sessionToken" : "AJyC3MiVXTgxC8bj3CJFopEPQyrFG8smzdd71ohQ8kTCbDAgRYyd6Uz"  
}
šŸ“˜

Ɖ bom saber!

  1. O conteĆŗdo do Body estarĆ” criptografado;
  2. Os métodos para a execução de cada módulo são exclusivos para o fluxo ao qual pertence;
  3. 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
HeadersDescrição
Content-Typeapplication/json

Body Params

BodyDescrição
appkeyChave de acesso para validação.
userAgentString do userAgent fornecida pelo SDK 3D Liveness.
faceScanBlob do mapa tridimensional da face, conforme fornecido pelo SDK 3D Liveness.
auditTrailImageImagem frontal do usuƔrio fornecida pelo SDK 3D Liveness, encodada e criptografada.
lowQualityAuditTrailImageImagem de baixa qualidade do usuƔrio fornecida pelo SDK 3D Liveness, encodada e criptografada.
sessionIdO 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!

  1. As URLs podem ser atualizadas de acordo as propriedades internas.

Response

HeadersDescrição
Content-Typeapplication/json

Response Body

BodyDescrição
validIndica Acesso Negativo ou Acesso Positivo (true or false).
codIDCódigo identificador do tipo da transação (detalhes mais abaixo).
causeIndica por qual motivo o processo finalizou sem sucesso (Biometria ou Prova de Vida).
protocolProtocolo da transação de prova de vida. Ex: "201900039067".
scanResultBlobƉ um blob criptografado para uso do SDK 3D Liveness para tratar o retorno.

codID

codIDDescrição
200.0Prova de vida vƔlida.
300.1Prova de vida invƔlida.
300.2UsuƔrio bloqueado.

Responses

Status CodeDescrição
200OK.
401NĆ£o autorizado ou credenciais expiradas.
500Erro 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
HeadersDescrição
Content-Typeapplication/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.

BodyDescrição
appkeyChave de acesso para validação.
userAgentString 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"  
}
HeadersDescrição
Content-Typeapplication/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.

BodyDescrição
isContingencyIndicador de contingĆŖncia da API
tokenToken de sessão gerado pelo API do 3D Liveness para habilitar a validação biométrica.
vendorNome do provedor de serviƧo do Liveness 3D
urlURL 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 CodeDescrição
200OK
401NĆ£o autorizado ou credenciais expiradas.
500Erro 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
HeadersDescrição
Content-Typeapplication/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.

BodyDescrição
appkeyChave de acesso para validação.
sessionTokenToken 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.

HeadersDescrição
Content-Typeapplication/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.

BodyDescrição
validIndica Acesso Negativo ou Acesso Positivo (true or false).
codIDCódigo identificador do tipo da transação (detalhes mais abaixo).
causeIndica por qual motivo o processo finalizou sem sucesso (Biometria ou Prova de Vida).
protocolProtocolo 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".

codIDDescrição
200.0Prova de vida vƔlida.
300.1Prova de vida invƔlida.
300.2UsuƔ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çãoStatus 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
HeadersDescrição
Content-Typeapplication/json

Body Params

BodyDescrição
appkeyAppkey gerada pelo mƩtodo "/appkey".
imagesArray 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

HeadersDescrição
Content-Typeapplication/json

Response Body

BodyDescrição
appkeyAppkey gerada pelo mƩtodo "/appkey".
idIdentificação interna.

Responses

Status CodeDescrição
200OK
400Imagem sem documento, pode ser enviado outra imagem utilizando a mesma appkey. (alerta de documento não encontrado, voltar para captura de documentos).
401NĆ£o autorizado ou credenciais expiradas.
500Erro 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/*/
HeadersDescrição
Content-Typeapplication/json

Body Params

BodyDescrição
StatusComportamento esperado do status: "Completo". ou "Error"
AppkeyAppkey 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
HeadersDescrição
Content-Typeapplication/x-www-form-urlencoded

Body Params

BodyDescrição
appkeyAppkey gerada pelo mƩtodo "/appkey".

Request example

{
  appkey: "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EiPqfNVnPzDill2E5YyYdSpS38iw"
}

Response

HeadersDescrição
Content-Typeapplication/json

Response Body

BodyDescrição
statusStatus do processamento da jornada: "Completo"; "Em processamento"; "NĆ£o processado"; "Erro".
idExternoClienteCampo de referência da identificação da proposta do cliente, conforme enviado na etapa 2. Appkey.
dataCriacaoAppkeyData em que foi gerada a appkey pelo mƩtodo do passo 2.
analiseDocumentoAnƔlise do documento. (OCR e Documentoscopia). Conforme tabela a seguir.
certifaceIDRetorno do objeto CertifaceID. (Bureau de Faces). Ver tabela certifaceID abaixo.
facecaptchaRetorno do objeto Facecaptcha. (Prova de Vida). Ver tabela facecaptcha abaixo.
fotosRetorno do objeto das fotos enviadas. (Prova de Vida e Documentos).

analiseDocumento

analiseDocumentoDescrição
idIdentificação interna.
idExternoCódigo de identificação interna do cliente.
ticketTicket do(s) documento(s) em processamento.
dtCriacaoData de criação do ticket.
idClienteCódigo de identificação do cliente no sistema de Documentoscopia.
idSubclienteCódigo de identificação do subcliente no sistema de Documentoscopia.
idUsuarioCódigo de identificação do usuÔrio.
statusProcessamentoIdentificador de status de processamento. Vide tabela abaixo.
dtStatusProcessamentoData e hora do status de processamento finalizado.
idTipoProcessamentoCódigo do tipo de processamento realizado. Código interno.
scoreValor 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.
urlRetornoTicketEndereƧo web onde serƔ postado o resultado do processamento.
dtRetornoTicketData e hora de retorno do ticket.
responseClientDadosOcrDTOTodos os dados extraídos do documento; tendo ou não duas partes, a primeira sendo RG, a segunda CNH.
biometriaCertifaceResultado do Facematch do documento.
documentosLista de todos os status dos documentos processados pela API.

statusProcessamento

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

responseClientDadosOcrDTO

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

responseClientRGOcrDTO

responseClientRGOcrDTODescrição
estadoEstado onde foi emitido o documento.
documentoIdentificação do tipo do documento.
dtExpedicaoData da expedição do documento (formato: dd/mm/yyyy).
dtExpedicaoFormatadaData da expedição do documento (formato: yyyy-mm-dd).
dtNascimentoFormatadaData de nascimento (formato: yyyy-mm-dd).
nrRgNĆŗmero do documento RG.
nomeNome e sobrenome do titular do documento.
filiacaoNome do pai e nome da mãe.
nomePaiNome do Pai.
nomeMaeNome da MĆ£e.
docOrigemOrigem do Documento.
dtNascimentoData de nascimento (formato: dd/mm/aaaa).
cpfNĆŗmero do CPF (formato: "999999999/99").
naturalidadeNaturalidade.
nomenclaturaNome do órgão emissor.
dtCriacaoData de criação do processo (formato: "yyyy-mm-dd hh:mm:ss").
flAnalfabetoIdentificaçã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

ResponseClientCNHOcrDTODescrição
estadoSigla do estado da emissão do documento CNH.
estadoNomeNome do estado da emissão do documento CNH.
documentoTipo do documento (CNH).
nomeNome e sobrenome do titular do documento.
docOrigemDados do documento de origem: número de identificação e emissor de origem.
documentoOrigemNúmero de identificação do documento de origem.
emissorOrigemEmissor de Origem.
ufOrigemUF de Origem.
cpfNĆŗmero do CPF (formato "999.999.999-99").
dtNascimentoData de Nascimento (formato: dd/mm/aaaa).
dtNascimentoFormatadaData de Nascimento (formato: yyyy-mm-aa).
filiacaoNome do pai e nome da mãe.
nomePaiNome do Pai.
nomeMaeNome da MĆ£e.
permissao"PERMISSƃO" ou NULL.
accAutorização para conduzir ciclomotores.
categoriaCategoria ("ABCDE" ou individual).
numeroRegistroNĆŗmero do registro do documento.
validadeData de validade do documento (formato: "dd/mm/aaaa").
primeiraHabilitacaoData da primeira habilitação (formato: "dd/mm/aaaa").
localCidade e estado onde foi emitido o documento ("SƃO PAULO, SP").
dtExpedicaoData da expedição do documento (formato: "dd/mm/aaaa").
dtExpedicaoFormatadaData da expedição do documento (formato: yyyy-mm-dd).
codSegurancaCódigo de segurança.
espelhoNĆŗmero de controle do documento (papel documento).
renachNumeração do Renach.
dtCriacaoData de criação do processo (formato: "yyyy-mm-dd hh:mm:ss").

ResponseClientDNIOcrDTO

ResponseClientDNIOcrDTODescrição
estadoEstado de emissão do Documento Nacional de Identidade (DNI).
nomenclaturaNome do orgão emissor.
naturalidadeNaturalidade.
filiacaoNome do pai e nome da mãe.
nomePaiNome do pai.
nomeMaeNome da mãe.
dtNascimentoData de Nascimento (formato: dd/mm/aaaa).
dtNascimentoFormatadaData de Nascimento (formato: yyyy-mm-aa).
nomeNome e sobrenome do titular do documento.
observacaoFrontObservação.
outroRGNĆŗmero de outro RG caso possua.
orgaoƓrgĆ£o Emissor.
fatorTipo sanguĆ­neo com fator Rh.
registroCivilInformação de origem do Registro civil.
cnhNĆŗmero do CNH.
cnsCartão Nacional de Saúde.
cpfNĆŗmero do CPF.
ctpsNĆŗmero da Carteira de Trabalho PrevidĆŖncia Social.
serieCTPSSérie da Carteira de Trabalho Previdência Social.
ufctpsUF de emissão da Carteira de Trabalho Previdência Social.
dniNĆŗmero do DNI.
tituloEleitorNĆŗmero do TĆ­tulo de Eleitor.
dtExpedicaoData da expedição do DNI (formato: "dd/mm/aaaa").
dtExpedicaoFormatadaData da expedição do DNI (formato: yyyy-mm-dd).
localPosto onde o DNI foi emitido.
certMilitarNúmero da Certidão Militar.
nomeSocialNome Social.
pisNĆŗmero do PIS.
profissionalIdentidade Profissional ou CIP.
rgNĆŗmero do RG.
dtCriacaoData de criação do processo (formato: "yyyy-mm-dd hh:mm:ss").
flAnalfabetoIdentificaçã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

ResponseClientCINOcrDTODescrição
documentoTipo do documento (neste caso, CIN).
estadoEstado de emissão do documento CIN.
nomenclaturaNome do orgão emissor.
nomeNome e sobrenome do titular do documento.
cpfNĆŗmero do CPF.
sexoGĆŖnero do titular do documento.
dtNascimentoData de Nascimento (formato: dd/mm/yyyy).
nacionalidadeNacionalidade.
naturalidadeNaturalidade.
dtValidadeData validade documento (sem definição de formato).
postoLocal de emissão.
filiacaoNome do pai e nome da mãe.
nomePaiNome do Pai.
nomeMaeNome da MĆ£e.
orgaoEmissorƓrgĆ£o Emissor.
localEstado onde foi emitido o documento ("SƃO PAULO").
dtExpedicaoData da expedição do documento (formato: dd/mm/yyyy).
analfabetoIdentificaçã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.
dtExpedicaoFormatadaData da expedição do documento (formato: yyyy-mm-dd).
dtNascimentoFormatadaData de nascimento (formato: yyyy-mm-dd).
dtCriacaoData e hora do envio do documento para anƔlise (formato: yyyy-mm-dd hh:mm:ss).

biometriaDocumento

biometriaDocumentoDescrição
protocoloProtocolo da Requisição da validação de biometria do documento.
facematch.codigoCódigo da resposta do Facematch. Vide tabela abaixo.
facematch.causaMensagem referente ao código da resposta.
facematch.scorePontuação da validação da foto-documento versus foto-usuÔrio (selfie) enviada de 0.0 a 1.0, retornado apenas quando executado.
serpro.codigoCódigo da resposta do Facematch. Vide tabela abaixo.
serpro.causaMensagem referente ao código da resposta.
serpro.scorePontuaçã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.codigoDescrição
1Erros gerais na validação da entrada, itens obrigatórios nulos ou com dados descritos invÔlidos.
2Operador ativo não encontrado.
3CPF invÔlido, formatação ou número.
4CPF não cadastrado na base interna.
5Arquivo da imagem com formato ou extensão não suportada.
101Falha na configuração. Contate o Suporte.
102Falha na configuração. Contate o Suporte.
103Operador não possui acesso.
200Validação Positiva. Biometria validada corretamente com o documento (faces similares).
300Validação Negativa. Biometria não validada corretamente com o documento (similaridade baixa).
400Face não encontrada no documento.
401Falha na validação documento-biometria. Falha interna na validação do documento.
402Documento ilegĆ­vel. Falta de legibilidade/qualidade da imagem. Recomenda-se nova captura de imagem.
500Erro interno.

documentos

documentosDescrição
arquivoNĆŗmero serial, gerado a partir da ordem dos recebimentos dos arquivos que existem no ticket.
statusArquivoIdentificador de status de processamento; possui as seguintes codificaƧƵes apresentadas na tabela "statusArquivo" a seguir.
arquivosProcessado.tipoTipo do documento identificado; possui as seguintes codificaƧƵes apresentadas na tabela "tipo" a seguir.
arquivosProcessado.statusArquivoProcessadoIdentificador de status do tipo de documento processado da imagem; possui as seguintes codificaƧƵes apresentadas na tabela "statusArquivoProcessado" a seguir.

statusArquivo

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

tipo

tipoDescrição
1RG[FRONT]
2RG[BACK]
4CNH[FRONT]
5CNH[BACK]
6DNI[FRONT]
7DNI[BACK]
10CNH2022[FRONT]
11CNH2022[BACK]
13CIN[FRONT]
14CIN[BACK]
15CRNM[FRONT]
16CRNM[BACK]
17PASSPORT[FRONT]
18PASSPORT[BACK]

statusArquivoProcessado

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

certifaceID

certifaceIDDescrição
codigoCódigo referente ao resultado do processo. Vide tabela abaixo.
protocoloProtocolo da transação CertifaceID.
scoreRetorno da classe de risco.

codigo

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

score

Classe de RiscoDescrição
000Sem informação
100BaixĆ­ssimo Risco
200BaixĆ­ssimo Risco
300Baixo Risco
400MƩdio Risco
500MƩdio Risco
600MƩdio Risco
700Alto Risco
800Alto Risco
900AltĆ­ssimo Risco
1000AltĆ­ssimo Risco

facecaptcha

facecaptchaDescrição
causaIndica a etapa em que o processo terminou.
codIDCódigo identificador do tipo da transação. Vide tabela abaixo.
protocoloProtocolo da transação de Prova de Vida.
validTrue acesso positivo; False indica acesso negativo ou erro no processo de Prova de Vida.

codID

codIDDescrição
200.0Prova de vida vƔlida.
300.1Prova de vida invƔlida.
300.2UsuƔrio bloqueado.

Fotos

FotosDescrição
facecaptcha.frontalImagem frontal em base64.
documento.descriçãoDescrição da imagem do documento (face A; fac B).
documento.imagemImagem 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 CodeDescrição
200OK.
400Requisição mal formada ou os dados não foram informados corretamente.
401NĆ£o autorizado ou credenciais expiradas.
404Appkey não encontrada ou não realizada a Prova de Vida.
500Erro genƩrico.
šŸ“˜

Ɖ bom saber!

  1. 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;

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

BodyDescrição
protocoloProtocolo da Transação
cpfCPF do usuÔrio que realizarÔ a transação
novoStatusNovo status da suspeita de fraude.
descricaoDescrição do novo status da notificação.

Request example

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

GostarĆ­amos de informar que estamos substituindo o domĆ­nio comercial.certiface.com.br pelo novo domĆ­nio hml.certiface.com.br.

šŸ“… Data inicial para atualização: 10/06/2024
āš ļø Prazo limite para atualização: 10/12/2024