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
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
A Configuração do serviço REST está documentada no link Configuração REST SERVER - Protheus.
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 |
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:
| Parâmetro | Descrição | Obrigatório |
|---|---|---|
| ticketCode | TAFTICKET | OC |
| registryKey | TAFKEY | OC |
| startRecNo | RecNo inicial para consulta | O |
| searchMode | Filtro para busca | N |
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 |
| lastRecNo | - | 1 | 1 | Int(9999) |
| maxRecNo | - | 1 | 1 | Int(9999) |
Exemplos de requisição utilizando o método GET:
Request:
http://172.16.31.214:8085/rest/wsqueryelements2?status=4&startRecNo=0
{
"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
} |
Request:
http://172.16.31.214:8085/rest/wsqueryelements2?registryType=S-2200&startRecNo=0
{
"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
} |
Request:
http://172.16.31.214:8085/rest/wsqueryelements2?status=4®istryType=S-2200&startRecNo=0
{
"type": "status",
"code": "4",
"items": [
{
"registryKey": "KEY000001S-220020170101",
"registryType": "S-2200",
"registryTypeDescription": "Admissão do Funcionário",
"registryProtocol": "20170520081000S2200"
}
],
"lastRecNo": 2,
"maxRecNo": 2
} |
Quando a consulta for por status + registryType o retorno será agrupado por registryType. |
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:
{
"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
{
"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
} |
#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 |
"errorCode": 101, "errorMessage": "obrigatorio o envio do parametro status ou registryType" } |