AGR Publicação do Cadastro de Fardão WS REST

PUBLICAÇÃO WEB SERVICE REST DO CADASTRO DE FARDÃO

Características do Requisito

Pré-requisito

  No que diz respeito ao sistema, a funcionalidade de integração está funcional. Porém, é necessário configurar o AppServer para que o Protheus disponibilize a URL de acesso ao serviço de Web Service REST do sistema. Uma vez configurado o serviço, a integração está pronta para ser utilizada.

  Para isso, segue link para consulta: 1. Configuração do REST do Protheus

Descrição

  Para os usuários que possuem algum aplicativo customizado, e que precisam efetuar o cadastro de fardão no produto Gestão Agroindústria (SIGAAGR), foi disponibilizado o método Web Service REST. 

Método Publicado

Exemplo de Utilização

Para realizar testes, pode-se utilizar qualquer programa de sua preferência, que teste API Web Service REST. O SoapUI e a extensão Postman do Navegador Chrome são exemplos de bons programas para isso. 

Inserindo um registro

Abaixo, uma persistência de dados, pelo método Post, na tabela DXL (Cadastro de fardão).

No exemplo acima, a operação foi concluída com sucesso. O retorno da operação, parte de baixo da imagem, é o registro que foi inserido no banco.

Abaixo, um caso em que o modelo impede a gravação do registro por conter algum dado inconsistente. No caso em questão, a safra não existe no banco de dados.

Consultando informações

Abaixo, uma consulta dos dados da tabela DXL através do método GET.

Caso se deseje filtrar os resultados que serão trazidos, basta colocar as regras nos params.

Existem várias possibilidades de se restringir quais dados o GET irá retornar. Segue link da documentação relativa a este assunto: http://tdn.totvs.com.br/pages/viewpage.action?pageId=271671548

Segue, para consulta, a estrutura JSON que foi utilizada como exemplo para a confecção deste documento.

{
     "id": "AGRA601",
     "operation": 3,
     "models": [
          {
               "id": "DXLMASTER",
               "modeltype": "FIELDS",
               "fields": [
                   {
                         "id": "DXL_SAFRA",
                         "order": 4,
                         "value": "2017"
                   },
                   {
                         "id": "DXL_CODPRO",
                         "order": 5,
                         "value": "00001"
                   },
                   {
                         "id": "DXL_PRDTOR",
                         "order": 6,
                         "value": "000001"
                   },
                   {
                         "id": "DXL_LJPRO",
                         "order": 7,
                         "value": "01"
                   },
                   {
                         "id": "DXL_FAZ",
                         "order": 9,
                         "value": "01"
                   },
                   {
                         "id": "DXL_TALHAO",
                         "order": 11,
                         "value": "TL0001"
                   },
                   {
                         "id": "DXL_CODVAR",
                         "order": 12,
                         "value": "000001"
                   },
                   {
                         "id": "DXL_LOCAL",
                         "order": 14,
                         "value": "01"
                   },
                   {
                         "id": "DXL_BORDA",
                         "order": 18,
                         "value": "2"
                   },
                   {
                         "id": "DXL_RDMTOP",
                         "order": 19,
                         "value": "40.00"
                   },
                   {
                         "id": "DXL_TPRENS",
                         "order": 21,
                         "value": "1"
                   },
                   {
                         "id": "DXL_STATUS",
                         "order": 32,
                         "value": "1"
                   }
              ]
          }
     ]
}

Dados técnicos

• Sobre a estrutura JSON esperada, pode ser dividida em 3 partes, sendo elas:

1. "id": "AGRA601",

           "operation": 3,

           "models": [

                 O ID refere-se ao nome do programa que está sendo chamado no Protheus. Por padrão, os programas no Protheus que possuem disponibilização de web service são publicados com o nome do fonte.

                 Operation refere-se a qual operação (operações padrões do MVC do ADVPL) será efetuada. Isso está diretamente ligado com a operação de REST que será efetuada, no exemplo acima a operação 3 se refere a uma inserção, então a operação REST que será efetuada é um POST. Como a operação é um POST, a inserção indifere da informada, contudo, ela precisa ser informada.     

                 Models refere-se a quais modelos, existentes na rotina publicada, serão manipulados.

Essa definição ocorre logo na segunda parte.

1. "id": "DXLMASTER",

           "modeltype": "FIELDS",

           "fields": [

                 Aqui, o ID se refere ao nome do Modelo que está contido na rotina que está sendo manipulada. Neste caso, DXLMASTER é o único modelo dp AGRA601.

                 Modeltype se refere ao tipo do modelo no Protheus: Field ou Grid.

                No caso em questão, o modelo é um Field, então os campos a serem preenchidos devem ser informados logo abaixo, na terceira parte da estrutura.

1. "id": "DXL_SAFRA",

          "order": 4,

          "value": "2017"

                 Nesta etapa, ID refere-se ao nome do campo na tabela referente à rotina.

                 Order indica a ordem deste campo definido no dicionário de dados.

                 Value é o valor que será inserido neste campo.

  Vale ressaltar que todas as validações do modelo são feitas automaticamente pelo Protheus, ou seja, caso algum dado esteja errado ou incoerente, o sistema envia uma mensagem de erro, em formato JSON, e a operação não é concluída.

• OBS: os campos citados são referentes a tabela DXL que é a tabela de cadastro de fardão. Todos os campos desta tabela podem ser consultados pelo configurador.
• Campos mínimos necessários (Chave da tabela): DXL_FILIAL, DXL_CODIGO, DXL_SAFRA, DXL_PRDTOR, DXL_LJPRO, DXL_FAZ.   
• O campo DXL_CODIGO, caso não seja informado, assume o incremental e persiste com a próxima numeração do banco. Caso ele seja informado no POST, o registro é gravado com o código informado.
• Na tela do Protheus, alguns campos são preenchidos através de perguntes. Com exceção dos campos que compõem a chave, são eles: DXL_CODPRO, DXL_LOCAL, DXL_BORDA, DXL_TPPRENS, DXL_PSESTI, DXL_RDMTOP, DXL_OBS. Caso esses campos não sejam informados no POST, o sistema assume os valores que estão selecionados no Protheus para preencher estes campos no momento da inserção. Caso o valor deles seja informado, o valor que está no JSON predomina.

Campo: DXL_FILIAL, Tipo: Caracter, Tamanho: 2, Descrição: Filial do Sistema;

Campo: DXL_CODIGO, Tipo: Caracter, Tamanho: 6, Descrição: Código do Fardão;

Campo: DXL_DTDIGI, Tipo: Data, Tamanho: 8, Descrição: Data de Digitação;

Campo: DXL_SAFRA, Tipo: Caracter, Tamanho: 15, Descrição: Safra;

Campo: DXL_CODPRO, Tipo: Caracter, Tamanho: 15, Descrição: Código do Produto;

Campo: DXL_PRDTOR, Tipo: Caracter, Tamanho: 6, Descrição: Código da Entidade;

Campo: DXL_LJPRO, Tipo: Caracter, Tamanho: 2, Descrição: Loja da Entidade;

Campo: DXL_FAZ, Tipo: Caracter, Tamanho: 2, Descrição: Fazenda de Produção;

Campo: DXL_TALHAO, Tipo: Caracter, Tamanho: 16, Descrição: Talhão de Produção;

Campo: DXL_CODVAR, Tipo: Caracter, Tamanho: 6, Descrição: Variedade do Algodão;

Campo: DXL_LOCAL, Tipo: Caracter, Tamanho: 2, Descrição: Local do Estoque;

Campo: DXL_PSESTI, Tipo: Numérico, Tamanho: 11 Inteiros e 2 Decimais, Descrição: Peso Estimado do Fardão;

Campo: DXL_BORDA, Tipo: Caracter, Tamanho: 1, Descrição: Alg. de Beira de Estrada;

Campo: DXL_TPRENS, Tipo: Caracter, Tamanho: 1, Descrição: Tipo de prensagem;

Campo: DXL_STATUS, Tipo: Caracter, Tamanho: 2, Descrição: Status do Fardão (1=Previsto;2=Em Romaneio;3=Disponivel;4=Em Beneficiamento;5=Beneficiado;6=Finalizado );

Campo: DXL_CODUNI, Tipo: Caracter, Tamanho: 2, Descrição: Unidade de Beneficiamento;