Seu Primeiro Webservice REST No ERP Protheus

10/08/2020 Seu primeiro Webservice REST no ERP Protheus | Desmistificando o MVC no AdvPL
Desmistificando o MVC no AdvPL
Procurando conteúdo sobre MVC na linguagem AdvPL?

Achou.
Seu primeiro Webservice REST no ERP Protheus
16 16+00:00 ABRIL 16+00:00 201716 16+00:00 ABRIL 16+00:00 2017 ⁄ VICTOR ANDRADE
– O que é REST?
A web é amplamente utilizada e reconhecida principalmente por sua arquitetura

robusta, escalável e tolerante a falhas. Quem sustenta esses fatores e lhe dá todo este poder é
o protocolo HTTP (h p://pt.wikipedia.org/wiki/Hypertext_Transfer_Protocol) (o protocolo HTTP é
utilizado, em regra, quando se deseja evitar que a informação transmitida entre o cliente e
o servidor seja visualizada por terceiros, como, por exemplo, no caso de compras online.). Atualmente,
muitas vezes necessitamos integrar aplicações em ambientes totalmente diferentes e
os WebServices são uma das maneiras mais comuns e fáceis de integrar os diferentes sistemas. Este
post mostrará um pouco de um modelo de WebService chamado REST.
Representational State Transfer ou somente REST, é cada vez mais usado como alternativa ao “já
antigo” SOAP onde que a principal crítica a esta é a burocracia, algo que REST possui em uma escala
muito menor.
REST é baseado no design do protocolo HTTP, que já possui diversos mecanismos embutidos para
representar recursos como código de status, representação de tipos de conteúdo, cabeçalhos, etc.
O principal nesta arquitetura são as URLs do sistema e os resources (resource é um recurso, entidade).
Ele aproveita os métodos HTTP para se comunicar, que são:
GET: Solicita a representação de um determinado recurso. É definido como um método seguro e não
deve ser usado para disparar uma ação (remover um usuário, por exemplo);
POST: As informações enviadas no corpo (body) da requisição são utilizadas para criar um novo
recurso. Também é responsável por fazer processamentos que não são diretamente relacionados a um
recurso.
DELETE: Remove um recurso.
PUT: Atualiza um recurso na URI especificada. Caso o recurso não exista, ele pode criar um. A
principal diferença entre POST e PUT é que o primeiro pode lidar não somente com recursos, mas
também pode fazer processamento de informações.
https://mvcadvpl.wordpress.com/2017/04/16/introducao-ao-webservice-rest-no-erp-protheus/ 1/14
Agora que já entendemos um pouco sobre o que é um webservice rest, “vamos por a mão na massa” e
desenvolver uma aplicação “Hello Word REST” como diz a Ju rs.
O primeiro passo para criarmos um serviço REST é configurar o Protheus como um servidor HTTP
REST. Para isso vamos manipular o arquivo .ini do AppServer, conforme exemplo abaixo:
A função HTTP_START que prepara o AppServer como servidor HTTP para REST, necessitando ser
configurada na seção ONSTART:
[GENERAL]
MAXSTRINGSIZE=10
[ONSTART]
JOBS=HTTPJOB
REFRESHRATE=120
[HTTPJOB]
MAIN=HTTP_START
ENVIRONMENT=P12LOCAL
Habilitando o servidor HTTP para REST:
[HTTPV11]
Enable=1
Sockets=HTTPREST
Obs: A chave Sockets referencia a(s) seção(ões) com a configuração de porta e URL que a mesma irá
atender, permitindo que o Application Server seja configurado com mais de uma porta HTTP do REST:
[HTTPV11]
Enable=1
Sockets=HTTPREST,HTTPREST2
Configuração do(s) socket(s) definidos na seção HTTPV11:
[HTTPREST]
Port=8080
IPsBind=
URIs=HTTPURI
Security=0
Descrição
Parametro
Port Porta HTTP
IPsBind Indica os IPs que serão atendidos por essa porta, se não informado atenderá qualquer
IP / DNS associado ao servidor
URIs Seções com configuração de URL e ambiente (pelo menos uma seção)
Security Indica se a autenticação de requisição esta habilitada
Observação
O HTTP do REST verifica existência do campo Authorization no HEADER da requisição, porém a
autorização é realizada pelo framework do produto que está/ utilizando o protocolo
Para facilitar o desenvolvimento e testes pode-se configurar a chave Security com valor 0 (zero)
para desabilitar a autenticação
A chave URIs referência a(s) seção(ões) com a configuração da URL que a porta irá atender, permite
também que seja configurado com mais de uma URL:
[HTTPREST]
Port=8012
IPsBind=
URIs=HTTPURI,HTTPURI2
Security=1
Configuração da(s) seções URIs:
[HTTPURI]
URL=/rest
PrepareIn=99,01
Instances=1,1
Parametro Descrição
URL Indica o endereço que será atendido
Nesse exemplo h p://localhost:8012/rest (h p://localhost:8080/rest)
Preparein Informações de empresa e filial para preparação do ambiente das working threads
Instances Configuração de inicialização de working threads
CorsEnable Indica se habilita o CORS
Observaçoes
A chave CORS é utilizada para permitir que páginas WEB de diferentes domínio do qual o servidor
HTTP do Protheus está alocado, consigam realizar a requisição na nossa URI.
Essa parte configuração não temos muito como fugir do que está descrito no TDN, está bem
documentado por parte da TOTVS.
Após a configuração, o appserver.ini deverá ficar da seguinte maneira:
Após a adição das seções no .ini, deve reiniciar o appserver e podemos ver no log que está no ar nosso
servidor h p/rest:
Com nosso servidor web no ar, vamos acessar via navegador a URI que configuramos no .ini, para ter
100% de certeza que estamos prontos para “por a mão na massa”. Para acessar nossa URI, devemos
acessar o caminho definido via navegador. Nesse caso, (exemplo acima) a URL que vamos acessar
para testar nossa URI é a seguinte:
h p://localhost:8012/rest (h p://localhost:8012/rest)
Deverá ser exibida a seguinte tela:
Onde nada mais é que uma página WEB contendo todas as API’s rest que está disponível no ERP
Protheus.
“Pondo a mão na massa”
A nossa primeira API rest do advpl, vamos fazer um programa para retornar a descrição, unidade de
medida e o status de um determinado produto.
Passo 01: Includes
Para criar um webservice REST no Protheus, precisamos da utilização de um include específico, esse
include possui alguns DEFINES que facilita muito o desenvolvimento da nossa funcionalidade. Esse
include é o RestFul.CH.
#Include 'Protheus.ch'
#Include 'FWMVCDEF.ch'
#Include 'RestFul.CH'
User Function EREST_01()

Return
Acima definimos uma User Function, porém ela serve apenas com “Dummy Function” (Função
fantasma) ou seja, ela serve apenas para reservarmos o nome do nosso “.prw” dentro do repositório, é
claro que nada te impede de utilizar essa “Dummy function” como uma função de processamento
chamada no nosso programa ADVPL.
Passo 02: Definição da estrutura do WebService
Para criarmos um webservice, precisamos definir a estrutura do mesmo, ou seja, os atributos e

métodos que iremos disponibilizar.
Nesse nosso primeiro exemplo, como citado acima, vamos falar apenas do método GET (método
responsável por retornar informações, se estivéssemos tratando de um CRUD esse “cara” seria o
Ready).
WSRESTFUL PRODUTOS DESCRIPTION "Serviço REST para manipulação de Produtos"
WSDATA CODPRODUTO As String
WSMETHOD GET DESCRIPTION "Retorna o produto informado na URL" WSSYNTAX "/PRODUTOS
END WSRESTFUL
Entendendo o trecho de código acima:
Linha 1:
WSRESTFUL -> Início da declaração da estrutura do Webservice;

PRODUTOS -> Nome do webservice
DESCRIPTION -> Descrição do serviço
Logo após definirmos a criação do webservice, deveremos definir quais atributos o mesmo terá.
Linha 3:
WSDATA -> Definição dos atributos
No nosso caso, teremos um único atributo que é o CODPRODUTO e esse atributo é do tipo string,
porém ele poderia ser:
Float
Boolean
String
Array
Integer
Linha 5:
WSMETHOD -> Definição de um método

GET -> Define qual o tipo do método que estamos criando, podendo ser
GET
POST
UPDATE
DELETE
DESCRIPTION -> Descrição do método.
SYNTAX -> Sintaxe HTTP da chamada REST. Esta informação é utilizada na documentação do
REST.
Linha 6:
END WSRESTFUL -> Encerra a declaração da estrutura do webservice.
Passo 03: Definição do método.
A definição do método é o passo onde vamos desenvolver toda a regra de negócio do método. Como
nosso método é um GET, deveremos devolver um JSON para a aplicação CLIENT. Para a criação do
JSON que vamos devolver para o Client, iremos utilizar a função FWJsonSerialize, veremos mais a
frente sua utilização.
WSMETHOD GET WSRECEIVE CODPRODUTO WSSERVICE PRODUTOS

Local cCodProd := Self:CODPRODUTO
Local aArea := GetArea()
Local oObjProd := Nil
Local cStatus := ""
Local cJson := ""
::SetContentType("application/json")
DbSelectArea("SB1")
SB1->( DbSetOrder(1) )
If SB1->( DbSeek( xFilial("SB1") + cCodProd ) )
cStatus := Iif( SB1->B1_MSBLQL == "1", "Sim", "Nao" )
oObjProd := Produtos():New(SB1->B1_DESC, SB1->B1_UM, cStatus)
EndIf
cJson := FWJsonSerialize(oObjProd)
::SetResponse(cJson)
RestArea(aArea)
Return(.T.)
Entendendo o trecho de código acima:
Linha 1:
WsMethod -> Indica a iniciação de escrita do método

GET -> Tipo do método (Podendo ser GET, POST, UPDATE e DELETE).
WSRECEIVE -> Indica os parâmetros que iremos receber, no nosso caso, iremos receber o código
de produtos via URL (Request Get), mas poderíamos receber também um JSON Object (Request
POST).
WSSERVICE -> Indica o nome do webservice ao qual esse método pertence, no nosso caso o nome
é PRODUTOS.
Abaixo temos a declaração das variáveis que iremos utilizar, onde no nosso caso, temos 2 que requer
nossa atenção, que são as seguintes:
cCodProd -> Armazena o código do produto informado na URL.

oObjProd -> Classe que iremos criar para serializar o nosso json;
Linha 9:
Definição do tipo de retorno:
::SetContentType(“application/json”)
Após a definição do tipo de retorno, possuímos um pequeno trecho de código que nos serve para
posicionar no produto que recebemos pela URL e iremos serializar o mesmo.
Para serializar o nosso registro JSON, devemos criar uma classe com os atributos que iremos retornar
e alimentar os atributos com os valores desejados.
Para mais informações acesse a documentação da função na TDN:
h p://tdn.totvs.com/display/public/mp/FWJsonSerialize+-
+Serializa+qualquer+tipo+de+dado+no+formato+JSON
(h p://tdn.totvs.com/display/public/mp/FWJsonSerialize+-
+Serializa+qualquer+tipo+de+dado+no+formato+JSON)
Linha 18:
Após alimentarmos o objeto criado com os atributos que queremos retornar, então devemos utilizar a
função FWJsonSerialize que retorna a string do objeto passado como parâmetro.
cJson := FWJsonSerialize(oObjProd)
Linha 20:
Seta a resposta para a aplicação Client
::SetResponse(cJson)
Agora vamos ver a nossa aplicação na prática:
Feito toda a codificação do nosso exemplo e compilado no RPO, vamos verificar se o nosso WS Rest
está disponível para utilização através do nossa URI:
Agora iremos realizar o “consumo” da API Rest criada através da ferramenta Postman ou no nosso
caso como se trata de uma API aberta e sem nenhum tipo de autenticação, também pode ser chamado
direto pela URL no navegador:
Teste pelo Postman:
Teste pelo Navegador:
Esse é um exemplo muito simples do que podemos fazer com webservices REST, nos próximos Posts
vamos nos aprofundar cada vez mais.
Fontes no GitHub:
https://github.com/VctrAndrade/RestAdvplPost01
EREST_01.prw (https://github.com/VctrAndrade/RestAdvplPost01/blob/master/EREST_01
EREST_01A.prw (https://github.com/VctrAndrade/RestAdvplPost01/blob/master/EREST_0
—————————————————————————————————————————————-
Obrigado Galera e espero que tenham gostado.
Victor Andrade
Referências:
h p://www.matera.com/br/2012/10/22/como-funciona-um-webservice-rest/
(h p://www.matera.com/br/2012/10/22/como-funciona-um-webservice-rest/)
h p://tdn.totvs.com/display/home/TDN+-+TOTVS+Developer+Network
(h p://tdn.totvs.com/display/home/TDN+-+TOTVS+Developer+Network)
Categorias: REST Tags: rest advpl protheus
16 comentários em “Seu primeiro Webservice REST no

ERP Protheus”
1. Siga0984 disse:
17 17+00:00 ABRIL 17+00:00 2017 ÀS 23:44
Republicou isso em Tudo em AdvPL.
RESPONDER
2. Siga0984 disse:
17 17+00:00 ABRIL 17+00:00 2017 ÀS 23:46
Fantástico !! Parabéns pela iniciativa !!
RESPONDER
1. Victor Andrade disse:
18 18+00:00 ABRIL 18+00:00 2017 ÀS 00:51
Obrigado Júlio!!!
RESPONDER
3. zedacapela disse:
18 18+00:00 ABRIL 18+00:00 2017 ÀS 11:33
Muito bom! Já estão até chupinhando seu post!
RESPONDER
18 18+00:00 ABRIL 18+00:00 2017 ÀS 13:48
rs
RESPONDER
4. Alexander Santos disse:

18 18+00:00 ABRIL 18+00:00 2017 ÀS 12:44
Boa Victor… excelente material, de um profissional com ótimos conhecimentos… Aguardamos os
próximos Post…
RESPONDER
18 18+00:00 ABRIL 18+00:00 2017 ÀS 13:48
RESPONDER
5. Renato disse:
19 19+00:00 ABRIL 19+00:00 2017 ÀS 19:21
Muito Bom , parabéns!!
RESPONDER
6. Kanaãm disse:
24 24+00:00 ABRIL 24+00:00 2017 ÀS 18:33
Muito bom material Victor!
Abraços!!
RESPONDER
24 24+00:00 ABRIL 24+00:00 2017 ÀS 18:54
RESPONDER
7. Ernani Forastieri da Silva disse:

5 05+00:00 MAIO 05+00:00 2017 ÀS 16:53
Parabéns Vitor
Pela iniciativa e pela didática
Excelente
RESPONDER
5 05+00:00 MAIO 05+00:00 2017 ÀS 22:14
Obrigado Ernani
Abs!
RESPONDER
8. Junior Sobral disse:
16 16+00:00 JUNHO 16+00:00 2017 ÀS 19:34
Muitíssimo Obrigado pelo conhecimento compartilhado!! =)
RESPONDER
9. Marcio disse:
28 28+00:00 JUNHO 28+00:00 2017 ÀS 17:23
Olá,
Sou iniciante no Protheus, e tenho uma duvida para um trabalho, para inserir um pedido de
venda, e seus itens é necessário realizar os cálculos de impostos ou apenas informar a TES e o
sistema já inclui o pedido com os devidos calculos, ICMS, IPI e demais impostos contidos na TES ?
Obrigado
Marcio Eduardo
RESPONDER
28 28+00:00 JUNHO 28+00:00 2017 ÀS 20:12
Olá Marcio!
Somente informar o TES, e o sistema irá efetuar os cálculos conforme parametrizado.
Abs.
RESPONDER
10. Alexandre Pinheiro disse:

12 12+00:00 SETEMBRO 12+00:00 2017 ÀS 20:38
Olá Victor, consegue disponibilizar o include RestFul.CH?
RESPONDER
BLOG NO WORDPRESS.COM.

Seu Primeiro Webservice REST No ERP Protheus - Desmistificando o MVC No AdvPL

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Seu Primeiro Webservice REST No ERP Protheus - Desmistificando o MVC No AdvPL

Enviado por

Direitos autorais:

Formatos disponíveis

10/08/2020 Seu primeiro Webservice REST no ERP Protheus | Desmistificando o MVC no AdvPL

Desmistificando o MVC no AdvPL

Procurando conteúdo sobre MVC na linguagem AdvPL?

A web é amplamente utilizada e reconhecida principalmente por sua arquitetura

DELETE: Remove um recurso.

Habilitando o servidor HTTP para REST:

Conﬁguração do(s) socket(s) deﬁnidos na seção HTTPV11:

Conﬁguração da(s) seções URIs:

Após a conﬁguração, o appserver.ini deverá ﬁcar da seguinte maneira:

Deverá ser exibida a seguinte tela:

“Pondo a mão na massa”

Passo 01: Includes

User Function EREST_01()

Passo 02: Deﬁnição da estrutura do WebService

Para criarmos um webservice, precisamos deﬁnir a estrutura do mesmo, ou seja, os atributos e

WSRESTFUL PRODUTOS DESCRIPTION "Serviço REST para manipulação de Produtos"

WSDATA CODPRODUTO As String

WSMETHOD GET DESCRIPTION "Retorna o produto informado na URL" WSSYNTAX "/PRODUTOS

Entendendo o trecho de código acima:

WSRESTFUL -> Início da declaração da estrutura do Webservice;

WSDATA -> Deﬁnição dos atributos

WSMETHOD -> Deﬁnição de um método

END WSRESTFUL -> Encerra a declaração da estrutura do webservice.

Passo 03: Deﬁnição do método.

WSMETHOD GET WSRECEIVE CODPRODUTO WSSERVICE PRODUTOS

Entendendo o trecho de código acima:

WsMethod -> Indica a iniciação de escrita do método

cCodProd -> Armazena o código do produto informado na URL.

Deﬁnição do tipo de retorno:

Para mais informações acesse a documentação da função na TDN:

Seta a resposta para a aplicação Client

Agora vamos ver a nossa aplicação na prática:

Teste pelo Postman:

Teste pelo Navegador:

Obrigado Galera e espero que tenham gostado.

Categorias: REST Tags: rest advpl protheus

16 comentários em “Seu primeiro Webservice REST no

4. Alexander Santos disse:

7. Ernani Forastieri da Silva disse:

Somente informar o TES, e o sistema irá efetuar os cálculos conforme parametrizado.

10. Alexandre Pinheiro disse:

Você também pode gostar