Começar

Cálculo de salários para trabalhadores por conta de outrem. Para trabalhadores por conta própria, veja a documentação de trabalhador independente.

Instalação


npm install saldo
# ou
pnpm add saldo

Início Rápido (CLI)

Pode executar simulações diretamente a partir do terminal se instalar o pacote globalmente:


saldo dependent --year 2025 --income 1500 --twelfths 2

Início Rápido (Biblioteca)

Exemplo Interativo

const result = simulateDependentWorker({
year: 2025,
income: 1500, // Rendimento bruto mensal em euros
location: 'continent',
married: false
});

// Aceder ao breakdown de janeiro
const jan = result.monthlyBreakdown[0];
console.log(`Rendimento Bruto (Jan): €${jan.grossIncome.baseSalaryAmount.toFixed(2)}`);
console.log(`IRS Retido (Jan): €${jan.irsWithholdingTax.totalAmount.toFixed(2)}`);
console.log(`Segurança Social (Jan): €${jan.socialSecurityContribution.totalAmount.toFixed(2)}`);
console.log(`Rendimento Líquido (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);

// Totais anuais
console.log(`Líquido Anual: €${result.yearly.totalNetIncomeAmount.toFixed(2)}`);
const result = simulateDependentWorker({
year: 2025,
income: 1500, // Rendimento bruto mensal em euros
location: 'continent',
married: false
});

// Aceder ao breakdown de janeiro
const jan = result.monthlyBreakdown[0];
console.log(`Rendimento Bruto (Jan): €${jan.grossIncome.baseSalaryAmount.toFixed(2)}`);
console.log(`IRS Retido (Jan): €${jan.irsWithholdingTax.totalAmount.toFixed(2)}`);
console.log(`Segurança Social (Jan): €${jan.socialSecurityContribution.totalAmount.toFixed(2)}`);
console.log(`Rendimento Líquido (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);

// Totais anuais
console.log(`Líquido Anual: €${result.yearly.totalNetIncomeAmount.toFixed(2)}`);

Compreender o Resultado


interface DependentWorkerResult {
  yearly: {
    totalGrossIncomeAmount: number;         // Rendimento bruto anual
    totalNetIncomeAmount: number;           // Rendimento líquido anual
    totalLunchAllowanceGrossAmount: number; // Subsídio de refeição anual bruto
  };
  socialSecurityContributionRate: number;   // Taxa de SS aplicada
  monthlyBreakdown: MonthlyBreakdownResult[]; // 12 entradas, uma por mês
}
 
interface MonthlyBreakdownResult {
  month: MonthName;   // ex. "january"
  period: PeriodT;    // ex. "2025-01-01_2025-07-31"
  grossIncome: {
    baseSalaryAmount: number;
    baseSalaryAndLunchAllowanceAmount: number;
    totalWithLunchAllowanceAndSubsidyTwelfthsAmount: number;
  };
  irsWithholdingTax: {
    totalAmount: number;
    fromBaseSalaryAmount: number;
    fromLunchAllowanceAmount: number;
    fromSubsidyTwelfthsAmount: number;
  };
  socialSecurityContribution: {
    totalAmount: number;
    fromBaseSalaryAmount: number;
    fromLunchAllowanceAmount: number;
    fromSubsidyTwelfthsAmount: number;
  };
  netIncome: {
    totalAmount: number;        // Salário líquido mensal total
    fromBaseSalaryAmount: number;
    fromLunchAllowanceAmount: number;
    fromSubsidyTwelfthsAmount: number;
  };
  lunchAllowance: LunchAllowanceAmountBreakdown;
  subsidyTwelfths: SubsidyTwelfthsAmountBreakdown;
  bracket: BracketResult;
  taxRetentionTable: TaxRetentionTableResult;
}

Parâmetros Principais

year: Ano fiscal — obrigatório (ex: 2025)
income: Rendimento bruto mensal em euros
married / numberOfHolders: Obrigatórios em conjunto para trabalhadores casados (1 ou 2)
disabled, partnerDisabled, numberOfDependents, numberOfDependentsDisabled
location: 'continent' | 'azores' | 'madeira' (predefinição 'continent')
socialSecurityContributionRate: Predefinição 0.11
twelfths: Twelfths.NONE | ONE_HALF_MONTH | ONE_MONTH | TWO_MONTHS (predefinição TWO_MONTHS)
lunchAllowanceDailyValue, lunchAllowanceMode ("cupon" ou "salary"), lunchAllowanceDaysCount
includeLunchAllowanceInJune: Se junho inclui subsídio de refeição (predefinição false)
oneHalfMonthTwelfthsLumpSumMonth: "june" ou "december" (predefinição "december")
isencaoHorarioMonthly: Suplemento mensal de isenção de horário (Art. 218.º–219.º + 265.º CT). Predefinição 0
benefitsOfYouthIrs + yearOfYouthIrs: Isenção parcial mensal do IRS Jovem (Art. 2.º-C CIRS). Ver a secção IRS Jovem na referência da API

Cenários Comuns

Pessoa Solteira

Exemplo Interativo

const single = simulateDependentWorker({
year: 2025,
income: 1000,
location: 'continent'
});

console.log('=== Pessoa Solteira ===');
const jan = single.monthlyBreakdown[0];
console.log(`Líquido Mensal (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
console.log(`Líquido Anual: €${single.yearly.totalNetIncomeAmount.toFixed(2)}`);const single = simulateDependentWorker({
year: 2025,
income: 1000,
location: 'continent'
});

console.log('=== Pessoa Solteira ===');
const jan = single.monthlyBreakdown[0];
console.log(`Líquido Mensal (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
console.log(`Líquido Anual: €${single.yearly.totalNetIncomeAmount.toFixed(2)}`);

Casado com Filhos

Exemplo Interativo

const marriedWithKids = simulateDependentWorker({
year: 2025,
income: 1800,
married: true,
numberOfHolders: 1,
numberOfDependents: 2,
location: 'continent'
});

console.log('=== Casado com Filhos ===');
const jan = marriedWithKids.monthlyBreakdown[0];
console.log(`Líquido Mensal (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
console.log(`Dedução do Escalão: €${jan.bracket.deduction.toFixed(2)}`);const marriedWithKids = simulateDependentWorker({
year: 2025,
income: 1800,
married: true,
numberOfHolders: 1,
numberOfDependents: 2,
location: 'continent'
});

console.log('=== Casado com Filhos ===');
const jan = marriedWithKids.monthlyBreakdown[0];
console.log(`Líquido Mensal (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
console.log(`Dedução do Escalão: €${jan.bracket.deduction.toFixed(2)}`);

Trabalhador com Deficiência

Exemplo Interativo

const disabledWorker = simulateDependentWorker({
year: 2025,
income: 1200,
disabled: true,
location: 'continent'
});

console.log('=== Trabalhador com Deficiência ===');
const jan = disabledWorker.monthlyBreakdown[0];
console.log(`Líquido Mensal (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
console.log(`Dedução Adicional: €${jan.bracket.var1_deduction.toFixed(2)}`);const disabledWorker = simulateDependentWorker({
year: 2025,
income: 1200,
disabled: true,
location: 'continent'
});

console.log('=== Trabalhador com Deficiência ===');
const jan = disabledWorker.monthlyBreakdown[0];
console.log(`Líquido Mensal (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
console.log(`Dedução Adicional: €${jan.bracket.var1_deduction.toFixed(2)}`);

Com Subsídio de Refeição

Exemplo Interativo

const withLunch = simulateDependentWorker({
year: 2025,
income: 1400,
lunchAllowanceDailyValue: 7.5,
lunchAllowanceMode: "cupon",
lunchAllowanceDaysCount: 22,
location: 'continent'
});

console.log('=== Com Subsídio de Refeição ===');
const jan = withLunch.monthlyBreakdown[0];
console.log(`Líquido base: €${jan.netIncome.fromBaseSalaryAmount.toFixed(2)}`);
console.log(`Subsídio de refeição bruto: €${jan.lunchAllowance.grossAmount.toFixed(2)}`);
console.log(`Total Líquido (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);const withLunch = simulateDependentWorker({
year: 2025,
income: 1400,
lunchAllowanceDailyValue: 7.5,
lunchAllowanceMode: "cupon",
lunchAllowanceDaysCount: 22,
location: 'continent'
});

console.log('=== Com Subsídio de Refeição ===');
const jan = withLunch.monthlyBreakdown[0];
console.log(`Líquido base: €${jan.netIncome.fromBaseSalaryAmount.toFixed(2)}`);
console.log(`Subsídio de refeição bruto: €${jan.lunchAllowance.grossAmount.toFixed(2)}`);
console.log(`Total Líquido (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);

Utilizar o Enum Twelfths

Exemplo Interativo

const withoutHolidayAllowance = simulateDependentWorker({
year: 2025,
income: 1500,
twelfths: Twelfths.NONE, // Sem distribuição de subsídios de férias
location: 'continent'
});

const withBothHolidayAllowances = simulateDependentWorker({
year: 2025,
income: 1500,
twelfths: Twelfths.TWO_MONTHS, // Tanto o subsídio de Natal como o de férias
location: 'continent'
});

console.log('=== Comparação de Twelfths ===');
const janSem = withoutHolidayAllowance.monthlyBreakdown[0];
const janDois = withBothHolidayAllowances.monthlyBreakdown[0];
console.log(`Sem Distribuição - Líquido Mensal (Jan): €${janSem.netIncome.totalAmount.toFixed(2)}`);
console.log(`Dois Meses - Líquido Mensal (Jan): €${janDois.netIncome.totalAmount.toFixed(2)}`);
console.log(`Dois Meses - Líquido Anual: €${withBothHolidayAllowances.yearly.totalNetIncomeAmount.toFixed(2)}`);
const withoutHolidayAllowance = simulateDependentWorker({
year: 2025,
income: 1500,
twelfths: Twelfths.NONE, // Sem distribuição de subsídios de férias
location: 'continent'
});

const withBothHolidayAllowances = simulateDependentWorker({
year: 2025,
income: 1500,
twelfths: Twelfths.TWO_MONTHS, // Tanto o subsídio de Natal como o de férias
location: 'continent'
});

console.log('=== Comparação de Twelfths ===');
const janSem = withoutHolidayAllowance.monthlyBreakdown[0];
const janDois = withBothHolidayAllowances.monthlyBreakdown[0];
console.log(`Sem Distribuição - Líquido Mensal (Jan): €${janSem.netIncome.totalAmount.toFixed(2)}`);
console.log(`Dois Meses - Líquido Mensal (Jan): €${janDois.netIncome.totalAmount.toFixed(2)}`);
console.log(`Dois Meses - Líquido Anual: €${withBothHolidayAllowances.yearly.totalNetIncomeAmount.toFixed(2)}`);

Trabalhar com Tipos


import { 
  simulateDependentWorker, 
  LocationT, 
  Twelfths, 
  DependentWorkerResult,
  SimulateDependentWorkerOptions
} from 'saldo';
 
// Cálculo de trabalhador por conta de outrem com segurança de tipos
const dependentOpts: SimulateDependentWorkerOptions = {
  year: 2025,
  income: 1500,
  location: 'continent',
};
const dependentResult: DependentWorkerResult = simulateDependentWorker(dependentOpts);

Diferenças Regionais

Cada região portuguesa tem taxas fiscais diferentes:

Exemplo Interativo

// Portugal Continental
const continent = simulateDependentWorker({
year: 2025,
income: 1500,
location: 'continent'
});

// Açores
const azores = simulateDependentWorker({
year: 2025,
income: 1500,
location: 'azores'
});

// Madeira
const madeira = simulateDependentWorker({
year: 2025,
income: 1500,
location: 'madeira'
});

console.log('=== Comparação Regional (€1500, Janeiro) ===');
console.log(`Continente - Líquido: €${continent.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);
console.log(`Açores - Líquido: €${azores.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);
console.log(`Madeira - Líquido: €${madeira.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);// Portugal Continental
const continent = simulateDependentWorker({
year: 2025,
income: 1500,
location: 'continent'
});

// Açores
const azores = simulateDependentWorker({
year: 2025,
income: 1500,
location: 'azores'
});

// Madeira
const madeira = simulateDependentWorker({
year: 2025,
income: 1500,
location: 'madeira'
});

console.log('=== Comparação Regional (€1500, Janeiro) ===');
console.log(`Continente - Líquido: €${continent.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);
console.log(`Açores - Líquido: €${azores.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);
console.log(`Madeira - Líquido: €${madeira.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);

Tratamento de Erros

A biblioteca fornece mensagens de erro claras para configurações inválidas:

Exemplo Interativo

try {
const result = simulateDependentWorker({
  year: 2025,
  income: 1500,
  married: true,
  // Falta numberOfHolders - obrigatório para casados
});
} catch (error) {
console.error('Erro:', error.message); // "'numberOfHolders' é obrigatório para trabalhadores casados"
}try {
const result = simulateDependentWorker({
  year: 2025,
  income: 1500,
  married: true,
  // Falta numberOfHolders - obrigatório para casados
});
} catch (error) {
console.error('Erro:', error.message); // "'numberOfHolders' é obrigatório para trabalhadores casados"
}

Próximos Passos

Saiba mais sobre situações fiscais e cenários
Explore o explorador de tabelas fiscais
Compreenda subsídios de refeição
Consulte a API de trabalhador por conta de outrem
Explore os exemplos de trabalhador por conta de outrem
Para trabalhadores por conta própria, veja a documentação de trabalhador independente.