---
updatedAt: 2026-04-14T17:34:32.000Z
agentTools:
projectIndex: https://devcenter.certiface.io/llms.txt
---
# 🚧 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](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#1-credencial)
2. [Appkey](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#2-appkey)
3. [Liveness 2D](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#3-liveness-2d)\
3.1. [Challenge](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#3#1-challenge)\
3.2. [Captcha](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#3#1-captcha)
4. [Liveness 3D](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#4-liveness-3d)\
4.1. [Facetec](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#4#1-facetec)\
4.2. [3D Session](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#4#1#1-3d-session)\
4.3. [3D Liveness](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#4#1#2-3d-liveness)\
4.4. [Iproov](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#4#2-iproov)\
4.5. [3D Session](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#4#2#1-3d-session)\
4.6. [3D Liveness](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#4#2#2-3d-liveness)
5. [Document](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#5-document)
6. [Webhook](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#6-webhook)
7. [Result](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#7-result)
8. [Status Updater](https://certifaceid.readme.io/docs/guia-integracao-api-v1-3#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
```http
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
```yaml
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
```json
{
"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 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 .
## 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
```http
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
```yaml
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
```json
{
"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
```http
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
```yaml
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
```json
{
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
```http
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
```yaml
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
```json
{
"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
```http
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
```json
{
"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
```json
{
"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
```http
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
```json
{
" 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
| 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
```json
{
"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.
```http
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.
```json
{
"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.
```json
{
"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.
```http
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.
```json
{
" 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.
```json
{
"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
```http
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
```json
{
"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
```json
{
"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
```http
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"
```json
{
"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](https://devcenter.certiface.io/docs/guia-integracao-api-v1-3#2-appkey).
```http
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
```yaml
{
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; 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. |
| 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] |
| 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. |
| 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
```json
{
"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!
>
> 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
```json
{
"status": "ERR",
"resultado": "ERR",
"protocolo": "202001138311",
"msg": "NOME"
}
```
##### CPF Inválido
```json
{
"status": "ERR",
"resultado": "ERR",
"protocolo": "202001138315",
"msg": "INVALID CPF"
}
```
##### Nascimento Inválido
```json
{
"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
```json
{
"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