Facematch | ClearSale Docs

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.