Á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 consulsta geral de status de 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: WSQueryElements

Objetivo: Consultar uma lista de elementos presentes na base de dados do TAF através de um status ou 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 status pré-definido pela aplicação (de acordo com os status existentes no TAF) .ou do 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 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 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/wsqueryelements?status=4&registryType=S-1010&startRecNo=0

 

ParâmetroDescriçãoObrigatório
statusStatus do registro no TAFOC
registryTypeTipo do registro/layout. Exemplo: T007, S-1010...OC
startRecNoRecNo inicial para consultaO

 

  • status - Status do registro na base de dados do TAF. Os códigos válidos podem ser encontrados no Manual de Integração. Obrigatório caso registryType não seja informado.
  • registryType - Tipo do registro (código do campo TAFTPREG). Obrigatório caso status não seja informado.
  • startRecNoNúmero 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)

statusCode

Items

2

0:1

String(1)

statusDescription

Items

2

0:1

String(25)

registryType

Items

2

0:1

String(10)

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.
  • 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 – Campo não informado na estrutura do arquivo.
  • 801 – Campo obrigatório não enviado.
  • 802 – Campo com valor inválido.
  • 803 – TAFFIL não encontrado no complemento de empresas.
  • 804 – Layout Inválido.
  • 805 – Código de Prioridade inválido!
  • 806 – Campo com erro na codificação ou criptografia
  • 807 – Código de Fila inválido!
  • 808 – Estrutura da tabela TAFST2 está desatualizada

 

Bloco de código
languagejs
titleExemplo de mensagem POST:Exemplo de Resposta do método POST com erro de validação:
{ "ticketCode": "WIO9753123654789789363655241452363", "registryKey": [ { "key": "KEYIO7878874854545454998598525", "success": false, "error": [ { "coderr": 801, "description": "Campo TAFFIL (sourceBranch) e Obrigatorio." }, { "coderr": 803, "description": "O valor do campo TAFFIL (sourceBranch) nao esta cadastro no complemento de empresas." } { "coderr": 805, "description": "Codigo de Prioridade invalido! Codigo enviado: '8'. Codigos validos: 0 - Urgente, 1 - Prioridade Critica, 2 - Prioridade Alta, 3 - Prioridade Media, 4 - Prioridade Baixa, 5 - Nao Prioritario" } ] }, { "key": "KEYYZE7878RE4854545454998598576", "success": true }, { "key": "KEYQWE7878RE4854545454998598571", "success": true }, { "key": "KEYQIU7878RE4854545454998598544", "success": true } ], "keyAmount": 4 }
  • Status (status) solicitado no request é inválido.
  • 801 – Tipo de registro (registryType) solicitado no request é inválido.