Web Service REST

Produto:	TOTVS Automação Fiscal
Versões:	12.1.17+

Este documento tem o objetivo de fornecer informações para utilização do Web Service REST, para consulta de elementos/registros do TOTVS Automação Fiscal, de acordo com o status ou tipo do registro.

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.

Índice

Índice

indent	30px
absoluteUrl	true

Definição do Serviço

Nome: WSTAFQueryElements

Objetivo: Consultar uma lista de elementos presentes na base de dados do TAF, através de um tipo pré-definido.

Descrição: O serviço permite, que uma aplicação faça uma consulta generalizada na base de dados do TOTVS Automação Fiscal, para obter uma série de registros/elementos através de um tipo do registro (de acordo com os tipos existentes no TAF).

Métodos: GET

Configurações do Serviço

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

Nota

title	Importante

Na seção HTTPURI, a chave PrepareIn deve ser comentada. A empresa principal deverá estar informada na seção [TAF_CFGJOB]. Não há necessidade da inclusão de mais empresas, pois o próprio WS fará esse controle. Para acessar as demais empresas, basta informar o CNPJ (CGC), Inscrição Estadual (INSCEST) e Inscrição Municipal (INSCMUN) no Header da requisição ao WS.

Segue exemplo de configuração do WS REST:

[HTTPV11]
SOCKETS=HTTPREST
ENABLE=1

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

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

[HTTPJOB]
MAIN=HTTP_START
ENVIRONMENT=P12

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

[OnStart]
JOBS=HTTPJOB,TAF_CFGJOB
RefreshRate=120

Fonte: REST com ERP Microsiga Protheus

Definição dos métodos

GET

Descrição do Método:

O método GET retorna uma lista de elementos encontrados na base de dados, de acordo com os parâmetros (atributos) enviados na URL.

A Consulta pode combinar parâmetros utilizando a sintaxe “Query String”, conforme exemplo abaixo:

http://172.16.31.214:8085/rest/wstafqueryelements?status=4&registryType=S-1010&startRecNo=0

Parâmetro	Descrição	Obrigatório
status	Status do registro no TAF
registryType	Tipo do registro/layout. Exemplo: T007, S-1010...	O
startRecNo	RecNo inicial para consulta	O

- status - Status do registro na base de dados do TAF. Os códigos válidos podem ser encontrados no Manual de Integração. Não é obrigatório.
  Observação: Para consultar Status que seja "em branco" deve-se inserir da seguinte maneira: status: ' '

(aspassimplesespaçoaspassimples

- ( aspas simples espaço aspas simples ). Exemplo:
  http://localhost:8080/rest/WSTAFQueryElements?status=' '&registryType=T001AE&startRecNo=0

-

- Ou
  http://localhost:8080/rest/WSTAFQueryElements?status=%27%20%27&registryType=T001AE&startRecNo=0

- registryType - Tipo do registro ( código do campo TAFTPREG ). Obrigatório.
- startRecNo -

Número

- Número do RecNo Inicial a ser considerado na consulta.

Observação : O Tamanho máximo do Response é 850 kB, quando a mensagem chega neste valor, é realizado um retorno contendo os registros que já foram incrementados na resposta. O Controle dos itens restantes é feito através do lastRecNo, que informa o RecNo do ultimo registro que fez parte da mensagem anterior (respeitando a chave), caso o mesmo seja diferente de maxRecNo é por que existem itens a serem retornados, caso o contrario a consulta está completa.

Estrutura do HEADER da requisição:

Parâmetro	Descrição	Obrigatório
CGC	CGC da Empresa/Filial cadastrada no SIGAMAT.EMP	O
INSCEST	Inscrição estadual da Empresa/Filial cadastrada no SIGAMAT.EMP	O
INSCMUN	Inscrição Municipal da Empresa/Filial cadastrada no SIGAMAT.EMP

Estrutura da Resposta do método GET (Response):

Nivel

Atributo	Pai	Nível	Ocorrência	Formato
registryType	-	1	1	-
statusCode	-	1	0:1	String(1)
Items	-	1	1	-
registryKey	Items	2	1	String(100)
statusCode	Items	2	0:1	String(1)
statusDescription	Items	2	0:1	String(25)
validateErrors	Items	2	0:1	-
validateErrorCode	validateErrors	3	0:1	String(6)
validateErrorDetail	validateErrors	3	0:1	String(220)
streamingErrors	Items	2	0:1	-
streamingErrorCode	streamingErrors	3	0:1	String(6)
streamingErrorDetail	streamingErrors	3	0:1	String(220)
registryProtocol	Items	2	0:1	String(60)
lastRecNo	-	1	1	Int(9999)
maxRecNo	-	1	1	Int(9999)

registryType – Tipo do registro ( conforme campo TAFTPREG ).
statusCode – Status do registro no TAF, atributo exibido somente quando o parâmetro status for informado na requisição.
items – Itens do response.
registryKey – código do TAFKEY. Essa informação sempre será retornada, para que a aplicação de origem consiga identificar o registro em sua própria base de dados.
statusCode – Status do registro no TAF, atributo exibido somente quando o parâmetro status não for informado na requisição.
statusDescription – Descrição do status no TAF, atributo exibido somente quando o parâmetro status não for informado na requisição.
validateErrors – Agrupa todos os erros de layout identificado pelo processo de validação do TAF. Os erros são listados por validateErrorCode e validateErrorDetail.
validateErrorCode – Código do erro identificado pelo processo de validação do TAF.
validateErrorDetail – Descrição do erro identificado pelo processo de validação do TAF.
streamingErrors – Agrupa todos os erros de transmissão retornados do Governo para o TAF. Os erros são listados por streamingErrorCode e streamingErrorDetail.
streamingErrorCode – Código do erro retornado pelo Governo para o TAF, após transmissão do registro.
streamingErrorDetail – Descrição do erro retornado pelo Governo para o TAF, após transmissão do registro.
registryProtocol – Recibo retornado do Governo para o TAF após a transmissão do registro ter sido realizada com sucesso.
lastRecNo - Numero do RecNo do ultimo registro retornado na requisição.
maxRecNo - Informa o numero do RecNo do ultimo registro relacionado a consulta, deve ser utilizado juntamente com o lastRecNo para controlar a paginação e garantir o retorno de todos os registros.

Exemplos de requisição utilizando o método GET:

Consulta sem informar o STATUS:

Request:

GET http://localhost:8080/rest/WSTAFQueryElements?registryType=T011&startRecNo=70 HTTP/1.1

Accept-Encoding: gzip,deflate
CGC: 43211325000126 -> HEADER
INSCEST: 0621608450090 -> HEADER
INSCMUN: -> HEADER
Host: localhost:8080
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Bloco de código

language	js
theme	Eclipse
title	Response:

  {
   "registryType": "T011",
   "itens":    [
            {
         "registryKey": "20170620141315DMG01_0000000571",
         "statusCode": "0",
         "statusDescription": "Registro validado pelo TAF"
      },
            {
         "registryKey": "20170620141315DMG01_0000000572",
         "statusCode": "0",
         "statusDescription": "Registro validado pelo TAF"
      },
            {
         "registryKey": "20170620141315DMG01_0000000573",
         "statusCode": "0",
         "statusDescription": "Registro validado pelo TAF"
      },
            {
         "registryKey": "20170620141315DMG01_0000000574",
         "statusCode": "0",
         "statusDescription": "Registro validado pelo TAF"
      }
   ],
   "lastRecNo": 73,
   "maxRecNo": 73
}

Consulta informando o STATUS:

Request:

GET httpGET http://localhost:8080/rest/WSTAFQueryElements?status=1&registryType=S-1060&startRecNo=0 HTTP0 HTTP/1.1
Accept-Encoding: gzip,deflate
CGC: 43211325000126 -> HEADER
INSCEST: 0621608450090 -> HEADER
INSCMUN: -> HEADER
Host: localhost:8080
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Bloco de código

language	js
theme	Eclipse
title	Response após a execução do processamento:

{
   "registryType": "S-1060",
   "statusCode": "1",
   "itens":    [
            {
         "registryKey": "Inclusão Manual",
         "validateErrors":          [
                        {
               "validateErrorCode": "000692",
               "validateErrorDetail": "Cadastro de Ambientes de Trabalho - Campo: Tp.Inscrição (T04_TPINSC) - Se empregador PJ, o campo tipo de inscrição deve ser CNPJ (1)."
            },
                        {
               "validateErrorCode": "000693",
               "validateErrorDetail": "Cadastro de Ambientes de Trabalho - Campo: Nr.Insc. (T04_NRINSC) - Se o Local Amb. for próprio do empregador ({localAmb} = [1]), o estabelecimento deve pertencer ao empregador e constar da tabela S-1005."
            }
         ]
      },
            {
         "registryKey": "Inclusão Manual",
         "validateErrors":          [
                        {
               "validateErrorCode": "000692",
               "validateErrorDetail": "Cadastro de Ambientes de Trabalho - Campo: Tp.Inscrição (T04_TPINSC) - Se empregador PJ, o campo tipo de inscrição deve ser CNPJ (1)."
            },
                        {
               "validateErrorCode": "000693",
               "validateErrorDetail": "Cadastro de Ambientes de Trabalho - Campo: Nr.Insc. (T04_NRINSC) - Se o Local Amb. for próprio do empregador ({localAmb} = [1]), o estabelecimento deve pertencer ao empregador e constar da tabela S-1005."
            }
         ]
      },
            {
         "registryKey": "T1D MG 01_S-1060_20170626_1514430001.XML",
         "validateErrors": [         {
            "validateErrorCode": "000693",
            "validateErrorDetail": "Cadastro de Ambientes de Trabalho - Campo: Nr.Insc. (T04_NRINSC) - Se o Local Amb. for próprio do empregador ({localAmb} = [1]), o estabelecimento deve pertencer ao empregador e constar da tabela S-1005."
         }]
      },
            {
         "registryKey": "T1D MG 01_S-1060_20170626_1514430002.XML",
         "validateErrors": [         {
            "validateErrorCode": "000693",
            "validateErrorDetail": "Cadastro de Ambientes de Trabalho - Campo: Nr.Insc. (T04_NRINSC) - Se o Local Amb. for próprio do empregador ({localAmb} = [1]), o estabelecimento deve pertencer ao empregador e constar da tabela S-1005."
         }]
      },
            {
         "registryKey": "T1D MG 01_S-1060_20170626_1514430003.XML",
         "validateErrors": [         {
            "validateErrorCode": "000694",
            "validateErrorDetail": "Cadastro de Ambientes de Trabalho - Campo: Nr.Insc. (T04_NRINSC) - Se o Local Amb. de terceiros ({localAmb} = [2]), a raiz do CNPJ pode ser diferente da constante no S-1000, porém deve constar na Tabela de Lotações Tributárias (S-1020)."
         }]
      }
   ],
   "lastRecNo": 5,
   "maxRecNo": 5
}

Controle de Paginação:

Quando o retorno de uma requisição ultrapassa o valor de 850 Kb a mensagem de resposta é "quebrada" e retornada com o conteúdo até então incrementado, exemplo:

Bloco de código

theme	Eclipse
title	Exemplo de Paginação

{
   "registryType": "S-2200",
   "statusCode": "1",
  "items": [
    {
      "registryKey": "KEY000001S-220020170101",
      "registryProtocol": "20170520081000S2200"
    },
*
*
*
{several items}
*
*
*
    {
      "registryKey": "KEY000150S-220020170101",
      "registryProtocol": "20170521151402S2200"
    }
  ],
  "lastRecNo": 150,
  "maxRecNo": 322
}

No exemplo acima, a consulta retornou até o registro 150, sendo que o registro com maior RecNo pertencente a consulta é o 322, isso não quer dizer que foram retornados 150 registros e que faltam 172, o RecNo apenas informa a sequencia do registro no response, porém o lastRecNo menor que o maxRecNo indica que ainda existem registro a serem retornados para a chave requisitada. Para o retorno dos demais registros deve-se realizar uma nova requisição com o startRecNo igual a lastRecNo + 1, este procedimento deve ser adotado até que o lastRecNo seja igual ao maxRecNo, conforme exemplo abaixo:

Request:

GET httpGET http://localhost:8080/rest/WSTAFQueryElements?status=1&registryType=S-2200&startRecNo=151 HTTP151 HTTP/1.1
Accept-Encoding: gzip,deflate
CGC: 43211325000126 -> HEADER
INSCEST: 0621608450090 -> HEADER
INSCMUN: 047560 -> HEADER
Host: localhost:8080
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Bloco de código

theme	Eclipse
title	Response

{
   "registryType": "S-2200",
   "statusCode": "1",
  "items": [
    {
      "registryKey": "KEY000151S-220020170101",
      "registryProtocol": "201705206912365S2200"
    },
*
*
*
{several items}
*
*
*
    {
      "registryKey": "KEY000322S-220020170101",
      "registryProtocol": "20170529875302S2200"
    }
  ],
  "lastRecNo": 322,
  "maxRecNo": 322
}

Exemplo de Consumo do Serviço

Bloco de código

language	delphi
theme	Eclipse
title	Client REST

#Include 'Protheus.ch'
Function WSCTAFST2(cMetodo)
	Local oRestClient := FWRest():New("http://172.16.31.214:8085")
	Local oObj   	:= Nil
	Local lContinue := .T.
	Local nPag		:= 0
	Local nRec		:= 0
	Local cLayout  := "S-1060"
	Local aHeader := {"CGC: 43211325000126","INSCEST: 0621608450090"}	
	If cMetodo == "GET"
	
		While lContinue
			nPag++
			oRestClient:setPath("/rest/wstafqueryelements?status=1&registryType="+ cLayout +"&startRecNo=" + AllTrim(Str(nRec)))
			If oRestClient:Get(aHeader)
				ConOut("Pag: " + AllTrim(Str(nPag)))
			   	ConOut("GET", oRestClient:GetResult())
			  	
				If FWJsonDeserialize(oRestClient:GetResult(),@oObj)
			   		If oObj:lastRecNo == oObj:maxRecNo
			   			lContinue := .F.
			   		Else
			   			nRec := oObj:lastRecNo
			   		EndIf
			   	EndIf
			   	oObj := Nil
			Else
			   ConOut("GET", oRestClient:GetLastError())
			   lContinue := .F.
			EndIf
		End
		ConOut("------FIM------")
	EndIf
	
	FreeObj(oRestClient)
Return

Bloco de código

language	js
theme	Eclipse
title	Exemplo de Resposta do método GET com RESTFAULT

  "errorCode": 101,
  "errorMessage": "obrigatorio o envio do parametro  registryType"
}

Códigos De Erros De Validação:

800 – Status (status) solicitado no request é inválido.

801 – Tipo de registro (registryType) solicitado no request é inválido.

Árvore de páginas

Versões comparadas

Versão antiga 32

Nova versão 33

Chave

Web Service REST

Definição do Serviço

Configurações do Serviço

Definição dos métodos

GET

Descrição do Método:

Estrutura do HEADER da requisição:

Estrutura da Resposta do método GET (Response):

Exemplos de requisição utilizando o método GET:

Consulta sem informar o STATUS:

Consulta informando o STATUS:

Controle de Paginação:

Exemplo de Consumo do Serviço

Códigos De Erros De Validação:

Árvore de páginas

Histórico da Página

Versões comparadas

Versão antiga 32

Nova versão 33

Chave

Web Service REST

Definição do Serviço

Configurações do Serviço

Definição dos métodos

GET

Descrição do Método:

Estrutura do HEADER da requisição:

Estrutura da Resposta do método GET (Response):

Exemplos de requisição utilizando o método GET:

Consulta sem informar o STATUS:

Consulta informando o STATUS:

Controle de Paginação:

Exemplo de Consumo do Serviço

Códigos De Erros De Validação: