RESTWeb Service REST
Produto: | TOTVS Automação Fiscal |
Versões: | 12.1.23+ |
Este documento tem o objetivo de fornecer informações para utilização do Web Service REST de integração com o TOTVS Automação Fiscal.
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: WSEsocial
Objetivo: Realizar o envio de informações relacionadas ao eSocial.
Descrição: Este serviço é responsável pela consulta e envio de informações ao TSS.
Métodos: POST e GET.
Configurações do Serviço
A Configuração do serviço REST está documentada no link Configuração REST SERVER - Protheus.
Estas parametrizações estão localizadas fisicamente no arquivo appserver.ini da pasta de instalação "[...]\BIN\APP"
Importante
Na seção HTTPURI, a chave PrepareIn deve ser comentada.
Segue exemplo de configuração do WS REST para utilização no modulo TAF:
[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
[OnStart]
JOBS=HTTPJOB
RefreshRate=120
Autenticação
A autenticação utilizada no serviço REST é a Basic, a mesma é obrigatória no header das requisições caso o ambiente esteja com a chave Security da seção HTTPREST configurada com o valor "1".
Exemplo:
Autenticação Basic
Authentication: Basic YWRtaW46IA==
Obs: A senha deve utilizar a criptografia base64.
O Serviço TSS também possui autenticação (JWT) a partir da versão 12.1.33, para a configuração é necessário seguir os passos deste documento: https://tdn.totvs.com/x/1RhcIw
Quando esta autenticação está em uso é necessário informar a chave TokenAuthTSS no header das requisições com o Token retornado pelo Serviço WSTSSTOKEN: https://tdn.totvs.com/x/YaYtJg
Exemplo:
Autenticação JWT (TSS)
TokenAuthTSS: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRpZCI6IjE2ODA1NmNjLTczNTYtNDAwMC04NUI0LWZlNjhiMjZhYjJjZiIsICJjbGllbnRfaWQiOiJiZDFlMjhkNGRmYmIwZDY2YjY0MGVhOTQyOThiMmU3N2MyNDMzMzRjIiwiaXNzIjoiVE9UVlNfVFNTXzEyLjEuMDMzIiwiaWF0IjoxNjMyMTUzNjkzLCJleHAiOjE2MzIxNTU0OTR9.ZTIwMjk4NTJkZTgwYWU3N2VlMTE5OTU1ZGJjYWFlODZlYTJhZTc1OGUxYjI2YWE5MWIwMWYzOTVmMDU2YTNiNTkzZjdiM2NhOGNhZGU3ZDI3ZGNhNmI1N2QyODc1NjM3Nzg5MzNhYTAzYzNlNzQ4N2QzMThkMWU0YmE3NmEyMjU
Definição dos métodos
SEND (Post)
Descrição do Método: O método POST segue o conceito do próprio método em qualquer outro tipo de serviço REST, devendo seu conteúdo ser enviado no corpo da mensagem (body) no formato json.
O objetivo do método é enviar informações relacionadas ao eSocial para o TSS.
Atenção!
ticketCode será mantido apenas para compatibilidade a partir de 18/10/2024
Estrutura da mensagem enviada no POST (Request):
Atributo | Pai | Nivel | Ocorrência | Formato |
|---|---|---|---|---|
ticketCode | - | 1 | 1 (mantido por compatibilidade) | String(36) |
sourceBranch | - | 1 | 1 | String(6) |
tpAmb | - | 1 | 1 | String(2) |
urlTSS | - | 1 | 1 | - |
lote | - | 1 | 1:50 | - |
registryType | 1 | 2 | 1 | String(6) |
registryKey | 1 | 2 | 1 | String(250) |
branchName | 1 | 2 | 1 | String(250) |
integrationMessage | 1 | 2 | 1 | Memo |
schemaVersion | - | 1 | 1 | String(8) |
ticketCode – atributo raiz (string(36))
sourceBranch - Código Identificador da entidade TSS ( retornado na configuração do certificado)
tpAmb – Tipo do Ambiente
urlTSS – URL serviço do TSS
lote - estrutura dos itens.
- registryType - Tipo do Registro
- registryKey – Chave do Registro (string(64))
- integrationMessage - Arquivo/Evento a ser integrado, a mensagem deve ser enviada com criptografia BASE64. Obs: O XML pode ser enviado com a codificação UTF-8, neste caso é obrigatório o uso da declaração <?xml version="1.0" encoding="utf-8"?> no inicio do Xml
- schemaVersion – XX_XX_XX
Atenção!
Os atributos não obrigatórios têm que fazer parte da estrutura, somente o seu preenchimento é opcional.
Exemplo da URL para chamada do método "send":
Estrutura da mensagem de retorno do POST (Response):
Atributo | Pai | Nivel | Ocorrência | Formato |
|---|---|---|---|---|
ticketCode | - | 1 | 0:1 | String(36) |
registryKey | - | 1 | 0:N | String(250) |
key | 1 | 2 | 1 | String(100) |
success | 1 | 2 | 1 | boolean (true : false) |
error | 1 | 2 | 0:N | - |
coderr | 2 | 3 | 1 | Int(3) |
description | 2 | 3 | 1 | Memo Base64 |
keyAmount | - | 1 | 0:1 | Int(9999) |
ticketCode: Atributo raiz
registryKey
- key: Chave do registro
- success: Status do processamento do registro (True / False)
error
- coderr: Código do erro
- description: Descrição do erro
keyAmount: Quantidade de registros processados na requisição
Exemplo do request para o método Send (Post)
{
"ticketCode": "b9ce64c5-094b-4c95-9b29-c22b5cbf94f3",
"sourceBranch": "000001",
"tpAmb": "2",
"urlTSS": "http://localhost:8088",
"lote": [
{
"registryType": "S-1200",
"registryKey": "dcd5ea38-3008-4229-ae80-6688e75dcefe",
"integrationMessage": "PGVTb2NpYWwgeG1sbnM9J2h0dHA6Ly93d3cuZXNvY2lhbC5nb3YuYnIvc2NoZW1hL2V2dC9ldnRUYWJSdWJyaWNhL3YwMl8wNV8wMCc+PGV2dFRhYlJ1YnJpY2EgSWQ9J0lEMjIwMTkwNjIxMTkxMzIzNjM5ODknPjxpZGVFdmVudG8+PHRwQW1iPjI8L3RwQW1iPjxwcm9jRW1pPjE8L3Byb2NFbWk+PHZlclByb2M+MS4wPC92ZXJQcm9jPjwvaWRlRXZlbnRvPjxpZGVFbXByZWdhZG9yPjx0cEluc2M+MjwvdHBJbnNjPjxuckluc2M+OTk5OTk5OTk5OTk5OTk5PC9uckluc2M+PC9pZGVFbXByZWdhZG9yPjxpbmZvUnVicmljYT48aW5jbHVzYW8+PGlkZVJ1YnJpY2E+PGNvZFJ1YnI+MDAwMDAxPC9jb2RSdWJyPjxpZGVUYWJSdWJyPjAwMDAwMTwvaWRlVGFiUnVicj48aW5pVmFsaWQ+MjAxOS0wMTwvaW5pVmFsaWQ+PC9pZGVSdWJyaWNhPjxkYWRvc1J1YnJpY2E+PGRzY1J1YnI+VEVTVEU8L2RzY1J1YnI+PG5hdFJ1YnI+MTAwMDwvbmF0UnVicj48dHBSdWJyPjE8L3RwUnVicj48Y29kSW5jQ1A+MDA8L2NvZEluY0NQPjxjb2RJbmNJUlJGPjAwPC9jb2RJbmNJUlJGPjxjb2RJbmNGR1RTPjAwPC9jb2RJbmNGR1RTPjxjb2RJbmNTSU5EPjAwPC9jb2RJbmNTSU5EPjwvZGFkb3NSdWJyaWNhPjwvaW5jbHVzYW8+PC9pbmZvUnVicmljYT48L2V2dFRhYlJ1YnJpY2E+PC9lU29jaWFsPg==",
"schemaVersion": "02_05_00"
},
{
"registryType": "S-1010",
"registryKey": "57e09889-fb99-4a65-99f7-c2039041e151",
"integrationMessage": "PGVTb2NpYWwgeG1sbnM9J2h0dHA6Ly93d3cuZXNvY2lhbC5nb3YuYnIvc2NoZW1hL2V2dC9ldnRUYWJSdWJyaWNhL3YwMl8wNV8wMCc+PGV2dFRhYlJ1YnJpY2EgSWQ9J0lEMjIwMTkwNjIxMTkxMzIzNjM5ODknPjxpZGVFdmVudG8+PHRwQW1iPjI8L3RwQW1iPjxwcm9jRW1pPjE8L3Byb2NFbWk+PHZlclByb2M+MS4wPC92ZXJQcm9jPjwvaWRlRXZlbnRvPjxpZGVFbXByZWdhZG9yPjx0cEluc2M+MjwvdHBJbnNjPjxuckluc2M+OTk5OTk5OTk5OTk5OTk5PC9uckluc2M+PC9pZGVFbXByZWdhZG9yPjxpbmZvUnVicmljYT48aW5jbHVzYW8+PGlkZVJ1YnJpY2E+PGNvZFJ1YnI+MDAwMDAxPC9jb2RSdWJyPjxpZGVUYWJSdWJyPjAwMDAwMTwvaWRlVGFiUnVicj48aW5pVmFsaWQ+MjAxOS0wMTwvaW5pVmFsaWQ+PC9pZGVSdWJyaWNhPjxkYWRvc1J1YnJpY2E+PGRzY1J1YnI+VEVTVEU8L2RzY1J1YnI+PG5hdFJ1YnI+MTAwMDwvbmF0UnVicj48dHBSdWJyPjE8L3RwUnVicj48Y29kSW5jQ1A+MDA8L2NvZEluY0NQPjxjb2RJbmNJUlJGPjAwPC9jb2RJbmNJUlJGPjxjb2RJbmNGR1RTPjAwPC9jb2RJbmNGR1RTPjxjb2RJbmNTSU5EPjAwPC9jb2RJbmNTSU5EPjwvZGFkb3NSdWJyaWNhPjwvaW5jbHVzYW8+PC9pbmZvUnVicmljYT48L2V2dFRhYlJ1YnJpY2E+PC9lU29jaWFsPg==",
"schemaVersion": "02_05_00"
}
]
}
Exemplo da mensagem de retorno do método Send (Post)
{
"ticketCode": "b9ce64c5-094b-4c95-9b29-c22b5cbf94f3",
"registryKey": [
{
"key": "dcd5ea38-3008-4229-ae80-6688e75dcefe ",
"success": false,
"error": [
{
"coderr": "99",
"description": "RXJybyBkZSBzY2hlbWE6IEVsZW1lbnQgJ3todHRwOi8vd3d3LmVzb2NpYWwuZ292LmJyL3NjaGVtYS9ldnQvZXZ0VGFiUnVicmljYS92MDJfMDVfMDB9ZVNvY2lhbCc6IE5vIG1hdGNoaW5nIGdsb2JhbCBkZWNsYXJhdGlvbiBhdmFpbGFibGUgZm9yIHRoZSB2YWxpZGF0aW9uIHJvb3QuCg=="
}
]
},
{
"key": "57e09889-fb99-4a65-99f7-c2039041e151 ",
"success": false,
"error": [
{
"coderr": "99",
"description": "RXJybyBkZSBzY2hlbWE6IEVsZW1lbnQgJ3todHRwOi8vd3d3LmVzb2NpYWwuZ292LmJyL3NjaGVtYS9ldnQvZXZ0VGFiUnVicmljYS92MDJfMDVfMDB9bnJJbnNjJzogW2ZhY2V0ICdwYXR0ZXJuJ10gVGhlIHZhbHVlICc5OTk5OTk5OTk5OTk5OTknIGlzIG5vdCBhY2NlcHRlZCBieSB0aGUgcGF0dGVybiAnXGR7OCwxNH0nLgpFbGVtZW50ICd7aHR0cDovL3d3dy5lc29jaWFsLmdvdi5ici9zY2hlbWEvZXZ0L2V2dFRhYlJ1YnJpY2EvdjAyXzA1XzAwfW5ySW5zYyc6ICc5OTk5OTk5OTk5OTk5OTknIGlzIG5vdCBhIHZhbGlkIHZhbHVlIG9mIHRoZSBsb2NhbCBhdG9taWMgdHlwZS4K"
}
]
}
],
"keyAmount": 2
}
GET
Descrição do Método: O método GET segue o conceito do próprio método em qualquer outro tipo de serviço REST, devendo seu conteúdo ser enviado no corpo da mensagem (body) no formato json.
O objetivo do método é consultar informações relacionadas ao eSocial que foram previamente enviadas para o TSS.
Atenção!
ticketCode será mantido apenas para compatibilidade a partir de 18/10/2024
Estrutura da mensagem enviada no GET (Request):
Atributo | Pai | Nivel | Ocorrência | Formato |
|---|---|---|---|---|
sourceBranch | - | 1 | 1 | String(36) |
tpAmb | - | 1 | 1 | String(6) |
urlTSS | - | 1 | 1 | String(2) |
lote | - | 1 | 1:50 | - |
registryType | 1 | 2 | 1 | String(6) |
ticketCode | 1 | 2 | 1 (mantido por compatibilidade) | String(36) |
registryKey | 1 | 2 | 1 | String(100) |
returnRetResponse | 1 | 2 | 1 | boolean (true : false) |
sourceBranch - Código Identificador da entidade TSS ( retornado na configuração do certificado).
tpAmb – Tipo do Ambiente
urlTSS – URL serviço do TSS
Lote (1 – 50)
- registryType - Tipo do Registro.
- ticketCode – Código do TAFTICKET (Obrigatório)
- registryKey – Código do TAFKEY (Obrigatório)
- returnRetResponse – Define se deverá ser retornado o XML de retorno do RET
Atenção!
Os atributos não obrigatórios têm que fazer parte da estrutura, somente o seu preenchimento é opcional.
Exemplo da URL para chamada do método "get":
Estrutura da mensagem de retorno (Request):
Atributo | Pai | Nivel | Ocorrência | Formato |
|---|---|---|---|---|
Items | - | 1 | 1 | - |
success | 1 | 2 | 1 | boolean(true : false) |
proccessed | 1 | 2 | 1 | boolean(true : false) |
registryKey | 1 | 2 | 0:1 | String(100) |
registryType | 1 | 2 | 0:1 | String(6) |
ticketCode | 1 | 2 | 0:1 | String(36) |
statusCode | 1 | 2 | 0:1 | String(1) |
statusDescription | 1 | 2 | 0:1 | String(25) |
| streamingErrors | 1 | 2 | 0:1 | - |
| streamingErrorCode | 2 | 3 | 0:1 | String(6) |
| streamingErrorDetail | 2 | 3 | 0:1 | String(220) |
| receiptNumber | 1 | 2 | 0:1 | String(45) |
| xmlRetResponse | 1 | 2 | 0:1 | Memo Base64 |
items – Itens do response.
- success – informa que o envio do registro pelo método POST foi realizado com sucesso. (entrou no TSS)
- proccessed – Informa se o registro foi integrado com o Governo.
- registryKey – código do TAFKEY
- ticketCode – código do TAFTICKET
- statusCode – Status do registro, atributo exibido somente quando proccessed for igual a true.
- statusDescription – Descrição do status, atributo exibido somente quando proccessed for igual a true.
- streamingErrors – Agrupa todos os erros de transmissão retornados do Governo.
- streamingErrorCode – Código do erro retornado pelo Governo, após transmissão do registro.
- streamingErrorDetail – Descrição do erro retornado pelo Governo, após transmissão do registro.
- receiptNumber – Número do recibo retornado pelo Governo
- xmlRetResponse – Retorno resposta do governo quando o parâmetro returnRetResponse na solicitação for = true (ex.: totalizadores)
Exemplo do request para o método Get
{
"sourceBranch": "000001",
"tpAmb": "2",
"urlTSS": "http://localhost:8088",
"lote": [
{
"registryType":"S-1210",
"ticketCode": "TICKET5",
"registryKey": "XX001",
"returnRetResponse": true
},
{
"registryType":"S-1210",
"ticketCode": "TICKET4",
"registryKey": "X002",
"returnRetResponse": true
},
{
"registryType":"S-1210",
"ticketCode": "TICKET5",
"registryKey": "XX003",
"returnRetResponse": true
},
{
"registryType":"S-1010",
"ticketCode": "TICKET5",
"registryKey": "XX005",
"returnRetResponse": true
}
]
}
Exemplo da mensagem de retorno do método Get
{
"items": [
{
"receiptNumber": " ",
"processed": false,
"ticketCode": "TICKET5",
"statusCode": "3",
"xmlRetResponse": "",
"registryKey": "XX001",
"statusDescription": "Evento rejeitado",
"success": true,
"streamingErrorDetail": [
{
"streamingErrorCode": "609",
"streamingErrorDetail": "Código inválido."
}
]
},
{
"receiptNumber": "",
"processed": false,
"ticketCode": "TICKET4",
"statusCode": "",
"xmlRetResponse": "",
"registryKey": "X002",
"statusDescription": "",
"success": false,
"streamingErrorDetail": []
},
{
"receiptNumber": " ",
"processed": false,
"ticketCode": "TICKET5",
"statusCode": "3",
"xmlRetResponse": "",
"registryKey": "XX003",
"statusDescription": "Evento rejeitado",
"success": true,
"streamingErrorDetail": [
{
"streamingErrorCode": "609",
"streamingErrorDetail": "Código inválido."
},
{
"streamingErrorCode": "609",
"streamingErrorDetail": "Código inválido."
},
{
"streamingErrorCode": "609",
"streamingErrorDetail": "Código inválido."
}
]
},
{
"receiptNumber": " ",
"processed": false,
"ticketCode": "TICKET5",
"statusCode": "3",
"xmlRetResponse": "",
"registryKey": "XX005",
"statusDescription": "Evento rejeitado",
"success": true,
"streamingErrorDetail": [
{
"streamingErrorCode": "609",
"streamingErrorDetail": "Código inválido."
}
]
}
]
}
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas