Envio e análise de documentos pessoais

A análise de documentos é a primeira etapa na jornada de Onboarding de pessoa física. Após essa análise, recuperaremos os resultados detalhados de cada imagem e os anexaremos à requisição para examinarmos o perfil do cliente. As imagens a serem analisadas nessa etapa são:

• Selfie;
• Frente do Documento de Identidade;
• Verso do Documento de Identidade.

❗️

Atenção

Para aumentar as chances de aprovação no Onboarding, é preciso seguir todas as recomendações contidas na página Orientações para envio de fotos .

Diagrama de atividades

Etapas

Para que o processo de análise de documentos seja realizado corretamente, o parceiro deve utilizar os endpoints descritos a seguir.

Envio de documentos pessoais

Endpoint

Para o uso do endpoint de envio de documentos, é preciso preencher os seguintes campos obrigatórios:

Path

• documentNumber: número do documento CPF do cliente. Informe somente os números;

Header

• Content-type: formato do conteúdo a ser enviado no form da requisição. Neste caso, preencha com multipart/form-data;

• boundary: sequência de 1 a 70 caracteres, que não podem terminar com espaço em branco;

Form

• documentType: informe o tipo de documento (SELFIE, RG, CNH, RNE, DNI ou CRNM);
• documentSide: informe o lado do documento (FRONT ou BACK);
• image: arquivo físico da imagem.

curl --location --request PUT 'https://api-mtls.sandbox.bankly.com.br/document-analysis/{{documentNumber}}' \ 
--header 'api-version: 1' \ 
--header 'Authorization: Bearer {{accessToken}}' \ 
--header 'Content-Type: multipart/form-data; boundary=<calculated when request is sent>'\ 
--form 'documentType="{{documentType}}"' \ 
--form 'documentSide="{{documentSide}}"' \ 
--form 'image=@"/{{path-to-image}}"'

Cada tipo de imagem tem seu próprio pipeline de análise, que resulta em conjunto de informações que complementarão os dados fornecidos pelo cliente durante o Onboarding.

• Na selfie, são realizadas análises de prova de vida (liveness) e detecção de características faciais (face details) da pessoa.
• No caso da frente do documento de identificação pessoal (onde está a foto do portador do documento), fazemos uma comparação da foto da pessoa no documento com a selfie enviada previamente. Também extrairemos informações da foto documento (OCR).
• Para o verso do documento de identificação pessoal, fazemos apenas a extração de informações do documento (OCR).

Retorno

A cada envio de documento, será retornado um token, necessário para a consulta de status de análise do documento. Guarde-o, pois ele não poderá ser recuperado posteriormente.

{ 
    "token": "tokenDoDocumentoEnviado" 
}

Após o envio, é possível verificar o status da análise do documento por meio do endpoint explicitado a seguir.

Consulta do status da análise

Uma análise de documento é concluída quando todo o pipeline é executado, resultando no status ANALYSIS_COMPLETED.

Endpoint

Para o consumo do endpoint de consulta do status da análise, preencha no path da requisição os seguintes campos:

• documentNumber: número do documento CPF do cliente. Informe somente os números;
• token: informe o token retornado no envio do documento.

curl --location --request GET 'https://api-mtls.sandbox.bankly.com.br/document-analysis/{{documentNumber}}?token={{analysisToken}}' \ 
--header 'api-version: 1' \ 
--header 'Authorization: Bearer {{accessToken}}'

Os possíveis status de análise durante o processo são:

🚧

Importante

Antes de prosseguir com o Onboarding do cliente, o parceiro deve consultar o resultado de cada análise para decidir se é necessário solicitar-lhe uma nova imagem.

Retorno

{ 
  "token": "string", 
  "documentType": "SELFIE", 
  "documentSide": "FRONT", 
  "status": "ANALYSIS_COMPLETED", 
    "liveness": { 
    "status": "LIVENESS_FOUND", 
    "confidence": 1.9746 
  }, 
  "faceDetails": { 
    "status": "DETECTED_FACE", 
    "confidence": 99.99689, 
    "ageRange": { 
      "low": 18, 
      "high": 23 
    }, 
    "gender": { 
      "value": "Male", 
      "confidence": 99.21723 
    }, 
    "sunglasses": { 
      "value": false, 
      "confidence": 99.40401 
    }, 
    "eyesOpen": { 
      "value": false, 
      "confidence": 57.259457 
    }, 
    "emotions": [ 
      { 
        "value": "CALM", 
        "confidence": 95.32976 
      }, 
      { 
        "value": "SAD", 
        "confidence": 2.078439 
      }, 
      { 
        "value": "CONFUSED", 
        "confidence": 0.9475501 
      }, 
      { 
        "value": "ANGRY", 
        "confidence": 0.6159508 
      }, 
      { 
        "value": "SURPRISED", 
        "confidence": 0.37119603 
      }, 
      {
        "value": "FEAR", 
        "confidence": 0.24299896 
      }, 
      { 
        "value": "HAPPY", 
        "confidence": 0.20983662 
      }, 
      { 
        "value": "DISGUSTED", 
        "confidence": 0.20425977 
      } 
    ] 
  }, 
  "analyzedAt": "2021-08-31T21:20:58.754Z" 
}

{ 
  "token": "string", 
  "documentType": "RG", 
  "documentSide": "FRONT", 
  "status": "ANALYSIS_COMPLETED", 
  "faceMatch": { 
    "status": "HAS_FACE_MATCH", 
    "similarity": 99.98459, 
    "confidence": 99.99835 
  }, 
  "documentDetails": { 
    "status": "DETECTED_DOCUMENT", 
    "identifiedDocumentType": "RG", 
    "idNumber": "string", 
    "cpfNumber": "string", 
    "birthDate": "string", 
    "fatherName": "string", 
    "motherName": "string", 
    "registerName": "string", 
    "validDate": "string", 
    "driveLicenseCategory": "string", 
    "driveLicenseNumber": "string", 
    "driveLicenseFirstQualifyingDate": "string", 
    "federativeUnit": "string", 
    "issuedBy": "string", 
    "issuePlace": "string", 
    "issueDate": "string" 
  }, 
  "analyzedAt": "2021-08-31T21:20:58.754Z" 
}

{ 
  "token": "string", 
  "documentType": "RG", 
  "documentSide": "BACK", 
  "status": "ANALYSIS_COMPLETED", 
  "documentDetails": { 
    "status": "DETECTED_DOCUMENT", 
    "identifiedDocumentType": "RG", 
    "idNumber": "string", 
    "cpfNumber": "string", 
    "birthDate": "string", 
    "fatherName": "string", 
    "motherName": "string", 
    "registerName": "string", 
    "validDate": "string", 
    "driveLicenseCategory": "string", 
    "driveLicenseNumber": "string", 
    "driveLicenseFirstQualifyingDate": "string", 
    "federativeUnit": "string", 
    "issuedBy": "string", 
    "issuePlace": "string", 
    "issueDate": "string" 
  }, 
  "analyzedAt": "2021-08-31T21:20:58.754Z" 
}

Análise da selfie

A análise de selfie primariamente identifica se há uma prova de vida na imagem. Posteriormente, essa imagem será utilizada como imagem base (source) ao ser comparada com a foto existente na frente do documento (target), com o intuito de comprovar se o portador do documento é a mesma pessoa que solicitou a abertura de conta.

🚧

Importante

Lembre-se de seguir todas as recomendações contidas na página Orientações para envio de fotos.

Análise de prova de vida (Liveness)

Tem como principal objetivo identificar se há prova de vida, ou seja, há uma pessoa na imagem, e a imagem não é a foto de uma foto.

A seguir, os status referentes a essa análise:

Análise de características faciais (Face details)

Visa identificar as características do rosto da pessoa. Como objetivo secundário, ajuda a verificar se há mais de uma face na selfie, indicando que há mais de uma pessoa. Seus status são:

📘

Nota

Uma selfie é considerada válida para o processo de onboarding quando os status das análises de liveness e face details são LIVENESS_FOUND e DETECTED_FACE respectivamente.

Análise da frente do documento de identidade

Essa análise tem como principal objetivo identificar se o documento que está sendo enviado é válido e se ele pertence à pessoa que está presente na selfie.

Por isso, é importante que a selfie seja enviada antes da foto da frente do documento.

🚧

Importante

Lembre-se de seguir todas as recomendações contidas na página Orientações para envio de fotos.

Análise de comparação facial (Face match)

Essa análise tem como objetivo identificar a correspondência entre a face do titular do documento (target) e a da selfie previamente analisada (source).

Extração de textos (OCR)

Essa análise tem como objetivo extrair os textos do documento e determinar se o tipo de documento enviado é o mesmo informado pelo cliente.

📘

Nota

Uma foto da frente do documento é considerada válida para o processo de onboarding quando os status das análises de face match e OCR são HAS_FACE_MATCH e DETECTED_DOCUMENT, respectivamente.

Análise do verso do documento de identidade

Esse tipo de análise complementa a análise da frente do documento.

Não há uma ordem de envio das fotos de frente e verso. O importante é que a selfie seja enviada antes das duas imagens do documento e que todas essas imagens sejam enviadas antes do pedido de abertura da conta.

🚧

Importante

Lembre-se de seguir todas as recomendações contidas na página Orientações para envio de fotos.

Extração de textos (OCR)

Essa análise tem como objetivo extrair os textos do documento e determinar se o tipo do documento enviado é o mesmo informado pelo cliente.

📘

Nota

Uma foto do verso do documento é considerada válida para o processo de Onboarding quando os status da análise OCR é DETECTED_DOCUMENT.

❗️

Atenção

Antes de iniciar a etapa de registro do cliente, verifique os status de análises das imagens. Se as imagens não estiverem aprovadas, não será possível prosseguir com o cadastro. Consulte as recomendações contidas na página Orientações para envio de fotos.

Evento

Caso o parceiro deseje receber atualizações referentes ao processo de análise de documentos, é possível configurar o webhook e receber os seguintes eventos do contexto "Document":

• DOCUMENT_WAS_RECEIVED
• DOCUMENT_WAS_PROCESSED