RESTWeb Service REST

Produto:

TOTVS Prestadores de Serviços Transporte de Passageiros

Versões:

12.1.2310+

Este documento tem o objetivo de fornecer informações para utilização do Web Service REST de integração com oTOTVS Prestadores de Serviços Transporte de Passageiros

Para mais detalhes sobre o conceito de um serviços REST clique aqui.

Para mais detalhes sobre serviços REST na arquitetura Protheus clique aqui.




Definição do Serviço

Nome: WSCOLETOR

Objetivo: Permitir a Integração com o módulo SIGAGTP utilizando um WebService do Tipo REST.

Descrição: Integra os dados do coletor para gerar a prestação de contas.

Métodos: POST

Configurações do Serviço


A  Configuração do serviço REST está documentada  no link Configuração REST SERVER - Protheus.

Estas parametrizações estão localizadas fisicamente no arquivo appserver.ini da pasta de instalação "[...]\BIN\APP"

Na seção HTTPURI, a chave PrepareIn deve ser comentada.

Segue exemplo de configuração do WS REST para utilização no modulo GTP:


[HTTPV11]
SOCKETS=HTTPREST
ENABLE=1

[HTTPREST]
Port=8080
URIs=HTTPURI
Security=1

[HTTPURI]
URL=/rest
;PrepareIn=
Instances=1,2
CORSEnable=1
AllowOrigin=*

[HTTPJOB]
MAIN=HTTP_START
ENVIRONMENT=P12

[TAF_CFGJOB]
Main=TAF_CFGJOB
Instances=1,2,1,1
PrepareIn=T1 
RefreshRate=50
ENVIRONMENT=P12

[OnStart]
JOBS=HTTPJOB
RefreshRate=120

A chave PrepareIn deve conter o código do Grupo de Empresas(sigamat.emp/syscompany) utilizado no modulo GTP, abaixo exemplos configurações possíveis para as mesmas:

  • Utilizando o código do grupo; Ex: PrepareIn=01
  • Utilizando diversos códigos de grupos; Ex: PrepareIn=01,02,99 .
  • Utilizando a palavra ALL, neste caso o server vai considerar todos os grupos contidos no arquivo de empresas do Protheus; Ex PrepareIn=ALL

O servidor cria Threads especificas para cada grupo de empresas de acordo com a configuração da chave Instances, por isso essa configuração deve ser realizada considerando a capacidade computacional do servidor.


Fonte: REST com ERP Microsiga Protheus

Definição dos métodos

POST

Descrição do Método: O método POST segue o conceito do próprio método em qualquer outro tipo de serviço REST, devendo seu conteúdo ser enviado no corpo da mensagem (body) no formato json.

O objetivo do método é enviar informações que devem ser gravadas nas tabelas do GTP, permitindo que os dados sejam submetidos aos processos de integração da filipetas

Estrutura da mensagem enviada no POST (Request):


Atributo

Pai

Nivel

Ocorrência

Formato

Cadastros Protheus

layoutColetor

-

1

1

-


softwareColetor

layoutColetor

1

1:1

String(36)


versaoColetor

layoutColetor

1

1:1

String(36)


cabecalho

-

1

1

-


empresa

cabecalho

1

1:1

String()

De/Para de empresas no configurador

matMotorista

cabecalho

1

0:1

String(03)


cartaoMotorista

cabecalho

1

0:1

String(10)


matCobrador

cabecalho

1

0:1

String(100)


cartaoCobrador

cabecalho

1

0:1

Memo - Base64


dataMovimento

cabecalho

1

1:1

String - AAAAMMDD


filipeta

cabecalho

1

1:1

String(100)


servicos-20:1Array
codServicoservicos20:1String(01)
codVeiculoservicos20:1String(40)

prefixoLinha

servicos

2

0:1

String(100)


codigoLinhaservicos20:1

String(40)


turnoservicos20:1String(100)
dataInicioViagemservicos21:1String - AAAAMMDD
dataTerminoViagemservicos21:1String - AAAAMMDD
hrInicioservicos21:1String(01)
hrFimservicos21:1String(01)
dadosValidadorservicos21-
roletaInicioValidadordadosValidador20:1String(01)
roletaFimdadosValidador20:1String(01)
pagamentos-31Array
tipoPagamentopagamentos31:1String(01)
quantidadePassageirospagamentos31:1Numerico
valorUnitariopagamentos31:1Numerico
totalArrecadadoservicos20:1Numerico
totalGratuidadesservicos20:1Numerico
totalDinheiroservicos20:1Numerico
diferencaservicos20:1Numerico

Os atributos não obrigatórios têm que fazer parte da estrutura, somente o seu preenchimento é opcional.

{
    "layoutColetor":{        
		"softwareColetor": "Software coletor",   
		"versaoColetor": "20"
	},
    "cabecalho":{
			  "empresa": "02",        
        "matMotorista": "000063",
			  "cartaoMotorista":"7475975", 
        "matCobrador": "919191",
			  "cartaoCobrador":"7475976",  
		    "dataMovimento": "20240101",
			  "filipeta":"000002582789610"
    },
    "servicos":[
        {
            "codServico": "02",
            "codVeiculo": "PREFIX",
            "prefixoLinha": "73859",
            "codigoLinha": "20",
            "turno": "1",
            "dataInicioViagem": "20240101",
            "dataTerminoViagem": "20240101",
            "hrInicio": "0200",
            "hrFim": "0300",            
            "dadosValidador":{    
                    "roletaInicioValidador": "0000001",
                    "roletaFim": "0000002",
                    "pagamentos":[{
                        "tipoPagamento": "000004",  
                        "quantidadePassageiros": 20,
                        "valorUnitario": 20.02                        
                    }]
                },
                "totalArrecadado": 200.00,
                "totalGratuidades": 12.30,
                "totalDinheiro": 32.50,  
                "diferenca": 10.10      
            }        
    ]
}


Estrutura da mensagem de retorno do POST (Response):


Atributo

Pai

Nivel

Ocorrência

Formato

status

-

1

0:1

String(7)

prestacaoContas

-

1

0:1

String(6)

message-10:1String(36)


  • status – Informação de sucesso ou erro
  • prestacaoContas – Código cadastrado da prestação de contas
  • Message - Mensagem de sucesso ou de erro



{
"status": "sucess",
"prestacaoContas": "000002",
"status": "Prestação de contas incluída com sucesso",
}


Código De Erro De Validação:


  • 400 – Cadastro não encontrado


Legenda:

# - valor variável.

{
	"errorCode": 400,
	"errorMessage": "Cadastro de linha não encontrada"
}



RESTFAULT*


  • 500 - Erro Interno no Servidor
{
	"code": 500,
	"detailedMessage": "",
	"message": "Internal Server Error"
}