🚧
Atualizações
Data de atualização (14/07/2022)

Edição do campo expires no body do Response da etapa 1. Credencial.

Data de atualização (31/05/2022)

Inserção do campo Flanalfabeto no body do Response Documentos da etapa 7. Result; JSON atualizado.

Data de atualização (24/05/2022)

Inserção do parâmetro IdExternoCliente no Request da etapa 2. Appkey; YAML atualizado.

Inserção do campo IdExternoCliente no body do Response da etapa 7. Result; JSON atualizado.

Data de atualização (25/04/2022)

A Etapa 3.2 3D Session recebeu um novo método: Initialize. Agora, esta etapa conta com dois métodos: 3.2.1 Initialize e 3.2.2 Session Token;

Alteração no método 3.2.2 Session Token, cujo retorno agora é criptografado;

Alteração no método 4.2 3D Liveness, no body, campos: auditTrailImage e lowQualityAuditTrailImage que, agora, devem ser enviados criptografados.

Data de atualização (22/04/2022)

Inserção do quadro facematch.codigo na etapa 7. Result.

Data de atualização (19/08/2022)
-Atualização dos códigos de retorno da Serpro serpro.codigo na etapa 7. Result.

:: Passo a passo

A Certiface ID possui 7 passos que segue:

Credencial
Appkey
Preparation: Challenge / 3D Session
Validation: Captcha / 3D Liveness
Document
Webhook
Result

1. Credencial

Trata-se do primeiro método que deve ser acessado para gerar as credenciais, utilizadas para gerar uma Appkey.
Devem ser informados login e senha de acesso à integração. O serviço deve retornar as credenciais de acesso ao Certiface ID.

Request

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

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

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

Exemplo de Body

user: login
pass: 3355a3973f54a008c642ee94fd0313d7

Response

Headers	Descrição
Content-Type	application/json

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

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.

Exemplo de Body

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

📘
Notas

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çohttps://comercial.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 da Certiface ID uma Appkey deve ser criada, informando: os dados do cliente, o login do operador e as credenciais geradas no passo anterior. O Certiface deve gerar 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://comercial.certiface.com.br/facecaptcha/service/captcha/appkey

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

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.

Exemplo de Body

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

Response

Headers	Descrição
Content-Type	application/json

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

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.

Exemplo de Body

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

📘
Nota
A appkey gerada por este método possui tempo de expiração configurável. O padrão é de5 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. Preparation

Abaixo, estão apresentados dois métodos: Challenge e 3D Session. Nesta fase deve-se escolher um método a ser seguido.

3.1 Challenge

Este método cria os desafios que o usuário deverá realizar com a "appkey" gerada no método 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://comercial.certiface.com.br/facecaptcha/service/captcha/challenge

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

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

Exemplo de Body

appkey: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EaiHfZC9VdEVBNiPqfNVnPzDill2E5YyYdSpS38iw

Response

Headers	Descrição
Content-Type	application/json

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.

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.

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

Exemplo de Body

{
    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"
        }
    }]
}

📘
Nota
O conteúdo do Body estará criptografado.
Exemplo: YtyB6DGov4NNVGskJnxwKtA4QKmQnZDmPxFJSSfC...JZbNyTWD171A==

3.2 3D Session

Para esta etapa deve-se executar dois métodos: Initialize e Session Token.
Os dois métodos estão descritos a seguir.

3.2.1 Initialize

Esse método recebe a appkey gerada no passo 2 e retorna as chaves para inicializar o SDK Liveness 3D.

Request

POST https://comercial.certiface.com.br/facecaptcha/service/captcha/3d/initialize

Headers	Descrição
Content-Type	application/json

Body	Descrição
appkey	Chave de acesso para validação.
platform	São dois valores permitidos: 'web' para o SDK 'web'; 'mobile' para o SDK 'mobile'.

{  
  "appkey" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EaiHfZC9VdEVBNiPqfNVnPzDill2E5YyYdSpS38iw",  
 "platform" : "web ou mobile"  
}

Response

Headers	Descrição
Content-Type	application/json

Body	Descrição
productionKey	Chave para liberação do SDK, de acordo com a plataforma (web ou mobile).

Status Code	Descrição
200	OK
401	Não autorizado ou credenciais expiradas.
500	Erro interno no retorno da chave.

Exemplo de Body

{
  "productionKey": "{\"domains\":\"domain.com\",\"expiryDate\":\"2002-20-02\",\"key\":\"234567drctvgybunhjimkftvgybhu\"}" 
}

📘
Nota
O conteúdo do Body estará criptografado.

3.2.2 Session Token

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 à appkey gerada no método do passo 2.

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

Request

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

Headers	Descrição
Content-Type	application/json

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

Exemplo de Body

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

Response

Headers	Descrição
Content-Type	application/json

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

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

Exemplo de Body

{  
		"sessionToken" : "AJyC3MiVXTgxC8bj3CJFopEPQyrFG8smzdd71ohQ8kTCbDAgRYyd6Uz"  
}

📘
Nota

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

Estão apresentados abaixo dois métodos: Captcha e 3D Liveness. Nesta fase deve-se escolher um método a ser seguido.

4.1 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://comercial.certiface.com.br/facecaptcha/service/captcha

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

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.

Exemplo de Body

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

Response

Headers	Descrição
Content-Type	application/json

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	Descrição
1.1	Cadastro com sucesso.
1.2	Certificação positiva. (Conhecido = True)
200.1	Cadastro com alertas.
200.2	Certificação negativa. (Conhecido = True)
200.3	Certificação positiva. (Conhecido = False)
200.4	Certificação negativa. (Conhecido = False)
200.5	Validação na Base da Serpro
300.1	Prova de vida inválida.
300.2	Usuário foi bloqueado.

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

Exemplo de Body

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

4.2 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://comercial.certiface.com.br/facecaptcha/service/captcha/3d/liveness

Headers	Descrição
Content-Type	application/json

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.

Exemplo de 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"
}

📘
Nota

As URLs podem ser atualizadas de acordo as propriedades internas.

Response

Headers	Descrição
Content-Type	application/json

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	Descrição
1.1	Cadastro com sucesso.
1.2	Certificação positiva. (Conhecido = True)
200.1	Cadastro com alertas.
200.2	Certificação negativa. (Conhecido = True)
200.3	Certificação positiva. (Conhecido = False)
200.4	Certificação negativa. (Conhecido = False)
200.5	Validação na Base da Serpro
300.1	Prova de vida inválida.
300.2	Usuário foi bloqueado.

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

Exemplo de Body

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

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://comercial.certiface.com.br/facecaptcha/service/captcha/document

Headers	Descrição
Content-Type	application/json

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

Exemplo de Body

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

Response

Headers	Descrição
Content-Type	application/json

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

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.

Exemplo de Body

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

📘
Nota
Em todo retornostatus 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 de 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	Descrição
Status	Comportamento esperado do status: "Completo" ou "Error"
Appkey	Appkey gerada pelo método "/appkey".

Exemplo de Body 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); pode ser chamado a qualquer momento, de preferência após o recebimento da finalização via Webhook.

Para realizar a chamada, é necessário a Appkey gerada no item 2.

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

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

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

Exemplo de Body

{
  appkey: "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXJ0aWZhY2UifQ.u6EiPqfNVnPzDill2E5YyYdSpS38iw"
}

Response

Headers	Descrição
Content-Type	application/json

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	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	Descrição
2	Aguardando Processamento.
3	Em Processamento.
4	Processado.
5	Cancelado.
6	Falha no Processamento.
70	Upload Incorreto.

responseClientDadosOcrDTO	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 (CNH; DNI; ou RG). True = documento não assinado; False: documento assinado.

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").
flAnalfabeto	Identificação de assinatura do usuário no documento para leitura no OCR. Enviado de acordo com o tipo de documento (CNH; DNI; ou RG). True = documento não assinado; False: documento assinado.

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.
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 (CNH; DNI; ou RG). True = documento não assinado; False: documento assinado.

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	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	FaceMatch Positiva.
300	FaceMatch Negativa.
400	Face não encontrada no documento.
401	Falha na validação documento-biometria.
402	Documento ilegível.
500	Erro interno.

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	Descrição
7	Aguardando Identificação.
8	Falha Identificação.
9	Sucesso Identificação.
21	Cancelado.
22	Processado.

tipo	Descrição
1	RG[FRONT]
2	RG[BACK]
3	CNH
4	CNH[FRONT]
5	CNH[BACK]
6	DNI[FRONT]
7	DNI[BACK]

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

certifaceID	Descrição
aprovado	True indica que a transação foi aprovada com baixa possibilidade de fraude; False indica alta possibilidade de fraude ou erro.
codigo	Código referente ao resultado do processo. Vide tabela abaixo.
conhecido	True indica que o usuário já possui cadastro sólido na base; False indica cadastro recente ou com baixa confiança.
protocolo	Protocolo da transação CertifaceID.
scoreBiometrico	Score de biometria. Float de -100.0 à 100.0.

codigo	Descrição
201	Cadastro com sucesso.
202	Cadastro com pendência.
212	Cadastro com pendência e similares restritos.
203	Certificação positiva.
204	Certificação negativa.
205	Validação na Base da Serpro
401	Falha na qualidade da imagem da face.
402	Cadastro desabilitado.
501	Falha ao cadastrar.

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	Descrição
1.1	Cadastro com sucesso.
1.2	Certificação positiva.
200.1	Cadastro com alertas.
200.2	Certificação negativa.
200.5	Validação na Base da Serpro
300.1	Prova de vida inválida.
300.2	Usuário foi bloqueado.

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.

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.

Exemplo de Body

{
    "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://comercial.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" ,
                "flAnalfabeto": "True" 
            },
            "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": "CERT. CASAMENTO CARTÓRIO 1º OFICIO TERMO: 9999999 FOLHA:"+ "9999999 LIVRO: XXXXXX CATARINA - CE",
                "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"  
            }
        },
        "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": {
        "aprovado": true,
        "codigo": 203,
        "conhecido": true,
        "protocolo": 202101420655,
        "scoreBiometrico": 98
    },    
    "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"
            }
        ]
    }
}

📘
Nota

Exemplo do retorno da Certiface ID completa. O OCR pode ser de três tipos: RG, CNH ou DNI, quando enviado qualquer um desses tipos, os outros dois 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.

Outras Informações

Detalhes código/causa Facematch

Código	Causa	Descrição da causa Facematch
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.	Face não encontrada no tratamento do 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.

Detalhes código/causa Serpro

Código	Causa	Descrição da causa Serpro
200	Validação positiva.	Biometria-documento validado corretamente com a Serpro.
300	validação negativa.	foto-documento não validado corretamente com a Serpro.
450	Falha da validação Serpro- (código Serpro).	Erros da integração Serpro.

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"
}