TOTVS RM

Integração com o TOTVS RM (Framework RM) via API REST nativa, usada para sincronizar o cadastro de funcionários com o VELIX e receber eventos de admissão/demissão.

Endpoint de funcionários

O RM expõe o cadastro de colaboradores via:

GET /api/framework/v1/funcionarios

Parâmetros úteis: coligada, situacao (ativo/inativo), dataAlteracaoInicial para sincronização incremental.

Autenticação — OAuth2 client_credentials

curl -X POST https://SEU_RM/api/oauth2/v1/token \
  -d 'grant_type=client_credentials' \
  -d 'client_id=SEU_CLIENT_ID' \
  -d 'client_secret=SEU_CLIENT_SECRET'

A resposta traz um access_token que deve ser enviado em Authorization: Bearer em todas as chamadas subsequentes ao RM. Renove antes da expiração (expires_in).

Mapeamento de campos

Campo RM	Campo VELIX (Person)
CodColigada + CodFunc (concatenados)	externalId
Nome	name
CPF	document
Situacao = 'A'	active: true
Situacao = 'D' (demitido)	dispara DELETE /v1/persons/:id ou soft-delete

externalId recomendado: ${CodColigada}-${CodFunc} — garante unicidade entre coligadas diferentes que reaproveitam o mesmo CodFunc.

Sync periódico

TypeScript (SDK)

import { VelixClient, PersonsModule } from '@velix/sdk';
import axios from 'axios';

const velix = new VelixClient({
  apiUrl: process.env.VELIX_API_URL!,
  apiKey: process.env.VELIX_API_KEY!,
});
const persons = new PersonsModule(velix);

async function syncTotvsRM() {
  const { data: token } = await axios.post(`${process.env.RM_URL}/api/oauth2/v1/token`, null, {
    params: {
      grant_type: 'client_credentials',
      client_id: process.env.RM_CLIENT_ID,
      client_secret: process.env.RM_CLIENT_SECRET,
    },
  });

  const { data: funcionarios } = await axios.get(`${process.env.RM_URL}/api/framework/v1/funcionarios`, {
    headers: { Authorization: `Bearer ${token.access_token}` },
    params: { situacao: 'A' },
  });

  for (const f of funcionarios) {
    const externalId = `${f.CodColigada}-${f.CodFunc}`;
    await persons.upsert({
      externalId,
      name: f.Nome,
      document: f.CPF,
    });
  }
}

Delphi

uses Velix.Client, System.Net.HttpClient, System.JSON;

procedure SyncTotvsRM(VelixClient: TVelixClient; RMBaseUrl, Token: string);
var
  HttpClient: THTTPClient;
  Response: IHTTPResponse;
  Funcionarios: TJSONArray;
  Func: TJSONValue;
  ExternalId: string;
begin
  HttpClient := THTTPClient.Create;
  try
    HttpClient.CustomHeaders['Authorization'] := 'Bearer ' + Token;
    Response := HttpClient.Get(RMBaseUrl + '/api/framework/v1/funcionarios?situacao=A');
    Funcionarios := TJSONObject.ParseJSONValue(Response.ContentAsString) as TJSONArray;

    for Func in Funcionarios do
    begin
      ExternalId := Func.GetValue<string>('CodColigada') + '-' + Func.GetValue<string>('CodFunc');
      VelixClient.Persons.Upsert(ExternalId, Func.GetValue<string>('Nome'), Func.GetValue<string>('CPF'));
    end;
  finally
    HttpClient.Free;
  end;
end;

Execute este job via cron/scheduler externo (ex: Task Scheduler do Windows, onde o RM normalmente roda) a cada 15–30 minutos.

Webhook de admissão/demissão via RM Workflow

O RM permite configurar uma ação de Workflow para disparar uma chamada HTTP externa quando um processo de admissão ou demissão é concluído. Configure o Workflow para chamar:

POST https://api.velixbiometrics.com/v1/persons          (admissão)
DELETE https://api.velixbiometrics.com/v1/persons/:id    (demissão)

com o Bearer token da API key dedicada à integração, no header customizado da ação HTTP do Workflow Designer. Isso reduz a latência de sincronização de ~30 minutos (polling) para segundos.