InstitucionalBlogService DeskStatus Page

Consulta do status da análise

stable

Suggest Edits

Este endpoint possibilita consultar o status da análise dos documentos enviados pelo endpoint Envio de documentos pessoais.

A consulta de status é um passo imprescindível antes de iniciar a etapa de registro do cliente e antes do envio de cada imagem, pois, por meio do resultado, o parceiro poderá verificar se é necessário solicitar uma nova foto ao cliente.

❗️

Atenção

O parceiro deverá consultar o resultado da análise da imagem enviada previamente antes do envio da próxima imagem. 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.

A consulta pode ser realizada informando apenas o documento do cliente ou o documento e a lista de tokens correspondentes às análises solicitadas.

Requisição

Requisição HTTP

GET https://api-mtls.sandbox.bankly.com.br/document-analysis/{documentNumber}?resultLevel={resultLevel}&token={analysisToken}

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

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:

ScopeDescrição
kyc.document.readConcede acesso para consulta de análise de imagens enviadas para KYC.

Cabeçalhos (Headers)

NomeDescrição
api-versionObrigatório. Versão da API. Atualmente estamos na versão 1.0.
AuthorizationObrigatório. Token de autorização do tipo Bearer.

🚧

Importante

Recomendamos que o parceiro implemente o header cache-control em sua aplicação, para definir o intervalo de tempo de pooling, visando a um melhor desempenho entre cliente e servidor. O tempo sugerido é de 300 segundos (max-age=300). De todos os modos, reforçamos que o pooling deve ser evitado e recomendamos que a configuração de webhooks seja priorizada para a obtenção de informações.

Parâmetros da rota (Path)

No path desta requisição envie os seguintes campos:

NomeTipoDescrição
documentNumberpathObrigatório. número do documento CPF do cliente. Informe somente os números.
tokenqueryLista de tokens de análise do documento.
resultLevelqueryTipo de busca, que pode ser ONLY_STATUS (retorna apenas o status da análise) ou DETAILED (detalhada, que retorna dados da imagem analisada).

Corpo da requisição (Body)

Não é necessário enviar campos no body desta requisição.

Resposta (Response)

O status code 200 indicará sucesso na consulta.

Para a análise de selfie, o retorno irá trazer os seguintes campos em formato JSON:

NomeTipoDescrição
tokenstringToken da imagem.
documentTypestringTipo de documento. Nesse caso, será “SELFIE”.
documentSidestringLado do documento. Nesse caso, será retornado “FRONT”.
statusstringSituação da análise, conforme a tabela Status da análise da imagem.
livenessobjectObjeto que contém informações sobre a análise de prova de vida.
liveness.statusstringResultado da análise de prova de vida, o qual pode ser "LIVENESS_FOUND”, “NO_LIVENESS” e “COULD_NOT_DETECT_FACE”. Confira a tabela Status da análise de prova de vida para mais informações.
faceDetailsobjectObjeto que contém informações sobre a análise facial.
faceDetails.statusstringResultado da análise facial, o qual pode ser ”DETECTED_FACE”, “MANY_FACES_DETECTED” e “COULD_NOT_DETECT_FACE”. Confira a tabela Status da análise de características faciais para mais informações.
faceDetails.confidencenumberNível de confiança da análise.
faceDetails.ageRangeobjectObjeto que contém informações sobre a faixa etária identificada.
faceDetails.ageRange.lownumberIdade mínima detectada.
faceDetails.ageRange.highnumberIdade máxima detectada.
faceDetails.genderobjectObjeto que contém informações sobre o gênero identificado.
faceDetails.gender.valuestringGênero identificado.
faceDetails.gender.confidencenumberNível de confiança da análise.
faceDetails.sunglassesobjectObjeto que contém informações sobre a identificação de óculos na imagem.
faceDetails.sunglasses.valuebooleanCampo que indica a identificação de óculos na face da imagem.
faceDetails.sunglasses.confidencenumberNível de confiança da análise.
faceDetails.eyesOpenobjectObjeto que contém informações sobre a identificação de olhos abertos na imagem.
faceDetails.eyesOpen.valuebooleanCampo que indica a identificação de olhos abertos na face da imagem.
faceDetails.eyesOpen.confidencenumberNível de confiança da análise.
faceDetails.emotions[]array of objectsObjeto que contém uma lista de expressões detectadas na face da imagem.
faceDetails.emotions[].valuestringTipo do detalhe facial identificado, como "CALM" (calmo), "SAD" (triste), "CONFUSED" (confuso), "ANGRY" (zangado), "SURPRISED" (surpreso), "FEAR" (receoso), "HAPPY" (feliz) e "DISGUSTED" (enojado).
faceDetails.emotions[].confidencenumberNível de confiança da análise.
analyzedAtstringData da análise do documento, no formato ISO 8601 - UTC.

Para as análises de documento (frente e verso), o retorno trará os seguintes campos:

NomeTipoDescrição
tokenstringToken da imagem.
documentTypestringTipo de documento. Nesse caso, poderá ser “RG”, “CNH”, “RNE”, “CRNM” ou “DNI”.
documentSidestringLado do documento, que pode ser “FRONT” (frente) ou “BACK” (verso).
statusSituação da análise, conforme a tabela Status da análise da imagem.
faceMatchobjectObjeto que contém informações relativas à análise face match (correspondência entre a face do titular do documento e a da selfie previamente analisada). Objeto retornado na análise da frente do documento.
faceMatch.statusstringResultado da análise de face match, o qual pode ser “HAS_FACE_MATCH”, “UNMATCHED_DOCUMENT” e “MANY_FACES_DETECTED”. Confira a tabela Status da análise de comparação facial para mais informações.
faceMatch.similaritystringNível de similaridade entre as faces comparadas.
faceMatch.confidencestringNível de confiança da análise.
documentDetailsobjectObjeto que contém informações extraídas documento analisado.
documentDetails.statusstringResultado da análise OCR, que pode ser “DETECTED_DOCUMENT”, “NO_DOCUMENT_FOUND” e “NO_INFO_FOUND”. Confira a tabela Status da extração de textos (OCR) para mais informações.
documentDetails.identifiedocumentTypestringTipo do documento detectado.
documentDetails.idNumberstringNúmero do RG.
documentDetails.cpfNumberstringNúmero do CPF.
documentDetails.birthDatestringData de nascimento, no formato ISO 8601 - UTC.
documentDetails.fatherNamestringNome do pai do titular do documento.
documentDetails.motherNamestringNome do mãe do titular do documento.
documentDetails.registerNamestringNome do titular do documento.
documentDetails.valideDatestringValidade do documento, no formato ISO 8601 - UTC.
documentDetails.driveLicenseCategorystringCategoria da CNH (em caso de envio de CNH).
documentDetails.driveLicenseNumberstringNúmero da carteira de habilitação do motorista (em caso de envio de CNH).
documentDetails.driveLicenseFirstQualifyingDatestringData da primeira habilitação (CNH) do motorista.
documentDetails.federativeUnitstringUnidade Federativa onde o documento foi emitido.
documentDetails.issuedBystringÓrgão emissor do documento.
documentDetails.issuedPlacestringLocalidade onde o documento foi emitido.
documentDetails.issuedDatestringData em que o documento foi emitido, no formato ISO 8601 - UTC.
analyzedAtstringData da análise do documento, no formato ISO 8601 - UTC.

Status da análise da imagem

StatusDescriçãoO que fazer?
ANALYZINGA imagem recebida está em análise (status inicial).Aguarde até que a análise seja concluída.
PARTIALLY_ANALYZEDParcialmente analisada. Isso significa que nem todas as análises foram concluídas até o momento.Aguarde até que a análise seja concluída.
ANALYSIS_COMPLETEDTodos os pipelines de análise foram executados e os resultados obtidos.O sistema deve avaliar os resultados. Se a imagem for considerada válida, o registro do cliente poderá prosseguir. Caso contrário, é recomendado solicitar uma nova imagem.
UNEXPECTED_ERRORAlgum erro inesperado ocorreu durante a análise e ela não pôde ser concluída.Solicite ao cliente que nos envie uma nova imagem.

🚧

Importante

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

[
  { 
    "token": "string", 
    "`documentType`": "SELFIE", 
    "`documentSide`": "FRONT", 
    "status": "ANALYSIS_COMPLETED", 
    "liveness": { 
      "status": "LIVENESS_FOUND"
      }, 
    "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", 
      "identified`documentType`": "RG", 
      "idNumber": "48151623", 
      "cpfNumber": "47742663023", 
      "birthDate": "1810-10-12", 
      "fatherName": "", 
      "motherName": "Dionísia Gonçalves Pinto", 
      "registerName": "Nísia Floresta", 
      "validDate": "2030-01-30", 
      "driveLicenseCategory": "string", 
      "driveLicenseNumber": "string", 
      "driveLicenseFirstQualifyingDate": "string", 
      "federativeUnit": "SP", 
      "issuedBy": "SSP", 
      "issuePlace": "SP", 
      "issueDate": "1820-10-12" 
    }, 
    "analyzedAt": "2021-08-31T21:20:58.754Z" 
  }
]

[
  { 
    "token": "string", 
    "documentType": "RG", 
    "documentSide": "BACK", 
    "status": "ANALYSIS_COMPLETED", 
    "documentDetails": { 
      "status": "DETECTED_DOCUMENT", 
      "identified`documentType`": "RG", 
      "idNumber": "48151623", 
      "cpfNumber": "47742663023", 
      "birthDate": "1810-10-12", 
      "fatherName": "", 
      "motherName": "Dionísia Gonçalves Pinto", 
      "registerName": "Nísia Floresta", 
      "validDate": "2030-01-30", 
      "driveLicenseCategory": "string", 
      "driveLicenseNumber": "string", 
      "driveLicenseFirstQualifyingDate": "string", 
      "federativeUnit": "SP", 
      "issuedBy": "SSP", 
      "issuePlace": "SP", 
      "issueDate": "1820-10-12" 
    }, 
    "analyzedAt": "2021-08-31T21:20:58.754Z" 
  }
]

[
    {
        "token": "wGW_jgBuoZNMxqBYwzFIPZGT0jbgRzJL",
        "documentType": "SELFIE",
        "documentSide": "FRONT",
        "status": "ANALYZING"
    },
    {
        "token": "pRW_jgBuoZNMxqFGwzFIPZGT0jbgRzKL",
        "documentType": "RG",
        "documentSide": "FRONT",
        "status": "ANALYZING"
    }
]

👍

Dica

Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

Este endpoint não retorna erros específicos. Porém, ele poderá retornar alguns erros comuns entre todos os endpoints.

Eventos

Este endpoint não possui eventos relacionados a ele.

Como as análises ocorrem

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.

Análise de prova de vida (Liveness)

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


Status da análise de prova de vida

StatusDescriçãoO que fazer?
LIVENESS_FOUNDA prova de vida foi detectada.---
NO_LIVENESSNão foi encontrada nenhuma prova de vida.Instrua o cliente a tirar uma nova selfie, em um local bem iluminado e mantendo o rosto descoberto, sem utilizar acessórios como bonés, óculos de sol etc.
COULD_NOT_DETECT_FACEAlguma prova de vida foi detectada, mas não foi possível identificar um rosto.Oriente o cliente a tirar uma nova selfie, evitando manter o rosto coberto.

🚧

Importante

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

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.


Status da análise de características faciais

StatusDescriçãoO que fazer?
DETECTED_FACEUma prova de vida foi detectada.---
MANY_FACES_DETECTEDMais de um rosto foi identificado na foto.Instrua o cliente a tirar uma nova selfie, evitando pessoas próximas.
COULD_NOT_DETECT_FACENão foi encontrado um rosto na foto.Oriente o cliente a tirar uma nova selfie, evitando manter o rosto coberto.

📘

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, é imprescindível 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).


Status da análise de comparação facial

StatusDescriçãoO que fazer?
HAS_FACE_MATCHHá correspondência entre o rosto presente na foto do documento e o rosto exibido na selfie.---
UNMATCHED_DOCUMENTA foto não atinge a resolução esperada (formato VGA) ou a selfie enviada previamente não é válida.Certifique-se de que o cliente enviará uma selfie válida antes de carregar as fotos do documento. Além disso, é importante instruí-lo a buscar um enquadramento adequado, que permita a análise de face match.
MANY_FACES_DETECTEDMais de um rosto foi identificado na foto.Certifique-se de que a selfie enviada previamente pelo cliente é válida.

🚧

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 de documento enviado é o mesmo informado pelo cliente.


Status da extração de textos (OCR)

StatusDescriçãoO que fazer?
DETECTED_DOCUMENTUm documento (RG, CNH, RNE, DNI ou CRNM) foi identificado na foto.---
NO_DOCUMENT_FOUNDNão foi possível identificar um documento na foto.Instrua o cliente a tirar uma nova foto do documento em um local bem iluminado, atentando-se ao enquadramento da imagem.
NO_INFO_FOUNDFoi identificado um documento, mas não foi possível extrair informações dele.Instrua o cliente a tirar uma nova foto do documento em um local bem iluminado, atentando-se ao enquadramento da imagem. Evite zoom muito próximo e imagens desfocadas

📘

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 de documento enviado é o mesmo informado pelo cliente.

StatusDescriçãoO que fazer?
DETECTED_DOCUMENTUm documento (RG, CNH, RNE, DNI ou CRNM) foi identificado na foto.---
NO_DOCUMENT_FOUNDNão foi possível identificar um documento na foto.Instrua o cliente a tirar uma nova foto do documento em um local bem iluminado, atentando-se ao enquadramento da imagem.
NO_INFO_FOUNDFoi identificado um documento, mas não foi possível extrair informações dele.Instrua o cliente a tirar uma nova foto do documento em um local bem iluminado, atentando-se ao enquadramento da imagem. Evite zoom muito próximo e imagens desfocadas

📘

Nota

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

Updated 5 days ago