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 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
|
---|
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 | ||
---|---|---|
| ||
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 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 |
- 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) |
status | Items | 2 | 1 | String(2) |
xml | Items | 2 | 0:1 | Memo - Base64 |
error | Items | 2 | 0:1 | String(220) |
messageApp | Items | 2 | 0:1 | String(3) |
lastRecNo | - | 1 | 1 | Int(9999) |
maxRecNo | - | 1 | 1 | Int(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 | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "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:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "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:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "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 | ||
---|---|---|
| ||
Quando a consulta for por status + registryType o retorno será agrupado por ticketCode. |
- Consulta paginada:
Request:
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 | ||||
---|---|---|---|---|
| ||||
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": "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:
Bloco de código | ||||
---|---|---|---|---|
| ||||
{
"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 | ||||
| ||||
|
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("/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 | ||||||
---|---|---|---|---|---|---|
| ||||||
"errorCode": 101, "errorMessage": "obrigatorioÉ obrigatório o envio do parametro status ou registryTypeparâmetro startRecNo" } |
Códigos De Erros De Validação
:
N/A
801 – Tipo de registro (registryType) solicitado no request é inválido.