Regras de negócio

A API possui um serviço genérico para aplicar consultas em todas as Entidades disponíveis no ERP: CRUDServiceProvider.loadRecords. Por definição, uma entidade mapeia uma tabela que está no banco de dados, vejamos a seguir alguns exemplos de Entidade:
• Entidade Produtos mapena a tabela TGFPRO
• Entidade Parceiros mapeia a tabela TGFPAR

Exemplo de uso:

• URL Gateway Produção: https://api.sankhya.com.br/
• URL Gateway Sandbox: https://api.sandbox.sankhya.com.br/

URL de chamada: https://[URL_GATEWAY]/gateway/v1/mge/service.sbr?serviceName=CRUDServiceProvider.loadRecords&outputType=json
Vejamos a seguir a estrutura completa de uma requisição do serviço loadRecords:

{
    "serviceName": "CRUDServiceProvider.loadRecords",
    "requestBody": {
        "dataSet": {
            "rootEntity": "Produto",
            "ignoreCalculatedFields": "true",
            "useFileBasedPagination": "true",
            "includePresentationFields": "N",
            "tryJoinedFields": "true",
            "modifiedSince": "2024-04-16T12:59:59",
            "offsetPage": "0",
            "criteria": {
                "expression": {
                  "$": "CODPROD IN ( ?, ? ) AND DESCRPROD LIKE '%?%'"
                },
                "parameter": [
                    {
                        "$": "1",
                        "type": "I"
                    },
                    {
                        "$": "2",
                        "type": "I"
                    },
                    {
                        "$": "QUEIJO",
                        "type": "S"
                    }
                ]
            },
            "entity": [
                {
                    "path": "",
                    "fieldset": {
                        "list": "CODPROD, DESCRPROD"
                    }
                },
                {
                    "path": "GrupoProduto",
                    "fieldset": {
                        "list": "CODGRUPOPROD, DESCRGRUPOPROD"
                    }
                }
            ]
        }
    }
}

Agora, vamos detalhar as propriedades utilizadas:

• serviceName: nome do serviço e por padrão, sempre será: CRUDServiceProvider.loadRecords rootEntity: nome da entidade a ser consultada.
• modifiedSince: faz referência a funcionalidade de logAlteracoesTabelas (clique aqui para mais detalhes sobre o recurso de LogAlteracoesTabelas). Quando esta funcionalidade está habilitada, é possível trazer apenas registros que tiveram alteração a partir de uma determinada data/hora. Vale ressaltar que este parâmetro é opcional, e ao enviar valores o serviço irá considerar “apenas” registros contidos no logAlteracoesTabelas. Caso não tenha informações logadas no sistema, o retorno do serviço será vazio (ZERO registros).
• ignoreCalculatedFields: quando configurado como `true`, os campos calculados são ignorados e apenas os campos persistidos em banco são retornados, reduzindo o volume de processamento e aumentando a performance da consulta. O valor padrão é false, ou seja, por padrão os campos calculados são incluídos no resultado.
• useFileBasedPagination: este atributo habilita a paginação baseada em disco. O padrão é utilizar memória do servidor para fazer paginações. É indicado para consultas com grande volume de dados (superior a 1000 páginas). Quando configurado como `true`, o processamento passa a ser realizado em disco, garantindo maior estabilidade e performance em cenários massivos. O valor padrão é false, mantendo a paginação tradicional para consultas comuns.
• offsetPage: indica a página a ser retornada. A página tem início em 0 (zero) e novas requisições devem ser realizadas, incrementando este valor, sempre que o retorno indicar mais registros através do parametro "hasMoreResult" com valor "true".
• criteria -> expression: condição da consulta. Sempre que houver "parâmetros" variáveis, deve ser utilizado os parâmetros (parameter) para indicar os valores para critério da consulta.
• criteria -> parameter: deve ser informado os valores para os parâmetros utilizados na consulta (clique aqui para mais detalhes sobre o recurso de critérios nos filtros).
• entity: são indicados os campos a serem retornados na consulta. Os campos estão disponíveis no Dicionário de Dados para identificar quais campos serão necessários em cada entidade consultada. Esta propriedade também permite obter informações de entidades com ligação direta ao registro consultado. Ex.: para buscar um parceiro, através do CODBAI é possível trazer na consulta o nome do bairro. Isso se aplica a qualquer informação com ligação similar a esta (cidade, endereço, perfil, etc.). Clique aqui e para mais detalhes sobre "join" de dados nas consultas.

Vejamos agora um exemplo de consulta de parceiros do tipo "Cliente" realizado na entidade "Parceiro":

{
    "serviceName": "CRUDServiceProvider.loadRecords",
    "requestBody": {
        "dataSet": {
            "rootEntity": "Parceiro",
            "ignoreCalculatedFields": "true",
            "useFileBasedPagination": "true",
            "includePresentationFields": "N",
            "tryJoinedFields": "true",
            "offsetPage": "0",
            "criteria": {
                "expression": {
                  "$": "CLIENTE = ?"
                },
                "parameter": [
                    {
                        "$": "S",
                        "type": "S"
                    }
                ]
            },
            "entity": [
                {
                    "path": "",
                    "fieldset": {
                        "list": "CODPARC, NOMEPARC, NUMEND, COMPLEMENTO, CEP"
                    }
                },
                {
                    "path": "Endereco",
                    "fieldset": {
                        "list":"CODEND, TIPO, NOMEEND"
                    }
                },
                {
                    "path": "Bairro",
                    "fieldset": {
                        "list": "CODBAI, NOMEBAI"
                    }
                },
                {
                    "path": "Cidade",
                    "fieldset": {
                        "list": "CODCID, NOMECID, UF"
                    }
                }
            ]
        }
    }
}