RH - RM - FOP - Como utilizar a API REST rmsrestdataserver e utilizar filtros na chamada?

Tempo aproximado para leitura: 00:07:00 min

Dúvida
Como utilizar a API REST nativa do TOTVS RM (rmsrestdataserver) para realizar consultas de dados nos DataServers, aplicando corretamente paginação e filtros?

Ambiente
TOTVS RH - TOTVS RH (Linha RM) - TOTVS Folha de Pagamento - Todas as versões

Solução
No TOTVS RM, um DataServer (como FopFuncData) é a camada da arquitetura responsável por concentrar toda a regra de negócio, validações e persistência de dados do sistema.

Em vez de acessar as tabelas do banco de dados diretamente, o TOTVS RM utiliza o DataServer para garantir que nenhuma regra do sistema seja violada.

Como Descobrir/Solicitar qual DataServer Utilizar?
 

Atalho na tela da MDI do RM 

1. Acesse o sistema TOTVS RM  e abra a visão/tela desejada (exemplo: Visão de Funcionários).
2. Pressione as teclas CTRL + ALT + F9 simultaneamente no seu teclado.
3. Uma janela detalhada será exibida informando o nome da Action e o nome exato do DataServer (ex: DataServer: FopFuncData).
   

Na ferramenta de requisição (exemplo: Postman), acesse a aba de autorização, selecione Basic Auth e insira o Username e Password de um usuário válido.

Inclua no cabeçalho (Header) da requisição a chave CODCOLIGADA informando o código da coligada de contexto (exemplo: 1).

Monte a URL de consulta utilizando o endpoint base no padrão:
http://{servidor}:{porta}/rmsrestdataserver/rest/{NomeDoDataServer}

Exemplo de uso: http://localhost:8051/rmsrestdataserver/rest/FopFuncData

Método GET (Consultar Todos / Paginação)

Utilizado para listar múltiplos registros de um DataServer. Para evitar sobrecarga no servidor e lentidão, é obrigatório o uso de paginação.

Parâmetros de URL (Query Params)

• start: Indica a partir de qual registro a busca deve começar (O primeiro registro é o 0).
• limit: Indica a quantidade máxima de registros que serão retornados na chamada.

Exemplo Simples de Paginação

Para buscar os 5 primeiros funcionários da base:
http://localhost:8051/rmsrestdataserver/rest/FopFuncData?start=0&limit=5

Trabalhando com Filtros (filter)

A API do RM possui uma sintaxe específica e muito poderosa para filtragem. O parâmetro filter deve ser enviado na URL e obedece a uma estrutura de Array (Lista).

Como montar a estrutura do Filtro?

A estrutura do array segue a regra: filter=["ESQUEMA DA CONSULTA", "VALOR_PARAMETRO_1", "VALOR_PARAMETRO_2"]. 

1. O Esquema (Índice 0): É a sua condição (parecido com a cláusula WHERE do SQL). Você deve usar Parâmetros Nomeados (variáveis com : na frente) no lugar dos valores.
   • Exemplo: "PFUNC.CODSITUACAO = :situacao"
     
      
2. Os Valores (Índices seguintes): São os valores reais que vão substituir os parâmetros nomeados, exatamente na mesma ordem.
   • Exemplo: "A" (onde A = Ativo).
      

Prefixo das Tabelas (Evitando o Erro 500)

Os DataServers do RM (como o FopFuncData) fazem consultas complexas unindo várias tabelas no banco de dados. Se você filtrar por um campo que existe em mais de uma tabela (ex: RECMODIFIEDON), a API retornará o erro "Ambiguous column name".

• Solução: Sempre coloque o nome da tabela principal antes do campo. Exemplo: Use PFUNC.RECMODIFIEDON ao invés de apenas RECMODIFIEDON.

Exemplos Práticos de Filtros

Exemplo de Filtro Simples (Buscar funcionários Ativos)

Queremos listar apenas os funcionários cuja situação seja "A" (Ativo).

Array do Filtro:

filter=["PFUNC.CODSITUACAO = :status", "A"]

URL no Postman (Aba Params):

• Key: filter
• Value: ["PFUNC.CODSITUACAO = :status", "A"]

URL Completa:
http://localhost:8051/rmsrestdataserver/rest/FopFuncData?start=0&limit=5&FILTER=["PFUNC.CODSITUACAO = :status", "A"]

Saiba mais
Integração API REST (rmsrestdataserver)