Processos de cadastro, de autenticação e de validação de usuários são burocráticos e lentos. Nós queremos te ajudar a criar fluxos com baixa fricção e maior segurança, onde os bons usuários são beneficiados e os fraudadores barrados. Nossa solução de FACEMATCH irá te ajudar na automação e segurança desses processos, comparando duas imagens de faces para identificar se ambas são referidas à mesma pessoa. Entregamos após o processamento uma variável booleana (TRUE ou FALSE) parametrizada por um nível de confiança definido pelo cliente.
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.
POST https://facematch.clearsale.com.br/api/authentication/login HTTP/1.1
Content-Type: application/json
{
"clientId": "*******",
"clientSecret": "*******"
}
POST https://webapp-idlab-facematch-api-hml.azurewebsites.net/api/authentication/login HTTP/1.1
Content-Type: application/json
{
"clientId": "*******",
"clientSecret": "*******"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"access_token": "{Valor do Token}",
"expires_in": "{Tempo de Expiração do Token}",
"token_type": "{Tipo do Token}"
}
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{
"title": "Unauthorized.",
"detail": "Acesso não autorizado",
"status": 401,
"instance": "/api/authentication/login"
}
HTTP/1.1 404 NotFound
HTTP/1.1 500 InternalServerError
Content-Type: application/json; charset=utf-8
{
"title": "Internal server error.",
"detail": "Ocorreu um erro. Se o erro persistir, contate o administrador do sistema",
"status": 500,
"instance": "/api/authentication/login"
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
{
"title": "Unauthorized.",
"detail": "Acesso não autorizado",
"status": 401,
"instance": "/api/authentication/login"
}
Através do endpoint a seguir , será criada uma requisição de Facematch entre as duas imagens fornecidas. Imagens de rosto 2D de documentos de identificação, de bancos de dados ou até de perfis de mídia social podem ser combinadas com outras imagens 2D, desde que sejam respeitados os requisitos.
O endpoint funciona de forma assíncrona e o resultado será fornecido via webhook ou via consulta ao endpoint de GET
POST https://facematch.clearsale.com.br/api/v2/Facematch/faces/match2d-2d HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}
{
"identifierId": "123456",
"cpf":"xxxxxxxxxxx",
"minMatchLevel":"6",
"image0":"{base64Image}", (obrigatório)
"image1":"{base64Image}" (obrigatório)
}
POST https://webapp-idlab-facematch-api-hml.azurewebsites.net/api/v2/Facematch/faces/match2d-2d HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}
{
"identifierId": "123456",
"cpf":"xxxxxxxxxxx",
"minMatchLevel":"6",
"image0":"{base64Image}", (obrigatório)
"image1":"{base64Image}" (obrigatório)
}
HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
"createdDate": "2023-03-09T17:33:23.4692342+00:00",
"status": "Processing",
"transactionId": "c2a6b5c4-7650-4676-8322-b85c5e0357c1"
}
HTTP/1.1 400 BadRequest
Content-Type: application/json; charset=utf-8
{
"title": "One or more validation errors occurred.",
"status": 422,
"instance": "/api/v2/Facematch/faces/match2d-2d",
"errors": {
"base64": [
"'base64' não pode ser nulo."
],
"Document": [
"Document must be a valid CPF."
]
}
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
{
"title": "Unauthorized",
"detail": "Invalid token",
"status": 401,
"instance": "/api/v2/Facematch/faces/match2d-2d"
}
HTTP/1.1 500 InternalServerError
Content-Type: application/json; charset=utf-8
{
"title": "Internal server error.",
"detail": "An error has occurred. If the error persists, contact your system administrator.",
"status": 500,
"instance": "/api/v1/Facematch"
}
Sempre que ocorrer uma alteração de status da transação, o Webhook de Facematch irá enviar uma notificação
para uma URL que deverá ser implementada no lado do integrador.
Para cadastrar as URLs é necessário contatar seu gerente de conta informando os dados da tabela abaixo:
Nome | Descrição |
---|---|
Nome Cliente | Nome fantasia do cliente |
URL | URL que será chamada quando houver uma alteração na transação |
Token | O token informado deverá ser uma chave secreta enviada nas chamadas de Webhook, no Header "Authorization: Bearer {Token}" |
POST {URL cadastrada} HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"clientId": "clientID",
"identifierId": "{Valor do IdentifierID enviado na requisição}",
"cPF": "12345678909",
"confiability": 6,
"isMatch": false,
"transactionId": "498ec3978529454aac7bd1628d6074ed",
"transactionStatus": "Success",
"message": "{Campo retornado caso aconteça qualquer tipo de erro no processamento da Transação}"
}
Importante: Se a URL do integrador retornar qualquer Status HTTP diferente de 200 (Ok), será feita outra tentativa de notificar a transação.
O objetivo deste endpoint é permitir que o cliente consulte um score gerado para uma transação, através do TransactionID obtido em endpoint anterior.
GET https://facematch.clearsale.com.br/api/v2/Facematch/faces/match2d-2d/{transactionId} HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}
GET https://webapp-idlab-facematch-api-hml.azurewebsites.net/api/v2/Facematch/faces/match2d-2d/{transactionId} HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"identifierId": "{Valor do IdentifierID enviado na requisição}",
"cpf": "12345678912",
"confiability": 6,
"isMatch": true,
"transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"transactionStatus": "{Status da Transação}",
"message": "{Campo retornado caso aconteça qualquer tipo de erro no processamento da Transação}"
}
HTTP/1.1 404 NotFound
{
"title": "The origin server did not find a current representation for the target resource.",
"detail": "Transaction Id: {transactionId} não encontrada",
"status": 404,
"instance": "/api/v2/Facematch/faces/match2d-2d/{transactionId}"
}
HTTP/1.1 500 InternalServerError
Content-Type: application/json; charset=utf-8
{
"title": "Internal server error.",
"detail": "Ocorreu um erro. Se o erro persistir, contate o administrador do sistema",
"status": 500,
"instance": "/api/v2/Facematch/faces/match2d-2d/{transactionId}"
}
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
{
"title": "Unauthorized",
"detail": "Invalid token",
"status": 401,
"instance": "/api/v2/Facematch/faces/match2d-2d/{transactionid}"
}
Nome | Descrição | Tipo | Tamanho | Obrigatório |
---|---|---|---|---|
IdentifierID | ID do pedido controlado pela entidade | String | 100 | Não |
CPF | CPF para consulta | String | 11 | Não |
Image0 | Imagem em formato BASE64 | String | - | Sim |
Image1 | Imagem em formato BASE64 | String | - | Sim |
MinMatchLevel | Valor de match level desejado para ser considerado um match, deve ser entre 1 e 6 | Int | - | Não |
Nome | Descrição | Tipo | Tamanho |
---|---|---|---|
IdentifierID | O valor enviado na transação será retornado na resposta | String | - |
TransactionId | Identificador gerado pela ClearSale | String | - |
CPF | O valor enviado na transação será retornado na resposta | String | 11 |
Confiability | Nível de confiabilidade entre as duas fotos enviadas | Int | 1 |
IsMatch | Indica se as fotos são da mesma pessoa ou não | Bool | - |
TransactionStatus | Status da transação. Possíveis status: - Success - Processing - Error | String | - |
Message | Campo retornado caso aconteça qualquer tipo de erro no processamento da Transação | String | - |
Errors | Objeto que apresenta mensagens de erro que indicam o motivo da não comparação de imagens na requisição | String[] | - |
Importante: Recomendamos que as fotos tenham o formato .JPG ou .PNG, e tenham no mínimo 150px de largura.
Nome | Descrição |
---|---|
Match level 0 | Indica que não houve match |
Match Level 1 | 1/100 FAR |
Match Level 2 | 1/250 FAR |
Match Level 3 | 1/500 FAR |
Match Level 4 | 1/1.000 FAR |
Match Level 5 | 1/10.000 FAR |
Match Level 6 | 1/100.000 FAR |
FAR: Indica uma porcentagem de aceitação de casos em que ocorrem falsos resultados.
Importante: Os números de confiabilidade retornados variam de 0 a 6.