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
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
Ć 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"
}
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.
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
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.
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".
Imagem sem documento, pode ser enviado outra imagem utilizando a mesma appkey. (alerta de documento não encontrado, voltar para captura de documentos).
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; CRNM e Passaporte).
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.
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]
15
CRNM[FRONT]
16
CRNM[BACK]
17
PASSPORT[FRONT]
18
PASSPORT[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.
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.