Tempo aproximado para leitura: 00:02:00 min
Dúvida
Como utilizar a API REST nativa do TOTVS RM (rmsrestdataserver) para consultar dados e aplicar filtros no módulo de Folha de Pagamento?
Ambiente
TOTVS RH - TOTVS RH (Linha RM) - TOTVS Folha de Pagamento - Todas as versões
Solução
A API nativa do TOTVS RM (rmsrestdataserver) permite consultar dados do sistema comunicando-se diretamente com os DataServers (como o FopFuncData para Funcionários). Essa arquitetura garante o cumprimento de todas as regras de negócio, validações e persistências sem acessar as tabelas diretamente.
Requisitos de Autenticação e Cabeçalhos
-
Autenticação: Exige o tipo Basic Auth. Utilize usuário e senha válidos no RM com permissão de leitura no DataServer consultado.
-
Header Opcional/Recomendado:
CODCOLIGADAcom o código da coligada para contexto da requisição.
Estrutura da URL Base
http://{servidor}:{porta}/rmsrestdataserver/rest/{NomeDoDataServer}Como identificar o DataServer correto
- Acesse o sistema TOTVS RM na visão/tela desejada (exemplo: Visão de Funcionários).
- Pressione as teclas
CTRL+ALT+F9simultaneamente. -
A janela exibida informará o nome da Action e do DataServer (ex: DataServer:
FopFuncData).
Paginação (Obrigatória no Método GET)
Para prevenir indisponibilidade, timeouts e sobrecarga no servidor, utilize sempre os parâmetros de paginação:
start: Registro inicial (inicia em 0).limit: Quantidade máxima de registros retornados.
Exemplo de chamada com paginação:
Estrutura de Filtros (Parâmetro
filter)
O parâmetro
filter segue a estrutura de um array JSON com parâmetros nomeados:filter=["ESQUEMA_DA_CONSULTA", "VALOR_PARAMETRO_1", "VALOR_PARAMETRO_2"]- Índice 0: Condição equivalente à cláusula
WHEREutilizando parâmetros nomeados (iniciados com:). - Índices seguintes: Valores reais que substituirão os parâmetros na ordem declarada.
-
Boas Práticas para Evitar Erro 500 (
Ambiguous column name): Como os DataServers realizam joins entre tabelas, sempre adicione o prefixo da tabela principal antes do nome do campo (ex:PFUNC.RECMODIFIEDONem vez deRECMODIFIEDON).
Exemplos Práticos de Filtros:
-
Filtro Simples (Funcionários Ativos):
-
Array:
filter=["PFUNC.CODSITUACAO = :status", "A"] - URL:
http://localhost:8051/rmsrestdataserver/rest/FopFuncData?start=0&limit=5&filter=["PFUNC.CODSITUACAO = :status", "A"]
-
-
Filtro Composto (Usuário e Data de Modificação Exata):
-
Array:
filter=["PFUNC.RECMODIFIEDBY = :user AND PFUNC.RECMODIFIEDON = :data", "mestre", "2025-10-01T09:53:39-03:00"] -
URL:
http://localhost:8051/rmsrestdataserver/rest/FopFuncData?start=0&limit=5&filter=["PFUNC.RECMODIFIEDBY = :user AND PFUNC.RECMODIFIEDON = :data", "mestre", "2025-10-01T09:53:39-03:00"]
-
-
Filtro de Intervalo e Comparação (Operadores
>,<,>=,<=,LIKE):-
Array:
filter=["PFUNC.RECMODIFIEDON >= :dataInicio", "2024-01-01T00:00:00"] -
URL:
http://localhost:8051/rmsrestdataserver/rest/FopFuncData?start=0&limit=5&filter=["PFUNC.RECMODIFIEDON >= :dataInicio", "2024-01-01T00:00:00"]
-
Recomendações de Desenvolvimento:
-
URL Encoding: Em requisições via código (JavaScript, C#, Python, etc.), converta o array do filtro para string JSON e aplique a codificação de URL (
encodeURIComponentno JS) antes de anexar à URL. - Desempenho: Evite utilizar
limit=0, pois a busca sem limitação pode causar lentidão severa e timeout na aplicação.
0 Comentários