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

Índice

indent	30px
absoluteUrl	true

Definição do Serviço

Nome: WSTAFCREDTRAB

Objetivo: Consultar

Descrição: Este serviço é responsável pela consulta e envio de informações ao TSS.

Métodos: 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

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:

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]
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

[TAF_CFGJOB]
MAIN=TAF_CFGJOB
Instances=2,2
Environment=P12
RefreshRate=120
PrepareIn=ALL

[OnStart]
JOBS=HTTPJOB, TAF_CFGJOB
RefreshRate=120

Fonte: REST com ERP Microsiga Protheus

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

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

Bloco de código

title	Autenticação JWT (TSS)

TokenAuthTSS: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRpZCI6IjE2ODA1NmNjLTczNTYtNDAwMC04NUI0LWZlNjhiMjZhYjJjZiIsICJjbGllbnRfaWQiOiJiZDFlMjhkNGRmYmIwZDY2YjY0MGVhOTQyOThiMmU3N2MyNDMzMzRjIiwiaXNzIjoiVE9UVlNfVFNTXzEyLjEuMDMzIiwiaWF0IjoxNjMyMTUzNjkzLCJleHAiOjE2MzIxNTU0OTR9.ZTIwMjk4NTJkZTgwYWU3N2VlMTE5OTU1ZGJjYWFlODZlYTJhZTc1OGUxYjI2YWE5MWIwMWYzOTVmMDU2YTNiNTkzZjdiM2NhOGNhZGU3ZDI3ZGNhNmI1N2QyODc1NjM3Nzg5MzNhYTAzYzNlNzQ4N2QzMThkMWU0YmE3NmEyMjU

Definição dos EndPoints

GET(Middleware)

Descrição do Método: O método GET segue o 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):

Table Filter

id	1757420737456_1714750560

Atributo	Ocorrência	Formato
sourceBranch	1	string
period	1	string
forceRequest	1	boolean/string
urlTSS	1	string
environment	1	string

sourceBranch – Código Identificador da entidade TSS ( retornado na configuração do certificado)

period - Competência dos dados consultados (Ex.: 202501)

forceRequest –

urlTSS – URL serviço do TSS

environment - Tipo do Ambiente ( 1= Produção ; 2- Homologação)

Exemplo da URL para chamada do método "sendget":

{{baseUrl}}/api/rh/esocial/v1/wstafcredtrab/middleware?sourceBranch=string&period=202509&forceRequest=true&urlTSS=http://tss-server:8080/&environment=2

GET (TAFFUL)

Descrição do Método: O método GET segue o 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	Ocorrência	Formato
sourceBranch	1	string
period	1	string
forceRequest	1	boolean/string

sourceBranch – Código Identificador da entidade TSS ( retornado na configuração do certificado)

period - Competência dos dados consultados (Ex.: 202501)

forceRequest –

Nota

title	Importante

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

{{baseUrl}}/api/rh/esocial/v1/wstafcredtrab/tafFull?sourceBranch=string&period=202509&forceRequest=true

Retorno de dados (TAFFUL e Middleware)

Bloco de código

language	js
theme	Eclipse
title	Exemplo do request para o método Get

{
    "sourceBranchAmbiente": "000001",
    "tpAmb": "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

language	js
theme	Eclipse
title	Exemplo da mensagem de retorno do método Get

{
    "items": [
        {
            "receiptNumber": "                              ""CodRequisicao": "200",
    "Competencia": "202501",
    "DescrErro": "",
            "processed": false,
            "ticketCode": "TICKET5",
            "statusCode": "3",
        "HrSolicitacao": "10:15:49",
    "xmlRetResponseId": "2fb395c0-b7f5-13c2-cebe-2a2c48c9b272",
            "registryKeyId_ent": "XX001000014",
            "statusDescriptionStatus": "Evento rejeitado1",
            "successDtSolicitacao": 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."
                }
            ]
        }
    ]
}"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

Árvore de páginas

Versões comparadas

Versão antiga 2

Nova versão Atual

Chave

Definição do Serviço

Configurações do Serviço

Autenticação

Definição dos EndPoints

GET(Middleware)

Estrutura de parâmetros que podem ser passados na requisição (GET):

GET (TAFFUL)

Retorno de dados (TAFFUL e Middleware)

Árvore de páginas

Histórico da Página

Versões comparadas

Versão antiga 2

Nova versão Atual

Chave

Definição do Serviço

Configurações do Serviço

Autenticação

Definição dos EndPoints

GET(Middleware)

Estrutura de parâmetros que podem ser passados na requisição (GET):

GET (TAFFUL)

Retorno de dados (TAFFUL e Middleware)