Á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, para consulta de elementos/registros do TOTVS Automação Fiscal, de acordo com o status ou tipo do registro.

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

Nota
titleImportante

Na seção HTTPURI, a chave PrepareIn deve ser 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

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

 


ParâmetroDescriçãoObrigatório
statusStatus do registro no TAF
 

registryTypeTipo do registro/layout. Exemplo: T007, S-1010...O
startRecNoRecNo inicial para consultaO

 

 
sourceBranchCódigo Identificador da filial


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

ParâmetroDescriçãoObrigatórioCGCCGC da Empresa/Filial cadastrada no SIGAMAT.EMPOINSCESTInscrição estadual da Empresa/Filial cadastrada no SIGAMAT.EMPOINSCMUNInscrição Municipal da Empresa/Filial cadastrada no SIGAMAT

.

EMP  


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

 


AtributoPaiNívelOcorrênciaFormato

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)

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)
 


  • 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
languagejs
themeEclipse
titleResponse:
  {
   "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
languagejs
themeEclipse
titleResponse 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
themeEclipse
titleExemplo 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
themeEclipse
titleResponse
{
   "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
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
	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
languagejs
themeEclipse
titleExemplo 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.