Começar

Cálculos para trabalhadores independentes (categoria B). Para processamento salarial, veja a documentação de trabalhador por conta de outrem.

Instalação


npm install saldo
# ou
pnpm add saldo

Início Rápido (CLI)

Pode executar cálculos de trabalhador independente diretamente do terminal se instalar o pacote globalmente:


saldo independent --income 30000 --expenses 2000 --benefits-of-youth-irs
 
# Ou para processar os Recibos Verdes diretamente:
saldo independent-csv --csv path/to/receipts.csv

Início Rápido (Biblioteca)

Exemplo Interativo

const result = simulateIndependentWorker({
income: 30000, // Rendimento anual por predefinição
incomeFrequency: 'year',
nrDaysOff: 20,
expenses: 2000,
benefitsOfYouthIrs: true,
yearOfYouthIrs: 1
});

console.log(`Rendimento Bruto (ano): €${result.grossIncome.year.toFixed(2)}`);
console.log(`Rendimento Tributável: €${result.taxableIncome.toFixed(2)}`);
console.log(`IRS: €${result.irsPay.year.toFixed(2)}`);
console.log(`Segurança Social: €${result.ssPay.year.toFixed(2)}`);
console.log(`Rendimento Líquido (ano): €${result.netIncome.year.toFixed(2)}`);
const result = simulateIndependentWorker({
income: 30000, // Rendimento anual por predefinição
incomeFrequency: 'year',
nrDaysOff: 20,
expenses: 2000,
benefitsOfYouthIrs: true,
yearOfYouthIrs: 1
});

console.log(`Rendimento Bruto (ano): €${result.grossIncome.year.toFixed(2)}`);
console.log(`Rendimento Tributável: €${result.taxableIncome.toFixed(2)}`);
console.log(`IRS: €${result.irsPay.year.toFixed(2)}`);
console.log(`Segurança Social: €${result.ssPay.year.toFixed(2)}`);
console.log(`Rendimento Líquido (ano): €${result.netIncome.year.toFixed(2)}`);

Compreender o Resultado


interface IndependentWorkerResult {
  grossIncome: CurrencyByFrequency; // ano/mês/dia
  taxableIncome: number;
  ssPay: CurrencyByFrequency;       // SS após descontos/limites
  specificDeductions: number;       // Máx de €4104 vs 10% SS
  expenses: number;                 // Despesas declaradas
  expensesNeeded: number;           // Faltam para atingir o limite simplificado
  youthIrsDiscount: number;         // Benefício de juventude limitado por IAS
  irsPay: CurrencyByFrequency;      // IRS devido (progressivo ou RNH fixo)
  netIncome: CurrencyByFrequency;
  taxRank: TaxRank;                 // Escalão progressivo usado
  currentIas: number;               // IAS para o ano selecionado
  maxSsIncome: number;              // Limite 12 × IAS
  ssTax: number;
  maxExpensesTax: number;           // Percentagem do regime simplificado
  workerWithinFirstFinancialYear: boolean; // Fator 37.5%
  workerWithinSecondFinancialYear: boolean; // Fator 56.25%
  workerWithinFirst12Months: boolean; // Janela de isenção SS
  rnh: boolean;
  rnhTax: number;
  benefitsOfYouthIrs: boolean;
  yearOfYouthIrs: number;
}

Parâmetros Principais

income + incomeFrequency: 'year' (predefinição), 'month', ou 'day' (dias úteis do ano). Em alternativa, pode passar um array de 12 números (um por mês do calendário) para rendimentos mensais variáveis — neste caso, incomeFrequency é ignorado e a SS é calculada com base em médias trimestrais.
yearBusinessDays: Substituição opcional da base dias úteis do ano
nrDaysOff: Para frequência diária; deve ser um inteiro < yearBusinessDays
ssTax: Taxa de segurança social (predefinição 0.214) e ssDiscount intervalo -0.25..0.25
currentTaxRankYear: Tabelas IRS 2023 | 2024 | 2025 | 2026
maxExpensesTax: Percentagem do regime simplificado (predefinição 15)
expenses: Despesas declaradas (0 por predefinição)
dateOfOpeningActivity: Determina fatores de primeiro/segundo ano fiscal e isenção SS nos primeiros 12 meses
rnh / rnhTax: Aplicar imposto fixo RNH em vez de escalões progressivos
benefitsOfYouthIrs + yearOfYouthIrs: Descontos IRS de juventude com limites IAS (1–10 anos dependendo do ano fiscal)

Cenários Comuns

Contratado diário com dias de folga e desconto SS

Exemplo Interativo

const daily = simulateIndependentWorker({
income: 120,
incomeFrequency: 'day',
nrDaysOff: 30,
ssDiscount: -0.1, // Redução de 10% na base SS
});

console.log('=== Contratado diário ===');
console.log(`Líquido diário: €${daily.netIncome.day.toFixed(2)}`);
console.log(`Líquido mensal: €${daily.netIncome.month.toFixed(2)}`);const daily = simulateIndependentWorker({
income: 120,
incomeFrequency: 'day',
nrDaysOff: 30,
ssDiscount: -0.1, // Redução de 10% na base SS
});

console.log('=== Contratado diário ===');
console.log(`Líquido diário: €${daily.netIncome.day.toFixed(2)}`);
console.log(`Líquido mensal: €${daily.netIncome.month.toFixed(2)}`);

Taxa fixa RNH vs. IRS progressivo

Exemplo Interativo

const standard = simulateIndependentWorker({ income: 45000 });
const rnh = simulateIndependentWorker({
income: 45000,
rnh: true,
rnhTax: 0.2,
});

console.log('=== Trabalhador Independente ===');
console.log(`IRS Padrão (ano): €${standard.netIncome.year.toFixed(2)}`);
console.log(`IRS RNH (ano): €${rnh.netIncome.year.toFixed(2)}`);
console.log(`Desconto IRS de juventude: €${standard.youthIrsDiscount.toFixed(2)}`);const standard = simulateIndependentWorker({ income: 45000 });
const rnh = simulateIndependentWorker({
income: 45000,
rnh: true,
rnhTax: 0.2,
});

console.log('=== Trabalhador Independente ===');
console.log(`IRS Padrão (ano): €${standard.netIncome.year.toFixed(2)}`);
console.log(`IRS RNH (ano): €${rnh.netIncome.year.toFixed(2)}`);
console.log(`Desconto IRS de juventude: €${standard.youthIrsDiscount.toFixed(2)}`);

Abertura de atividade e isenção SS

Exemplo Interativo

const now = new Date();

const firstYear = simulateIndependentWorker({
income: 28000,
dateOfOpeningActivity: new Date(now.getFullYear(), 0, 15), // mesmo ano -> primeiro ano fiscal
});

const older = simulateIndependentWorker({
income: 28000,
dateOfOpeningActivity: new Date(now.getFullYear() - 2, 0, 15),
});

console.log('=== Comparação de Isenção SS ===');
console.log(`Primeiros 12 meses SS: €${firstYear.ssPay.year.toFixed(2)}`);
console.log(`Após isenção SS: €${older.ssPay.year.toFixed(2)}`);const now = new Date();

const firstYear = simulateIndependentWorker({
income: 28000,
dateOfOpeningActivity: new Date(now.getFullYear(), 0, 15), // mesmo ano -> primeiro ano fiscal
});

const older = simulateIndependentWorker({
income: 28000,
dateOfOpeningActivity: new Date(now.getFullYear() - 2, 0, 15),
});

console.log('=== Comparação de Isenção SS ===');
console.log(`Primeiros 12 meses SS: €${firstYear.ssPay.year.toFixed(2)}`);
console.log(`Após isenção SS: €${older.ssPay.year.toFixed(2)}`);

Trabalhar com Tipos


import { 
  simulateIndependentWorker,
  FrequencyChoices,
  SimulateIndependentWorkerOptions,
  IndependentWorkerResult
} from 'saldo';
 
const independentOpts: SimulateIndependentWorkerOptions = {
  income: 35000,
  incomeFrequency: FrequencyChoices.Year,
  benefitsOfYouthIrs: true,
  yearOfYouthIrs: 2,
};
const independentResult: IndependentWorkerResult = simulateIndependentWorker(independentOpts);

Tratamento de Erros

Exemplo Interativo

try {
simulateIndependentWorker({
  income: 100,
  incomeFrequency: 'day',
  nrDaysOff: 400, // Demasiados dias de folga para calendário de 248 dias
});
} catch (error) {
console.error('Erro de trabalhador independente:', error.message);
}try {
simulateIndependentWorker({
  income: 100,
  incomeFrequency: 'day',
  nrDaysOff: 400, // Demasiados dias de folga para calendário de 248 dias
});
} catch (error) {
console.error('Erro de trabalhador independente:', error.message);
}

Próximos Passos

API de trabalhador independente
Exemplos de trabalhador independente
Para processamento salarial, veja a documentação de trabalhador por conta de outrem.