Histórico da Página
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
|
---|
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 | ||
---|---|---|
| ||
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 |
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®istryType=S-1010&startRecNo=0
Parâmetro | Descrição | Obrigatório |
---|---|---|
status | Status do registro no TAF | OC |
registryType | Tipo do registro/layout. Exemplo: T007, S-1010... | OC |
startRecNo | RecNo inicial para consulta | O |
- 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.
- startRecNo - Nú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) |
validateErrors | Items | 2 | 0:1 | - |
validateErrorCode | validateErrors | 3 | 0:1 | String(6) |
validateErrorDetail | validateErrors | 3 | 0:1 | String(220) |
streamingErrors | Items | 2 | 0:1 | - |
streamingErrorCode | streamingErrors | 3 | 0:1 | String(6) |
streamingErrorDetail | streamingErrors | 3 | 0:1 | String(220) |
registryProtocol | Items | 2 | 0:1 | String(60) |
lastRecNo | - | 1 | 1 | Int(9999) |
maxRecNo | - | 1 | 1 | Int(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 | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "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 | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "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®istryType=S-2200&startRecNo=0
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "type": "status", "code": "4", "items": [ { "registryKey": "KEY000001S-220020170101", "registryType": "S-2200", "registryTypeDescription": "Admissão do Funcionário", "registryProtocol": "20170520081000S2200" } ], "lastRecNo": 2, "maxRecNo": 2 } |
Aviso | ||
---|---|---|
| ||
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 | ||||
---|---|---|---|---|
| ||||
{ "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®istryType=S-2200&startRecNo=151
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "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 | ||||||
---|---|---|---|---|---|---|
| ||||||
#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 | ||||||
---|---|---|---|---|---|---|
| ||||||
"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
language | js |
---|---|
title | Exemplo de mensagem POST:Exemplo de Resposta do método POST com erro de validação: |
- Status (status) solicitado no request é inválido.
- 801 – Tipo de registro (registryType) solicitado no request é inválido.