Manual de Integração Receituário WebService Versão (2.0)

Transcrição

1 Manual de Integração Receituário WebService Versão (2.0) 1

2 CONTEÚDO 1 Introdução Tecnologia utilizada WebServices WeBService Produto Listar todos os produtos Elementos do retorno Parâmetros obrigatórios Listar produtos por nome Elementos do retorno Parâmetros obrigatórios WebService Cultura Listas todas as Culturas Elementos de retorno Parâmetros obrigatórios Listar Cultura por nome Elementos de retorno Parâmetros obrigatórios Listar Cultura por produto Elementos de retorno Parâmetros obrigatórios WebService Alvo Listar Alvos Elementos de retorno Parâmetros obrigatórios Listar Alvo por nome Elementos de retorno Parâmetros obrigatórios Listar Alvo por Produto e Cultura Elementos de retorno Parâmetros obrigatórios WEBSERVICE Receita Abrir Receita Elementos de retorno

3 3.9.3 Parâmetros obrigatórios CLIENTE DE TESTE (DELPHI) CONFIGURAÇÃO DO CLIENTE DE TESTE (DELPHI) LEITURA JSON CLIENTE (DELPHI) EXEMPLO JAVA CÓDIGO DE CONEXÃO webservice (JAVA) LEITURA do RETORNO (JAVA) LISTAGEM DE WEBSERVICE DO RECEITUARIO

4 1 INTRODUÇÃO O Manual de Integração versão 1.0 aborda conceitos sobre a tecnologia utilizada para construção dos WebServices do Receituário Agronômico, Conexão dos WebServices e exemplos de sua utilização. Este manual aborda detalhadamente todos os processos de como utilizar a tecnologia. 4

5 2 TECNOLOGIA UTILIZADA Todos os WebServices do Receituário Agronômico tem como base a arquitetura REST (Representation State Transfer) usando a implementação RestFull e como formato de apresentação das informações JSON (Javascript Object Notation). Combinadas, estas tecnologias permitem um ganho em rapidez e praticidade no desenvolvimento de integrações. O protocolo de comunicação é o HTTP e as operações utilizadas são: GET, POST, PUT E DELETE, as quais vão estar associados as URL dos WebServices do Receituário. Observe a imagem abaixo que apresenta o fluxo dos dados entre o cliente e o servidor. O diagrama acima apresenta como funciona a tecnologia e como é simples sua utilização. Os próximos capítulos deste manual vão apresentar detalhes da implementação do WebService do Receituário. 5

6 3 WEBSERVICES Este capitulo vai apresentar com detalhes os WebService que compõem a estrutura do Receituário. Basicamente, são consultas de: produto, cultura e alvo e por fim a abertura da Receita agronômica para emissão. A estrutura deste capitulo será dividia em tópicos que explanará as rotinas de cada WebService, como também parâmetros obrigatórios e o retorno de suas consultas. 6

7 3.1. WEBSERVICE PRODUTO Basicamente, o WebService do produto é dividido em dois: 1. Consulta de todos os produtos: Esta consulta traz uma lista contendo todos os produtos da base de dados. A URL de conexão é: 2. Consulta de produto por nome: Esta consulta necessita o envio do nome do produto ou de parte do nome, por exemplo: O usuário precisa saber todos os produtos que iniciam com a letra L. A URL de conexão é: LISTAR TODOS OS PRODUTOS Como explicado no item 3.1, este WebService faz consulta e retorna todos os produtos contidos na base de dados. Observe a imagem abaixo que mostra o resultado da consulta: 7

8 ELEMENTOS DO RETORNO Este item descreve cada um dos elementos do retorno da consulta de produtos, acompanhe: ELEMENTO DESCRIÇÃO TIPO DE DADOS idproduto Este é o código do produto na base de Integer dados do Receituário. nomeproduto Trata-se do nome do produto (agrotóxico). String registromapa É um identificador único de cada produto. String Trata-se de um Registro Federal fornecido pelo Ministério da Agricultura. ativo Indica se o produto consultado está ativo na Boolean base de dados ou não PARÂMETROS OBRIGATÓRIOS Este WebService exige um parâmetro obrigatório, que é: 1. Chave de acesso: Parâmetro que deve ser enviado para validar o acesso à base de dados; Observe a URL abaixo: Note o campo CHAVE destacado é este o campo obrigatório LISTAR PRODUTOS POR NOME Este WebService faz consulta enviado o nome do produto e retorna os produtos conforme o nome enviado. Observe abaixo o retorno da consulta: 8

9 3.2.1 ELEMENTOS DO RETORNO Este item descrever cada um dos elementos do retorno da consulta de produtos por nome acompanhe: ELEMENTO DESCRIÇÃO TIPO DE DADOS idproduto Este é o código do produto na base de Integer dados do Receituário. nomeproduto Trata-se do nome do produto (agrotóxico). String registromapa É um identificador único de cada produto. String Trata-se de um Registro Federal fornecido pelo Ministério da Agricultura. ativo Indica se o produto consultado está ativo na Boolean base de dados ou não PARÂMETROS OBRIGATÓRIOS Este WebService exige dois parâmetros obrigatórios, que são: 1. Chave de acesso: Parâmetro que deve ser enviado para validar o acesso à base de dados; 2. Nome do produto: Nome do produto que se deseja pesquisar. Obs: É possível enviar apenas a uma lenta ex: L e o WebService retorna todos os produtos que iniciam com a letra enviada. Observe a URL abaixo: Produto=Locker Note que os campos CHAVE e NOMEPRODUTO estão destacados, são esses os campos obrigatórios. 9

10 3.3. WEBSERVICE CULTURA Cultura é composta por três WebServices, que são: 1. Listar todas as culturas: Este WebService traz todas as culturas cadastradas na base de dados. A URL é: 2. Listar Culturas por nome: Este WebService traz as Culturas conforme o nome enviado para pesquisa. A URL e: 3. Listar Culturas por Produto: Este WebService traz todas as culturas de um determinado produto. A URL é: LISTAS TODAS AS CULTURAS Conforme descrito no item 3.3 este WebService traz todas as culturas. Observe abaixo o retorno da consulta: 10

11 3.3.2 ELEMENTOS DE RETORNO Este item descreve cada um dos elementos do retorno da consulta de todas as Culturas acompanhe: ELEMENTO DESCRIÇÃO TIPO DE DADOS idcultura Código da cultura em nosso banco de Integer dados. nomecomum Nome comum da cultura. Ex.: soja, milho. String nome Cientifico Nome científico da cultura. Ex.: Glycine max, Zea mays. String codsiagro Código para as culturas SOMENTE utilizado Integer para clientes no Estado do Paraná PARÂMETROS OBRIGATÓRIOS Este WebService exige um parâmetro obrigatório, que é: 1. Chave de acesso: Parâmetro que deve ser enviado para validar o acesso à base de dados; Observe a URL abaixo: Note que o campo CHAVE está destacado é ele o campo obrigatório LISTAR CULTURA POR NOME Conforme descrito no item 3.3, este WebService faz consulta passando o nome da Cultura e retorna uma lista de culturas por nome. Observe abaixo o retorno da consulta: 11

12 3.4.1 ELEMENTOS DE RETORNO Este item descreve cada um dos elementos do retorno da consulta de Culturas por nome acompanhe: ELEMENTO DESCRIÇÃO TIPO DE DADOS idcultura Código da cultura em nosso banco de Integer dados. nomecomum Nome comum da cultura. Ex.: soja, milho. String nomecientifico Nome científico da cultura. Ex.: Glycine String max, Zea mays. codsiagro Código para as culturas SOMENTE utilizado Integer para usuários no Estado do Paraná PARÂMETROS OBRIGATÓRIOS Este WebService exige dois parâmetros obrigatórios, que são: 1. Chave de acesso: Parâmetro que deve ser enviado para validar o acesso à base de dados; 2. Nome da Cultura: Parâmetro que deve ser enviado para filtrar as Culturas por nome. Observe a URL abaixo: Note que o campo CHAVE e o campo NOMECULTURA estão destacados esses são os campos obrigatórios LISTAR CULTURA POR PRODUTO Conforme descrito no item 3.3 este WebService faz consulta passando o código do Produto e retorna uma lista de culturas por Produto. Observe abaixo o retorno da consulta: 12

13 3.5.1 ELEMENTOS DE RETORNO Este item descreve cada um dos elementos do retorno da consulta de Culturas por Produto acompanhe: ELEMENTO DESCRIÇÃO TIPO DE DADOS idcultura Código da cultura em nosso banco de Integer dados. nomecomum Nome comum da cultura. Ex.: soja, milho. String PARÂMETROS OBRIGATÓRIOS Este WebService exige dois parâmetros obrigatórios, que são: 1. Chave de acesso: Parâmetro que deve ser enviado para validar o acesso à base de dados; 2. Código do produto: Parâmetros que deve ser enviado para realizar o filtro por produto na tabela de Cultura; Observe a URL abaixo: Note que o campo CHAVE e o campo IDPRODUTO estão destacados, esses são os campos obrigatórios. 13

14 3.6. WEBSERVICE ALVO Alvo é composto por três WebServices, que são: 1. Listar todos os Alvos: Este WebService traz todos os Alvos cadastrados na base de dados. A URL é: 2. Listar Alvos por nome: Este WebService traz os Alvos conforme o nome enviado para pesquisa. A URL e: 3. Listar Alvos por Produto e Cultura: Este WebService traz os Alvos de um determinado produto e cultura que foi enviado para pesquisa. A URL é: LISTAR ALVOS Conforme descrito no item 3.6 este WebService traz todos os Alvos cadastrados na base de dados. Observe abaixo o retorno da consulta: 14

15 3.6.2 ELEMENTOS DE RETORNO Este item descreve cada um dos elementos do retorno da consulta de Alvos, acompanhe: ELEMENTO DESCRIÇÃO TIPO DE DADOS idalvo Código do alvo (problema) em nossa base Integer de dados. nomecomum Nome comum do alvo. Ex.: Bicho-mineiro- String do-café, Cigarra-cafeeiro. nomecientifico Nome científico do alvo. Ex.: Leucoptera String coffeella, Quesada gigas. codsiagro Código para os alvos SOMENTE utilizado Integer para usuários no Estado do Paraná PARÂMETROS OBRIGATÓRIOS Este WebService exige um parâmetro obrigatório, que é: 1. Chave de acesso: Parâmetro que deve ser enviado para validar o acesso a base de dados; Observe a URL abaixo: Note que o campo CHAVE está destacado é ele o campo obrigatório LISTAR ALVO POR NOME Conforme descrito no item 3.6 este WebService faz consulta passando o nome do Alvo e retorna uma lista de Alvos por nome. Observe abaixo o retorno da consulta: 15

16 3.7.1 ELEMENTOS DE RETORNO Este item descreve cada um dos elementos do retorno da consulta de Alvos por nome, acompanhe: ELEMENTO DESCRIÇÃO TIPO DE DADOS idalvo Código do alvo (problema) em nossa base Integer de dados. nomecomum Nome comum do alvo. Ex.: Bicho-mineiro- String do-café, Cigarra-cafeeiro. nomecientifico Nome científico do alvo. Ex.: Leucoptera String coffeella, Quesada gigas. codsiagro Código para os alvos SOMENTE utilizado Integer para usuários no Estado do Paraná PARÂMETROS OBRIGATÓRIOS Este WebService exige dois parâmetros obrigatórios, que é: 1. Chave de acesso: Parâmetro que deve ser enviado para validar o acesso a base de dados; 2. Nome do Alvo: Parâmetro que deve ser enviado para filtrar os Alvos por nome. Observe a URL abaixo: farnesiana Note que o campo CHAVE e o campo NOMEALVO estão destacados, esses são os campos obrigatórios. 16

17 3.8. LISTAR ALVO POR PRODUTO E CULTURA Conforme descrito no item 3.6 este WebService faz consulta passando o código do Produto e o código da Cultura o qual retorna uma lista de Alvos filtrados por Produto e Cultura. Observe abaixo o retorno da consulta: ELEMENTOS DE RETORNO Este item descreve cada um dos elementos do retorno da consulta de Culturas por Produto acompanhe: ELEMENTO DESCRIÇÃO TIPO DE DADOS idcultura Código da cultura em nosso banco de Integer dados. nomecomum Nome comum da cultura. Ex.: soja, milho. String PARÂMETROS OBRIGATÓRIOS Este WebService exige três parâmetros obrigatórios, que são: 1. Chave de acesso: Parâmetro que deve ser enviado para validar o acesso a base de dados; 2. Código do produto: Parâmetro que deve ser enviado para realizar o filtro por produto; 3. Código da Cultura: Parâmetro que deve ser enviado para realizar o filtro por cultura; Observe a URL abaixo: &idcultura=12 Note que os campos CHAVE, IDPRODUTO e IDCULTURA estão destacados, esses são os campos obrigatórios. 17

18 3.9. WEBSERVICE RECEITA Receita é composto por um WebService, que é: 1. Abrir Receita: Este WebService traz baseadas no Produto, Cultura e Alvo. A URL é: ABRIR RECEITA Conforme descrito no item 3.9 este WebService traz informações baseados no Produto, Cultura e Alvo. Observe abaixo o retorno da consulta: 18

19 3.9.2 ELEMENTOS DE RETORNO Este item descreve cada um dos elementos do retorno da consulta Abrir Receita, acompanhe: ELEMENTO DESCRIÇÃO TIPO DE DADOS idproduto Código do Produto (agrotóxico) em Integer nosso banco de dados. nomeproduto Nome Comercial do Produto. String idcultura Código da cultura em nosso banco Integer de dados. nomecomumcultura Nome comum da cultura. Ex. soja, String milho, algodão, arroz, etc. nomecientificocultura Nome científico da cultura. Ex.: String Glycine max, Zea mays. Etc. epocacultura Época que se encontra a Cultura String que receberá o tratamento objeto da receita agronômica. Ex.: préemergente, pós-emergente, précolheita, etc. idpragas Código do alvo/praga (objeto da Integer receita agronômica) em nosso banco de dados. nomecomumpraga Nome comum do alvo/praga. String nomecientificopraga Nome científico do alvo/praga. String epocapraga Época de ocorrência do alvo/praga. String Ex.: pré-plantio, pós-emergente, infecção, infestação, etc. dosemin Dose mínima do produto comercial Double (agrotóxico) a ser utilizado. dosemax Dose máxima do produto comercial Double (agrotóxico) a ser utilizado. numeroaplicacoesmin Número mínimo de aplicações do Integer produto comercial a ser recomendado na receita agronômica. numeroaplicacoesmax Número máximo de aplicações do Integer produto comercial a ser 19

20 recomendado na receita agronômica. unidadeaplicacao Unidade de medida recomendada String no produto comercial (agrotóxico). Ex.: ml/ha, g/ha, ml/planta, etc. unidadecultura Unidade de medida para o Volume String de Calda (água + agrotóxico) recomendado. volumecalda Número de litros de água Integer recomendado na receita agronômica. Ex.: 150 L, 300 L, L. etc. descantidototratamento Descrição do Antídoto e tratamento em caso de intoxicação pelo agrotóxico. Este item compõe o Anexo Complementar da receita agronômica. String descepi Descrição do Equipamento de String Proteção Individual a ser utilizado na utilização do produto. descincompatibilidade Descrição de incompatibilidade String entreousodeprodutos simultâneos. Somente aparecerá se houver essa informação na Bula do Produto Agrotóxico. descmodoaplicacao Descrição do modo de utilização e String aplicação do Agrotóxico. descprecaucaouso Descrição das Precauções de Uso String do agrotóxico. descprimeirosocorro Descrição dos Primeiros Socorros String em caso de acidente com o agrotóxico PARÂMETROS OBRIGATÓRIOS Este WebService exige quatro parâmetros obrigatórios, que são: 1. Chave de acesso: Parâmetro que deve ser enviado para validar o acesso à base de dados; 2. Código do produto: Parâmetro que deve ser enviado para realizar o filtro por Produto 20

21 3. Código da cultura: Parâmetro que deve ser enviado para realizar o filtro por Cultura; 4. Código do alvo: Parâmetro que deve ser enviado para realizar o filtro por Alvo; Observe a URL abaixo: a=12&idalvo=64 Note que os campos CHAVE, IDPRODUTO, IDCULTURA e IDALVO estão destacados, esses são os parâmetros obrigatórios. 21

22 4. CLIENTE DE TESTE (DELPHI) Trata-se de um aplicativo que permite realizar a conexão com o WebServices do Receituário e observar o retorno. 4.1 CONFIGURAÇÃO DO CLIENTE DE TESTE (DELPHI) Basicamente são quatro campos a serem preenchidos para que o cliente realize a conexão com os WebServices: 1. Usuário: O valor é o usuário registrado para conexão; 2. Senha: O valor é a senha registrada para conexão; 3. Chave: O valor é chave fornecida para acesso ao WebService; 4. URL: O Valor é o caminho do WebService. Observe abaixo a imagem que apresenta o resultado da conexão realizada no WebService do Produto. 22

23 4.2 LEITURA JSON CLIENTE (DELPHI) Trata-se de um aplicativo que fazer a leitura do JSON que o WebService retorna. Para executar o testar basta colocar usuário, senha e chave, observe a imagem abaixo: Ao clicar no botão executar é feita a leitura a qual é armazenada em ComboBox do Produto, Cultura e Alvo. Obs. para ter acesso a essa interface basta clicar no botão Na tela principal do Cliente de Teste. Nota: Todos os códigos fontes serão enviados juntos com o Manual. 23

24 5 EXEMPLO JAVA Foi feita dois exemplos um de conexão e outra de leitura do retorno do WebService de Produto, acompanhe: 5.1 CÓDIGO DE CONEXÃO WEBSERVICE (JAVA) A imagem abaixo apresenta o código usado para realizar a conexão ao WebService Listar Produtos, observe: 5.2 LEITURA DO RETORNO (JAVA) A imagem abaixo apresenta o código usado para realizar a leitura do retorno do WebService Listar Produtos, observe: Nota: Os códigos fontes dos exemplos em Java estão em anexo junto com o manual. 24

25 6 LISTAGEM DE WEBSERVICE DO RECEITUARIO

26 Contato: 26