1. Introdução¶

Este manual descreve brevemente cada fluxo padrão do GBDS 4 como uma sequência de chamadas de API, que são pedidos HTTP/HTTPS para um servidor GBDS. Para referência completa das chamadas da API do GBDS, consulte o manual GBDS API specification.

O GBDS 4 provê notificações assíncronas para operações demoradas. Os fluxos de notificação estão detalhados no Manual de Fluxos de Notificação.

A autenticação para todas as chamadas de API é realizada com a apresentação de um token válido. Um novo token pode ser criado com a chamada createToken. Um token pode e deve ser usado para múltiplas chamadas. Criar um novo token antes de cada chamada afeta negativamente a performance do sistema.

Todos os diagramas neste manual seguem esta convenção:

Além disso, o GBDS segue um índice para identificação biométrica, conforme representado na tabela abaixo:

Índice	Biometria
0	Mínimo Esquerdo
1	Anelar Esquerdo
2	Médio Esquerdo
3	Indicador Esquerdo
4	Polegar Esquerdo
5	Polegar Direito
6	Indicador Direito
7	Médio Direito
8	Anelar Direito
9	Mínimo Direito
10	Face
13	Íris Esquerda
14	Íris Direita
20	Assinatura
31	Interdigital da Palmar Esquerda
32	Tenar da Palmar Esquerda
33	Hipotenar da Palmar Esquerda
34	Interdigital da Palmar Direita
35	Tenar da Palmar Direita
36	Hipotenar da Palmar Direita
40	Palmar Esquerda Completa
41	Writer da Palmar Esquerda
45	Palmar Direita Completa
46	Writer da Palmar Direita
200	Palmar Esquerda de Recém-Nascidos
210	Palmar Direita de Recém-Nascidos
900	Controle de Sequência - Mínimo Esquerdo
901	Controle de Sequência - Anelar Esquerdo
902	Controle de Sequência - Médio Esquerdo
903	Controle de Sequência - Indicador Esquerdo
904	Controle de Sequência - Polegar Esquerdo
905	Controle de Sequência - Polegar Direito
906	Controle de Sequência - Indicador Direito
907	Controle de Sequência - Médio Direito
908	Controle de Sequência - Anelar Direito
909	Controle de Sequência - Mínimo Direito
940	Controle de Sequência - Quatro Dedos Esquerdo
941	Controle de Sequência - Quatro Dedos Direito
942	Controle de Sequência - Dois Polegares

2. Fluxo de Cadastro (Enroll)¶

Neste caso, o usuário quer inserir uma nova pessoa no ABIS. Para tal, o usuário realiza uma chamada enroll (uma solicitação POST para o endpoint /gbds/v2/people).

Uma chamada de enroll bem-formada retornará uma resposta HTTP com um ID único de transação (tguid) como data.tguid e uma string de status em data.status.

O tguid será usado para identificar esta transação em chamadas futuras e notificações assíncronas.

O usuário será notificado quando o GBDS concluir o processamento da transação. O usuário também pode consultar o status da transação com a chamada getTransaction (uma solicitação GET para o endpoint /gbds/v2/people/transactions/{tguid}).

Se a transação for concluída com sucesso (status ENROLLED), um identificador único de pessoa (pguid) será gerado para operações de consulta como getPerson.

O status de uma transação de cadastro pode ser:

ENQUEUED

A transação foi enfileirada para processamento.

PROCESSING

A transação está sendo processada.

FAILED

A transação de cadastro não pôde ser completada. Esta situação é consequência de tratamento de exceção ou de tratamento de controle de qualidade.

EXCEPTION

O cadastro gerou pelo menos uma exceção, e a transação permanecerá neste estado até que a exceção seja tratada (pela aplicação GBS ETR ou programaticamente).

PENDING

O cadastro falhou no controle automático de qualidade, e a transação permanecerá neste estado até que a análise de qualidade seja realizada (pela aplicação GBS MIR ou programaticamente).

ENROLLED

O cadastro foi concluído com sucesso, e a transação é associdada a um identificador único de pessoa válido (pguid), que pode ser obtido com a chamada getTransaction.

REFUSED

A transação entrante foi recusada por ter casado com outra transação associada a uma ou mais exceções ativas pendentes.

3. Fluxo de Atualização (Update)¶

Neste caso, o usuário deseja atualizar os dados associados a uma pessoa já existente no ABIS. Se o usuário não tem o identificador de pessoa (pguid), ele deve obtê-lo usando uma chave biográfica ou um identificador de transação (tguid):

Para obter um pguid a partir de chaves biográficas, o usuário deve chamar getPGuidUsingKeys (uma solicitação GET para o endpoint /gbds/v2/people/pguid).

Para obter o pguid associado a um tguid conhecido, o usuário deve chamar getTransaction.

Para realizar a atualização, o usuário deve chamar update (uma solicitação PUT para o endpoint /gbds/v2/people/{pguid}).

Uma chamada de atualização bem-formada retornará uma resposta HTTP com um identificador único de transação (tguid) como data.tguid e uma string de status em data.status.

Chamadas de atualização que modifiquem dados biométricos serão processadas de modo similar a transações de cadastro (Enroll), podendo gerar exceções e análise de qualidade (status EXCEPTION e PENDING), e gerarão notificações para quem iniciou a transação. O status da transação também pode ser consultado com chamadas getTransaction.

Chamadas de atualização que modifiquem apenas dados biográficos serão processadas de forma síncrona. A resposta HTTP conterá apenas um status OK ou ERROR.

4. Fluxo de Verificação¶

Nesta caso, o usuário deseja realizar uma busca de Verificação (1:1), comparando dados biométricos a uma pessoa específica no ABIS. O alvo da busca deve ser identificado por um único pguid ou por uma chave biográfica.

Para realizar a verificação, o usuário deve chamar search (uma solicitação POST para o endpoint /gbds/v2/people/searches). O perfil alvo da comparação deve ser dado por uma chave biográfica no parâmetro data.keys ou por um pguid em data.pguids.

A resposta HTTP trará o resultado da verificação no campo data.status, que pode ser:

MATCH

Os dados biométricos fornecidos casaram com o registro da pessoa no ABIS.

NOT_MATCH

Os dados biométricos fornecidos não casaram com o registro da pessoa no ABIS.

PERSON_NOT_FOUND

A pessoa-alvo (pguid ou chave biográfica) não foi encontrada na base de dados.

Um identificador de transação (data.tguid) também será retornado, e maiores detalhes sobre a operação de verificação podem ser obtidos com a chamada getSearchResult (uma solicitação GET para o endpoint /gbds/v2/people/searches/{tguid}).

4.1. Verificação com Múltiplos GUIDs¶

O endpoint /gbds/v2/people/searches permite requisições de verificação com multiplos PGUIDs ou multiplos UGUIDs no caso de verificação de latentes.

Isso permite alguns novos recursos:

Verificação de vários PGUIDs
- Valida verificação com lista de pguids. Apenas se isUlSearch for definido como false.
- Valida verificação com lista de chaves, usando o atributo keys.
  - A lista filtra apenas uma pessoa.
  - Este recurso é válido apenas se isUlSearch for definido como false.
Verificação de vários UGUIDs usando isUlSearch=true.
- Usa o atributo uguids como uma lista de strings.
- Valida a verificação com esta lista de uguid. Apenas se isUlSearch for definido como true.
Pesquisa de latente em pguids/uguids
- A pesquisa de latente estará ativada se isLatentSearch definido como true para busca de pguids. Para busca de uguids o valor é sempre true.

5. Fluxo de Identificação¶

Neste caso, o usuário deseja realizar uma busca de Identificação (1:N), comparando dados biométricos para vários (possivelmente todos) registros no ABIS.

Para realizar a identificação, o usuário deve chamar search (uma solicitação POST para o endpoint /gbds/v2/people/searches) mantendo vazios os parâmetros data.keys e data.pguids.

Warning

No caso de uma busca de identificação, o atributo matcher DEVE ser definido como DEFAULT. Usar o valor MOBILE resultará no retorno de um erro ao usuário.

Buscas de identificação são realizadas de forma assíncrona. Uma chamada de busca bem-sucedida retornará uma resposta HTTP com um identificador de transação (data.tguid) e um status (data.status).

O usuário receberá uma notificação quando a busca for concluída. O usuário também pode consultar o status da transação com a chamada getSearchResult (uma solicitação GET para o endpoint /gbds/v2/people/searches/{tguid}).

O status da transação de busca pode ser:

ENQUEUED

A busca está enfileirada, e ainda não começou a ser processada.

PREPARED, PROCESSING

Estes valores indicam que a busca está sendo processada.

MATCH

A busca foi processada, e pelo menos um casamento foi encontrado. Os casamentos são retornados no campo data.cadidates da resposta a getSearchResult.

NOT_MATCH

A busca foi processada e nenhum casamento foi encontrado.

PERSON_NOT_FOUND

O domínio de busca estava vazio: o filtros especificados, como lista de pguids e/ou filtros de labels resultaram em um conjunto vazio de candidatos.

6. Fluxos de Recuperação de Cadastro¶

Essa seção apresentará os fluxos para recuperar informações de perfis usando o GBDS. Para opções avançadas de filtragem nas chamadas de listPeople e listTransactions, consulte o Manual Usando Coringas para Recuperar Informação do GBDS.

6.1. Recuperando o Cadastro de uma Única Pessoa¶

Para obter os dados mais atuais associados a uma pessoa específica, o usuário deve chamar getPerson (uma solicitação GET para o endpoint /gbds/v2/people/{pguid}).

A resposta HTTP conterá os dados biográficos da pessoa e a mais recente transação de cadastro (Enroll) associada a ela.

6.2. Obtendo o Pguid a partir de Chaves Biográficas¶

Para obter o identificar único de uma pessoa (pguid) a partir de uma chave biográfica, o usuário deve chamar getPguidUsingKeys (uma solicitação GET para o endpoint /gbds/v2/people/pguid).

6.3. Obtendo o Pguid a partir de Dados Biográficos¶

Para obter uma lista de identificadores de pessoa (pguids) que casam dados biográficos (e não apenas chaves), o usuário pode chamar listPeople (uma solicitação POST para o endpoint /gbds/v2/people/list).

Note

É possível realizar uma chamada de listPeople fornecendo somente o “valor” que será usado para filtrar por chave ou biográfico.

Warning

Esse formato de solicitação só pode ser usada para listas filtradas por chaves ou biográficos. Se o critério de filtragem for qualquer outro campo, deve ser especificado no formato de “campo:valor”.

6.3.1. Critérios do Campo Restriction¶

É possível realizar uma chamada de listPeople fornecendo os critérios para filtrar a lista retornada. O campo restriction deve conter um array de objetos que variam de acordo com o tipo de dado (representado pelo campo type) usado como patâmetro de filtragem. Cada chamada pode conter uma ou mais restrições, os tipos aceitos são: BIOGRAPHIC, DATE, KEY e LABEL. Os objetos para cada tipo são listados abaixo:

BIOGRAPHIC:

Campo	Requerido	Tipo
type	Sim. O valor DEVE ser BIOGRPAHIC	String
id	Sim	String
value	Sim	String
exists	Sim. Padrão true.	Boolean
matchMode	Padrão EXACT. Enum: - START - EXACT - ANYWHERE - END - NOT_EQUALS	String

DATE:

Campo	Requerido	Tipo
type	Sim. O valor DEVE ser DATE	String
startTime	Sim. Deve estar em milisegundos.	String
endTime	Não. Deve estar em milisegundos	String

KEY:

Campo	Requerido	Tipo
type	Sim. O valor DEVE ser KEY	String
id	Sim	String
value	Sim	String
exists	Sim. Padrão true.	Boolean
matchMode	Padrão EXACT. Enum: - START - EXACT - ANYWHERE - END - NOT_EQUALS	String

LABEL:

Campo	Requerido	Tipo
type	Sim. O valor DEVE ser KEY	String
label	Sim	String
exists	Sim. Default true.	Boolean

7. Fluxo de Transações Recusadas (REFUSED)¶

O resultado REFUSED irá ocorrer em atualizações e cadastros quando uma nova transação casar com uma transação existente que estiver associada a uma exceção biométrica pendente.

7.1. Transações Síncronas¶

Quando uma transação é submetida a uma operação síncrona, a resposta conterá um campo data.status com o valor REFUSED:

{
  "data":
  {
         "status":"REFUSED",
         "tguid": "string"
  }
}

7.2. Transações Assíncronas¶

No caso de uma transação de cadastro submetida assincronamente, a resposta conterá um campo data.status com o valor ENQUEUED:

{
  "data":
  {
         "status":"ENQUEUED",
         "tguid": "string"
  }
}

7.2.1. Recebendo a Notificação¶

Quando o GBDS finaliza o processamento de uma transação, o GBS Notifier envia uma notificação a um endpoint configurado com o TGUID e o resultado do processamento (status) da transação. Se a transação for recusada, o Notifier mandará uma notificação no formato:

{
   "operation": "ENROLL",
   "tguid": "string",
   "status": "REFUSED"
}

ou

{
   "operation": "UPDATE",
   "tguid": "string",
   "status": "REFUSED"
}

Important

Depois de receber a notificação de uma transação recusada (REFUSED), uma chamada de getTransaction deve ser submetida ao GBDS com o TGUID como parâmetro para que possa se obter os detalhes envolvendo a transação e suas exceções.

A operação de getTransaction é descrita na próxima seção, enquanto a informação sobre como tratar uma transação recusada é descrita na seção Tratando uma Transação Recusada.

7.2.2. Realizando Consulta Ativa¶

Para realizar consulta ativa para obter os resultados de uma transação, uma chamada de getTransaction deverá ser submetida ao GBDS com o TGUID do cadastro como um parâmetro com o seguinte endpoint:

http://<ip>:8085/gbds/v2/people/transactions/{tguid}

O resultado dessa chamada conterá um campo data.status com o valor REFUSED, como mostrado no exemplo abaixo:

{
   "data":
   {
         "tguid": "string",
         "pguid": "string",
         "status": "REFUSED",
         "timestamp": 0,
         "progress": 0,
         "Candidates": [],
         "Person": {},
         "qualityAnalysis": {},
         "failReason": "Enroll matches 2 person(s) that are already involved in a pending exception. PGUIDs: 75ABF575-6825-41D7-A2A7-2C0D64CF9FE7, B393C481-C0AF-456C-9155-1510AFDC7D86",
         "isCurrentTransaction": false
   }
 }

7.3. Tratando uma Transação Recusada (REFUSED)¶

Como mencionado previamente, uma transação recusada ocorre quando um perfil entrante casa com um existente que está vinculado a uma exceção ativa. Quando uma transação finaliza com esse status, o perfil entrante é descartado e uma nova transação deve ser submetida para esse perfil após as exceções ativas pendentes serem tratadas.

Depois de identificar o cadastro recusado e executar as chamadas de getTransaction, o campo “failReason” da resposta do getTransaction conterá os PGUIDs do perfil de referência que o perfil entrante casou. A quantidade de PGUIDs retornada na resposta é ilimitada e separada por vírgulas.

Depois que todas as exceções forem tratadas, o cadastro recusado pode ser ressubmetido.

O fluxo de trabalho completo para resolver com cadastros recusados é:

Important

O mesmo fluxo de trabalho pode ser usado para resolver atualizações recusadas usando os comandos equivalentes.

Exemplo:

Cadastro 1 - Gera TGUID 1 e PGUID 1;
1. TGUID 1 - cria uma exceção biométrica com um PGUID 0 já existente;
2. A aplicação é notificada com:
```
{
    "operation": "ENROLL",
    "tguid": "<TGUID 1>",
    "status": "EXCEPTION"
}
```
1. Salve TGUID 1 e PGUID 1

A aplicação executa GET /gbds/v2/exceptions/{tguid}

E a resposta é:

{
   "data": [
   {
      "transactionTimestamp": 0,
      "match": {
         "matchedPersonPguid": "PGUID 0",
         "matchedPersonTguid": "TGUID 0",
         "biometricMatches": []
      }
   }
   ],
   "pagination": {
   "total": 0,
   "count": 0,
   "pageSize": 0,
   "currentPage": 0,
   "totalPages": 0
   }
}

Crie e salve um mapeamento artificial do PGUID 0 ao PGUID 1 / TGUID 1

Cadastro 2 - TGUID 2;

TGUID 2 casa com PGUID 0;
TGUID 2 - recebe status REFUSED porque casou com o PGUID 0 que já estava vinculado a uma exceção;

{
    "data":
    {
        "tguid": "string",
        "pguid": "string",
        "status": "REFUSED",
        "timestamp": 0,
        "progress": 0,
        "Candidates": [],
        "Person": {},
        "qualityAnalysis": {},
        "failReason": "Enroll matches 1 person(s) that are already involved in a pending exception. PGUIDs: PGUID 0",
        "isCurrentTransaction": false
    }
}

Salve o PGUID <PGUID 0> associado com TGUID 2;
1. Atualize o mapeamento indicando que PGUID 0 / PGUID 1 / TGUID 1 / TGUID 2 estão vinculados

Um examinador resolve a exceção gerada no Passo 1: a. A aplicação é notificada com:

{
    "operation": "TREAT_EXCEPTION",
    "tguid": "<TGUID 1>",
    "status": "OK",
    "treatment": "TREATMENT_OPTION"
}

Envie um novo cadastro para o TGUID 2.

Warning

É possível que um PGUID que casou ter multiplas exceções vinculadas a ele. Nesse cenário, todas exceções para o PGUID devem ser tratadas antes de tentar ressubmeter o cadastro ou atualização recusada.

É importante mencionar que o fluxo de trabalho acima deve ser implementado para completar automaticamente as transações sem nenhuma intervenção manual.

Em outras palavras, para obter o resultado final para essa transação (TGUID 2), é necessário aguardar a notificação do GBS Notifier informando o tratamento da exceção para a exceção existente (TGUID 1) e executar a chamada de getTransaction para recuperar a informação sobre os PGUIDs que casaram do GBDS (veja as seções Recebendo a Notificação e Realizando Consulta Ativa).