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

Índice

indent	30px
absoluteUrl	true

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âmetros.

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

title	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

Fonte: REST com ERP Microsiga Protheus

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.

Estrutura da mensagem enviada no POST (Request):

Table Filter

id	1571258717045_-1186532069

Atributo	Pai	Nivel	Ocorrência	Formato
ticketCode	-	1	1	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

Aviso

title	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":

http://localhost:8090/rest/wsesocial/v1/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

Bloco de código

language	js
theme	Eclipse
title	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"
        }
    ]
}

Bloco de código

language	js
theme	Eclipse
title	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.

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

title	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":

http://localhost:8090/rest/wsesocial/v1/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

language	js
theme	Eclipse
title	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"	
		}		
	]
}

Bloco de código

language	js
theme	Eclipse
title	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."
                }
            ]
        }
    ]
}

...

Árvore de páginas

Versões comparadas

Versão antiga 14

Nova versão 15

Chave

Definição do Serviço

Configurações do Serviço

Definição dos métodos

SEND (Post)

Estrutura da mensagem enviada no POST (Request):

Estrutura da mensagem de retorno do POST (Response):

GET

Estrutura da mensagem enviada no GET (Request):

Estrutura da mensagem de retorno (Request):

Árvore de páginas

Histórico da Página

Versões comparadas

Versão antiga 14

Nova versão 15

Chave

Definição do Serviço

Configurações do Serviço

Definição dos métodos

SEND (Post)

Estrutura da mensagem enviada no POST (Request):

Estrutura da mensagem de retorno do POST (Response):

GET

Estrutura da mensagem enviada no GET (Request):

Estrutura da mensagem de retorno (Request):