# 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](https://docs.griaule.com/apis/).
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](/integracao-do-gbds/notifier.md).
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](https://gitbook.griaule.com/apis/gbds-4/tokens#post-tokens). 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 |
## 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](https://gitbook.griaule.com/apis/gbds-4/people#post-people) (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](/integracao-do-gbds/notifier.md) 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](https://gitbook.griaule.com/apis/gbds-4/transaction#get-people-transactions-tguid) (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](https://gitbook.griaule.com/apis/gbds-4/people#get-people-pguid-1) (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](https://gitbook.griaule.com/apis/gbds-4/transaction#get-people-transactions-tguid).
Para realizar a atualização, o usuário deve chamar [update](https://gitbook.griaule.com/apis/gbds-4/people#put-people-pguid) (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](https://gitbook.griaule.com/apis/gbds-4/searches#post-people-searches) (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](https://gitbook.griaule.com/apis/gbds-4/searches#get-people-searches-tguid) (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](https://gitbook.griaule.com/apis/gbds-4/searches#post-people-searches) (uma solicitação *POST* para o endpoint */gbds/v2/people/searches*) mantendo vazios os parâmetros **data.keys** e **data.pguids**.
{% hint style="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.
{% endhint %}
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](https://gitbook.griaule.com/apis/gbds-4/searches#get-people-searches-tguid) (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](#usando-coringas-para-recuperar-informacao-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](https://gitbook.griaule.com/apis/gbds-4/people#get-people-pguid) (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](https://gitbook.griaule.com/apis/gbds-4/people#get-people-pguid-1) (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](https://gitbook.griaule.com/apis/gbds-4/people#post-people-list) (uma solicitação *POST* para o endpoint */gbds/v2/people/list*).
{% hint style="info" %}
É possível realizar uma chamada de listPeople fornecendo somente o `valor` que será usado para filtrar por chave ou biográfico.
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`.
{% endhint %}
#### Critérios do Campo Restriction
É possível realizar uma chamada de [listPeople](https://gitbook.griaule.com/apis/gbds-4/people#post-people-list) 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 |
## 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*:
```json
{
"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*:
```json
{
"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:
```json
{
"operation": "ENROLL",
"tguid": "string",
"status": "REFUSED"
}
```
ou
```json
{
"operation": "UPDATE",
"tguid": "string",
"status": "REFUSED"
}
```
{% hint style="warning" %}
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](#tratando-uma-transacao-recusada-refused).
{% endhint %}
#### 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://:8085/gbds/v2/people/transactions/{tguid}`
O resultado dessa chamada conterá um campo `data.status` com o valor *REFUSED*, como mostrado no exemplo abaixo:
```json
{
"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 é:
{% hint style="warning" %}
O mesmo fluxo de trabalho pode ser usado para resolver atualizações recusadas usando os comandos equivalentes.
{% endhint %}
**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:
```json
{
"operation": "ENROLL",
"tguid": "",
"status": "EXCEPTION"
}
```
3. Salve TGUID 1 e PGUID 1
2. A aplicação executa GET /gbds/v2/exceptions/{tguid}
1. E a resposta é:
```json
{
"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;
```json
{
"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 `` 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:
```json
{
"operation": "TREAT_EXCEPTION",
"tguid": "",
"status": "OK",
"treatment": "TREATMENT_OPTION"
}
```
6. Envie um novo cadastro para o TGUID 2.
{% hint style="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.
{% endhint %}
É 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](#recebendo-a-notificacao) e [Realizando Consulta Ativa](#realizando-consulta-ativa)).
## Usando Coringas para Recuperar Informação do GBDS
Quando recupera-se informação do GBDS usando [List Transactions](https://gitbook.griaule.com/apis/gbds-4/transaction#get-people-transactions) e [List People](https://gitbook.griaule.com/apis/gbds-4/people#post-people-list), é possível usar operadores coringas para filtrar os resultados.
Quando realiza-se uma chamada de [List Transactions](https://gitbook.griaule.com/apis/gbds-4/transaction#get-people-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.
{% hint style="warning" %}
Esses operadores coringa são **SUFIXOS**, então eles devem ser inseridos DEPOIS do ID e/ou DEPOIS do VALOR.
{% endhint %}
{% hint style="info" %}
Adicionalmente, id e valor podem ter diferentes sufixos para cada, então é possível haver operações como: `name[exact]:rob[atstart]`, onde será procurado por campos que são nomeados exatamente `name` por valores que começam com "rob".
{% endhint %}
#### 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](https://gitbook.griaule.com/apis/gbds-4/people#post-people-list), 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.
{% hint style="danger" %}
Tudo o que não é uma letra, um número ou um sublinhado é um separador. Um separador entre números ou letras causará a tokenização da palavra/número completo em todos os modos, exceto EXACT e NOT\_EQUALS.
{% endhint %}
{% hint style="warning" %}
No valor do filtro de restrição, apenas o espaço em branco \`\` \`\` é um delimitador e tokenizará as palavras/números. Esse comportamento não ocorre em EXACT e NOT\_EQUALS.
{% endhint %}
{% hint style="warning" %}
O parâmetro de pesquisa é sensível a caracteres especiais em letras, como â, é, ñ e outros.
{% endhint %}
{% stepper %}
{% step %}
#### EXACT
A operação *exact* pesquisa todo o valor fornecido. O uso de *exact* não tokenizará a expressão restrita. Este modo diferencia maiúsculas de minúsculas.
* Exemplo: A chamada deve retornar o valor "Jose Arruda". Usar EXACT com "Jose" ou "Arruda" funcionará para retornar o valor desejado.
{% hint style="info" %}
Pesquisas como "Jo" ou "rrud" não retornarão Jose Arruda.
{% endhint %}
* Examplo 2: A chamada deve retornar um valor numérico de um documento, como "123456". Usando EXACT o valor DEVE ser "123456".
{% hint style="info" %}
Pesquisas com o valor "123" ou "456" não retornarão o valor correto.
{% endhint %}
{% hint style="warning" %}
Se o valor for armazenado com um separador, o separador deverá estar no valor de restrição.
{% endhint %}
{% endstep %}
{% step %}
#### START
A operação de *start* filtrará os valores tokenizando cada palavra ou conjunto de números dividido por um separador.
* Exemplo: Se o usuário está restringindo START para o valor "Jo", alguns retornos possíveis podem ser:
```default
Jose Arruda
John Doe
Marie Johnson
```
* Exemplo 2: Caso o usuário esteja restringindo START para o valor "Jose Arruda", alguns retornos possíveis podem ser:
```default
Jose Arruda
Jose Silva
Pedro Thomas Arruda
```
* Exemplo 3: Se o usuário estiver restringindo START para o valor "123", alguns retornos possíveis podem ser:
```default
1234567
123.456
456-123
a-b 123
```
* Exemplo 4: Se o usuário está restringindo START para o valor "123.456", alguns retornos possíveis podem ser:
```default
123.456
123.456.789-90
```
{% endstep %}
{% step %}
#### ANYWHERE
A operação em *anywhere* buscará o valor em qualquer parte da palavra ou número.
* Exemplo: Se a restrição do usuário for ANYWHERE para o valor "Jo", alguns retornos possíveis podem ser:
```default
Jose Arruda
Major
Pejorative
Banjo
```
* Exemplo 2: Pesquisar por "12" pode retornar:
```default
123456
641256
114-4312
a-b 123
```
* Exemplo 3: Se a restrição do usuário for ANYWHERE para o valor "Jo Ru", alguns retornos possíveis podem ser:
```default
Jose Arruda
Ruth Silva
Havier Russel
```
{% endstep %}
{% step %}
#### END
A operação *end* buscará o valor no FIM do token. Como START, esta operação tokenizará as palavras/números para cada separador.
* Exemplo: Se a restrição do usuário END para o valor "son", alguns retornos possíveis podem ser:
```default
Eric Johnson
Hudson Santos
```
* Exemplo 2: Se o usuário estiver restringindo END para o valor "Jose Arruda", alguns retornos possíveis podem ser:
```default
Jose Arruda
Jose Silva
Pedro Thomas Arruda
Arruda Bastos
```
* Exemplo 3: Se o usuário estiver restringindo END para o valor "123", alguns retornos possíveis podem ser:
```default
4567123
123.456
456-123
a-b 123
```
* Exemplo 4: Se o usuário estiver restringindo END para o valor "123.456", alguns retornos possíveis podem ser:
```default
123.456
789.123.456
```
{% endstep %}
{% step %}
#### NOT\_EQUALS
A operação *Not equals* funciona de modo inverso à operação EXACT. Ele filtrará e DESCARTARÁ correspondências exatas para o valor fornecido e mostrará TODOS OS OUTROS valores. Este modo diferencia maiúsculas de minúsculas.
* Exemplo: Usando NOT\_EQUALS com o valor "Jose" pode retornar:
```default
John Doe
Marie Johnson
Josemar Rodrigues
```
* Exemplo 2: Usar NOT\_EQUALS com o valor "123" pode retornar:
```default
4567123
123456
```
{% endstep %}
{% endstepper %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.griaule.com/integracao-do-gbds/gbsintegration.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.