Á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: 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.

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

statusItems21String(2)
xmlItems20:1Memo - Base64
errorItems20:1String(220)
messageAppItems20:1String(3)
lastRecNo-11Int(9999)
maxRecNo-11Int(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

 

 

Bloco de código
languagejs
themeEclipse
titleResponse:
 {
  "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

 

Bloco de código
languagejs
themeEclipse
titleResponse 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

 
Bloco de código
languagejs
themeEclipse
titleResponse:
{
  "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
}
Aviso
titleAtençã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:

Bloco de código
themeEclipse
titleExemplo de Paginação
 

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

 

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

 

Bloco de código
themeEclipse
titleResponse
  {
  "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
}
Bloco de código
themeEclipse
titleResponse
 

 

 

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("/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 :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."

 

Bloco de código
languagejs
themeEclipse
titleExemplo de Resposta do método GET com RESTFAULT
  "errorCode": 101,
  "errorMessage": "obrigatorioÉ obrigatório o envio do parametro status ou registryTypeparâmetro startRecNo"
}

 

Códigos De Erros De Validação

:

 

  • 800 – Status (status) solicitado no request é inválido.
  • N/A

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