PUBLICAÇÃO WEB SERVICE REST DO CADASTRO DE FAZENDA

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/consulta de fazenda 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 o Postman são exemplos de bons programas para isso. 

Inserindo um registro

Abaixo, uma persistência de dados, pelo método Post, na tabela NN2 (Fazendas).

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, o registro já existe no banco.

Consultando informações

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

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": "AGRA005",
     "operation": 3,
     "models": [
          {
               "id": "AGRA005_NN2",
               "modeltype": "FIELDS",
               "fields": [
          {
               "id": "NN2_CODFIL",
               "order": 2,
               "value": "D MG 01"
          },
          {
               "id": "NN2_NOMFIL",
               "order": 3,
               "value": "Filial Belo Hor"
          },
          {
               "id": "NN2_CODIGO",
               "order": 4,
               "value": "03"
          },
          {
               "id": "NN2_NOME",
               "order": 5,
               "value": "FAZENDA TESTE REST"
          },
          {
               "id": "NN2_ATIVA",
               "order": 10,
               "value": "A"
          },
          {
               "id": "NN2_PRDTOR",
               "order": 11,
               "value": "000001"
          },
          {
               "id": "NN2_LJPRO",
               "order": 12,
               "value": "01"
          },
          {
               "id": "NN2_ARMPAD",
               "order": 13,
               "value": "01"
          }
          ]
     }
     ]
}

Dados técnicos

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

1. "id": "AGRA005",

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

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

Essa definição ocorre logo na segunda parte.

1. "id": "AGRA005_NN2",

           "modeltype": "FIELDS",

           "fields": [

                 Aqui, o ID se refere ao nome do Modelo que está contido na rotina que está sendo manipulada. Neste caso, AGRA005_NN2 é o modelo 'master' do AGRA005.

                 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": "NN2_CODFIL",

          "order": 2,

          "value": "D MG 01"

                 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 devolve uma mensagem de erro, em formato JSON, e a operação não é concluída.

• OBS: os campos citados são referentes a tabela NN2 que são tabelas de cadastro de locais de estoque. Todos os campos desta tabela podem ser consultados pelo configurador.

Campo: NN2_CODFIL, Tipo: Caracter, Tamanho: 2, Descrição: Código da Filial;

Campo: NN2_NOMFIL, Tipo: Caracter, Tamanho: 15, Descrição: Nome da Filial;

Campo: NN2_CODIGO, Tipo: Caracter, Tamanho: 2, Descrição: Código da Fazenda;

Campo: NN2_NOME, Tipo: Caracter, Tamanho: 30, Descrição: Nome da Fazenda;

Campo: NN2_ATIVA, Tipo: Caracter, Tamanho: 1, Descrição: Fazenda Ativa;

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

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

Campo: NN2_ARMPAD, Tipo: Caracter, Tamanho: 2, Descrição: Armazém Padrão;