/api/framework/v1/genericRecords/ - consulta genérica relacional

01. OBJETIVO

Fornecer meio de consultar e recuperar os dados para uma determinada consulta genérica relacional criada no sistema através de API REST.

Disponível a partir da lib 20201019.

02. COMO USAR

A partir de uma consulta .ngc criada no sistema é possível fazer a consulta usando o endpoint ilustrado no exemplo a seguir.

A consulta a seguir funciona para os casos que o arquivos está disponível dentro da pasta /system/ no sistema.
GET host:[port][/uri]/api/framework/v1/genericRecords/{arquivo_da_consulta[.ngc]}

exemplo retorno GET {fornecedores}

{
    "items": [
        {
            "a2_loja": "01",
            "a2_cgc": "89652306000136",
            "a2_cod": "0001",
            "a2_nome": "BENJAMIN E GUSTAVO FILMAGENS LTDA",
            "a2_filial": "00"
        },
        {
            "a2_loja": "01",
            "a2_cgc": "94330307000102",
            "a2_cod": "0002",
            "a2_nome": "ESTHER E MÁRIO TELECOMUNICAÇÕES LTDA",
            "a2_filial": "00"
        },
        {
            "a2_loja": "01",
            "a2_cgc": "75185866000113",
            "a2_cod": "0003",
            "a2_nome": "LORENA E GIOVANNI LIMPEZA LTDA",
            "a2_filial": "00"
        }
    ],
    "hasNext": true
}

É possível realizar a exploração da API utilizando os recursos convencionados pelo padrão de APIs Totvs (vide link nos assuntos relacionados).
E com isso é recomendado que sejam recuperados os campos utilizados pela aplicação cliente com o uso de: page, pageSize e fields.

Como exemplo, o resultado da requisição anterior teve o resultado resumido utilizando os seguintes valores para filtro:
- host:[port][/uri]/api/framework/v1/genericRecords/fornecedores_basica?fields=a2_filial, a2_cod, a2_loja, a2_nome, a2_cgc&page=1&pageSize=3
fornecedores_basica ==> nome da consulta criada no sistema
fields => lista de campos desejados no retorno da consulta
page => página de resultados desejada para o retorno dos valores
pageSize => quantidade de registros por página desejado
Para mais informações sobre estes controles na exploração dos dados veja o link nos assuntos relacionados.

03. SITUAÇÕES ESPECÍFICAS

Consultas gravadas em pastas fora da /system/

Para recuperar os dados de consultas que não têm o arquivo .ngc gravado na pasta system pode ser informado o caminho através da propriedade folder no header da requisição. Essa propriedade permite que seja indicado um caminho a partir do protheus_data onde a consulta deve ser encontrada.

Como exemplo considere que a consulta esteja na pasta .../protheus_data/consultas/uma_consulta_relacional.ngc é necessário informar a proriedade folder: /consultas/ para o funcionamento adequado e recuperação dos dados.

Consultas com tabelas relacionadas e sem campos escolhidos

Quando uma consulta com duas ou mais tabelas for criada e nenhum campo seja escolhido para a exibição será realizado o retorno somente dos campos da tabela principal (primeira tabela). Este comportamento tem o objetivo de evitar o tráfego exagerado de dados das tabelas que prejudica o processamento tanto pelo servidor quanto pelo cliente.

Portanto sempre escolha deliberadamente os campos para exibição nas consultas, assim consultas SQL com * são evitadas e o serviço terá um desempenho melhor.

04. ASSUNTOS RELACIONADOS

Guia de implementação de API V2.0

Páginas filhas