Reconhecimento Facial

Todas as operações realizadas no serviço de reconhecimento facial são feitas através do recurso faces. Este recurso abstrai um único indivíduo e pode conter um ou mais templates de face, todos correspondentes ao mesmo indivíduo.

Template de face é o termo utilizado para a informação da biometria facial extraída a partir da imagem da face. Apenas os templates são armazenados pelo serviço de reconhecimento facial da TechTrue®, e é impossível refazer a imagem da face a partir deste template.

O identificador único deste recurso, ext_id, é responsável por identificar este indivíduo na base de dados e faz a agregação dos templates associados ao mesmo.

Nota

O identificador ext_id é de responsabilidade única e exclusiva da aplicação cliente deste serviço, ou seja, operações realizadas de forma erronea sobre o mesmo identificador ext_id não serão tratadas pelo serviço e não poderão ser desfeitas sem alguma ação explícita da aplicação cliente.

Nota

Recomendamos que não seja utilizado nenhum dado sensível do indivíduo na geração do ext_id. Idealmente, pode-se utilizar um UUID gerado de acordo com a norma ISO/IEC 9834-8:2014.

Ademais, é possível realizar a segregação da base de dados de face utilizando o conceito de aplicações, onde cada aplicação possui uma credencial específica, utilizada para geração do token de autenticação, que, por fim, definirá qual instância da base de dados será utilizada nas operações sobre uma face.

O exemplo mais básico do uso desta aplicação é para segregar as bases de dados utilizadas durante a fase de integração/testes da fase de produção/operação real do serviço. Assim, evita-se que faces utilizadas em testes acabem indo para a base de dados de produção e/ou que desenvolvedores tenham acesso indevido às faces utilizadas na operação do serviço.

Nota

Todas as contas possuem uma aplicação padrão chamada “demo”.

Quantidade de faces

shell

curl "https://api.techtrue.com.br/api/v1/services/face/count"
  -H "Authorization: Bearer {{token}}"

node.js

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.techtrue.com.br/api/v1/services/face/count',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{token}}'
  }
};

axios(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

O comando acima retorna o seguinte JSON:

  {
  "count": 10234
  }

Endpoint que retorna a quantidade de faces cadastradas na aplicação.

Nota

Note que “quantidade de faces” pode ser diferente da “quantidade de templates”!

HTTP Request

GET /api/v1/services/face/count

Parameters

Name	Located in	Description	Required	Type
none

HTTP Response

Code	Description
200	OK
401	Unauthorized

Listagem de faces

shell

curl "https://api.techtrue.com.br/api/v1/services/face/list"
  -H "Authorization: Bearer {{token}}"

node.js

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.techtrue.com.br/api/v1/services/face/list',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{token}}'
  }
};

axios(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

O comando acima retorna o seguinte JSON:

{
  "faces": [
    {
      "ExternalID": "<ext_id>",
      "CreatedAt": "{{timestamp}}"
    }
  ]
}

Endpoint que retorna uma lista com todas as faces cadastradas na aplicação.

HTTP Request

GET /api/v1/services/face/list

Parameters

Name	Located in	Description	Required	Type
none

HTTP Response

Code	Description
200	OK
401	Unauthorized

Export de faces

shell

curl "https://api.techtrue.com.br/api/v1/services/face/dump"
  -H "Authorization: Bearer {{token}}"

node.js

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.techtrue.com.br/api/v1/services/face/dump',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{token}}'
  }
};

axios(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

O comando acima retorna o seguinte JSON:

{
  "result": {
    "total_entries": 2,
    "faces": [
      {
        "ExternalID": "teste11",
        "Templates": [
          {
            "Data": "<base64_string>"
          }
        ],
        "CreatedAt": "{{timestamp}}",
        "UpdatedAt": "{{timestamp}}"
      },
      {
        "ExternalID": "teste1",
        "Templates": [
          {
            "Data": "<base64_string>"
          },
          {
            "Data": "<base64_string>"
          }
        ],
        "CreatedAt": "{{timestamp}}",
        "UpdatedAt": "{{timestamp}}"
      }
  }
}

Endpoint que retorna uma lista com todos os templates de faces cadastradas na aplicação. Esses templates podem ser utilizados para a carga de uma base de dados em um device, ou para migração de faces entre aplicações.

HTTP Request

GET /api/v1/services/face/dump

Query Parameters

Name	Located in	Description	Required	Type
page	query	Número da página a ser requisitada	False	integer
limit	query	Quantidade máxima de registros a ser retornado por página	False	integer

Nota

O valor padrão do limit é de 100.

HTTP Response

Code	Description
200	OK
401	Unauthorized

Quantidade de templates

shell

curl "https://api.techtrue.com.br/api/v1/services/face/templates/count/{ext_id}"
  -H "Authorization: Bearer {{token}}"

node.js

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.techtrue.com.br/api/v1/services/face/templates/count/{ext_id}',
  headers: {
    'Content-Type': 'application/json'
  }
};

axios(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

O comando acima retorna o seguinte JSON:

{
  "count": 3
}

Endpoint que retorna a quantidade de templates cadastrados para uma determinada face

HTTP Request

GET /api/v1/services/face/templates/count/{ext_id}

URL Parameters

Name	Located in	Description	Required	Type
ext_id	path	Identificador único da face	Yes	string

HTTP Response

Code	Description
200	OK
401	Unauthorized

Cadastrar uma face

shell

curl "https://api.techtrue.com.br/api/v1/services/face/enroll/{ext_id}" \
  -X POST --data "@images.json" \
  -H "Authorization: Bearer {{token}}"

node.js

const axios = require('axios');
let data = JSON.stringify({
  "Images": [
    {
        "imageType": "frontal",
        "imageData": "{{base64_image}}"
    }
  ]
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.techtrue.com.br/api/v1/services/face/enroll/{ext_id}',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{token}}'
  },
  data: data
};

axios(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error.response);
});

O comando acima retorna o seguinte JSON:

{
  "result": {
    "code": 1000,
    "message": "ENROLLED_SUCCESSFULLY"
  }
}

Endpoint que realiza o cadastro de uma face no serviço.

HTTP Request

POST /api/v1/services/face/enroll/{ext_id}

URL Parameters

Name	Located in	Description	Required	Type
ext_id	path	Identificador único da face	Yes	string

HTTP Response

Code	Description
200	OK
401	Unauthorized

Body payload

{
  "doLivenessCheck": true,
  "ReturnTemplate": false,
  "Images": [
      {
          "imageType": "frontal",
          "imageData": "{{base64_string}}"
      }
  ]
}

Body payload

• Parâmetro doLivenessCheck:

O parâmetro doLivenessCheck, quando passado com valor true, informa o serviço de que este deve executar o processo de avaliação de vivacidade de face sobre as imagens enviadas.

Caso a avaliação de vivacidade indique uma tentativa de ataque de apresentação, a requisição retorna erro no JSON.

Retorno em caso de erro do Liveness Check

{
  "result": {
    "code": 1013,
    "message": "LIVENESS_CHECK_FAILED",
    "detail": "liveness check failed"
  }
}

• Parâmetro ReturnTemplate:

Quando o parâmetro ReturnTemplate for true, a resposta da requisição conterá o template biométrico, em base64, das faces enviadas na requisição.

Retorno quando a requisição conter "ReturnTemplate": true

{
  "result": {
    "code": 1000,
    "message": "ENROLLED_SUCCESSFULLY"
  },
  "b64Templates": [
    {{base64_string}}
  ]
}

Atualizar uma face

Endpoint que atualiza o cadastro de uma face no serviço.

Nota

Ao atualizar uma face, todos os templates préviamente associados à mesma são removidos, e novos templates serão gerados para esta face.

shell

curl "https://api.techtrue.com.br/api/v1/services/face/{ext_id}" \
  -X PATCH --data "@images.json" \
  -H "Authorization: Bearer {{token}}"

node.js

const axios = require('axios');
let data = JSON.stringify({
  "Images": [
    {
        "imageType": "frontal",
        "imageData": "{{base64_image}}"
    }
  ]
});

let config = {
  method: 'patch',
  maxBodyLength: Infinity,
  url: 'https://api.techtrue.com.br/api/v1/services/face/{ext_id}',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{token}}'
  },
  data: data
};

axios(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error.response);
});

O comando acima retorna o seguinte JSON:

{
  "result": {
    "code": 1006,
    "message": "UPDATED_SUCCESSFULLY"
  }
}

HTTP Request

PATCH /api/v1/services/face/{ext_id}

URL Parameters

Name	Located in	Description	Required	Type
ext_id	path	Identificador único da face	Yes	string

HTTP Response

Code	Description
200	OK
401	Unauthorized

Body payload

{
  "doLivenessCheck": true,
  "ReturnTemplate": false,
  "Images": [
      {
          "imageType": "frontal",
          "imageData": "{{base64_string}}"
      }
  ]
}

Body payload

• Parâmetro doLivenessCheck:

O parâmetro doLivenessCheck, quando passado com valor true, informa o serviço de que este deve executar o processo de avaliação de vivacidade de face sobre as imagens enviadas.

Caso a avaliação de vivacidade indique uma tentativa de ataque de apresentação, a requisição retorna erro no JSON.

Retorno em caso de erro do Liveness Check

{
  "result": {
    "code": 1013,
    "message": "LIVENESS_CHECK_FAILED",
    "detail": "liveness check failed"
  }
}

• Parâmetro ReturnTemplate:

Quando o parâmetro ReturnTemplate for true, a resposta da requisição conterá o template biométrico, em base64, das faces enviadas na requisição.

Retorno quando a requisição conter "ReturnTemplate": true

{
  "result": {
    "code": 1000,
    "message": "ENROLLED_SUCCESSFULLY"
  },
  "b64Templates": [
    {{base64_string}}
  ]
}

Consultar os templates de uma face

Endpoint que consulta e retorna todos os templates de uma face do serviço.

shell

curl "https://api.techtrue.com.br/api/v1/services/face/templates/{ext_id}" \
  -H "Authorization: Bearer {{token}}"

node.js

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.techtrue.com.br/api/v1/services/face/templates/{ext_id}',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{token}}'
  }
};

axios(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error.response);
});

O comando acima retorna o seguinte JSON:

{
  "ExternalID": "{{ext_id}}",
  "Templates": [
    {
      "Data": "{{base64_string}}"
    }
  ],
  "CreatedAt": "{{timestamp}}",
  "UpdatedAt": "{{timestamp}}"
}

HTTP Request

GET /api/v1/services/face/templates/{ext_id}

Parameters

Name	Located in	Description	Required	Type
ext_id	path	Identificador único da face	Yes	string

HTTP Response

Code	Description
200	OK
401	Unauthorized

Remover uma face

Endpoint que remove uma face do serviço.

Nota

CUIDADO! Após removida, a face não pode ser recuperada pelo serviço.

shell

curl "https://api.techtrue.com.br/api/v1/services/face/{ext_id}" \
  -X DELETE \
  -H "Authorization: Bearer {{token}}"

node.js

const axios = require('axios');

let config = {
  method: 'delete',
  maxBodyLength: Infinity,
  url: 'https://api.techtrue.com.br/api/v1/services/face/{ext_id}',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{token}}'
  }
};

axios(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error.response);
});

O comando acima retorna o seguinte JSON:

{
  "result": {
    "code": 1004,
    "message": "DELETED_SUCCESSFULLY"
  }
}

HTTP Request

DELETE /api/v1/services/face/{ext_id}

Parameters

Name	Located in	Description	Required	Type
ext_id	path	Identificador único da face	Yes	string

HTTP Response

Code	Description
200	OK
401	Unauthorized

Verificar uma face

Endpoint que realiza a verificação (operação 1:1) de uma face.

shell

curl "https://api.techtrue.com.br/api/v1/services/face/{ext_id}/verify" \
  -X POST --data "@images.json" \
  -H "Authorization: Bearer {{token}}"

node.js

const axios = require('axios');
let data = JSON.stringify({
  "Images": [
    {
        "imageType": "frontal",
        "imageData": "{{base64_image}}"
    }
  ]
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.techtrue.com.br/api/v1/services/face/{ext_id}/verify',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{token}}'
  },
  data: data
};

axios(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error.response);
});

O comando acima retorna o seguinte JSON:

{
  "result": {
    "code": 1002,
    "message": "VERIFIED_SUCCESSFULLY"
  }
}

HTTP Request

POST /api/v1/services/face/{ext_id}/verify

Parameters

Name	Located in	Description	Required	Type
ext_id	path	Identificador único da face	Yes	string

HTTP Response

Code	Description
200	OK
401	Unauthorized

Body payload

{
  "doLivenessCheck": true,
  "Images": [
      {
          "imageType": "frontal",
          "imageData": "{{base64_string}}"
      }
  ]
}

Body payload

O parâmetro doLivenessCheck, quando passado com valor true, informa o serviço de que este deve executar o processo de avaliação de vivacidade de face sobre as imagens enviadas.

Caso a avaliação de vivacidade indique uma tentativa de ataque de apresentação, a requisição retorna erro no JSON.

Retorno em caso de erro do Liveness Check

{
  "result": {
    "code": 1013,
    "message": "LIVENESS_CHECK_FAILED",
    "detail": "liveness check failed"
  }
}

Identificar uma face

Endpoint que realiza a identificação (operação 1

) de uma face.

shell

curl "https://api.techtrue.com.br/api/v1/services/face/identify" \
  -X POST --data "@images.json" \
  -H "Authorization: Bearer {{token}}"

node.js

const axios = require('axios');
let data = JSON.stringify({
  "Images": [
    {
        "imageType": "frontal",
        "imageData": "{{base64_image}}"
    }
  ]
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.techtrue.com.br/api/v1/services/face/identify',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{token}}'
  },
  data: data
};

axios(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error.response);
});

O comando acima retorna o seguinte JSON:

{
  "ExternalID": "chad_smith",
  "result": {
    "code": 1008,
    "message": "IDENTIFIED_SUCCESSFULLY"
  }
}

HTTP Request

POST /api/v1/services/face/identify

Parameters

Name	Located in	Description	Required	Type
none

HTTP Response

Code	Description
200	OK
401	Unauthorized

Body payload

{
  "doLivenessCheck": true,
  "Images": [
      {
          "imageType": "frontal",
          "imageData": "{{base64_string}}"
      }
  ]
}

Body payload

O parâmetro doLivenessCheck, quando passado com valor true, informa o serviço de que este deve executar o processo de avaliação de vivacidade de face sobre as imagens enviadas.

Caso a avaliação de vivacidade indique uma tentativa de ataque de apresentação, a requisição retorna erro no JSON.

Retorno em caso de erro do Liveness Check

{
  "result": {
    "code": 1013,
    "message": "LIVENESS_CHECK_FAILED",
    "detail": "liveness check failed"
  }
}

Comparar duas faces

Endpoint que realiza a comparação de duas faces (1:1), sem a necessidade de realizar um cadastro prévio.

shell

curl "https://api.techtrue.com.br/api/v1/services/face/match" \
  -X POST --data "@images.json" \
  -H "Authorization: Bearer {{token}}"

node.js

const axios = require('axios');
let data = JSON.stringify({
  "Images": [
    {
        "imageType": "frontal",
        "imageData": "{{base64_image}}"
    },
    {
        "imageType": "frontal",
        "imageData": "{{base64_image}}"
    }
  ]
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.techtrue.com.br/api/v1/services/face/match',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{token}}'
  },
  data: data
};

axios(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error.response);
});

O comando acima retorna o seguinte JSON:

{
  "result": {
    "code": 1002,
    "message": "VERIFIED_SUCCESSFULLY"
  }
}

HTTP Request

POST /api/v1/services/face/match

Parameters

Name	Located in	Description	Required	Type
none

HTTP Response

Code	Description
200	OK
401	Unauthorized

Body payload

{
  "doLivenessCheck": true,
  "Images": [
      {
          "imageType": "frontal",
          "imageData": "<base64>"
      },
      {
          "imageType": "frontal",
          "imageData": "<base64>"
      }
  ]
}

Body payload

O parâmetro doLivenessCheck, quando passado com valor true, informa o serviço de que este deve executar o processo de avaliação de vivacidade de face sobre as imagens enviadas.

Nota

Como este endpoint deve ser utilizado para comparar uma selfie com uma face presente em um documento de identificação, a avaliação de vivacidade será realizada apenas na primeira imagem do vetor de imagens passado.

Caso a avaliação de vivacidade indique uma tentativa de ataque de apresentação, a requisição retorna erro no JSON.

Retorno em caso de erro do Liveness Check

{
  "result": {
    "code": 1013,
    "message": "LIVENESS_CHECK_FAILED",
    "detail": "liveness check failed"
  }
}