RESTWeb Service REST

Produto:	TOTVS Prestadores de Serviços Transporte de Passageiros
Versões:	12.1.23102410+

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"

Nota

title	Importante

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

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

Bloco de código

language	actionscript3
theme	Eclipse
title	appserver.ini

[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

Informações

title	PrepareIn

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

Aviso

title	Consumo de Memória e CPU

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

TAFST2

	Ocorrência	Formato

ticketCode

	Cadastros Protheus
layoutColetor	-	1	1	-
softwareColetor	layoutColetor	1	1:1	String(

36

30)

lote

versaoColetor

-

layoutColetor

1

1:

N

1	String(30)
cabecalho	-	1	1

sourceBranch

-

lote

empresa

2

cabecalho

TAFFIL

1

1:1

String(

40)

6)

De/Para de empresas no configurador (SIGACFG)

( Ambiente - Schedule - De/Para de Mensagem Única)

matMotorista

cabecalho

1

0:

messageType

lote

2

TAFCODMSG

1

String(

01

15)

messageSequential

lote

2

TAFSEQ

Matricula no cadastro de colaboradores
cartaoMotorista	cabecalho	1	0:1	String(

03

50)

registryType

matCobrador

lote

cabecalho

2

1

TAFTPREG

0:1

String(

10

15)

registryKey

lote

2

TAFKEY

Matricula no cadastro de colaboradores
cartaoCobrador	cabecalho	1	0:1	String(

100

50)

integrationMessage

dataMovimento

lote

cabecalho

2

1

TAFMSG

1:1

Memo

String -

Base64

AAAAMMDD

integrationDate

filipeta

lote

cabecalho

20

1

TAFDATA

1:1

String

- AAAAMM01

(30)
servicos	-

integrationTime

lote

2

TAFHORA

0:1

String - HH:MM:SS

Array
codServico	servicos

registryPrioritylote

2

TAFPRIORIT

0:1

String(

01

15)

integrationQueue

codVeiculo

lote

servicos

2

TAFSTQUEUE

0:1

String(

01

8)

erpowner

Prefixo no cadastro de frotas
prefixoLinha	servicos

lote

2

TAFOWNER

0:1

String(

40

5)

registryPredecessor

Prefixo no cadastro de linhas
codigoLinha	servicos

lote

2

TAFREGPRED

0:1

String(

100)transferBranch

5)	Código no cadastro de linhas
turno	servicos

lote

2

TAFFILTRAN

0:1

String(

40)complementlote2TAFCOMP

1)
dataInicioViagem	servicos	2	1:1	String - AAAAMMDD
dataTerminoViagem	servicos	2	1:1	String - AAAAMMDD
hrInicio	servicos	2	1

0

:1

String(

100

5)

ticketCode – atributo raiz

lote - estrutura dos itens.

sourceBranch - Código Identificador da filial do ERP emissor.

messageType - Determina se o arquivo enviado em TAFMSG é .txt (1)ou .Xml(2).

messageSequential - Sequência do arquivo; A Mensagem em TAFMSG pode ser enviada em mais de 1 registro, para isso deve-se repetir as informações dos demais campos e alterar a sequencia de acordo com a ordem das informações enviadas.

registryType - Chave do Registro.

integrationMessage - Arquivo/Evento a ser integrado, a mensagem deve ser enviada com criptografia BASE64.
Obs: O XML pode ser enviado com a codificação UTF-8, neste caso é obrigatório o uso da declaração <?xml version="1.0" encoding="utf-8"?> no inicio do Xml.

integrationDate - Data da Integração.

integrationTime - Hora da Integração.

registryPriority - Prioridade de processamento do registro.

integrationQueue - Registro será considerado na fila de integração. '1' - Enable ou '0' - Disable.

erpowner - Identificação do dono do XML a ser integrado

registryPredecessor - Identificador com o TAFKEY do registro predecessor, caso exista algum registro que o preceda.

transferBranch - Identificador da Filial original do trabalhador a ser transferido.

complement - Campo aberto na TAFST2, onde para os eventos S-1200 e S-1210, quando informado o conteúdo MV será utilizado a regra de gravação de eventos de múltiplos vínculos (gravação aberta).


hrFim	servicos	2	1:1	String(5)
dadosValidador	servicos	2	1	-
roletaInicioValidador	dadosValidador	2	0:1	String(10)
roletaFim	dadosValidador	2	0:1	String(10)
pagamentos	-	3	1	Array
tipoPagamento	pagamentos	3	1:1	String(6)	Tipo de pagamento no cadastro de Forma de pagamento
quantidadePassageiros	pagamentos	3	1:1	Numerico
valorUnitario	pagamentos	3	1:1	Numerico
totalArrecadado	servicos	2	0:1	Numerico
totalGratuidades	servicos	2	0:1	Numerico
totalDinheiro	servicos	2	0:1	Numerico
diferenca	servicos	2	0:1	Numerico

Aviso

title	Atenção!

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

Aviso

title	Atenção!

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

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(36)

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

Bloco de código

language	js
theme	Eclipse
title	Exemplo de mensagem POST:

{
    "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	-	1	0:1	String(36)

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

Bloco de código

language	js
theme	Eclipse
title	Response:

{
"ticketCodestatus": "WIO9753123654789789363655241452363sucess",
"registryKeyprestacaoContas": [
	{
		"key": "KEYIO7878874854545454998598525",
		"success": true
	},
	{
		"key": "KEYYZE7878RE4854545454998598576",
		"success": true
	}
  ],
"keyAmount": 2
}

Códigos De Erros De Validação:

800 – Campo não informado na estrutura do arquivo.
801 – Campo obrigatório não enviado.
802 – Campo com valor inválido.
803 – TAFFIL não encontrado no complemento de empresas.
804 – Layout Inválido.
805 – Código de Prioridade inválido!
806 – Campo com erro na codificação ou criptografia
807 – Código de Fila inválido!
808 – Estrutura da tabela TAFST2 está desatualizada
809 - Não há configuração de empresas na chave PrepareIn seção TAF_CFGJOB
810 - Chave # de Identificação de filial não encontrada.
811 - Não foi possível identificar a filial # no corpo da mensagem.
812 - Código da Filial ERP # não pertence ao mesmo Grupo de Empresas no TAF considerando os registros integrados anteriormente neste lote.
813 - O TAFKEY # já existe na TAFST2 e encontra-se pendente de processamento ou em processamento.
814 - O Xml Contido no campo TAFMSG (integrationMessage) esta em desacordo com as versoes suportadas pelo TAF. Integracao da Versao 1.0 disponivel apenas para eventos SESMT

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

Bloco de código

language	js
title	Exemplo de mensagem POST:Exemplo de Resposta do método POST com erro de validação no LOTE.

{
    "coderr	"errorCode": 803400,
    "description	"errorMessage": "OCadastro valorde do campo sourceBranch (TAFFIL)  não está no cadastro no complemento de empresas.linha não encontrada"
}

RESTFAULT*

500 - Erro Interno no Servidor

Bloco de código

language	js
title	Exemplo de mensagem POST:Exemplo de Resposta do método POST com erro de validação no ITEM:.

{
  	"ticketCodecode": "WIO9753123654789789363655241452363"500,
  "registryKey": [
    {
      "key	"detailedMessage": "KEYIO7878874854545454998598525",
      "success": false,
      "error": [
        {
          "coderr": 801,
          "description": "Campo TAFFIL (sourceBranch)  e Obrigatorio."
        },
        {
          "coderr": 803,
          "description": "O valor do campo TAFFIL (sourceBranch)  nao esta cadastro no complemento de empresas."
        }
       {
          "coderr": 805,
          "description": "Codigo de Prioridade invalido! Codigo enviado: '8'. Codigos validos: 0 - Urgente, 1 - Prioridade Critica, 2 - Prioridade Alta, 3 - Prioridade Media, 4 - Prioridade Baixa, 5 - Nao Prioritario"
        }
      ]
    },
    {
      "key": "KEYYZE7878RE4854545454998598576",
      "success": true
    },
    {
      "key": "KEYQWE7878RE4854545454998598571",
      "success": true
    },
    {
      "key": "KEYQIU7878RE4854545454998598544",
      "success": true
    }
  ],
  "keyAmount": 4
}

RESTFAULT*

500 - Erro Interno no Servidor

	"message": "Internal Server Error"
}

Árvore de páginas

Versões comparadas

Versão antiga 4

Nova versão Atual

Chave

Definição do Serviço

Configurações do Serviço

Definição dos métodos

POST

Estrutura da mensagem enviada no POST (Request):

Estrutura da mensagem de retorno do POST (Response):

Estrutura da mensagem de retorno do POST (Response):

Códigos De Erros De Validação:

Código De Erro De Validação:

Árvore de páginas

Histórico da Página

Versões comparadas

Versão antiga 4

Nova versão Atual

Chave

Definição do Serviço

Configurações do Serviço

Definição dos métodos

POST

Estrutura da mensagem enviada no POST (Request):

Estrutura da mensagem de retorno do POST (Response):

Estrutura da mensagem de retorno do POST (Response):

Códigos De Erros De Validação:

Código De Erro De Validação: