Histórico da Página
RESTWeb Service REST
Produto: | TOTVS Automação Fiscal |
Versões: | 12.1.2310+ |
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: WSTAFCREDTRAB
Objetivo: ConsultConsultar
Descrição: Este serviço é responsável pela consulta e envio de informações ao TSS.
Métodos: POST e GET.GET.
EndPoints:
- /api/rh/esocial/v1/wstafcredtrab/tafFull
- /api/rh/esocial/v1/wstafcredtrab/middleware
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"
| Nota | ||
|---|---|---|
| ||
Na seção HTTPURI, a chave PrepareIn deve ser comentada. Segue exemplo de configuração do WS REST para utilização no modulo TAF: Apenas para clientes TAFFUL é necessário a inclusão da seção TAF_CFGJOB para o correto funcionamento do DE/PARA de filiais entre o ERP de origem e o TAF [HTTPV11] [HTTPREST] [HTTPURI] [HTTPJOB] [TAF_CFGJOB] [OnStart] |
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:
| Bloco de código | ||
|---|---|---|
| ||
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:
| Bloco de código | ||
|---|---|---|
| ||
TokenAuthTSS: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRpZCI6IjE2ODA1NmNjLTczNTYtNDAwMC04NUI0LWZlNjhiMjZhYjJjZiIsICJjbGllbnRfaWQiOiJiZDFlMjhkNGRmYmIwZDY2YjY0MGVhOTQyOThiMmU3N2MyNDMzMzRjIiwiaXNzIjoiVE9UVlNfVFNTXzEyLjEuMDMzIiwiaWF0IjoxNjMyMTUzNjkzLCJleHAiOjE2MzIxNTU0OTR9.ZTIwMjk4NTJkZTgwYWU3N2VlMTE5OTU1ZGJjYWFlODZlYTJhZTc1OGUxYjI2YWE5MWIwMWYzOTVmMDU2YTNiNTkzZjdiM2NhOGNhZGU3ZDI3ZGNhNmI1N2QyODc1NjM3Nzg5MzNhYTAzYzNlNzQ4N2QzMThkMWU0YmE3NmEyMjU |
Definição dos
métodosEndPoints
SENDGET(
PostMiddleware)
Descrição do Método: O método POST 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 é enviar informações relacionadas ao eSocial para o TSS.
| Aviso | ||
|---|---|---|
| ||
ticketCode será mantido apenas para compatibilidade a partir de 18/10/2024 |
padrão REST, recebendo os parâmetros através da query string da requisição. Os dados enviados na URL são utilizados para consultar o serviço TSS e retornar o resultado em formato JSON.
Estrutura de parâmetros que podem ser passados na requisição (GET
Estrutura da mensagem enviada no POST (Request):
| Table Filter | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Pai Nivel
| -ticketCode
1 (mantido por compatibilidade) String(36)
| -sourceBranch
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)
|
sourceBranch – ticketCode – atributo raiz (string(36))sourceBranch - Código Identificador da entidade TSS ( retornado na configuração do certificado)tpAmb – Tipo do Ambiente
period - Competência dos dados consultados (Ex.: 202501)
forceRequest –
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
| title | Atenção! |
|---|
environment - Tipo do Ambiente ( 1= Produção ; 2- Homologação)
Exemplo da URL para chamada do método "sendget":
http://localhost:8090/rest/wsesocial{{baseUrl}}/api/rh/esocial/v1/send/
Estrutura da mensagem de retorno do POST (Response):
wstafcredtrab/middleware?sourceBranch=string&period=202509&forceRequest=true&urlTSS=http://tss-server:8080/&environment=2
GET (TAFFUL)
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
| Bloco de código | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"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"
}
]
} |
| Bloco de código | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"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.
| Aviso | ||
|---|---|---|
| ||
ticketCode será mantido apenas para compatibilidade a partir de 18/10/2024 |
Estrutura da mensagem enviada no GET (Request):
padrão REST, recebendo os parâmetros através da query string da requisição. Os dados enviados na URL são utilizados para consultar o serviço TSS e retornar o resultado em formato JSON.
Estrutura de parâmetros que podem ser passados na requisição (GET):
Atributo |
|---|
Atributo
Pai
Ocorrência | Formato | |
|---|---|---|
sourceBranch |
1 |
1
String(36)
tpAmb
-
string | |
period | 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)
string | ||
forceRequest | 1 | boolean/string |
sourceBranch – sourceBranch - Código Identificador da entidade TSS ( retornado na configuração do certificado)
period - Competência dos dados consultados (Ex.
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
| Aviso | ||
|---|---|---|
| ||
Os atributos não obrigatórios têm que fazer parte da estrutura, somente o seu preenchimento é opcional. |
: 202501)
forceRequest –
| Nota | ||
|---|---|---|
| ||
Para clientes TAFFUL a configuração da URL do TSS e do ambiente a ser consultado são feitas através dos seguintes parâmetros: MV_TAFSURL : url do TSS MV_TAFAMBE: ambiente a ser consultado (1- Produção, 2 - Homologação) |
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)
{{baseUrl}}/api/rh/esocial/v1/wstafcredtrab/tafFull?sourceBranch=string&period=202509&forceRequest=true
Retorno de dados (TAFFUL e Middleware
– Itens do response.)
| Bloco de código | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"sourceBranch": "000001",
"tpAmbAmbiente": "2",
"urlTSSArquivo": "http://localhost:8088W3siaWZDb25jZXNzb3JhLmNvZGlnbyI6MTA0LCJpZkNvbmNlc3NvcmEuZGVzY3JpY2FvIjoiQmFuY28gWFlaIiwiY29udHJhdG8iOiJDT05UUkFUTzEyMzQ1NiIsImNwZiI6IjY5Njk1NDk4MDE5IiwibWF0cmljdWxhIjoiTUFUMTIzNDU2IiwiaW5zY3JpY2FvRW1wcmVnYWRvci5jb2RpZ28iOjEsImluc2NyaWNhb0VtcHJlZ2Fkb3IuZGVzY3JpY2FvIjoiQ05QSiIsIm51bWVyb0luc2NyaWNhb0VtcHJlZ2Fkb3IiOiI1MzExMzc5MSIsImluc2NyaWNhb0VzdGFiZWxlY2ltZW50by5jb2RpZ28iOjEsImluc2NyaWNhb0VzdGFiZWxlY2ltZW50by5kZXNjcmljYW8iOiJDTlBKIiwibnVtZXJvSW5zY3JpY2FvRXN0YWJlbGVjaW1lbnRvIjoiNTMxMTM3OTEwMDAxMjIiLCJub21lVHJhYmFsaGFkb3IiOiJUcmFiYWxoYWRvciBUZXN0ZSIsIm5vbWVFbXByZWdhZG9yIjoiRW1wcmVnYWRvciBUZXN0ZSIsImRhdGFJbmljaW9Db250cmF0byI6IjEwLzEyLzIwMjQiLCJkYXRhRmltQ29udHJhdG8iOiIxMC8xMi8yMDI1IiwiY29tcGV0ZW5jaWFJbmljaW9EZXNjb250byI6IjAxLzIwMjUiLCJjb21wZXRlbmNpYUZpbURlc2NvbnRvIjoiMTIvMjAyNSIsInRvdGFsUGFyY2VsYXMiOjEyLCJ2YWxvclBhcmNlbGEiOjM1MCwidmFsb3JFbXByZXN0aW1vIjozNTAwLCJ2YWxvckxpYmVyYWRvIjowLCJjYXRlZ29yaWFUcmFiYWxoYWRvci5jb2RpZ28iOjEwNCwiY2F0ZWdvcmlhVHJhYmFsaGFkb3IuZGVzY3JpY2FvIjoiRW1wcmVnYWRvIC0gRG9tw6lzdGljbyIsInF0ZFBhZ2FtZW50b3MiOjEsInF0ZEVzY3JpdHVyYWNvZXMiOjEsImNvbXBldGVuY2lhIjoiMDEvMjAyNSIsImRhdGFBZG1pc3NhbyI6IjExLzA5LzIwMDUifSx7ImlmQ29uY2Vzc29yYS5jb2RpZ28iOjIzNywiaWZDb25jZXNzb3JhLmRlc2NyaWNhbyI6IkJhbmNvIFhZWiIsImNvbnRyYXRvIjoiQ09OVFJBVE8xMjM0NTYiLCJjcGYiOiI2MDg1MDUyNjAwMCIsIm1hdHJpY3VsYSI6Ik1BVDEyMzQ1NiIsImluc2NyaWNhb0VtcHJlZ2Fkb3IuY29kaWdvIjoxLCJpbnNjcmljYW9FbXByZWdhZG9yLmRlc2NyaWNhbyI6IkNOUEoiLCJudW1lcm9JbnNjcmljYW9FbXByZWdhZG9yIjoiNTMxMTM3OTEiLCJpbnNjcmljYW9Fc3RhYmVsZWNpbWVudG8uY29kaWdvIjoxLCJpbnNjcmljYW9Fc3RhYmVsZWNpbWVudG8uZGVzY3JpY2FvIjoiQ05QSiIsIm51bWVyb0luc2NyaWNhb0VzdGFiZWxlY2ltZW50byI6IjUzMTEzNzkxMDAwMTIyIiwibm9tZVRyYWJhbGhhZG9yIjoiVHJhYmFsaGFkb3IgVGVzdGUiLCJub21lRW1wcmVnYWRvciI6IkVtcHJlZ2Fkb3IgVGVzdGUiLCJkYXRhSW5pY2lvQ29udHJhdG8iOiIxMC8xMi8yMDI0IiwiZGF0YUZpbUNvbnRyYXRvIjoiMTAvMTIvMjAyNSIsImNvbXBldGVuY2lhSW5pY2lvRGVzY29udG8iOiIwMS8yMDI1IiwiY29tcGV0ZW5jaWFGaW1EZXNjb250byI6IjEyLzIwMjUiLCJ0b3RhbFBhcmNlbGFzIjoxMiwidmFsb3JQYXJjZWxhIjozNTAsInZhbG9yRW1wcmVzdGltbyI6MzUwMCwidmFsb3JMaWJlcmFkbyI6MCwiY2F0ZWdvcmlhVHJhYmFsaGFkb3IuY29kaWdvIjoxMDQsImNhdGVnb3JpYVRyYWJhbGhhZG9yLmRlc2NyaWNhbyI6IkVtcHJlZ2FkbyAtIERvbcOpc3RpY28iLCJxdGRQYWdhbWVudG9zIjoxLCJxdGRFc2NyaXR1cmFjb2VzIjoxLCJjb21wZXRlbmNpYSI6IjAxLzIwMjUiLCJkYXRhQWRtaXNzYW8iOiIxMS8wOS8yMDA1In1d",
"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
}
]
} | ||||||
| Bloco de código | ||||||
| ||||||
"CodRequisicao": "200",
"Competencia": "202501",
"DescrErro": "",
"HrSolicitacao": "10:15:49",
"Id": "2fb395c0-b7f5-13c2-cebe-2a2c48c9b272",
"Id_ent": "000014",
"Status": "1",
"DtSolicitacao": "20250911"
} |
Atributo | Ocorrência | Formato |
|---|---|---|
Ambiente | 1 | string |
Arquivo | 1 | base64 |
CodRequisicao | 1 | string |
Competencia | 1 | string |
DescrErro | 0-1 | string |
HrSolicitacao | 1 | string |
Id | 1 | string |
Status | 1 | string |
DtSolicitacao | 1 | string |