Referência da API

APIs de trabalhador independente (regime simplificado/RNH). Para cálculos de processamento salarial, consulte a API de trabalhador por conta de outrem.

Função Principal

simulateIndependentWorker(options)

Calcula o rendimento de categoria B (trabalhador independente) português com regras de regime simplificado, segurança social, IRS de juventude e imposto fixo RNH opcional.

Parâmetros

interface SimulateIndependentWorkerOptions {
  income: number | number[];
  incomeFrequency?: FrequencyChoices;
  nrDaysOff?: number;
  ssDiscount?: number;
  maxExpensesTax?: number;
  expenses?: number;
  ssTax?: number;
  currentTaxRankYear?: 2023 | 2024 | 2025 | 2026;
  rnh?: boolean;
  rnhTax?: number;
  dateOfOpeningActivity?: Date | null;
  benefitsOfYouthIrs?: boolean;
  yearOfYouthIrs?: number;
  previousYearQ4MonthlyIncome?: number;
}

Valor de Retorno

interface IndependentWorkerResult {
  grossIncome: CurrencyByFrequency;
  yearBusinessDays: number;
  taxableIncome: number;
  ssPay: CurrencyByFrequency;
  specificDeductions: number;
  expenses: number;
  expensesNeeded: number;
  youthIrsDiscount: number;
  irsPay: CurrencyByFrequency;
  netIncome: CurrencyByFrequency;
  taxTableUsed: TaxRank[];
  taxRank: TaxRank;
  currentIas: number;
  maxSsIncome: number;
  ssTax: number;
  maxExpensesTax: number;
  workerWithinFirstFinancialYear: boolean;
  workerWithinSecondFinancialYear: boolean;
  workerWithinFirst12Months: boolean;
  rnh: boolean;
  rnhTax: number;
  benefitsOfYouthIrs: boolean;
  yearOfYouthIrs: number;
  ssQ1Approximated: boolean;
  monthlyBreakdown: IndependentWorkerMonthlyBreakdownResult[];
  normalizedInternals: IndependentWorkerNormalizedInternals;
}
 
interface IndependentWorkerMonthlyBreakdownResult {
  month: IndependentMonthName;
  grossIncome: number;
  taxableIncome: number;
  irsPay: number;
  ssPay: number;
  netIncome: number;
  totalTax: number;
  overallTaxBurden: number;
  effectiveBracketRate: number | null;
  marginalRate: number;
}

Exemplo

const result = simulateIndependentWorker({
income: 40000,
incomeFrequency: 'year',
expenses: 3000,
ssDiscount: -0.1,
benefitsOfYouthIrs: true,
yearOfYouthIrs: 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: €${result.netIncome.year.toFixed(2)}`);

Recibos Verdes

Um conjunto de funções utilitárias projetadas para analisar e processar as exportações oficiais em CSV de Recibos Verdes (SIRE) do Portal das Finanças.

parseGreenReceiptsCsv(content)

Analisa a string CSV em bruto descarregada do SIRE para um array de strings (GreenReceiptRawRow) representando a tabela.

toGreenReceipt(rawRow)

Transforma uma linha da tabela num GreenReceipt tipificado, convertendo automaticamente números em formato português (ex: "3.945,51") para números nativos de JavaScript e normalizando datas.

computeGreenReceiptsAnnualStats(receipts)

Agrega um array de GreenReceipt em estatísticas anuais detalhadas (GreenReceiptAnnualStats), agrupadas por ano. Calcula automaticamente o IVA total, IRS retido e fornece um detalhe financeiro por cliente.

simulateFromGreenReceiptsCsv(options)

Lê os dados CSV e executa diretamente o simulador `simulateIndependentWorker`, colocando as faturas nos seus respetivos meses de acordo com a predefinição para `currentTaxRankYear`. Se o CSV detiver documentos provenientes do 4º trimestre do ano passado (Ou, Nov e Dez), tira a devida média deles para definir automaticamente o `previousYearQ4MonthlyIncome`.

// 1. Conteúdo original do CSV:
const csvContent = "...";

// 2. Analisar do formato exportado das Finanças e correr simulador:
const result = simulateFromGreenReceiptsCsv({
csvContent, 
currentTaxRankYear: 2025,
expenses: 500, // Envie qualquer atributo regular da simulação
});

console.log(`Rendimento líquido final: €${result.netIncome.year.toFixed(2)}`);
console.log(`SS de Janeiro estimada? ${result.ssQ1Approximated}`);
console.log(`IRS a Pagar: €${result.irsPay.year.toFixed(2)}`);

Tipos e Enums

FrequencyChoices

enum FrequencyChoices {
  Year = "year",
  Month = "month",
  Day = "day"
}

Usado por simulateIndependentWorker para interpretar o valor income.

CurrencyByFrequency

interface CurrencyByFrequency {
  year: number;
  month: number;
  day: number;
}

A maioria dos resultados de trabalhador independente são devolvidos nesta forma (sempre usando 12 meses e 248 dias úteis).

IndependentMonthName

type IndependentMonthName =
  | "january"
  | "february"
  | "march"
  | "april"
  | "may"
  | "june"
  | "july"
  | "august"
  | "september"
  | "october"
  | "november"
  | "december";

TaxRank

interface TaxRank {
  id: number;
  min: number;
  max: number | null;
  normalTax: number;
  averageTax: number | null;
}

Representa um escalão IRS progressivo para trabalhadores independentes (tabelas para 2023, 2024, 2025 e 2026).

Funções de Validação

• validateIncome, validateIncomeFrequency, validateNrDaysOff
• validateSsDiscount, validateMaxExpensesTax, validateExpenses, validateSsTax
• validateCurrentTaxRankYear, validateRnhTax
• validateYearOfYouthIrs (limita anos a 1-5 para 2023/2024 e 1-10 para 2025/2026)

Tratamento de Erros

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);
}

Uso Avançado

Abertura de atividade e IRS de juventude

// Primeiro ano fiscal: fator 37.5% + isenção SS nos primeiros 12 meses
const firstYear = simulateIndependentWorker({
income: 28000,
dateOfOpeningActivity: new Date(new Date().getFullYear(), 0, 15),
benefitsOfYouthIrs: true,
yearOfYouthIrs: 1,
});

// Segundo ano fiscal: fator 56.25%, SS a pagar
const secondYear = simulateIndependentWorker({
income: 28000,
dateOfOpeningActivity: new Date(new Date().getFullYear() - 1, 3, 1),
benefitsOfYouthIrs: true,
yearOfYouthIrs: 2,
});

console.log('=== Impacto da Abertura de Atividade ===');
console.log(`Primeiro ano tributável: €${firstYear.taxableIncome.toFixed(2)}`);
console.log(`Segundo ano tributável: €${secondYear.taxableIncome.toFixed(2)}`);
console.log(`Primeiro ano SS: €${firstYear.ssPay.year.toFixed(2)}`);
console.log(`Segundo ano SS: €${secondYear.ssPay.year.toFixed(2)}`);

Rendimento Variável e Segurança Social

Ao fornecer um array de exatamente 12 números para income, o simulador processa o rendimento como variável ao longo do ano. O campo frequência (incomeFrequency) é ignorado, e a Segurança Social é unicamente calculada com base trimestral, espelhando as declarações trimestrais do mundo real:

Por a contribuição de Jan/Fev/Mar depender do rendimento de Out–Dez do ano anterior, o simulador aceita um parâmetro adicional opcional previousYearQ4MonthlyIncome. Quando este é omitido, os três meses baseiam-se numa estimativa para a média do 3º trimestre do ano correspondente e o parâmetro ssQ1Approximated retorna true no resultado — o que é útil para expor um aviso ao utilizador na interface.

// Sem dados do ano anterior — a contribuição para Jan/Fev/Mar da SS será uma estimativa
const estimated = simulateIndependentWorker({
income: [1500, 1800, 2000, 1200, 1000, 2500, 3000, 3200, 1500, 1000, 2800, 4000],
expenses: 3000,
});

if (estimated.ssQ1Approximated) {
console.log('⚠️  A contribuição SS para Jan/Fev/Mar é uma estimativa — preencha previousYearQ4MonthlyIncome para valor exato');
}

// Com dados do ano anterior — cálculo exato
const accurate = simulateIndependentWorker({
income: [1500, 1800, 2000, 1200, 1000, 2500, 3000, 3200, 1500, 1000, 2800, 4000],
expenses: 3000,
previousYearQ4MonthlyIncome: 2200, // rendimento bruto médio para Out/Nov/Dez do ano anterior
});

console.log('SS em Janeiro (estimativa):', estimated.monthlyBreakdown[0].ssPay.toFixed(2));
console.log('SS em Janeiro (exato):', accurate.monthlyBreakdown[0].ssPay.toFixed(2));
console.log('SS Anual (estimativa):', estimated.ssPay.year.toFixed(2));
console.log('SS Anual (exato):', accurate.ssPay.year.toFixed(2));