Facematch

Última atualização: 23 de Fevereiro de 2023

Introdução

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.

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://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": "*******"
}
Resposta
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"
}

Comparação entre faces

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

Requisição
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)
}
Resposta
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"
}

Notificação via Webhook

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}"
Requisição
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.

Consulta por TransactionID

O objetivo deste endpoint é permitir que o cliente consulte um score gerado para uma transação, através do TransactionID obtido em endpoint anterior.

Requisição
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}
Resposta
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}"
}

Dicionário de variáveis


Requisição
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
Resposta
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.

Guia de match levels


Valores
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.