Configuração do REST Protheus para uso com os aplicativos Mobile

1 - Visão Geral

Para utilização dos Apps é necessário que o REST do Protheus esteja habilitado e configurado corretamente, com a autenticação habilitada. Nas seções abaixo temos alguns exemplos de configuração e validação.

2 - Configuração do REST

Para fazer a configuração do Rest é recomendado que seja criada uma cópia do appserver do Protheus para que ele rode em instâncias separadas conforme no exemplo abaixo:

Os arquivos podem ser copiados da pasta appserver, sendo necessário alterar apenas o arquivo appserver.ini da pasta onde ficará o REST.

3 - Configuração do appserver.ini:

O arquivo appserver.ini deve conter as chaves abaixo:

[General]
MAXSTRINGSIZE=10      
 
[HTTPV11]
Enable=1
Sockets=HTTPREST
 
[HTTPREST]
Port=8080              
IPsBind=
URIs=HTTPURI
Security=1             
 
[HTTPURI]              
URL=/rest              
PrepareIn=ALL          
Instances=2,5,1,1      
CORSEnable=1           
AllowOrigin=*          
 
[HTTPJOB]
MAIN=HTTP_START         
ENVIRONMENT=environment 
 
[ONSTART]
jobs=HTTPJOB            
RefreshRate=30          

Obs: O exemplo abaixo contém  valores obrigatórios referente ao REST com comentários.

[General]
MAXSTRINGSIZE=10      
	;//MAXSTRINGSIZE: Essa chave é obrigatória com o valor mínimo de 10.
 
[HTTPV11]
Enable=1
Sockets=HTTPREST
 
[HTTPREST]
Port=8080              
	;//Port: Porta que o REST irá utilizar para subir o serviço, pode ser alterada para qualquer outra porta.
IPsBind=
URIs=HTTPURI
Security=1             
	;//Security: O valor 1 é obrigatório.

InactiveTimeout=60
	;// Tempo em segundos que a conexão será mantida sem que o cliente efetue requisições.
MaxRequests=0
	;//Número máximo de requisições por conexão
SSLCheckClientCert=0
	;//Indica se fará ou não a validação do certificado de cliente, encerrando a conexão caso não valide.

 
[HTTPURI]              
	;//HTTPURI: Mesmo valor da chave URIs, definido na linha 13.
URL=/rest              
	;//URL: Path onde o rest irá subir, pode ser alterado.
PrepareIn=ALL          
	;//PrepareIn: Chave que indica qual environment será preparado para o rest. ALL significa que deve ser preparado para atender todas as empresas. Caso você queira utilizar o REST com empresa 1 filial 01, por exemplo, inserir na chave 1,01.
Instances=2,5,1,1      
	;//Instances: Chave obrigatória, mais informações sobre configuração em http://tdn.totvs.com/display/tec/Instances . A configuração desta chave impacta diretamente no total de licenças consumidas pelo REST.
CORSEnable=1           
	;//CORSEnable: Essa chave é obrigatória e com o valor 1, caso contrário, o REST não aceitara as requisições dos apps.
AllowOrigin=*          
	;//AllowOrigin: Essa chave limita os IP's que o REST do Protheus pode responder, deve conter o valor * (responder para qualquer ip) ou os ip's específicos onde a integração será realizada.
 
[HTTPJOB]
MAIN=HTTP_START         
	;//MAIN: Cria um JOB que inicializa o servidor HTTP na inicialização do serviço.
ENVIRONMENT=environment 
	;//ENVIRONMENT: Diz em qual environment(ambiente) o JOB será configurado.
 
[ONSTART]
jobs=HTTPJOB            
	;//Jobs: Indica que o HTTPJOB será iniciado quando o serviço for iniciado.
RefreshRate=30          
	;//RefreshRate: Indica qual a taxa de atualização para reiniciar o JOB em caso de falha.

[HTTPURI]
Module=46

3.1 Configuração REST no Intera

Se você está na modalidade Intera de licenciamento, a configuração do REST terá uma pequena particularidade.

Estamos falando da chave "stateless" na sessão [URIHTML], que define a maneira em que as licenças serão consumidas: Na inicialização da thread ou por demanda.

Para habilitar o comportamento de consumo de licença por demanda, o conteúdo da chave deve ser "1". Caso a chave não exista ou contenha o valor zero, o consumo de licença na inicialização da thread será mantido.

Saiba mais detalhes acessando este link.

Após configurado, você pode iniciar o executável do appserver do REST em modo console e verificar se ele subiu corretamente através da mensagem no console:

4 - Problemas mais comuns:

A falta de quaisquer uma das chaves no exemplo acima faz com que o REST não funcione como esperado. Abaixo listamos algumas:

• SECURITY=0

               A chave SECURITY indica se o REST irá validar o usuário que esta fazendo a chamada ou não, quando o valor esta como 0, é desconsiderado o usuário enviado e o Protheus executa a chamada com o usuário administrador. Essa configuração traz grandes problemas de segurança para o Protheus e deve ser usado apenas em modo de desenvolvimento.
             Os aplicativos também não funcionam corretamente, pois independente do usuário que fez o login, os dados e configurações de usuário exibidos dentro do aplicativo, são do usuário administrador.
             Caso não haja a chave SECURITY, o valor dela é 1, o que esta correto também.

• PrepareIn

            A chave prepareIn indica para quais empresas/filiais o REST irá subir uma thread. O Valor ALL usado no exemplo acima sobe uma thread para cada empresa e filial. Porém é consumida uma licença (TOTVS i) para cada thread. Caso o cliente não for utilizar todas as empresas, é possível subir apenas para as que ele deseja. Exemplo:
PrepareIn=T1, D MG 01

• CORSEnable

           A chave CORSEnable indica se o REST do Protheus pode receber requisições fora do próprio servidor. Para utilização dos Apps, essa chave é obrigatória com o valor 1. Pois seu valor padrão é 0.

• AllowOrigin

          A chave AllowOrigin indica de quais ip's o REST pode responder. Quando o valor é * (asterisco), indica que o Protheus pode responder para qualquer ip.

          Para utilização dos Apps, é possível limitar o acesso apenas para os ranges de ip's do Mingle listados abaixo: 

• 34.66.1.67
• 34.66.27.255
• 34.121.152.77
• 34.122.88.30
• 146.148.50.219
• 104.155.181.56
• 34.28.132.209
• 35.225.171.255
• 34.69.186.150

Obs: Essa configuração também deve ser feita no firewall da rede do cliente.

5 - Validações:

Existem diferentes maneiras para verificar se o REST esta com a configuração correta.

5.1 Acesso pelo navegador

A primeira e mais fácil de fazer, é acessa-lo pelo navegador, verificando esse acesso é possível saber se o REST esta de pé. Caso não seja possível acessa-lo, os aplicativos não irão funcionar.

Como testar:

5.1.1 - Ambiente local

Caso esteja fazendo o teste em ambiente local, siga os passos abaixo:

1. Descobrir o ip local:
   é possível verificar rodando o comando ipconfig no command do windows:
   
   
   
2. Verificar qual porta foi configurado o rest:
   é a chave Port dentro da tag HTTPREST do arquivo appserver.ini.  ( linha 9 do exemplo na sessão 3)
   
   
3. Verificar qual a chave do rest:
   é a chave URL dentro da tag HTTPURI do arquivo appserver.ini.  ( linha 15 do exemplo na sessão 3)

Em nosso exemplo, ficaria 

http://10.172.145.178:8080/rest

Acessar o endereço pelo navegador.

5.1.2 - Ambiente do cliente

Caso o teste seja feito em um ambiente do cliente, será necessário orienta-lo a seguir os passos acima. 

Após ter o endereço do REST em mãos, é recomendado testar de um outro aparelho que não seja o próprio servidor. Pode ser qualquer computador ou celular que esteja na mesma rede (do cliente).

Em ambos os casos, deverá ser aberta uma página semelhante a abaixo:

6 - Exposição do endereço externo

Após ter seu REST configurado e funcional no ambiente, para alguns aplicativos, pode ser necessário expo-lo em IP fixo externo (para configuração do ALIAS do Mingle).

Esta configuração deve ser feita na infraestrutura de rede de sua empresa, e os IPs de origem do Mingle devem ser liberados para realizar conexões de entrada e saída.

1. Não é recomendável liberar o acesso à todas as requisições no firewall, pois pode gerar um problema de segurança.

7 - Documentações auxiliares:

Abaixo algumas documentações que podem auxiliar em caso de dúvidas/problemas:

Framework: Configuração do REST (Geral)

02. REST com ERP Microsiga Protheus

Exemplo de configuração do REST

Dicas sobre Configuração REST Protheus®

Pacotes de atualização Mobile