Cálculo de Valores por Funções Personalizadas

Disponível com a Service Release 6 da versão 10.20

As funções personalizadas permitem efetuar cálculos de valores através de scripts (escritas em Javascript), sem recurso a extensibilidade. Estas funções podem ser utilizadas no cálculo de valores de remunerações, descontos e horas extra.

A implementação e validação destas funções exigem conhecimentos de programação em JavaScript, bem como da API do ERP Primavera, em particular das entidades envolvidas no processamento salarial.

Cálculo

Esta funcionalidade permite calcular remunerações, descontos e horas extra através da definição de regras de cálculo específicas. Destina-se, sobretudo, a cenários em que os valores a calcular não podem ser obtidos através das fórmulas standard da aplicação, permitindo implementar lógica de cálculo personalizada.

As funções personalizadas são uma versão simplificada da extensibilidade, ou seja, permitem definir uma fórmula em JavaScript que calcula o valor, sem necessidade de recorrer à extensibilidade clássica.

Assistência do Cegid Pulse (Apenas Evolution)

O Cegid Pulse pode auxiliar na criação de funções personalizadas, convertendo um pedido escrito em linguagem natural num script JavaScript. Apesar desta assistência, deverá sempre rever, validar e testar o código gerado antes da sua utilização em ambiente produtivo.

A função personalizada deve devolver exclusivamente o valor da rúbrica (remuneração, desconto ou hora extra). Sempre que aplicável, a quantidade continua a ser calculada segundo as regras normais da respetiva rúbrica.

Particularidades dos descontos

Nos descontos, a função personalizada não é aplicada aos descontos de sistema:

• IRS;

• Segurança Social;

• CGA;

• Fundos;

• ADSE;

• Seguros

Como exceção, a funcionalidade pode ser utilizada nos seguintes tipos de desconto:

• Outros descontos de IRS;

• Descontos de sindicato;

• Qualquer outro desconto que não se enquadre nos descontos de sistema.

Quando um desconto é calculado através de uma função personalizada, o valor devolvido é tratado como a base de incidência do desconto, sendo posteriormente aplicada a percentagem configurada na rúbrica. Tal significa que, quando o valor devolvido pela função corresponde ao valor final pretendido, a percentagem do desconto deverá ser configurada com o valor 100%.

Criação

Para adicionar uma função personalizada, siga os seguintes passos:

1. Aceder à respetiva entidade (tabelas de Remunerações, Descontos ou Horas Extra), onde pretende calcular o valor;

2. Criar a rúbrica e preencher os campos habituais;

3. Configurar o cálculo da seguinte forma:

   • Remunerações: selecionar a fórmula Função Personalizada;

   • Horas Extra e Descontos: selecionar a opção Função Personalizada;

4. Clicar no botão Fx para abrir o editor de fórmulas;

5. Introduzir ou utilizar o Pulse para gerar o código da função;

6. Validar o comportamento da função através de um processamento manual;

7. Utilizar a função em ambiente produtivo.

A expressão da função personalizada deverá devolver o valor da remuneração, desconto ou hora extra que será considerado para o valor final, sendo que o valor devolvido deverá ser um número (Number).

Deverá escrever funções que sejam simples e eficientes, dado que a função será avaliada para cada caso onde está referenciada. Funções com complexidade elevada podem impactar o desempenho do processamento.

Saiba mais sobre o editor de fórmulas no artigo de apoio.

Objetos de contexto

Quando a função personalizada é avaliada, o sistema irá disponibilizar como variáveis de contexto os seguintes parâmetros:

Exemplos

Os parâmetros indicados anteriormente fornecem informações que podem ser necessárias para que a função personalizada possa calcular corretamente o valor, considerando-os na sua lógica de cálculo. De seguida, apresentamos algumas exemplos de utilização destas variáveis:

let dataAdmissao = Funcionario.DataAdmissao; // Data de admissão do funcionário
let dataProcessamento = Processamento.DataProcessamento; // Data do processamento
let codigoRemuneracaoVenc = Params.CodVencimento; // Código da remuneração de vencimento

Na estrutura das entidades está disponível no formulário de edição da função personalizada (janela de contexto), onde é possível navegar pelas propriedades das entidades e consultar os tipos de dados de cada propriedade.

Poderão existir propriedades que não estão preenchidas no processamento atual ou no momento da avaliação da função personalizada. Por exemplo:

• a propriedade Processamento.DataSaida só estará preenchida se o processamento for fim de contrato;

• a propriedade Processamento.SalarioHoraHExtra não tem valor porque este só é obtido após o cálculo de todas as remunerações do processamento, incluindo a remuneração que está a ser calculada.

Saiba mais informações no artigo de apoio.

Cegid Pulse

Para simplificar o processo de criação de funções, poderá escrever o cálculo que pretende em linguagem natural e solicitar ao Cegid Pulse para que converta numa função em javascript. Para obter melhores resultados, deverá

• utilizar descrições objetivas e detalhadas;

• indicar claramente as regras de cálculo pretendidas;

• identificar as entidades e propriedades relevantes.

Uma vez que o resultado é gerado por Inteligência Artificial, deverá sempre validar e testar o código antes da sua utilização.

Exemplos de funções personalizadas

 var valor = 0;
    for (const remuneracao of Processamento.Remuneracoes) {
        if (!Object.is(remuneracao, Remuneracao)) {
            valor += remuneracao.Valor;
            dependencia(remuneracao);
        }
    }
    return valor * 0.1;

const diaSemana = ProcHoraExtra.Data.getDay(); // 0 = domingo, 6 = sábado
const tempoHoras = ProcHoraExtra.Tempo;
if (tempoHoras <= 0) {
    throw new Error("Tempo de horas extra inválido (deve ser superior a 0).");
}
const valorBaseHora = ProcHoraExtra.ValorUnitario;
if (valorBaseHora <= 0) {
    throw new Error("Valor base da hora extra inválido (deve ser superior a 0).");
}
let valorCalculado;
if (diaSemana === 0 || diaSemana === 6) {
    // Fim de semana: 200% por cada hora
    valorCalculado = tempoHoras * valorBaseHora * 2;
} else {
    // Dia útil: 150% pela primeira hora, 175% pelas restantes horas ou frações
    const primeiraHora = Math.min(tempoHoras, 1); // máximo 1 hora para a primeira hora
    const horasRestantes = Math.max(tempoHoras - primeiraHora, 0);
    const valorPrimeiraHora = primeiraHora * valorBaseHora * 1.5; // 150% = 1.5 * base
    const valorHorasSeguintes = horasRestantes * valorBaseHora * 1.75; // 175% = 1.75 * base
    valorCalculado = valorPrimeiraHora + valorHorasSeguintes;
}
// Arredonda o resultado final a 2 casas decimais
const valorFinal = Number(valorCalculado.toFixed(2));
return valorFinal;

const valorPorConjugeAtivo = 480.92;
const valorPorFilhoAtivo = 250;
let numConjugesAtivos;
if (Funcionario.EstadoCivil === "001") {
    numConjugesAtivos = 1;
} else {
    numConjugesAtivos = 0;
}
const numFilhosAtivos = Funcionario.Dependentes;
let valorDesconto = (numConjugesAtivos * valorPorConjugeAtivo) + (numFilhosAtivos * valorPorFilhoAtivo);
valorDesconto = Number(valorDesconto.toFixed(2));
return valorDesconto;

Estes exemplos foram gerados com recurso a Inteligência Artificial. Se tentar replicar o exemplo ,poderá obter scripts diferentes.

Métodos especiais

Além das variáveis de contexto, existem alguns métodos especiais que podem ser utilizados na função personalizada:

    dependencia(remuneracao);

    log('Valor = ' + valor.toString());

// Obter os campos da tabela Instrumentos, pedindo apenas o atributo 'NumHoras'
 const camposInstrumento = DaValorAtributos(
    'Instrumentos',   // nome da tabela
    'NumHoras',       // lista de atributos a devolver (apenas NumHoras)
    'Instrumento',    // campo chave na tabela Instrumentos
    Funcionario.Instrumento // valor da chave: instrumento do funcionário
);
const campoNumHoras = camposInstrumento[0];
log("numHoras" + campoNumHoras.valor.toString());
return campoNumHoras.Valor;

const camposInstrumento = DaValorAtributosCondicao(
    "RHP_ParametrosIAS", //nome da tabela
    "ValorIAS,Tipo",     //lista de atributos a devolver( valorIAS e o tipo)
    "DataInicio = '2026-01-01' and tipo = 1" //expressão da condição
);
if (camposInstrumento)
{
    return camposInstrumento["ValorIAS"].Valor;
}
return 0;