Histórico da Página
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: Essa interface de integração irá realizar a criação de entidade, configuração do certificado digital e também disponibilizará método para consultar o ID da entidade, de acordo com parâmetrosEste 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"
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: [HTTPV11] [HTTPREST] [HTTPURI] [HTTPJOB] [OnStart] *A chave PrepareIn deve conter o código do Grupo de Empresas(sigamat.emp/syscompany) utilizado no modulo TAF, abaixo exemplos configurações possíveis para as mesmas:
** A chave Instances na seção TAF_CFGJOB é opcional, se a mesma não existir o sistema ira considerar a quantidade de threads declarada na chave instances da seção HTTPURI. Obs: O servidor cria Threads especificas para cada grupo de empresas de acordo com a configuração da chave Instances, por isso essa configuração deve ser realizada considerando a capacidade computacional do servidor. |
Definição dos métodos
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étodos
SEND (Post)
POSTDescriçã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.
Estrutura da mensagem enviada no POST (Request):
Table Filter | |||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||
|
|
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
Aviso | ||
---|---|---|
| ||
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) | coderr | - | 1 | 0:1 | String(3) | description | - | 1 | 1 |
Memo Base64 | 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
coderr: Código do erro
description: Descrição do erro
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": "TICKETABC1234b9ce64c5-094b-4c95-9b29-c22b5cbf94f3", "sourceBranch": "000004000001", "tpAmb": "2", "urlTSS": "http://localhost:8088", "lote": [ { "registryType": "S-10101200", "registryKey": "CHAVEDORERISTRO123dcd5ea38-3008-4229-ae80-6688e75dcefe", "integrationMessage": "<eSocial xmlns='<evttabrubrica'>http://www.esocial.gov.br/schema/evt/evtTabRubrica/v02_05_00'><evtTabRubrica</evttabrubrica'> Id='ID1024973980000002019061817343887589'><ideEvento><tpAmb>2</tpAmb><procEmi>1</procEmi><verProc>1.0</verProc></ideEvento><ideEmpregador><tpInsc>1</tpInsc><nrInsc>02497398</nrInsc></ideEmpregador></evtTabRubrica></eSocial>", "schemaVersion":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" }, { "registryType } ] } |
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "ticketCode": "S-1020b9ce64c5-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.
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 | 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
Aviso | ||
---|---|---|
| ||
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)
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "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 } ": "CHAVEDORERISTRO124", "integrationMessage": "<eSocial xmlns='<evttablotacao'>http://www.esocial.gov.br/schema/evt/evtTabLotacao/v02_05_00'><evtTabLotacao</evttablotacao'> Id='ID1024973980000002019031317110011792'><ideEvento><tpAmb>2</tpAmb><procEmi>1</procEmi><verProc>1.0</verProc></ideEvento><ideEmpregador><tpInsc>1</tpInsc><nrInsc>02497398</nrInsc></ideEmpregador><infoLotacao><inclusao><ideLotacao><codLotacao>LOT001001</codLotacao><iniValid>2018-01</iniValid></ideLotacao><dadosLotacao><tpLotacao>01</tpLotacao><tpInsc>1</tpInsc><nrInsc>02497398000149</nrInsc><fpasLotacao><fpas>507</fpas><codTercs>0079</codTercs></fpasLotacao></dadosLotacao></inclusao></infoLotacao></evtTabLotacao></eSocial>", "schemaVersion":"02_05_00" }, { "registryType": "S-1005", "registryKey": "CHAVEDORERISTRO126", "integrationMessage": "<eSocial xmlns='<evttabestab'>http://www.esocial.gov.br/schema/evt/evtTabEstab/v02_05_00'><evtTabEstab</evttabestab'> Id='ID1024973980000002019061817341123822'><ideEvento><tpAmb>2</tpAmb><procEmi>1</procEmi><verProc>1.0</verProc></ideEvento><ideEmpregador><tpInsc>1</tpInsc><nrInsc>02497398</nrInsc></ideEmpregador><infoEstab><inclusao><ideEstab><tpInsc>2</tpInsc><nrInsc>22573711005</nrInsc><iniValid>2019-01</iniValid></ideEstab><dadosEstab><cnaePrep></cnaePrep><aliqGilrat><aliqRat>0</aliqRat></aliqGilrat><infoTrab><regPt>0</regPt><infoApr><contApr>0</contApr></infoApr></infoTrab></dadosEstab></inclusao></infoEstab></evtTabEstab></eSocial>", "schemaVersion":"02_05_00" }] } |
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "items": [ { "receiptNumber": " ", "processed": false, "{ "ticketCode": "TICKETABC1234TICKET5", "coderr "statusCode": "3", "description "xmlRetResponse": "", "registryKey": [ { "key"XX001", "statusDescription": "CHAVEDORERISTRO123Evento rejeitado", "success": falsetrue, "error "streamingErrorDetail": [ { "coderr "streamingErrorCode": "99609", "description "streamingErrorDetail": "RXJybyBkZSBzY2hlbWE6IEVsZW1lbnQgJ3todHRwOi8vd3d3LmVzb2NpYWwuZ292LmJyL3NjaGVtYS9ldnQvZXZ0VGFiUnVicmljYS92MDJfMDVfMDB9ZXZ0VGFiUnVicmljYSc6IE1pc3NpbmcgY2hpbGQgZWxlbWVudChzKS4gRXhwZWN0ZWQgaXMgKCB7aHR0cDovL3d3dy5lc29jaWFsLmdvdi5ici9zY2hlbWEvZXZ0L2V2dFRhYlJ1YnJpY2EvdjAyXzA1XzAwfWluZm9SdWJyaWNhICkuCg==" } ] }, { "key": "CHAVEDORERISTRO124 ", "success": true }, { "key": "CHAVEDORERISTRO126 ", "success": false, "error": [ { "coderr": "99", "description": "RXJybyBkZSBzY2hlbWE6IEVsZW1lbnQgJ3todHRwOi8vd3d3LmVzb2NpYWwuZ292LmJyL3NjaGVtYS9ldnQvZXZ0VGFiRXN0YWIvdjAyXzA1XzAwfWNuYWVQcmVwJzogJycgaXMgbm90IGEgdmFsaWQgdmFsdWUgb2YgdGhlIGxvY2FsIGF0b21pYyB0eXBlLgo=" } ] } ], "keyAmount": 3Có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." } ] } ] } |