Registration

Antes da utilização do recurso de Validação Facial da API é necessário que seja feito o cadastro do cliente. Esta ação gerará uma entrada inicial no banco de dados que fornecerá uma imagem para ser usada como base durante a validação.

Definição de Objeto

Request Body

{        
    "registration_key": "ee37510e-4dfe-4b9c-b1f4-667288de2190",
    "document_number": "123.456.789-00",
    "image": {
        "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
        "file_size": 47407,
        "width_px": 0,
        "height_px": 0,
        "created_at": "2020-07-29T18:40:57Z",
    },
    "status": "indeterminate",
    "registration_status_events": [],
    "registration_date": "2020-07-29T18:40:57Z"
} 

Ao cadastrar um cliente, nossa API gerará um objeto JSON contendo todas as informações relacionadas a este cadastro. Esse objeto será utilizado como referência ao realizar o reconhecimento facial deste cliente antes de uma transação.

nome	tipo	descrição
registration_key	string	Chave do objeto Registration
document_number	string	CPF do cliente
image	image	Objeto que carrega as propriedades da imagem enviada no cadastro
status	string	Situação do cadastro do cliente
registration_status_events	registration_status_events	Objeto que carrega o histórico de modificação de status do cadastro
registration_date	datetime	Data de realização do cadastro em UTC

Dinâmica dos Status - status

Uma vez feito o cadastro de um cliente, será retornado sob a flag status a situação deste cadastro. Os resultados possíveis são:

Resultado	Descrição
authentic	Este cadastro possui histórico de transações concluídas com sucesso
undefined	Este cadastro não possui histórico de fraudes nem histórico de transações concluído com sucesso
fraud	Este cadastro possui histórico de fraudes associado

Criação de um Registration

Request Body: Envio simultâneo de imagem (Base64)

{
    "document_number": "123.456.789-00",
    "image": "base_64_image_code",
}

Request Body: Envio antecipado da imagem

{
    "document_number": "123.456.789-00",
    "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
}

Para efetuar o cadastro de um cliente, basta realizar o envio de um objeto JSON de cadastro com uma requisição POST no endpoint:

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

São suportados dois tipos objetos JSON de cadastro. Um em caso de envio prévio da imagem através do endpoint /image, e outro em caso de envio da imagem simultâneamente à requisição de cadastro.

nome	tipo	descrição
document_number	String	CPF do cliente
image	String	Base64 da imagem sem cabeçalhos ou informações adicionais
image_key	String	UUID4 retornado durante o envio da imagem pelo endpoint /image

Após o envio, será retornado um objeto Registration contendo os dados de cadastro do usuário.

Atenção - Ao efetuar o envio simultâneo da imagem com a realização do cadastro, esta será submetida aos mesmos testes de qualidade executados quando a imagem é enviada pelo endpoint /image. Assim, a imagem enviada está sujeita as mesmas regras descritas na sessão Imagem desta documentação.

Atualização dos Status - status

Request Body

{
    "registration_status": "fraud",
    "incident": "misappropriation",
    "event_date": "2029-08-25T13:34:12-03:00"                  
}

Para garantir a retroalimentação do banco de dados de fraudadores, é necessário informar ao sistema caso um cliente cometa qualquer tipo de fraude ou caso o cliente complete a sua primeira transação com sucesso.

Para isso, a atualização do status de cadastro de um cliente como fraudador deverá sem enviada uma requisição do tipo PUT para o endpoint:

https://api.caas.qitech.app/face_recognition/registration/{registration_key}/status

Os seguintes valores podem ser utilizados no campo incident, que indica o tipo de fraude cometida pelo cliente:

Enumerador	Descrição
misappropriation	Indivíduo realizou apropriação indébita sobre algum produto
misrepresentation	Indivíduo cadastrado sob documentos falsos ou de terceiros
successfull_transaction	Indivíduo completou uma transação com sucesso
status_restoration	Enumerador usado em casos que se deseja restaurar o status para undefined

Recuperação de objeto

Response Body

{        
    "registration_key": "ee37510e-4dfe-4b9c-b1f4-667288de2190",
    "document_number": "123.456.789-00",
    "image": {
        "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
        "file_size": 47407,
        "width_px": 0,
        "height_px": 0,
        "created_at": "2020-07-29T18:40:57Z",
    },
    "status": "fraud",
    "registration_status_events": [
        {
        "registration_status": "fraud",
        "incident": "misappropriation",
        "event_date": "2020-08-25T13:34:12Z"        
        }
    ],
    "registration_date": "2020-07-29T18:40:57Z"
}   

Em qualquer momento os dados de registro de um cliente poderão ser recuperados através de uma requisição GET ao endpoint:

https://api.caas.qitech.app/face_recognition/registration/{registration_key}