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.

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. 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 do HEADER da requisição:

.

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

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 http://localhost:8080/rest/WSTAFQueryElements?status=1&registryType=S-1060&startRecNo=0 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 http://localhost:8080/rest/WSTAFQueryElements?status=1&registryType=S-2200&startRecNo=151 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.