Biometrics

Última atualização: 25 de Maio de 2021

Introdução

Processos cadastrais e de autenticação de usuários são burocráticos e lentos e nós queremos te ajudar a criar fluxos com baixa fricção, onde os bons usuários são beneficiados e os fraudadores barrados. Nossa solução de Biometria Facial irá te ajudar na automatização desse processo, analisando as faces dos seus usuários na maior base do mercado e trazendo o melhor score para sua decisão.

A Biometria Facial faz uso do padrão ICAO de fotos. Abaixo seguem algumas recomendações para realizar a captura de fotos de seus clientes de forma que possamos oferecer uma melhor avaliação biométrica.

  • O rosto deve estar centralizado e de frente, com olhos abertos direcionados para a câmera;

  • A distância máxima aceita é de 60 cm da câmera;

  • O posicionamento deve ser frontal;

  • A foto não deve apresentar expressão facial, a fisionomia deve permanecer neutra;

  • Não utilizar acessórios que obstrua a face (exemplo: óculos escuros ou de grau, boné, gorro, chapéu, outros);

  • A iluminação deve estar adequada para visualização da foto.
  • Autenticação

    Todas as requisições submetidas à nossa API devem ser realizadas através de um token, gerado por usuário e senha fornecidos pela ClearSale. Entre em contato com o seu consultor de vendas para mais informações.

    Na autenticação, além do token, retornamos seu tempo de expiração. É necessário que contemple no seu desenvolvimento o gerenciamento da vida útil do token com base nesse tempo de expiração. Só gere um novo token após a expiração do seu token atual.

    Requisição
    POST https://api-biometrics.clearsale.com.br/authentication HTTP/1.1
    Content-Type: application/json
    {
        "Login": "{Seu login}",
        "Password": "{Sua senha}"
    }
    
    POST https://api-biometrics-hml.clearsale.com.br/authentication HTTP/1.1
    Content-Type: application/json
    {
        "Login": "{Seu login}",
        "Password": "{Sua senha}"
    }
    
    Resposta
    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    {
        "Token": "{Valor do Token}",
        "ExpirationDate": "{Tempo de Expiração do Token}"
    }
    
    HTTP/1.1 400 Bad Request
    Content-Type: application/json; charset=utf-8
    {
        "Message": "Invalid username and/or password. Check the field and try again" 
    }
    
    HTTP/1.1 404 NotFound
    
    
    HTTP/1.1 500 InternalServerError
    
    

    Biometric

    O objetivo deste endpoint é apresentar um único score de similaridade, resultante da comparação entre a selfie do usuário e a foto que consta nas bases públicas e privadas, à partir do envio do CPF, Nome, Nascimento e Selfie desse usuário.

    Importante: Recomendamos que a foto tenha tamanho de, no máximo, 1.5MB

    Requisição
    POST https://api-biometrics.clearsale.com.br/v1/faces HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {Token}
    {
        "document": "12345678912", (obrigatório)
        "imageBase64": "base64", (obrigatório)
        "name": "João Henrique Silva", (obrigatório)
        "birthdate": "2019-06-05T12:00:00.000", (obrigatório)
        "originID": "Teste", // opcional
        "externalID": "Teste" // opcional
    }
    
    POST https://api-biometrics-hml.clearsale.com.br/v1/faces HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {Token}
    {
        "document": "12345678912", (obrigatório)
        "imageBase64": "base64", (obrigatório)
        "name": "João Henrique Silva", (obrigatório)
        "birthdate": "2019-06-05T12:00:00.000", (obrigatório)
        "originID": "Teste", // opcional
        "externalID": "Teste" // opcional
    }
    
    Resposta
    HTTP/1.1 201 CREATED
    Content-Type: application/json; charset=utf-8
    {
        "ExternalID": "{Valor do ExternalID enviado na requisição}",
        "OriginID": "{Valor do OriginID enviado na requisição}",
        "TransactionID": "b1ca3eb6-3d68-41a1-8a9b-93674b205cca",
        "Date": "2020-08-20T14:10:00.000",
        "Score": "0.9998",
    }
    
    HTTP/1.1 400 Bad Request
    Content-Type: application/json; charset=utf-8
    {
       "Date":"2020-08-20T17:16:51.3152935Z",
       "Errors":[
          "Document must be a valid CPF.",
          "The field Name is invalid and must be filled as specified in the documentation.",
          "Birthdate must be a valid date.",
          "The image must be in base64 format.",
          "Face not found. Try again."
        ]
    }
    
    HTTP/1.1 500 InternalServerError
    
    
    HTTP/1.1 204 NoContent
    
    
    HTTP/1.1 401 Unauthorized
    
    

    Dicionário de variáveis


    Transaction

    Nome Descrição Tipo Tamanho Obrigatório
    Document CPF para consulta String 11 Sim
    Image Imagem no formato base64 String - Sim
    Name Nome completo do cliente (Sem abreviaturas) String - Sim
    Birthdate Data de Nascimento do cliente
    [YYYY-MM-DD]
    DateTime 10 Sim
    OriginID Campo de preenchimento livre, o valor será retornado na resposta String - Não
    ExternalID Campo de preenchimento livre, o valor será retornado na resposta String - Não

    Results

    Nome Descrição Tipo Tamanho
    OriginID Campo de preenchimento livre, o valor será retornado na resposta String -
    ExternalID Campo de preenchimento livre, o valor será retornado na resposta String -
    TransactionID Identificador gerado pela ClearSale String 36
    Score Resultado da comparação da similaridade entre a imagem enviada e a foto que temos atrelada ao CPF em nossas bases, compreendido entre 0.0000 e 1.0000 Decimal 6
    Errors Objeto que apresenta mensagens de erro que indicam o motivo da não geração do score na requisição String[] -

    Consulta por ID

    O objetivo deste endpoint é disponibilizar a consulta a um score obtido anterior, através do transactionID retornado no endpoint anterior.

    Requisição
    GET https://api-biometrics.clearsale.com.br/v1/faces/{transactionId} HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {Token}
    
    GET https://api-biometrics-hml.clearsale.com.br/v1/faces/{transactionId} HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {Token}
    
    Resposta
    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    {
        "ExternalID": "{Valor do ExternalID enviado na requisição}",
        "OriginID": "{Valor do OriginID enviado na requisição}",
        "TransactionID": "b1ca3eb6-3d68-41a1-8a9b-93674b205cca",
        "Date": "2020-08-20T14:10:00.000",
        "Score": 0.9645
    }
    
    HTTP/1.1 500 InternalServerError
    
    
    HTTP/1.1 404 NotFound
    
    
    HTTP/1.1 401 Unauthorized
    
    

    Dicionário de variáveis


    Transaction

    Nome Descrição Tipo Tamanho Obrigatório
    TransactionID Identificador gerado pela ClearSale String 36 Sim

    Results

    Nome Descrição Tipo Tamanho
    OriginID Campo de preenchimento livre, o valor será retornado na resposta String -
    ExternalID Campo de preenchimento livre, o valor será retornado na resposta String -
    TransactionID Identificador gerado pela ClearSale que foi usado para buscar a consulta String 36
    Score Resultado da comparação da similaridade entre a imagem enviada e a foto que temos atrelada ao CPF em nossas bases, compreendido entre 0.0000 e 1.0000 Decimal 6

    Cenários Mockados

    A fim de validar seus cenários de testes, nossa API oferece em homologação diferentes escalas de ranges do score de similaridade conforme o que recebemos de input no campo ExternalID. Segue abaixo o mapeamento para testes:

    1. ExternalID = 123 o score será randômico entre os valores de 0.0000 a 0.3999
    2. ExternalID = 456 o score será randômico entre os valores de 0.4000 a 0.6999
    3. ExternalID = 789 o score será randômico entre os valores de 0.7000 a 1.0000
    4. ExternalID = null o score será null
    5. ExternalID com qualquer outro valor, o score será randômico de 0.0000 a 1.0000

    Os outros parâmetros de input podem ser enviados como desejar, desde que respeitando as características dos campos.