Referência da API

APIs de trabalhador por conta de outrem para processamento salarial em Portugal. Para cálculos de trabalhadores por conta própria, consulte a API de trabalhador independente.

Função Principal

`simulateDependentWorker(options)`

Calcula os impostos e o rendimento líquido de trabalhadores por conta de outrem portugueses usando as tabelas de retenção oficiais. Devolve um resumo mensal completo (12 meses), aplicando automaticamente o período fiscal correto para cada mês.

Parâmetros


interface SimulateDependentWorkerOptions {
  year: number;
  income: number;
  married?: boolean;
  disabled?: boolean;
  partnerDisabled?: boolean;
  location?: LocationT;
  numberOfHolders?: number | null;
  numberOfDependents?: number | null;
  numberOfDependentsDisabled?: number | null;
  socialSecurityContributionRate?: number;
  twelfths?: Twelfths;
  lunchAllowanceDailyValue?: number;
  lunchAllowanceMode?: "cupon" | "salary";
  lunchAllowanceDaysCount?: number;
  includeLunchAllowanceInJune?: boolean;
  oneHalfMonthTwelfthsLumpSumMonth?: "june" | "december";
  isencaoHorarioMonthly?: number;
  benefitsOfYouthIrs?: boolean;
  yearOfYouthIrs?: number;
}

Parâmetro	Tipo	Predefinição	Descrição
`year`	`number`	Obrigatório	Ano fiscal (ex: `2025`)
`income`	`number`	Obrigatório	Rendimento bruto mensal em euros
`married`	`boolean`	`false`	Se a pessoa é casada
`disabled`	`boolean`	`false`	Se a pessoa tem deficiência
`partnerDisabled`	`boolean`	`false`	Se o cônjuge tem deficiência
`location`	`LocationT`	`'continent'`	Região fiscal: `'continent'`, `'azores'`, ou `'madeira'`
`numberOfHolders`	`number \| null`	`null`	Número de titulares de rendimentos no casamento (1 ou 2)
`numberOfDependents`	`number \| null`	`null`	Número de dependentes
`numberOfDependentsDisabled`	`number \| null`	`null`	Número de dependentes com deficiências
`socialSecurityContributionRate`	`number`	`0.11`	Taxa de contribuição de segurança social (11%)
`twelfths`	`Twelfths`	`Twelfths.TWO_MONTHS`	Distribuição de subsídios de férias
`lunchAllowanceDailyValue`	`number`	`10.2`	Valor diário do subsídio de refeição em euros
`lunchAllowanceMode`	`"cupon" \| "salary"`	`"cupon"`	Tipo de subsídio de refeição
`lunchAllowanceDaysCount`	`number`	`22`	Dias úteis por mês para subsídio de refeição
`includeLunchAllowanceInJune`	`boolean`	`false`	Se junho inclui subsídio de refeição
`oneHalfMonthTwelfthsLumpSumMonth`	`"june" \| "december"`	`"december"`	Mês para o pagamento único de ONE_HALF_MONTH
`isencaoHorarioMonthly`	`number`	`0`	Suplemento mensal de isenção de horário (Art. 218.º–219.º + 265.º CT). Conta para o subsídio de férias mas não para o subsídio de Natal
`benefitsOfYouthIrs`	`boolean`	`false`	Aplica a isenção parcial mensal do IRS Jovem (Art. 2.º-C CIRS)
`yearOfYouthIrs`	`number`	`1`	Ano de benefício (1–10 a partir de 2025, 1–5 para 2023/2024)

Valor de Retorno


interface DependentWorkerResult {
  yearly: YearlyDependentWorkerSummary;
  socialSecurityContributionRate: number;
  monthlyBreakdown: MonthlyBreakdownResult[];
}
 
interface YearlyDependentWorkerSummary {
  totalGrossIncomeAmount: number;         // Rendimento bruto total do ano
  totalNetIncomeAmount: number;           // Rendimento líquido total do ano
  totalLunchAllowanceGrossAmount: number; // Subsídio de refeição bruto total do ano
}
 
interface MonthlyBreakdownResult {
  month: MonthName;
  period: PeriodT;
  taxableIncomeForIrsCalculation: number;
  incomeSubjectToIrsAndSocialSecurity: number;
  grossIncome: GrossIncomeAmountBreakdown;
  irsWithholdingTax: IncomeComponentAmountBreakdown;
  socialSecurityContribution: IncomeComponentAmountBreakdown;
  netIncome: IncomeComponentAmountBreakdown;
  lunchAllowance: LunchAllowanceAmountBreakdown;
  subsidyTwelfths: SubsidyTwelfthsAmountBreakdown;
  bracket: BracketResult;
  taxRetentionTable: TaxRetentionTableResult;
  youthIrs: YouthIrsBreakdown;
}
 
interface YouthIrsBreakdown {
  applied: boolean;            // true se o IRS Jovem reduz a retenção deste mês
  yearOfBenefit: number;       // ano de benefício (1–10)
  exemptionPercentage: number; // 0–1 (ex.: 0.75 para o 2.º–4.º ano em 2025+)
  monthlyExemptCap: number;    // tecto por pagamento = (multiplicador × IAS) / 14
  exemptIncome: number;        // parte isenta do mês (após aplicação do tecto)
}

Propriedade	Tipo	Descrição
`yearly.totalGrossIncomeAmount`	`number`	Rendimento bruto anual (14 meses + subsídio de refeição)
`yearly.totalNetIncomeAmount`	`number`	Rendimento líquido anual
`yearly.totalLunchAllowanceGrossAmount`	`number`	Subsídio de refeição bruto anual
`socialSecurityContributionRate`	`number`	Taxa de contribuição para a SS aplicada
`monthlyBreakdown`	`MonthlyBreakdownResult[]`	Array com 12 breakdowns mensais
`monthlyBreakdown[n].grossIncome.baseSalaryAmount`	`number`	Salário base mensal
`monthlyBreakdown[n].grossIncome.totalWithLunchAllowanceAndSubsidyTwelfthsAmount`	`number`	Total bruto mensal incluindo subsídios
`monthlyBreakdown[n].irsWithholdingTax.totalAmount`	`number`	Total de IRS retido nesse mês
`monthlyBreakdown[n].socialSecurityContribution.totalAmount`	`number`	Total de SS nesse mês
`monthlyBreakdown[n].netIncome.totalAmount`	`number`	Total do rendimento líquido mensal
`monthlyBreakdown[n].lunchAllowance.grossAmount`	`number`	Subsídio de refeição bruto do mês
`monthlyBreakdown[n].lunchAllowance.taxableAmount`	`number`	Porção tributável do subsídio
`monthlyBreakdown[n].lunchAllowance.taxExemptAmount`	`number`	Porção isenta de imposto do subsídio
`monthlyBreakdown[n].subsidyTwelfths.distributedMonthlyAmount`	`number`	Duodécimos distribuídos mensalmente
`monthlyBreakdown[n].subsidyTwelfths.lumpSumAmount`	`number`	Duodécimos em montante único neste mês
`monthlyBreakdown[n].bracket`	`BracketResult`	Informação do escalão fiscal
`monthlyBreakdown[n].taxRetentionTable`	`TaxRetentionTableResult`	Dados completos da tabela de retenção
`monthlyBreakdown[n].youthIrs.applied`	`boolean`	`true` quando o IRS Jovem reduz a retenção deste mês
`monthlyBreakdown[n].youthIrs.exemptionPercentage`	`number`	Percentagem de isenção do ano de benefício (`0`–`1`)
`monthlyBreakdown[n].youthIrs.monthlyExemptCap`	`number`	Tecto por pagamento = `(multiplicador × IAS) / 14`
`monthlyBreakdown[n].youthIrs.exemptIncome`	`number`	Parte isenta da remuneração do mês (após o tecto)

Exemplo

Exemplo Interativo

const result = simulateDependentWorker({
year: 2025,
income: 1500,
married: true,
numberOfHolders: 1,
numberOfDependents: 2,
location: 'continent',
lunchAllowanceDailyValue: 8.5,
lunchAllowanceMode: 'cupon',
lunchAllowanceDaysCount: 22,
twelfths: Twelfths.TWO_MONTHS
});

// Resumo anual:
console.log(`Bruto Anual: €${result.yearly.totalGrossIncomeAmount.toFixed(2)}`);
console.log(`Líquido Anual: €${result.yearly.totalNetIncomeAmount.toFixed(2)}`);

// Breakdown de janeiro:
const jan = result.monthlyBreakdown[0];
console.log(`IRS (Jan): €${jan.irsWithholdingTax.totalAmount.toFixed(2)}`);
console.log(`SS (Jan): €${jan.socialSecurityContribution.totalAmount.toFixed(2)}`);
console.log(`Líquido (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);
const result = simulateDependentWorker({
year: 2025,
income: 1500,
married: true,
numberOfHolders: 1,
numberOfDependents: 2,
location: 'continent',
lunchAllowanceDailyValue: 8.5,
lunchAllowanceMode: 'cupon',
lunchAllowanceDaysCount: 22,
twelfths: Twelfths.TWO_MONTHS
});

// Resumo anual:
console.log(`Bruto Anual: €${result.yearly.totalGrossIncomeAmount.toFixed(2)}`);
console.log(`Líquido Anual: €${result.yearly.totalNetIncomeAmount.toFixed(2)}`);

// Breakdown de janeiro:
const jan = result.monthlyBreakdown[0];
console.log(`IRS (Jan): €${jan.irsWithholdingTax.totalAmount.toFixed(2)}`);
console.log(`SS (Jan): €${jan.socialSecurityContribution.totalAmount.toFixed(2)}`);
console.log(`Líquido (Jan): €${jan.netIncome.totalAmount.toFixed(2)}`);

Tipos e Enums

`LocationT`


type LocationT = "continent" | "azores" | "madeira";

`Twelfths`


enum Twelfths {
  NONE = 0,           // Sem subsídios de férias
  ONE_HALF_MONTH = 0.5, // 1x50% - Um subsídio a 50% (meio mês)
  ONE_MONTH = 1,       // 2x50% - Dois subsídios a 50% cada (um mês total)
  TWO_MONTHS = 2       // 2x100% - Dois subsídios a 100% cada (dois meses total)
}

`GrossIncomeAmountBreakdown`


interface GrossIncomeAmountBreakdown {
  baseSalaryAmount: number;
  baseSalaryAndLunchAllowanceAmount: number;
  totalWithLunchAllowanceAndSubsidyTwelfthsAmount: number;
}

`IncomeComponentAmountBreakdown`

Usado para irsWithholdingTax, socialSecurityContribution e netIncome:


interface IncomeComponentAmountBreakdown {
  totalAmount: number;
  fromBaseSalaryAmount: number;
  fromLunchAllowanceAmount: number;
  fromSubsidyTwelfthsAmount: number;
}

`LunchAllowanceAmountBreakdown`


interface LunchAllowanceAmountBreakdown {
  grossAmount: number;
  taxableAmount: number;
  taxExemptAmount: number;
  isPaidInThisMonth: boolean;
}

Regras Fiscais:

Cartões de refeição ("cupon"): Isento até €10,20/dia
Subsídio em dinheiro ("salary"): Isento até €6,00/dia

`SubsidyTwelfthsAmountBreakdown`


interface SubsidyTwelfthsAmountBreakdown {
  distributedMonthlyAmount: number; // Porção distribuída mensalmente
  lumpSumAmount: number;            // Pagamento único em junho/dezembro
  totalAmount: number;              // distributedMonthlyAmount + lumpSumAmount
}

`SituationCodesT`


type SituationCodesT =
  | "TABLE1_SINGLE_OR_MARRIED_2_HOLDERS"      // Solteiro ou casado com 2 titulares
  | "TABLE2_SINGLE_ONE_OR_MORE_DEPENDENTS"     // Solteiro com dependentes
  | "TABLE3_MARRIED_1_HOLDER"                    // Casado, um titular
  | "TABLE4_SINGLE_OR_MARRIED_2_HOLDERS_NO_DEPENDENTS_PERSON_WITH_DISABILITY"  // Solteiro ou casado 2 titulares + deficiência
  | "TABLE5_SINGLE_ONE_OR_MORE_DEPENDENTS_PERSON_WITH_DISABILITY"     // Solteiro com dependentes + deficiência
  | "TABLE6_MARRIED_2_HOLDERS_ONE_OR_MORE_DEPENDENTS_PERSON_WITH_DISABILITY"    // Casado 2 titulares com dependentes + deficiência
  | "TABLE7_MARRIED_1_HOLDER_PERSON_WITH_DISABILITY";    // Casado um titular + deficiência

`Situation`


interface Situation {
  code: SituationCodesT;
  description: string;
  conditions: Condition[];
}

`Condition`


interface Condition {
  married: boolean;
  dependents: boolean;
  disabled: boolean;
  partnerDisabled: boolean;
  description: string;
  numberOfHolders?: number | null;
}

`BracketResult`


interface BracketResult {
  signal: "max" | "min";
  limit: number;
  max_marginal_rate: number;
  deduction: number;
  var1_deduction: number;
  var2_deduction: number;
  dependent_aditional_deduction: number;
  effective_mensal_rate: number;
}

`TaxRetentionTableResult`


interface TaxRetentionTableResult {
  situation: string;
  description: string;
  brackets: BracketResult[];
  dependent_disabled_addition_deduction?: number;
}

Funções Utilitárias

`SituationUtils.getSituation()`


SituationUtils.getSituation(
  married: boolean,
  disabled: boolean,
  partnerDisabled: boolean,
  numberOfHolders?: number | null,
  numberOfDependents?: number
): Situation | undefined

Determina a situação fiscal apropriada com base nas circunstâncias pessoais.

`SituationUtils.getSituationFromCode()`


SituationUtils.getSituationFromCode(code: string): Situation | undefined

Recupera uma situação fiscal pelo seu código.

Funções de Validação

A biblioteca inclui funções de validação internas que são chamadas automaticamente:

validateNumberOfHolders(numberOfHolders)
validateMarriedAndNumberOfHolders(married, numberOfHolders)
validatePartnerDisabled(married, partnerDisabled)
validateDependents(numberOfDependents, numberOfDependentsDisabled)
validateLunchAllowanceMode(lunchAllowanceMode)
validateYear(year)
validateYouthIrsForDependentWorker(benefitsOfYouthIrs, yearOfYouthIrs, year)

Tratamento de Erros

Exemplo Interativo

// Situação inválida
try {
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"
}// Situação inválida
try {
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"
}

Uso Avançado

Benefícios de Deficiência

Exemplo Interativo

// Trabalhador com deficiência
const workerDisability = simulateDependentWorker({
year: 2025,
income: 1500,
disabled: true,
location: 'continent'
});

// Cônjuge com deficiência (dedução extra)
const partnerDisability = simulateDependentWorker({
year: 2025,
income: 1500,
married: true,
numberOfHolders: 1,
partnerDisabled: true,
location: 'continent'
});

// Dependente com deficiência (dedução extra por dependente)
const dependentDisability = simulateDependentWorker({
year: 2025,
income: 1500,
numberOfDependents: 2,
numberOfDependentsDisabled: 1,
location: 'continent'
});

console.log('=== Comparação de Benefícios de Deficiência (Janeiro) ===');
console.log(`Deficiência do Trabalhador - Líquido: €${workerDisability.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);
console.log(`Deficiência do Cônjuge - Líquido: €${partnerDisability.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);
console.log(`Deficiência do Dependente - Líquido: €${dependentDisability.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);// Trabalhador com deficiência
const workerDisability = simulateDependentWorker({
year: 2025,
income: 1500,
disabled: true,
location: 'continent'
});

// Cônjuge com deficiência (dedução extra)
const partnerDisability = simulateDependentWorker({
year: 2025,
income: 1500,
married: true,
numberOfHolders: 1,
partnerDisabled: true,
location: 'continent'
});

// Dependente com deficiência (dedução extra por dependente)
const dependentDisability = simulateDependentWorker({
year: 2025,
income: 1500,
numberOfDependents: 2,
numberOfDependentsDisabled: 1,
location: 'continent'
});

console.log('=== Comparação de Benefícios de Deficiência (Janeiro) ===');
console.log(`Deficiência do Trabalhador - Líquido: €${workerDisability.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);
console.log(`Deficiência do Cônjuge - Líquido: €${partnerDisability.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);
console.log(`Deficiência do Dependente - Líquido: €${dependentDisability.monthlyBreakdown[0].netIncome.totalAmount.toFixed(2)}`);

IRS Jovem

Isenção parcial mensal da retenção na fonte para jovens trabalhadores. O escalão é determinado pela totalidade da remuneração mensal; a taxa efectiva resultante incide apenas sobre a parte não isenta. A parte isenta de cada pagamento está sujeita ao tecto (multiplicador × IAS) / 14.

Tabela de anos de benefício (a partir de 2025, conforme Lei n.º 45-A/2024 — OE 2025):

Ano de benefício	Isenção	Multiplicador IAS (tecto anual)
1.º	100 %	55 × IAS
2.º – 4.º	75 %	55 × IAS
5.º – 7.º	50 %	55 × IAS
8.º – 10.º	25 %	55 × IAS

Para 2023 e 2024 o regime é mais restrito (5 anos, percentagens inferiores) — ver youth-irs-data.ts.

Referências legais:

Art. 2.º-C do Código do IRS (CIRS) — define a isenção parcial para jovens trabalhadores.
Despacho n.º 9971-A/2024, alínea g) do n.º 7 — manda aplicar o escalão da remuneração total e cobrar retenção apenas sobre a parte não isenta.
Lei n.º 45-A/2024 (Orçamento do Estado para 2025) — alarga o regime para 10 anos e fixa o tecto anual em 55 × IAS.
Lei n.º 13/2023 — regime original do IRS Jovem (5 anos).

Exemplo Interativo

// Solteiro, 2.º–4.º ano de benefício (75% isenção), sem duodécimos
const result = simulateDependentWorker({
year: 2026,
income: 3000,
numberOfHolders: 1,
twelfths: Twelfths.NONE,
lunchAllowanceDailyValue: 0,
benefitsOfYouthIrs: true,
yearOfYouthIrs: 2,
});

const jan = result.monthlyBreakdown[0];
console.log('=== IRS Jovem (Ano 2 de benefício, 75%) ===');
console.log(`% de isenção:  ${(jan.youthIrs.exemptionPercentage * 100).toFixed(0)}%`);
console.log(`Tecto mensal:  €${jan.youthIrs.monthlyExemptCap.toFixed(2)}`);
console.log(`Parte isenta:  €${jan.youthIrs.exemptIncome.toFixed(2)}`);
console.log(`Retenção IRS:  €${jan.irsWithholdingTax.totalAmount.toFixed(2)}`);
console.log(`SS (sem alteração): €${jan.socialSecurityContribution.totalAmount.toFixed(2)}`);// Solteiro, 2.º–4.º ano de benefício (75% isenção), sem duodécimos
const result = simulateDependentWorker({
year: 2026,
income: 3000,
numberOfHolders: 1,
twelfths: Twelfths.NONE,
lunchAllowanceDailyValue: 0,
benefitsOfYouthIrs: true,
yearOfYouthIrs: 2,
});

const jan = result.monthlyBreakdown[0];
console.log('=== IRS Jovem (Ano 2 de benefício, 75%) ===');
console.log(`% de isenção:  ${(jan.youthIrs.exemptionPercentage * 100).toFixed(0)}%`);
console.log(`Tecto mensal:  €${jan.youthIrs.monthlyExemptCap.toFixed(2)}`);
console.log(`Parte isenta:  €${jan.youthIrs.exemptIncome.toFixed(2)}`);
console.log(`Retenção IRS:  €${jan.irsWithholdingTax.totalAmount.toFixed(2)}`);
console.log(`SS (sem alteração): €${jan.socialSecurityContribution.totalAmount.toFixed(2)}`);

Exemplo Interativo

const result = simulateDependentWorker({
year: 2025,
income: 1500,
socialSecurityContributionRate: 0.11, // 11% (predefinição)
location: 'continent'
});

const jan = result.monthlyBreakdown[0];
console.log('=== Taxa de SS Personalizada ===');
console.log(`Segurança Social (Jan): €${jan.socialSecurityContribution.totalAmount.toFixed(2)}`);
console.log(`Taxa Aplicada: ${(result.socialSecurityContributionRate * 100).toFixed(1)}%`);const result = simulateDependentWorker({
year: 2025,
income: 1500,
socialSecurityContributionRate: 0.11, // 11% (predefinição)
location: 'continent'
});

const jan = result.monthlyBreakdown[0];
console.log('=== Taxa de SS Personalizada ===');
console.log(`Segurança Social (Jan): €${jan.socialSecurityContribution.totalAmount.toFixed(2)}`);
console.log(`Taxa Aplicada: ${(result.socialSecurityContributionRate * 100).toFixed(1)}%`);

Referência da API

Função Principal

simulateDependentWorker(options)

Parâmetros

Valor de Retorno

Exemplo

Tipos e Enums

LocationT

Twelfths

GrossIncomeAmountBreakdown

IncomeComponentAmountBreakdown

LunchAllowanceAmountBreakdown

SubsidyTwelfthsAmountBreakdown

SituationCodesT

Situation

Condition

BracketResult

TaxRetentionTableResult

Funções Utilitárias

SituationUtils.getSituation()

SituationUtils.getSituationFromCode()

Funções de Validação

Tratamento de Erros

Uso Avançado

Benefícios de Deficiência

IRS Jovem

Taxa de Segurança Social Personalizada

`simulateDependentWorker(options)`

`LocationT`

`Twelfths`

`GrossIncomeAmountBreakdown`

`IncomeComponentAmountBreakdown`

`LunchAllowanceAmountBreakdown`

`SubsidyTwelfthsAmountBreakdown`

`SituationCodesT`

`Situation`

`Condition`

`BracketResult`

`TaxRetentionTableResult`

`SituationUtils.getSituation()`

`SituationUtils.getSituationFromCode()`