Introduction

Bem vindo à API de Reconhecimento Facial da Zaig! Você pode usar a nossa API para acessar os endpoints, cadastrar fotos de clientes e realizar o reconhecimento facial destes antes da execução de transações.

Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

Ambientes

Possuímos dois ambientes para os nossos clientes. A URL base das APIs são:

• Produção - https://api.caas.qitech.app/face_recognition/
• Sandbox - https://api.sandbox.caas.qitech.app/face_recognition/

Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da Zaig devem ser realizadas utilizando a comunicação HTTPS. Para garantir que, por desatenção ou qualquer outro motivo, não ocorram chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

Autenticação

Para autenticar uma chamada, utilize o código seguinte:

# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"

Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br.

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

Authorization: EXAMPLE_API_KEY

Imagem

O envio de uma foto de rosto é mandatório para a utilização de nossa API de reconhecimento facial. Visando garantir uma maior confiabilidade das análises executadas, é necessário que o cliente siga algumas regras na hora de tirar a foto:

• A foto deve conter apenas um rosto;
• Todo o rosto deve estar visível na foto;
• O rosto deve ocupar ao menos 15% da area da foto;
• O rosto deve estar encarando a câmera e paralelo a ela;
• O rosto deve estar com os olhos abertos;
• O rosto deve estar com a boca fechada;
• O rosto deve possuir expressão neutra e sem sorrisos;
• O rosto não deve estar coberto por nenhum tipo de acessório (chapéus, óculos ou máscaras).

Além disso, somente imagens .jpeg e .png com tamanho máximo de 3mb serão aceitas.

Envio de arquivos

Exemplo de envio de imagem

{
    "image": "base64_image_code"
}

Exemplo de retorno

{ 
    "image_key": "f4b5337a-7b50-406e-8c8e-7d0e77b5aa02",
    "file_size": 47407,
    "width_px": 0,
    "height_px": 0,
    "created_at": "2020-07-29T18:40:57Z"
}

Em casos que seja necessário o envio de uma imagem sem a execução imediata das rotinas de cadastro ou validação facial, um objeto JSON contendo o Base64 da imagem deve ser enviado. Para tal deve-se enviar uma requisição do tipo POST para o endpoint:

https://api.caas.qitech.app/face_recognition/image

Uma vez enviada, a imagem será submetida a testes de qualidade e, caso aprovada, será retornado um JSON contendo a chave de acesso à imagem. Essa chave deverá ser usada para referenciar a foto durante o cadastro ou validação facial.

Validação de qualidade da imagem

Exemplo de retorno em caso de imagem inválida

{
    "title": "image_quality",
    "description": "This image was not approved in quality assessment. The face is too close to image edges.",
    "image_status": "not_center"
}

Ao realizar um post no endpoint de imagem, caso a imagem não seja suficiente para validação, um HTTP Status Code 400 será retornado.

O valor do campo description é a mensagem que explica o motivo da imagem ser inválida.

Além disso, retornamos um enumerador image_status para que seja maepado o motivo da imagem ser inválida. Abaixo temos a listagem dos possíveis image_status:

Atenção - Existem outros motivos pelos quais retornaremos 400 (Todos relacionados a dados inválidos). Somente os retornos com title "image_quality" são resultantes da validação de qualidade da imagem e portanto devem ser repassados ao usuário.

Recuperação dos arquivos

Recuperação de imagem

    curl "https://api.caas.qitech.app/face_recognition/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \
         -H "Authorization: EXAMPLE_API_KEY"

Em qualquer momento é possível recuperar as imagens enviadas. Para isso, basta enviar uma requisição GET adequadamente autenticada no endpoint:

https://api.caas.qitech.app/face_recognition/image/{image_key}/file

Onde image_key é o valor retornado durante o envio da imagem.

Recuperação de arquivo processado

Recuperação de imagem processada

    curl "https://api.caas.qitech.app/face_recognition/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/cropped_file" \
         -H "Authorization: EXAMPLE_API_KEY"

Após a associação de uma imagem a um cadastro ou uma validação, essa imagem será processada e uma nova imagem contendo apenas o rosto utilizado nas rotinas de reconhecimento facial será gerada.

Esta imagem está disponível para ser recuperada através de uma requisição GET, adequadamente autenticada, no endpoint:

https://api.caas.qitech.app/face_recognition/image/{image_key}/cropped_file

Onde image_key é o valor retornado durante o envio da imagem base.

Recuperação dos meta-dados do arquivo

Recuperação de meta dados

    curl "https://api.caas.qitech.app/face_recognition/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02" \
         -H "Authorization: EXAMPLE_API_KEY"

Após o envio de uma imagem para a API, é possível recuperar os meta-dados da imagem utilizando o endpoint:

https://api.caas.qitech.app/face_recognition/image/{image_key}

Onde image_key é o valor retornado durante o envio da imagem.

Padrões

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

Data e Hora com Fuso Horário

Alguns exemplos:

2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.

A máscara utilizada para validação é a seguinte:

YYYY-MM-ddThh:mm:ss±hh:mm

Data e Hora sem Fuso Horario

Alguns exemplos:

2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

YYYY-MM-ddThh:mm:ssZ

Data

Alguns exemplos

2019-10-15
2019-01-01
2017-03-20

No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:

YYYY-MM-dd

Documentos

Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para definí-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.

CPF

Exemplos de CPFs válidos contra a máscara definida:

123.456.789-12
321.987.543-23
111.283.333-00

Exemplos de CPFs inválidos contra a máscara definida:

8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01

O CPF é sempre definido como uma string e será validado contra a máscara:

###.###.###-##

Status HTTP

Todas as APIs da Zaig utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231: