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

Definição do Serviço

Nome: WSTAFGetXML

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.

Importante

Na Seção TAF_CFGJOB a chave PrepareIn deve ser preenchida com o código da empresa/filial principal ou com "All" para todas os grupos de empresas:

PrepareIn para grupo de empresa e filial específica

[TAF_CFGJOB]

MAIN=TAF_CFGJOB

Instances=5,30,5,1

PrepareIn=99,01

Environment=p12116

RefreshRate=120

PrepareIn para grupo de empresa e empresa específica

[TAF_CFGJOB]

MAIN=TAF_CFGJOB

Instances=5,30,5,1

PrepareIn=T1,D MG 01

Environment=p12116

RefreshRate=120

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âmetro	Descrição	Obrigatório
ticketCode	TAFTICKET	OC
registryKey	TAFKEY	OC
startRecNo	RecNo inicial para consulta	O
searchMode	Filtro para busca	N
sourceBranch	Código Identificador da filial	N

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.
sourceBranch - Código Identificador da filial do ERP emissor.
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 da Resposta do método GET (Response):

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)
ticketCode	Items	2	0:1	String(1)
status	Items	2	1	String(2)
xml	Items	2	0:1	Memo - Base64
error	Items	2	0:1	String(220)
messageApp	Items	2	0:1	String(3)
lastRecNo	-	1	1	Int(9999)
maxRecNo	-	1	1	Int(9999)

type – Determina o agrupamento do retorno que pode ser por ticketCode (TAFTICKET) ou registryKey (TAFKEY), o agrupamento depende dos parâmetros enviados no request, quando o registryKey é informado e o ticketCode omitido, o retorno será por registryKey caso contrário por ticketCode.
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.
ticketCode – código do ticket ( TAFTICKET ) relacionado ao registro retornado. Esse atributo somente é exibido quando type for igual a registryKey.
status – Status do registro na base de dados do TAF. Caso o registro não tenha sido integrado com sucesso ao TAF, neste campo será retornado -1.
xml – XML do registro que foi ou será enviado ao Governo pelo TAF. A mensagem será retornada com criptografia BASE64.
error – Retorna erro ocorrido durante o processamento da mensagem XML. Pode retornar uma mensagem de registro e/ou lote não encontrado, ou alguma ocorrência durante a geração da mensagem
messageApp – Informa a aplicação que gerou o XML retornado. Caso o registro esteja com status de autorizado ('4') na base de dados do TAF, será retornado o xml gerado pelo TSS, para os demais status será retornado o XML gerado pelo TAF. Retornos possíveis: 'TAF' ou 'TSS'.
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 registryKey:

Request:
http://172.16.31.214:8085/rest/wstafgetxml?registryKey=99_01_S-1050_20160715_1601130001 (1).XML&startRecno=0

Response:

 {
  "type": "registryKey",
  "code": "99_01_S-1050_20160715_1601130001 (1).XML",
  "items": [
    {
      "ticketCode": "97250dd3-e1d9-1c59-622d-f20447e06879",
      "status": "0",
      "xml": "PGVTb2NpYWwgeG1sbnM9J2h0dHA6Ly93d3cuZXNvY2lhbC5nb3YuYnIvc2NoZW1hL2V2dC9ldnRUYWJIb3JUdXIvdjAyXzAyXzAxJz48ZXZ0VGFiSG9yVHVyIElkPSdJRDE1MzExMzc5MTAwMDAwMDIwMTcwNTMwMTYyNTUyMjgzOTgnPjxpZGVFdmVudG8+PHRwQW1iPjc8L3RwQW1iPjxwcm9jRW1pPjE8L3Byb2NFbWk+PHZlclByb2M+MS4wPC92ZXJQcm9jPjwvaWRlRXZlbnRvPjxpZGVFbXByZWdhZG9yPjx0cEluc2M+MTwvdHBJbnNjPjxuckluc2M+NTMxMTM3OTE8L25ySW5zYz48L2lkZUVtcHJlZ2Fkb3I+PGluZm9Ib3JDb250cmF0dWFsPjxpbmNsdXNhbz48aWRlSG9yQ29udHJhdHVhbD48Y29kSG9yQ29udHJhdD4wMDQwMTAxNjwvY29kSG9yQ29udHJhdD48aW5pVmFsaWQ+MjAxNi0wMzwvaW5pVmFsaWQ+PC9pZGVIb3JDb250cmF0dWFsPjxkYWRvc0hvckNvbnRyYXR1YWw+PGhyRW50cj4wOTAwPC9ockVudHI+PGhyU2FpZGE+MTgzMDwvaHJTYWlkYT48ZHVySm9ybmFkYT41MTA8L2R1ckpvcm5hZGE+PHBlckhvckZsZXhpdmVsPlM8L3BlckhvckZsZXhpdmVsPjwvZGFkb3NIb3JDb250cmF0dWFsPjwvaW5jbHVzYW8+PC9pbmZvSG9yQ29udHJhdHVhbD48L2V2dFRhYkhvclR1cj48L2VTb2NpYWw+",
      "messageApp": "TAF"
    }
  ],
  "lastRecNo": 204,
  "maxRecNo": 204
}

Consulta por ticketCode:

Request:
http://172.16.31.214:8085/rest/wstafgetxml?ticketCode=97250dd3-e1d9-1c59-622d-f20447e06879&startRecno=0

Response após a execução do processamento:

 {
  "type": "ticketCode",
  "code": "97250dd3-e1d9-1c59-622d-f20447e06879",
  "items": [
    {
      "registryKey": "99_01_S-1010_20160715_1201450001 (1).XML",
      "status": "1",
      "xml": "PGVTb2NpYWwgeG1sbnM9J2h0dHA6Ly93d3cuZXNvY2lhbC5nb3YuYnIvc2NoZW1hL2V2dC9ldnRUYWJSdWJyaWNhL3YwMl8wMl8wMSc+PGV2dFRhYlJ1YnJpY2EgSWQ9J0lEMTUzMTEzNzkxMDAwMDAwMjAxNzA1MzAxNjI3NDcyODM5OCc+PGlkZUV2ZW50bz48dHBBbWI+NzwvdHBBbWI+PHByb2NFbWk+MTwvcHJvY0VtaT48dmVyUHJvYz4xLjA8L3ZlclByb2M+PC9pZGVFdmVudG8+PGlkZUVtcHJlZ2Fkb3I+PHRwSW5zYz4xPC90cEluc2M+PG5ySW5zYz41MzExMzc5MTwvbnJJbnNjPjwvaWRlRW1wcmVnYWRvcj48aW5mb1J1YnJpY2E+PGluY2x1c2FvPjxpZGVSdWJyaWNhPjxjb2RSdWJyPjIwMzwvY29kUnVicj48aW5pVmFsaWQ+MjAxNi0wMzwvaW5pVmFsaWQ+PC9pZGVSdWJyaWNhPjxkYWRvc1J1YnJpY2E+PGRzY1J1YnI+RElGIENPTVBMIFBSRVZJRDwvZHNjUnVicj48bmF0UnVicj48L25hdFJ1YnI+PHRwUnVicj4xPC90cFJ1YnI+PGNvZEluY0NQPjAwPC9jb2RJbmNDUD48Y29kSW5jSVJSRj4xMTwvY29kSW5jSVJSRj48Y29kSW5jRkdUUz4wMDwvY29kSW5jRkdUUz48Y29kSW5jU0lORD4wMDwvY29kSW5jU0lORD48cmVwRFNSPk48L3JlcERTUj48cmVwMTM+TjwvcmVwMTM+PHJlcEZlcmlhcz5OPC9yZXBGZXJpYXM+PHJlcEF2aXNvPk48L3JlcEF2aXNvPjwvZGFkb3NSdWJyaWNhPjwvaW5jbHVzYW8+PC9pbmZvUnVicmljYT48L2V2dFRhYlJ1YnJpY2E+PC9lU29jaWFsPg==",
      "messageApp": "TAF"
    },
    {
      "registryKey": "99_01_S-1010_20160715_1201450001 (2).XML",
      "status": "-1",
      "error": "Registro nao integrado ao TOTVS Automacao Fiscal."
    }
  ],
  "lastRecNo": 251,
  "maxRecNo": 251
}

Consulta pelo registryKey+ ticketCode:

Request:
http://172.16.31.214:8085/rest/wstafgetxml?ticketCode=97250dd3-e1d9-1c59-622d-f20447e06879&registryKey=99_01_S-1010_20160715_1201450001 (1).XML&startRecno=0

Response:

{
  "type": "ticketCode",
  "code": "97250dd3-e1d9-1c59-622d-f20447e06879",
  "items": [
    {
      "registryKey": "99_01_S-1010_20160715_1201450001 (1).XML",
      "status": "1",
      "xml": "PGVTb2NpYWwgeG1sbnM9J2h0dHA6Ly93d3cuZXNvY2lhbC5nb3YuYnIvc2NoZW1hL2V2dC9ldnRUYWJSdWJyaWNhL3YwMl8wMl8wMSc+PGV2dFRhYlJ1YnJpY2EgSWQ9J0lEMTUzMTEzNzkxMDAwMDAwMjAxNzA1MzAxNjMwMTMyODM5OCc+PGlkZUV2ZW50bz48dHBBbWI+NzwvdHBBbWI+PHByb2NFbWk+MTwvcHJvY0VtaT48dmVyUHJvYz4xLjA8L3ZlclByb2M+PC9pZGVFdmVudG8+PGlkZUVtcHJlZ2Fkb3I+PHRwSW5zYz4xPC90cEluc2M+PG5ySW5zYz41MzExMzc5MTwvbnJJbnNjPjwvaWRlRW1wcmVnYWRvcj48aW5mb1J1YnJpY2E+PGluY2x1c2FvPjxpZGVSdWJyaWNhPjxjb2RSdWJyPjIwMzwvY29kUnVicj48aW5pVmFsaWQ+MjAxNi0wMzwvaW5pVmFsaWQ+PC9pZGVSdWJyaWNhPjxkYWRvc1J1YnJpY2E+PGRzY1J1YnI+RElGIENPTVBMIFBSRVZJRDwvZHNjUnVicj48bmF0UnVicj48L25hdFJ1YnI+PHRwUnVicj4xPC90cFJ1YnI+PGNvZEluY0NQPjAwPC9jb2RJbmNDUD48Y29kSW5jSVJSRj4xMTwvY29kSW5jSVJSRj48Y29kSW5jRkdUUz4wMDwvY29kSW5jRkdUUz48Y29kSW5jU0lORD4wMDwvY29kSW5jU0lORD48cmVwRFNSPk48L3JlcERTUj48cmVwMTM+TjwvcmVwMTM+PHJlcEZlcmlhcz5OPC9yZXBGZXJpYXM+PHJlcEF2aXNvPk48L3JlcEF2aXNvPjwvZGFkb3NSdWJyaWNhPjwvaW5jbHVzYW8+PC9pbmZvUnVicmljYT48L2V2dFRhYlJ1YnJpY2E+PC9lU29jaWFsPg==",
      "messageApp": "TAF"
    }
  ],
  "lastRecNo": 14,
  "maxRecNo": 14
}

Atenção!

Quando a consulta for por status + registryType o retorno será agrupado por ticketCode.

Consulta paginada:

Request:
http://172.16.31.214:8085/rest/wstafgetxml?ticketCode=97250dd3-e1d9-1c59-622d-f20447e06879&startRecno=0

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:

Exemplo de Paginação

  {
  "type": "ticketCode",
  "code": "97250dd3-e1d9-1c59-622d-f20447e06879",
  "items": [
    {
      "registryKey": "99_01_S-1010_20160715_1201450001 (1).XML",
      "status": "1",
      "xml": "PGVTb2NpYWwgeG1sbnM9J2h0dHA6Ly93d3cuZXNvY2lhbC5nb3YuYnIvc2NoZW1hL2V2dC9ldnRUYWJSdWJyaWNhL3YwMl8wMl8wMSc+PGV2dFRhYlJ1YnJpY2EgSWQ9J0lEMTUzMTEzNzkxMDAwMDAwMjAxNzA1MzAxNjI3NDcyODM5OCc+PGlkZUV2ZW50bz48dHBBbWI+NzwvdHBBbWI+PHByb2NFbWk+MTwvcHJvY0VtaT48dmVyUHJvYz4xLjA8L3ZlclByb2M+PC9pZGVFdmVudG8+PGlkZUVtcHJlZ2Fkb3I+PHRwSW5zYz4xPC90cEluc2M+PG5ySW5zYz41MzExMzc5MTwvbnJJbnNjPjwvaWRlRW1wcmVnYWRvcj48aW5mb1J1YnJpY2E+PGluY2x1c2FvPjxpZGVSdWJyaWNhPjxjb2RSdWJyPjIwMzwvY29kUnVicj48aW5pVmFsaWQ+MjAxNi0wMzwvaW5pVmFsaWQ+PC9pZGVSdWJyaWNhPjxkYWRvc1J1YnJpY2E+PGRzY1J1YnI+RElGIENPTVBMIFBSRVZJRDwvZHNjUnVicj48bmF0UnVicj48L25hdFJ1YnI+PHRwUnVicj4xPC90cFJ1YnI+PGNvZEluY0NQPjAwPC9jb2RJbmNDUD48Y29kSW5jSVJSRj4xMTwvY29kSW5jSVJSRj48Y29kSW5jRkdUUz4wMDwvY29kSW5jRkdUUz48Y29kSW5jU0lORD4wMDwvY29kSW5jU0lORD48cmVwRFNSPk48L3JlcERTUj48cmVwMTM+TjwvcmVwMTM+PHJlcEZlcmlhcz5OPC9yZXBGZXJpYXM+PHJlcEF2aXNvPk48L3JlcEF2aXNvPjwvZGFkb3NSdWJyaWNhPjwvaW5jbHVzYW8+PC9pbmZvUnVicmljYT48L2V2dFRhYlJ1YnJpY2E+PC9lU29jaWFsPg==",
      "messageApp": "TAF"
    },
*
*
*
{several items}
*
*
*
    {
      "registryKey": "99_01_S-1010_20160715_1201450001 (150).XML",
      "status": "-1",
      "error": "Registro nao integrado ao TOTVS Automacao Fiscal."
    }
  ],
  "lastRecNo": 150,
  "maxRecNo": 251
}

No exemplo acima a consulta retornou até o registro 150, sendo que o registro com maior RecNo pertencente a consulta é o 251, isso não quer dizer que foram retornados 150 registros e que faltam 101, 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/wstafgetxml?ticketCode=97250dd3-e1d9-1c59-622d-f20447e06879&startRecno=151

Response

  {
  "type": "ticketCode",
  "code": "97250dd3-e1d9-1c59-622d-f20447e06879",
  "items": [
    {
      "registryKey": "99_01_S-1010_20160715_1201450001 (151).XML",
      "status": "1",
      "xml": "PGVTb2NpYWwgeG1sbnM9J2h0dHA6Ly93d3cuZXNvY2lhbC5nb3YuYnIvc2NoZW1hL2V2dC9ldnRUYWJSdWJyaWNhL3YwMl8wMl8wMSc+PGV2dFRhYlJ1YnJpY2EgSWQ9J0lEMTUzMTEzNzkxMDAwMDAwMjAxNzA1MzAxNjI3NDcyODM5OCc+PGlkZUV2ZW50bz48dHBBbWI+NzwvdHBBbWI+PHByb2NFbWk+MTwvcHJvY0VtaT48dmVyUHJvYz4xLjA8L3ZlclByb2M+PC9pZGVFdmVudG8+PGlkZUVtcHJlZ2Fkb3I+PHRwSW5zYz4xPC90cEluc2M+PG5ySW5zYz41MzExMzc5MTwvbnJJbnNjPjwvaWRlRW1wcmVnYWRvcj48aW5mb1J1YnJpY2E+PGluY2x1c2FvPjxpZGVSdWJyaWNhPjxjb2RSdWJyPjIwMzwvY29kUnVicj48aW5pVmFsaWQ+MjAxNi0wMzwvaW5pVmFsaWQ+PC9pZGVSdWJyaWNhPjxkYWRvc1J1YnJpY2E+PGRzY1J1YnI+RElGIENPTVBMIFBSRVZJRDwvZHNjUnVicj48bmF0UnVicj48L25hdFJ1YnI+PHRwUnVicj4xPC90cFJ1YnI+PGNvZEluY0NQPjAwPC9jb2RJbmNDUD48Y29kSW5jSVJSRj4xMTwvY29kSW5jSVJSRj48Y29kSW5jRkdUUz4wMDwvY29kSW5jRkdUUz48Y29kSW5jU0lORD4wMDwvY29kSW5jU0lORD48cmVwRFNSPk48L3JlcERTUj48cmVwMTM+TjwvcmVwMTM+PHJlcEZlcmlhcz5OPC9yZXBGZXJpYXM+PHJlcEF2aXNvPk48L3JlcEF2aXNvPjwvZGFkb3NSdWJyaWNhPjwvaW5jbHVzYW8+PC9pbmZvUnVicmljYT48L2V2dFRhYlJ1YnJpY2E+PC9lU29jaWFsPg==",
      "messageApp": "TAF"
    },
*
*
*
{several items}
*
*
*
    {
      "registryKey": "99_01_S-1010_20160715_1201450001 (251).XML",
      "status": "-1",
      "error": "Registro nao integrado ao TOTVS Automacao Fiscal."
    }
  ],
  "lastRecNo": 251,
  "maxRecNo": 251
}

Exemplo de Consumo do Serviço

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
	
	If cMetodo == "GET"
	
		While lContinue
			nPag++
			oRestClient:setPath("/rest/wstafgetxml?registryKey=99_01_S-1010_20160715_1201450001 (1)&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

Códigos De Erros RESTFAULT

101 - "É obrigatório o envio do parâmetro startRecNo" ou "É obrigatório o envio do parâmetro ticketCode ou registryKey"
102 - "Erro na Criacao/Abertura da tabela TAFST2." ou "Erro na Criacao/Abertura da tabela TAFXERP."

Exemplo de Resposta do método GET com RESTFAULT

  "errorCode": 101,
  "errorMessage": "É obrigatório o envio do parâmetro startRecNo"
}

Códigos De Erros De Validação

N/A

Árvore de páginas

Web Service REST - Retorno de XML