Definição do Serviço

Nome: WSQueryElementsWSTAFQueryElements

Objetivo: Consultar uma lista de elementos presentes na base de dados do TAF, através de um status 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 Fiscal, para obter uma série de registros/elementos através de um status pré-definido pela aplicação tipo do registro ( de acordo com os status tipos existentes no TAF ).

Métodos: GET

Configurações do Serviço

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

Nota
title Importante
Na Seção seção HTTPURI, a chave PrepareIn deve ser preenchida com o código da empresa/filial principal ou com "All" para todas os grupos de empresas empresas: PrepareIn para grupo de empresa e filial específica [HTTPURI] URL=/rest PrepareIn=99,01 Instances=1,1 PrepareIn para grupo de empresa e empresa específica  [HTTPURI] URL=/rest PrepareIn=T1,D MG 01 Instances=1,1 PrepareIn para todas os grupos de empresas [HTTPURI] 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 URL=/rest PrepareIn=All Instances=1,1 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

• • status - Status do registro na base de dados do TAF. Os códigos válidos podem ser encontrados no Manual de Integração.
Obrigatório caso registryType não seja informado.
• registryType - Tipo do registro (código do campo TAFTPREG). Obrigatório caso status não seja informado.
startRecNo - Número do RecNo Inicial a ser considerado na consulta. 
Observação :
• • Não é obrigatório.
    Observação: Para consultar Status que seja "em branco" deve-se inserir da seguinte maneira: status: ' '  ( 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 do RecNo Inicial a ser considerado na consulta.
  • sourceBranch - Código Identificador da filial do ERP emissor.
    

Observação : O Tamanho máximo do Response é

850kB, 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 da Resposta do método GET ( Response ):

Atributo

Pai

Nivel

Nível

Ocorrência

Formato

type

registryType

-

1

1

-

code

statusCode

-

1

0:1

:N

String(

36-100

1)
Items	-	1	1	-
registryKey	Items	2	1	String(100)
statusCode	Items	2	0:1	String(1)
statusDescription	Items	2	0:1	String(25)

registryType

Items

2

0:1

String(10)

registryTypeDescription

Items

2

0:1

String(36)

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)

 

type – Determina o agrupamento do retorno que pode ser por status (

• registryType – Tipo do registro ( conforme campo TAFTPREG ).
• statusCode – Status do registro no TAF

) ou registryType (TAFTPREG), o agrupamento depende dos parâmetros enviados no request, quando o status é informado e o registryType omitido, o retorno será por status, caso contrário por registryType.code – Código do registro indicado no atributo type

• , 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 agrupamento do request for por registryType

• o parâmetro status não for informado na requisição.
• statusDescription – Descrição do status no TAF, atributo exibido somente quando

o agrupamento do request for por registryType

• o parâmetro status não for informado na requisição.

registryType – Tipo do registro (conforme campo TAFTPREG), atributo exibido somente quando o agrupamento do request for por status.

registryTypeDescription – Descrição do tipo do registro (conforme campo TAFTPREG), atributo exibido somente quando o agrupamento do request for por status.

validateErrors – Agrupa todos os erros de layout identificado pelo processo de validação do TAF. Os erros são listados por validateErrorCode e validateErrorDetail.

• 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 –

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

por status

sem informar o STATUS:

Request:

GET http://

172.16.31.214:8085

localhost:8080/rest/

wsqueryelements2

WSTAFQueryElements?

status

registryType=

4

T011&startRecNo=

0

70 HTTP/1.1

Accept-Encoding: gzip,deflate
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:
{ "

type

registryType": "

status

T011", "

code

itens":

"4",

"items":

[ { "registryKey": "

KEY000001S-220020170101

20170620141315DMG01_0000000571", "

registryType

statusCode": "

S-2200

0", "

registryTypeDescription

statusDescription": "

Admissão

Registro validado

do

pelo

Funcionário

TAF"

,

},

"registryProtocol": "20170520081000S2200"

},

{ "registryKey": "

KEY000001S-210020170101

20170620141315DMG01_0000000572", "

registryType

statusCode": "

S-2100

0", "

registryTypeDescription

statusDescription": "

Cadastro

Registro

Inicial

validado

do

pelo

Funcionário

TAF"

,

"registryProtocol": "20170521151402S2100"

},

}

],

"lastRecNo":

2,

"maxRecNo

{ "registryKey":

2 }

 

• Consulta por registryType:

Request:

http://172.16.31.214:8085/rest/wsqueryelements2?registryType=S-2200&startRecNo=0

 

Bloco de código

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

{ "type": "registryType", "code": "S-2200", "items": [

"20170620141315DMG01_0000000573", "statusCode": "0", "statusDescription": "Registro validado pelo TAF" }, { "registryKey": "

KEY000001S-220020170101

20170620141315DMG01_0000000574", "statusCode": "

4

0", "statusDescription": "Registro

Transmitido

validado

com

pelo

sucesso

TAF"

,

"registryProtocol": "20170520081000S2200"

}

}

],

{

"lastRecNo": 73,

"registryKey": "KEY004301S-220020170823", "statusCode": "1", "statusDescription": "Registro não Transmitido - Inválido", "validateErros": [ { "validateErrorCode": "000267", "validateErrorDetail": "A data de admissão do trabalhador João da Silva, para a categoria [103] (aprendiz), deve ser maior ou igual a [20/12/2000]" } { "validateErrorCode": "000335", "validateErrorDetail": "A data de admissão deve ser anterior a data de início do e-Social." } ] } ], "lastRecNo": 232, "maxRecNo": 232 }

 

• Consulta pelo status + registryType:

Request:

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

Bloco de código
language js theme Eclipse title Response:
{ "type": "status", "code": "4", "items": [ { "registryKey": "KEY000001S-220020170101", "registryType": "S-2200", "registryTypeDescription": "Admissão do Funcionário", "registryProtocol": "20170520081000S2200" } ], "lastRecNo": 2, "maxRecNo": 2 }

Aviso
title Atenção!
Quando a consulta for por status + registryType o retorno será agrupado por registryType.

 

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:

{
  "type": "status",
  "code": "4",
  "items": [
    {
      "registryKey": "KEY000001S-220020170101",
      "registryType": "S-2200",
      "registryTypeDescription": "Admissão do Funcionário",
      "registryProtocol": "20170520081000S2200"
    },
*
*
*
{several items}
*
*
*
    {
      "registryKey": "KEY000001S-210020170101",
      "registryType": "S-2100",
      "registryTypeDescription": "Cadastro Inicial do Funcionário",
      "registryProtocol": "20170521151402S2100"
    }
  ],
  "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:

http://172.16.31.214:8085/rest/wsqueryelements2?status=4&registryType=S-2200&startRecNo=151

"maxRecNo": 73
}

{
   "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
}

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

{
   "registryType": "S-2200",
   "statusCode": "1",
  "items

Exemplo de Consumo do Serviço

#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
	
	If cMetodo == "GET"
	
		While lContinue
			nPag++
			oRestClient:setPath("/rest/wsqueryelements?status=4&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+1
			   		EndIf
			   	EndIf
			   	oObj := Nil
			Else
			   ConOut("GET", oRestClient:GetLastError())
			   lContinue := .F.
			EndIf
		End
		ConOut("------FIM------")
	EndIf
	
	FreeObj(oRestClient)
Return 

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

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

": [
    {
      "

registryKey": "

KEY000151S-220020170101",
      "

registryProtocol": 

"201705206912365S2200"
    

},
*
*
*
{several items}
*
*
*
    {
    

"registryKey": "KEY000322S-220020170101",
      "

registryProtocol": 

"20170529875302S2200"
    }
  

],
  "

lastRecNo": 

322,
 

 "maxRecNo": 322
}

Exemplo de Consumo do Serviço

#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 

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