Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

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 onde o TOTVS Automação Fiscal retorna, a partir de parâmetros de entrada, as mensagens XML que foram (ou serão) enviadas à base de dados do Governo.

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
indent30px
absoluteUrltrue

Definição do Serviço

Nome: WSGetXML

Objetivo: Requisitar ao TOTVS Automação Fiscal o retorno do XML de determinado registro ou lote de registros.

Descrição: O serviço permite que uma aplicação requisite ao TAF que retorne um ou mais dados dentro de uma estrutura XML, a mesma que foi (ou que será) enviada ao Governo. Caso o evento ainda não tenha sido transmitido ao Governo, será retornado o XML gerado pelo próprio TAF. Caso o evento já tenha sido transmitido e autorizado pelo Governo, será retornado o XML final (inclusive com a assinatura do TSS).

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
titleImportante

Na 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]
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 o XML que o TAF enviou, ou enviará, ao Governo para determinado registro. Caso o evento ainda não tenha sido transmitido ao Governo, será retornado o XML gerado pelo próprio TAF. Caso o evento já tenha sido transmitido e autorizado pelo Governo, será retornado o XML final (inclusive com a assinatura do TSS).

 

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

http://172.16.31.214:8085/rest/wstafst2?ticketCode=F95975312365478978936365524145236352&RegistryKey=KEYQWE7878RE4854545454998598571&startRecNo=0


ParâmetroDescriçãoObrigatório
ticketCodeTAFTICKETOC
registryKeyTAFKEYOC
startRecNoRecNo inicial para consultaO
searchModeFiltro para buscaN

 

  • ticketCode – Código do TAFTICKET, Obrigatório caso registryKey não seja informado.
  • registryKey – Código do TAFKEY, Obrigatório caso ticketCode não seja informado.
  • startRecNo - Numero 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.
  • searchMode – Modo de pesquisa, quando não informado o response retorna todos os TAFKEYs relacionados a busca, quando igual a 1 retorna a última ocorrência do TAFKEY, quando igual a 2 retorna a última ocorrência válida do TAFKEY. Este parâmetro é útil quando o mesmo TAFKEY é enviado em vários TAFTICKET diferentes.
Estrutura da Resposta do método GET (Response):

 

Items20:String25registryTypeItems20:String10

Atributo

Pai

Nivel

Ocorrência

Formato

type

-

1

1

-

code

-

1

1:N

String(36-100)

Items

-

1

1

-

registryKey

Items

2

1

String(100)

statusCodeticketCode

Items

2

0:1

String(1)

statusDescription
lastRecNo-11Int(9999)
maxRecNo-11Int(9999)

registryTypeDescription

Items

2

0:1

String(36)

validateErrorsItems20:1-

validateErrorCode

validateErrors

3

0:1

String(6)

validateErrorDetail

validateErrors

3

0:1

String(220)

streamingErrorsItems20:1-

streamingErrorCode

streamingErrors

3

0:1

String(6)

streamingErrorDetail

streamingErrors

3

0:1

String(220)

registryProtocol

Items

2

0:1

String(60)

lastRecNo-11Int(9999)
maxRecNo-11Int(9999)

 

 

  • type – Determina o agrupamento do retorno que pode ser por status (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.
  • 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
  • type – Determina o agrupamento do retorno que pode ser por status (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.
  • 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.
  • statusDescription – Descrição do status no TAF, atributo exibido somente quando o agrupamento do request for por registryType.
  • 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.
  • 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:

Request:

http://172.16.31.214:8085/rest/wsqueryelements2?status=4&startRecNo=0

 

 

Bloco de código
languagejs
themeEclipse
titleResponse:
{
  "type": "status",
  "code": "4",
  "items": [
    {
      "registryKey": "KEY000001S-220020170101",
      "registryType": "S-2200",
      "registryTypeDescription": "Admissão do Funcionário",
      "registryProtocol": "20170520081000S2200"
    },
    {
      "registryKey": "KEY000001S-210020170101",
      "registryType": "S-2100",
      "registryTypeDescription": "Cadastro Inicial do Funcionário",
      "registryProtocol": "20170521151402S2100"
    }
 ],
  "lastRecNo": 2,
  "maxRecNo": 2
}

 

  • Consulta por registryType:

Request:

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

 

Bloco de código
languagejs
themeEclipse
titleResponse após a execução do processamento:
{
  "type": "registryType",
  "code": "S-2200",
  "items": [
    {
      "registryKey": "KEY000001S-220020170101",
      "statusCode": "4",
      "statusDescription": "Registro Transmitido com sucesso",
      "registryProtocol": "20170520081000S2200"
    },
    {
      "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
languagejs
themeEclipse
titleResponse:
{
  "type": "status",
  "code": "4",
  "items": [
    {
      "registryKey": "KEY000001S-220020170101",
      "registryType": "S-2200",
      "registryTypeDescription": "Admissão do Funcionário",
      "registryProtocol": "20170520081000S2200"
    }
 ],
  "lastRecNo": 2,
  "maxRecNo": 2
}
Aviso
titleAtençã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:

Bloco de código
themeEclipse
titleExemplo de Paginação
{
  "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

 

Bloco de código
themeEclipse
titleResponse
{
  "type": "status",
  "code": "4",
  "items": [
    {
      "registryKey": "KEY895424S-220020170723",
      "registryType": "S-2200",
      "registryTypeDescription": "Admissão do Funcionário",
      "registryProtocol": "20170723081032S2200"
    },
*
*
*
{several items}
*
*
*
    {
      "registryKey": "KEY072355S-210020170312",
      "registryType": "S-2100",
      "registryTypeDescription": "Cadastro Inicial do Funcionário",
      "registryProtocol": "20170312151402S2100"
    }
  ],
  "lastRecNo": 322,
  "maxRecNo": 322
}

 

 

Exemplo de Consumo do Serviço

 

Bloco de código
languagedelphi
themeEclipse
titleClient 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
	
	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 
Bloco de código
languagejs
themeEclipse
titleExemplo de Resposta do método GET com RESTFAULT
  "errorCode": 101,
  "errorMessage": "obrigatorio o envio do parametro status ou 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.