Integração do GBDS

Introdução

Este manual descreve brevemente cada fluxo padrão do GBDS 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 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:

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.

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.

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}).

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:

1. 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.

2. 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.

3. 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.

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.

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.

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.

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.

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).

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).

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:

• DATE:

• KEY:

• LABEL:

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.

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"
	}
}

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"
	}
}

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"
}

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
	}
}

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 é:

Exemplo:

1. 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:

      Copiar

      {
      	"operation": "ENROLL",
      	"tguid": "<TGUID 1>",
      	"status": "EXCEPTION"
      }

   3. Salve TGUID 1 e PGUID 1

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

   1. E a resposta é:

      Copiar

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

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

3. Cadastro 2 - TGUID 2;

   1. TGUID 2 casa com PGUID 0;

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

      Copiar

      {
      	"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
      	}
      }

4. 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

5. Um examinador resolve a exceção gerada no Passo 1:

   1. A aplicação é notificada com:

      Copiar

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

6. Envie um novo cadastro para o TGUID 2.

É 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).

Usando Coringas para Recuperar Informação do GBDS

Quando recupera-se informação do GBDS usando List Transactions e List People, é possível usar operadores coringas para filtrar os resultados.

Quando realiza-se uma chamada de List Transactions usando o parâmetro qualityStatus, os campos key, biographic, e label podem ser filtrados usando operadores conringas.

Os operadores coringas são descritos abaixo:

List Transactions

Sufixos

Os campos key ou biographic podem conter um id:value ou id|value, como por exemplo Name:John Doe, onde quatro sufixos podem ser inseridos.

• [anywhere]: Esse é o sufixo padrão, se nenhum for escrito, esse será selecionado. Nesse caso, a aplicação procurará pelo id ou valor fornecido em qualquer parte da string.

  Exemplo: Se a chave é name[anywhere]:rob, será procurado por nomes (name) como "Robbin" sobrenomes (surname) "Robarts".

• [atstart]: Se esse sufixo for usado, a aplicação procurará pelo id ou valor fornecido no início da string.

  Exemplo: Se a chave for passportNumber:123[atstart], será procurado por números de passaporte que começam com 123 e retornará todos casos válidos.

• [atend]: Se esse sufixo for usado, a aplicação procurará pelo id ou valor fornecido no final da string.

  Exemplo: Se a chave for passportNumber:123[atend], será procurado por números de passaporte que acabam com 123. name[atend]:son procurará por nomes (name) e sobrenomes (surname) que acabam com "son".

• [exact]: Se esse sufixo é usado, a aplicação procurará por casamentos identicos ao fornecido na string de procura.

  Exemplo: Se a chave for passportNumber:123[exact], será procurado por números de passaporte que são exatamente iguais a 123.

Prefixos

O campo de biograficos pode também ter um prefixo. Esse prefixo pode ser usado somente no PRIMEIRO biográfico, antes do id. Outros prefixos serão ignorados. Esse prefixo irá definir qual operação lógica a aplicação executará entre TODOS os campos de biográficos e de chaves. Os valores aceitos são [and] e [or], o primeiro sendo o valor padrão.

Exemplo: Se o biográfico é [or]id:value, uma operação OR será executada em todas as chaves e biográficos, como: (Key1 OR Biographic1 OR Biographic2).

Esse prefixo pode ser combinado com um sufixo, então valores como [or]id:value[exact] são aceitos.

List People

Quando realiza-se uma chamada de List People, o parâmetro operator pode ser tanto and ou or. O operador selecionado será aplicado nas comparações entre key, biographic e label. Após, uma comparação and será feita com o valor de data desejado para filtragem dos dados.

Exemplo: Se o operador selecionado for or, a comparação para filtragem dos dados será: ((Key1 OR Biographic1 OR Biographic2 OR Label1) AND Date).

Restrictions matchMode

Dentro do objeto de restrições (restrictions), é possível selecionar um de cinco matchMode quando a restrição for um Biográfico ou uma Chave. Os possíveis valores e suas operações estão listados abaixo.