Exemplos gerais

Scripts completos e prontos para adaptar, cobrindo os dois cenários mais pedidos por clientes com TOTVS RM: automação via PowerShell (equipes de TI que já usam Windows Task Scheduler) e integração via Delphi (empresas com sistemas internos de cadastro de funcionário em Delphi/RAD Studio, comum em RH brasileiro).

Script PowerShell — sync diário TOTVS RM → VELIX

Sincroniza admissões e demissões do dia, pensado para rodar via Windows Task Scheduler próximo ao servidor RM.

# sync-totvs-velix.ps1
# Executar diariamente via Task Scheduler: 06:00 (antes do expediente)

param(
    [string]$RmUrl        = $env:RM_URL,
    [string]$RmClientId   = $env:RM_CLIENT_ID,
    [string]$RmSecret     = $env:RM_CLIENT_SECRET,
    [string]$VelixApiUrl  = $env:VELIX_API_URL,
    [string]$VelixApiKey  = $env:VELIX_API_KEY
)

$ErrorActionPreference = "Stop"
Import-Module VelixSDK
Connect-Velix -ApiUrl $VelixApiUrl -ApiKey $VelixApiKey

# 1. Autentica no RM (OAuth2 client_credentials)
$tokenResponse = Invoke-RestMethod -Method Post -Uri "$RmUrl/api/oauth2/v1/token" -Body @{
    grant_type    = "client_credentials"
    client_id     = $RmClientId
    client_secret = $RmSecret
}
$rmToken = $tokenResponse.access_token

# 2. Busca funcionários ativos alterados nas últimas 24h
$ontem = (Get-Date).AddDays(-1).ToString("yyyy-MM-dd")
$funcionarios = Invoke-RestMethod -Uri "$RmUrl/api/framework/v1/funcionarios?dataAlteracaoInicial=$ontem" `
    -Headers @{ Authorization = "Bearer $rmToken" }

$admitidos = 0
$demitidos = 0

foreach ($f in $funcionarios) {
    $externalId = "$($f.CodColigada)-$($f.CodFunc)"

    if ($f.Situacao -eq "A") {
        # Admissão ou atualização
        Invoke-VelixUpsertPerson -ExternalId $externalId -Name $f.Nome -Document $f.CPF
        $admitidos++
    }
    elseif ($f.Situacao -eq "D") {
        # Demissão — desativa no VELIX (revoga acesso, mantém histórico para auditoria)
        try {
            Disable-VelixPerson -ExternalId $externalId
            $demitidos++
        } catch {
            Write-Warning "Falha ao desativar $externalId (pode já estar inativo): $_"
        }
    }
}

Write-Host "Sync concluído: $admitidos admissões/atualizações, $demitidos demissões processadas."

# 3. Log para auditoria (opcional — enviar para arquivo compartilhado ou monitoramento)
$logLine = "$(Get-Date -Format o) | admitidos=$admitidos | demitidos=$demitidos"
Add-Content -Path "C:\Logs\velix-totvs-sync.log" -Value $logLine

Configuração no Task Scheduler:

$action  = New-ScheduledTaskAction -Execute "PowerShell.exe" -Argument "-File C:\Scripts\sync-totvs-velix.ps1"
$trigger = New-ScheduledTaskTrigger -Daily -At 6am
Register-ScheduledTask -TaskName "VelixTotvsSync" -Action $action -Trigger $trigger -RunLevel Highest

Script Delphi — integração com tela de cadastro de funcionário existente

Muitas empresas de médio porte têm um sistema interno em Delphi para cadastro de funcionários, alimentando o RH antes (ou em paralelo) do ERP. O exemplo abaixo adiciona uma chamada ao VELIX no evento OnAfterPost do DataSet de funcionários — assim toda vez que um funcionário é salvo localmente, ele também é espelhado no VELIX.

unit FuncionarioVelixSync;

interface

uses
  System.SysUtils, System.Classes, Data.DB,
  Velix.Client, Velix.Types, Velix.Error;

type
  TFuncionarioVelixSync = class
  private
    FVelixClient: TVelixClient;
  public
    constructor Create(const ApiUrl, ApiKey: string);
    destructor Destroy; override;

    // Chamar no OnAfterPost do DataSet de funcionários
    procedure SincronizarFuncionario(DataSet: TDataSet);
  end;

implementation

constructor TFuncionarioVelixSync.Create(const ApiUrl, ApiKey: string);
begin
  inherited Create;
  FVelixClient := TVelixClient.Create(ApiUrl, ApiKey);
end;

destructor TFuncionarioVelixSync.Destroy;
begin
  FVelixClient.Free;
  inherited;
end;

procedure TFuncionarioVelixSync.SincronizarFuncionario(DataSet: TDataSet);
var
  ExternalId, Nome, CPF: string;
  Ativo: Boolean;
begin
  ExternalId := DataSet.FieldByName('CODIGO_FUNCIONARIO').AsString;
  Nome       := DataSet.FieldByName('NOME').AsString;
  CPF        := DataSet.FieldByName('CPF').AsString;
  Ativo      := DataSet.FieldByName('SITUACAO').AsString = 'A';

  try
    if Ativo then
      FVelixClient.Persons.Upsert(ExternalId, Nome, CPF)
    else
      FVelixClient.Persons.Disable(ExternalId);
  except
    on E: EVelixError do
      // Nunca deixar a sincronização com o VELIX bloquear o cadastro local —
      // logar e seguir. Considerar uma fila de retry (ex: tabela local
      // FILA_SYNC_VELIX) para reprocessar falhas de rede.
      TFile.AppendAllText('C:\Logs\velix_sync_errors.log',
        Format('[%s] Falha ao sincronizar %s: %s'#13#10,
          [DateTimeToStr(Now), ExternalId, E.Message]));
  end;
end;

end.

Uso no formulário de cadastro:

procedure TFrmFuncionario.dsFuncionarioDataSetAfterPost(DataSet: TDataSet);
begin
  FVelixSync.SincronizarFuncionario(DataSet);
end;

:::tip Não bloquear a UI Chamadas HTTP síncronas no OnAfterPost podem travar a UI se a rede estiver lenta. Para volumes maiores, mova SincronizarFuncionario para uma TThread separada ou para uma fila processada por um serviço Windows. :::