Tempo aproximado para leitura: 00:08:03 min
Dúvida
Para conexão via Webservice, como identificar e consumir DataServer e API disponíveis nos produtos de RH da linha RM?
Ambiente
TOTVS RH - TOTVS RH (Linha RM) - TOTVS Folha de Pagamento - Todas as versões
Solução
Os produtos de RH da linha RM disponibilizam duas tecnologias para integração e manipulação de dados: DataServer e API (REST).
A seguir, apresentamos as diferenças entre elas e os procedimentos para identificação e consumo.
Diferença entre DataServer e API
🔹 DataServer
Presente em todas as telas do RM
Forma nativa de comunicação do RM
Utiliza o formato XML (SOAP)
Permite consulta, inclusão e alteração de dados
Ideal para processos que ainda não possuem API disponível
🔹 API (Modernização)
Evolução do DataServer
Utiliza o padrão REST / JSON
Não está disponível para todas as funcionalidades
Aderente a padrões modernos de integração
⚠️ Ambos permitem consultar, incluir e alterar dados, desde que respeitadas as regras de negócio do sistema.
Escolha a tecnologia desejada
Utilizando um DataServer do RM RH
________________________________________________________________________________________________________________________
1- DATASERVER
1.1 - Documentação dos DataServers
1.2 - Descobrindo o nome do DataServer desejado
1.3 - Consumo de DataServer utilizando o SoapUI mesmo sem documentação
1.1 - DATASERVER - Documentação dos DataServers
É possível consultar os DataServers disponíveis nos produtos de RH da linha RM através da documentação oficial:
Documentação oficial dos DataServers
Caso o DataServer desejado não possua documentação, ele ainda poderá ser utilizado seguindo os procedimentos descritos nos tópicos abaixo.
1.2 - DATASERVER - Descobrindo o nome do DataServer desejado
Para identificar qual DataServer está associado a uma determinada tela do RM:
Acesse o RM
Entre na tela onde deseja incluir ou alterar registros
Pressione o atalho CTRL + ALT + F9
O sistema exibirá o nome do DataServer correspondente à tela.
Exemplo
Na tela de Cadastro de Atestados, o DataServer identificado é SmtAtestadoData:
Consultando detalhes do DataServer
Para obter informações detalhadas como:
Chaves primárias
Tabelas
Campos disponíveis
Utilize a ferramenta TOTVS WS Client, localizada no diretório de instalação: ...CorporeRM\RM.NET.
Esta ferramenta tem como objetivo auxiliar a utilização e/ou testar a execução dos DataServers disponíveis no RM. Através da aba Help, é possível consultar as chaves primárias, tabela e campos do dataServer.
1.3 - DATASERVER - Consumo de DataServer utilizando o SoapUI mesmo sem documentação
Processo via SoapUI
-
Para realizar o consumo dos dados, é necessário, primeiramente, executar um ReadRecord (Função de consultar dados) para obter as informações base.
Para isso, devem ser fornecidas as chaves primárias:
CODPESSOA (código da pessoa)
SEQATESTADO (Sequencial Atestados)
DTINICIO (Data Início Atestado)
CODTPATESTADO (Tipo Atestado)
Além das chaves primárias, é imprescindível informar o nome do DataServer correspondente, que, neste caso, é o SmtAtestadoData.
Por fim, deve-se especificar o contexto do consumo, fornecendo os seguintes parâmetros:
CODCOLIGADA
CODUSUARIO
CODSISTEMA
-
Após o consumo do DataServer pelo método ReadRecord, será possível extrair uma estrutura XML exemplo na tag "ReadRecordResult", a partir da tag <![CDATA[ "XML" ]]>.
Para inserir um novo registro, utilize o método SaveRecord. Informe o nome do DataServer correspondente na chave DataServerName, cole a estrutura XML de exemplo retornada pelo método ReadRecord e informe também o contexto, da mesma forma utilizada na chamada do ReadRecord.
Atualize os valores base do XML para as informações do novo registro que será inserido. Atente-se ao formato exigido pelas tags, seguindo o mesmo padrão da estrutura XML obtida no ReadRecord.
________________________________________________________________________________________________________________________
2- APIs
2.1 - Documentação das APIs
2.2 - Descobrindo o nome das APIs e testando a comunicação de uma API pelo Swagger
2.3 - Consumo de API utilizando o Postman mesmo sem documentação
2.1 - API - Documentação das APIs
Documentação para consultar informações das APIs via Swagger (O Swagger disponibiliza uma lista com todas as API's disponível do RM, além disso, também permite realizar teste de conexão)
2.2 - API - Descobrindo o nome das APIs e testando a comunicação de uma API pelo Swagger
O Swagger estará disponível após a inicialização do serviço de Host em seu ambiente, no endereço:
http://{dominio}:{ApiPort}/api/swagger/
Ao localizar a API desejada, ao clicar sobre ela, será possível consultar a lista detalhada de operações disponíveis. Neste exemplo, estamos utilizando a API de Pessoas (Person).
Ao selecionar o método desejado, por exemplo o GET, será apresentado um modelo de exemplo detalhado, contendo todas as informações sobre os campos e parâmetros. Para realizar uma requisição diretamente pelo Swagger, clique na opção “Try it out!”.
Em seguida, será solicitada a autenticação por meio das credenciais de um usuário do RM para validar a requisição:
Após a autenticação, o resultado da requisição será retornado no campo “Response Body”.
Também é possível realizar operações utilizando outros métodos disponíveis diretamente pelo Swagger. Ao selecionar o método POST, será exibido um modelo de exemplo, bem como o campo de texto “Record”, no qual é possível informar o JSON com os dados preenchidos e executar a requisição clicando novamente na opção “Try it out!”.
2.3 - API - Consumo de API utilizando o Postman mesmo sem documentação
Processo via Postman (Rest/APIs)
-
Assim como no SOAP, o primeiro passo é obter as informações do JSON base para realizar o envio. Para isso, deve-se utilizar a URL Serviços RESTful e informar o DataServer correspondente no método GET.
-
Além disso, é importante aplicar um filtro por ID, pois, caso o GET seja executado sem filtros, todos os registros serão retornados por padrão. Isso pode impactar o desempenho e resultar em alguns campos sendo carregados como nulos. Portanto, a aplicação de um filtro por ID é essencial para garantir que todos os campos sejam retornados corretamente, com as informações completas para nossa base.
Copie o campo "ID" retornado no primeiro GET sem filtro, e cole no final do endereço para realizar uma nova busca. Em alguns casos, pode ser retornado no campo ID algum filtro que tenha espaço, conforme exemplo abaixo:
O Postman não aceita espaço na URL, em cenários como este deverá localizar o valor da chave primária retornada no JSON e atualizar o valor do campo no ID. Neste exemplo, o espaço na tag ID estava sendo retornada no campo DTINICIO.
3. Para inserir um novo registro, utilizamos o método Post. Diferente do GET, no POST não é necessário informar o ID nem aplicar um filtro.
Copie apenas as informações retornadas dentro das chaves { } do Json, e remova apenas o campo "ID" que não deverá ser passado. Atualize os valores dos campos conforme desejado para inserção do novo registro, mantendo o mesmo padrão da estrutura JSON que foi retornada no GET executado com filtro.
Saiba mais
Cadastro de Funcionário via WebService/API utilizando o DataServer FopFuncData
Cadastro de Pessoa via WebService/API utilizando o DataServer RhuPessoaData
API disponíveis no TOTVS Folha de Pagamento
Utilizando o SoapUI para consumir DataServers RM via WebServices
Lista de DataServers Web Services
0 Comentários