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	TAFST2	Ocorrência	Formato
ticketCode	-	1		1	String(36)
lote	-	1		1:N	-
sourceBranch	lote	2	TAFFIL	1	String(40)
messageType	lote	2	TAFCODMSG	1	String(01)
messageSequential	lote	2	TAFSEQ	1	String(03)
registryType	lote	2	TAFTPREG	1	String(10)
registryKey	lote	2	TAFKEY	1	String(100)
integrationMessage	lote	2	TAFMSG	1	Memo - Base64
integrationDate	lote	2	TAFDATA	0:1	String - AAAAMM01
integrationTime	lote	2	TAFHORA	0:1	String - HH:MM:SS
registryPriority	lote	2	TAFPRIORIT	0:1	String(01)
integrationQueue	lote	2	TAFSTQUEUE	0:1	String(01)
erpowner	lote	2	TAFOWNER	0:1	String(40)
registryPredecessor	lote	2	TAFREGPRED	0:1	String(100)
transferBranch	lote	2	TAFFILTRAN	0:1	String(40)
complement	lote	2	TAFCOMP	0:1	String(100)

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

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

Para a utilização de caracteres especiais nos conteúdos dos atributos, é necessário a definição do encode correto no Header das mensagens de todos os métodos.
Por exemplo, para permitir caracteres como Ç ou Â, deve se usar o encode UTF-8 no Header.

Authorization : Basic ******

Content-Type : application/json;charset=UTF-8

Estrutura da mensagem de retorno do POST (Response):

Atributo	Pai	Nivel	Ocorrência	Formato
ticketCode	-	1	0:1	String(36)
registryKey	-	1	0:N	-
coderr	-	1	0:1	Int(3)
description	-	1	0:1	String(100)
key	registryKey	2	1	String(100)
success	registryKey	2	1	boolean(true : false)
error	registryKey	2	0:N	-
coderr	error	3	1	Int(3)
description	error	3	1	String(100)
keyAmount	registryKey	1	0:1	Int(9999)

ticketCode – atributo raiz
registryKey – Array contendo os TAFKEY requisitados.
coderr - Código de erro que impediu a integração do lote
description - Descrição do erro que impossibilitou a integração do lote.
key – Código do TAFKEY
success – Informa se o TAFKEY foi integrado ou não.
error – Array contendo os erros que impediram a integração do registro. Atributo gerado somente quando success for igual a false.
coderr – Código do erro que impossibilitou a integração.
description – Descrição do erro que impossibilitou a integração.
keyAmount – Número de registros enviados no POST.

{"ticketCode" : "WIO9753123654789789363655241452363",
  "lote": [
    	{"sourceBranch" : "0100",
      	 "messageType" : "2",
      	 "messageSequential" : "001",
      	 "registryType" : "S-1010",
      	 "registryKey" : "KEYIO7878874854545454998598525",
      	 "integrationMessage": "PGVTb2NpYWw+PGV2dFRhYlJ1YnJpY2EgaWQ9J1MtMTAxMDEzMDUyMDE2MTU0MDE2JyB2ZXJzYW89JzEuMSc+PGlkZUV2ZW50bz48dHBBbWI+MzwvdHBBbWI+PHByb2NFbWk+MTwvcHJvY0VtaT48dmVyUHJvYz48L3ZlclByb2M+PC9pZGVFdmVudG8+PGlkZUVtcHJlZ2Fkb3I+PHRwSW5zYz4xPC90cEluc2M+PG5ySW5zYz41MzExMzc5MTAwMDEyMjwvbnJJbnNjPjwvaWRlRW1wcmVnYWRvcj48aW5mb1J1YnJpY2E+PGFsdGVyYWNhbz48aWRlUnVicmljYT48Y29kUnVicj45OTg8L2NvZFJ1YnI+PGluaVZhbGlkPjIwMTYtMDM8L2luaVZhbGlkPjwvaWRlUnVicmljYT48ZGFkb3NSdWJyaWNhPjxkc2NSdWJyPkJBU0UgUEVOU0FPIFBHVE88L2RzY1J1YnI+PG5hdFJ1YnI+OTk4OTwvbmF0UnVicj48dHBSdWJyPjM8L3RwUnVicj48Y29kSW5jQ1A+MDA8L2NvZEluY0NQPjxjb2RJbmNJUlJGPjAwPC9jb2RJbmNJUlJGPjxjb2RJbmNGR1RTPjAwPC9jb2RJbmNGR1RTPjxjb2RJbmNTSU5EPjAwPC9jb2RJbmNTSU5EPjxyZXBEU1I+TjwvcmVwRFNSPjxyZXAxMz5OPC9yZXAxMz48cmVwRmVyaWFzPk48L3JlcEZlcmlhcz48cmVwUmVzYz5OPC9yZXBSZXNjPjwvZGFkb3NSdWJyaWNhPjwvYWx0ZXJhY2FvPjwvaW5mb1J1YnJpY2E+PC9ldnRUYWJSdWJyaWNhPjwvZVNvY2lhbD4=",
      	 "integrationDate" : "20161210",
	  	 "integrationTime": "14:15:22",
		 "erpowner" : "DATASUL"
    	},
		{"sourceBranch" : "0100",
      	 "messageType" : "2",
      	 "messageSequential" : "001",
      	 "registryType" : "S-2200",
	  	 "registryKey" : "KEYYZE7878RE4854545454998598576",
	  	 "integrationMessage":
"PGVTb2NpYWw+PGV2dENhZEluaWNpYWwgSWQ9J0lEMTUzMTEzNzkxMDAwMDAwMjAxNjEyMDkxNDU5NTQwMDAwMSc+PGlkZUV2ZW50bz48aW5kUmV0aWY+MTwvaW5kUmV0aWY+PG5yUmVjaWJvPjwvbnJSZWNpYm8+PHRwQW1iPjM8L3RwQW1iPjxwcm9jRW1pPjE8L3Byb2NFbWk+PHZlclByb2M+MS4wPC92ZXJQcm9jPjwvaWRlRXZlbnRvPjxpZGVFbXByZWdhZG9yPjx0cEluc2M+MTwvdHBJbnNjPjxuckluc2M+NTMxMTM3OTE8L25ySW5zYz48L2lkZUVtcHJlZ2Fkb3I+PHRyYWJhbGhhZG9yPjxjcGZUcmFiPjMyMDA5MDM3ODQ2PC9jcGZUcmFiPjxuaXNUcmFiPjEyMjAzNjcxODQ0PC9uaXNUcmFiPjxubVRyYWI+IEdUIFhNQlBFUkhVSlpOQ1FGU0lWTEFPRDwvbm1UcmFiPjxzZXhvPk08L3NleG8+PHJhY2FDb3I+MTwvcmFjYUNvcj48ZXN0Q2l2PjI8L2VzdENpdj48Z3JhdUluc3RyPjwvZ3JhdUluc3RyPjxuYXNjaW1lbnRvPjxkdE5hc2N0bz4xOTc2LTA0LTEzPC9kdE5hc2N0bz48Y29kTXVuaWM+MTIwMDEwNTwvY29kTXVuaWM+PHVmPlNQPC91Zj48cGFpc05hc2N0bz4wMTM8L3BhaXNOYXNjdG8+PHBhaXNOYWM+MDEzPC9wYWlzTmFjPjxubU1hZT5ORVVTQSBDQVJWQUxITyBORVZFUzwvbm1NYWU+PG5tUGFpPkpPU0UgUkVZTkFMRE8gQ1JFU1BPIE5FVkVTPC9ubVBhaT48L25hc2NpbWVudG8+PGRvY3VtZW50b3M+PENUUFM+PG5yQ3Rwcz4wMDAzNTgwMDwvbnJDdHBzPjxzZXJpZUN0cHM+MDAwNzM8L3NlcmllQ3Rwcz48dWZDdHBzPlNQPC91ZkN0cHM+PC9DVFBTPjxSRz48bnJSZz4xNi43MjEuMDMwPC9uclJnPjxvcmdhb0VtaXNzb3I+U1NQPC9vcmdhb0VtaXNzb3I+PGR0RXhwZWQ+MTk4Mi0wMy0wMjwvZHRFeHBlZD48L1JHPjxDTkg+PG5yUmVnQ25oPjAwMDAwMDAwMDA8L25yUmVnQ25oPjx1ZkNuaD48L3VmQ25oPjxkdFZhbGlkPjwvZHRWYWxpZD48Y2F0ZWdvcmlhQ25oPjwvY2F0ZWdvcmlhQ25oPjwvQ05IPjwvZG9jdW1lbnRvcz48ZW5kZXJlY28+PGV4dGVyaW9yPjxwYWlzUmVzaWQ+MDEzPC9wYWlzUmVzaWQ+PGRzY0xvZ3JhZD5BTEJBPC9kc2NMb2dyYWQ+PG5yTG9ncmFkPjE0NDQ8L25yTG9ncmFkPjxiYWlycm8+UFEuIEpBQkFRVUFSQTwvYmFpcnJvPjxubUNpZD5TQU4gTFVJWjwvbm1DaWQ+PGNvZFBvc3RhbD4wNDM0NjAwMDwvY29kUG9zdGFsPjwvZXh0ZXJpb3I+PC9lbmRlcmVjbz48aW5mb0RlZmljaWVuY2lhPjxkZWZGaXNpY2E+TjwvZGVmRmlzaWNhPjxkZWZWaXN1YWw+TjwvZGVmVmlzdWFsPjxkZWZBdWRpdGl2YT5OPC9kZWZBdWRpdGl2YT48ZGVmTWVudGFsPk48L2RlZk1lbnRhbD48ZGVmSW50ZWxlY3R1YWw+TjwvZGVmSW50ZWxlY3R1YWw+PHJlYWJSZWFkYXA+TjwvcmVhYlJlYWRhcD48L2luZm9EZWZpY2llbmNpYT48YXBvc2VudGFkb3JpYT48dHJhYkFwb3NlbnQ+TjwvdHJhYkFwb3NlbnQ+PC9hcG9zZW50YWRvcmlhPjxjb250YXRvPjxmb25lUHJpbmM+MDAxMzQ3MzU1NTUgLzwvZm9uZVByaW5jPjxmb25lQWx0ZXJuYXQ+MDExNzg5Nzk4Nzk4PC9mb25lQWx0ZXJuYXQ+PGVtYWlsQWx0ZXJuYXQ+UkVZTkFMRE9ASE9UTUFJTC5DT008L2VtYWlsQWx0ZXJuYXQ+PC9jb250YXRvPjwvdHJhYmFsaGFkb3I+PHZpbmN1bG8+PG1hdHJpY3VsYT4wMDAwMDAwMDAwMDAwMDAwMDAwNzwvbWF0cmljdWxhPjx0cFJlZ1RyYWI+MTwvdHBSZWdUcmFiPjx0cFJlZ1ByZXY+MTwvdHBSZWdQcmV2PjxpbmZvUmVnaW1lVHJhYj48L2luZm9SZWdpbWVUcmFiPjxpbmZvQ29udHJhdG8+PGNvZENhdGVnPjMwMjwvY29kQ2F0ZWc+PHJlbXVuZXJhY2FvPjx2clNhbEZ4PjEwMDAuMDA8L3ZyU2FsRng+PHVuZFNhbEZpeG8+NTwvdW5kU2FsRml4bz48L3JlbXVuZXJhY2FvPjxkdXJhY2FvPjx0cENvbnRyPjE8L3RwQ29udHI+PC9kdXJhY2FvPjxsb2NhbFRyYWJhbGhvPjwvbG9jYWxUcmFiYWxobz48L2luZm9Db250cmF0bz48L3ZpbmN1bG8+PC9ldnRDYWRJbmljaWFsPjwvZVNvY2lhbD4=",
	 	 "integrationDate" : "",
	 	 "integrationTime" :  "",
         "registryPriority" : "0",
	     "integrationQueue" : "1",
         "erpowner" : "DATASUL",
         "registryPredecessor" : "KEYIO7878874854545454998598525",
         "transferBranch" : "0200"
  		}
  	]
}

{
"ticketCode": "WIO9753123654789789363655241452363",
"registryKey": [
	{
		"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.

No método POST caso o primeiro item do lote não esteja com o TAFFIL cadastrado no complemento de empresas o sistema irá rejeitar o lote inteiro, caso contrario é realizado uma avaliação item a item verificando se a filial é válida e se pertence ao mesmo grupo de empresas no TAF, neste caso é rejeitado somente os registros inválidos dentro do lote.

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

Legenda:

# - valor variável.

{
    "coderr": 803,
    "description": "O valor do campo sourceBranch (TAFFIL)  não está no cadastro no complemento de empresas."
}

{
  "ticketCode": "WIO9753123654789789363655241452363",
  "registryKey": [
    {
      "key": "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*

701 - startRecno e ticketCode não informados no GET (é obrigatório que pelo menos 1 deles seja informado)
702 - Erro na criação/abertura da tabela TAFST2 ou TAFXERP
703 - O parâmetro searchMode deve ser preenchido com 1 ou 2.
704 - Arquivo vazio (Não foi enviado uma mensagem no body do POST)
705 - Erro ao realizar parser da mensagem (o arquivo enviado no Body não é um json válido)

Apesar do código de erro iniciar com 7 o status HTTP de um request que submetido a RestFault é 500 - Erro Interno no Servidor.