# Bituach Leumi Income Report (ביטוח לאומי) **Date:** 2026-06-01 **Status:** Draft **Spec:** 175 **Tier:** All tiers **Depends on:** `invoices-core`, `expenses-module`, `financial-statements`, `israeli-tax-reports`, `foundation-auth-rbac` **Referenced by:** `israeli-tax-reports` --- ## Overview Self-employed individuals in Israel must report their annual income to the National Insurance Institute (Bituach Leumi — ביטוח לאומי) and pay national insurance contributions (דמי ביטוח) and health insurance (ביטוח בריאות) based on their net income. This spec defines the annual Bituach Leumi income report: a pre-calculated summary of gross income, deductible expenses, and net income in the format required for the NII annual income report (טופס ב"ל), along with a contribution estimate based on current NII rates. --- ## NII Contribution Rates (2026 — verify at implementation) **Correction note (2026 self-employed rates):** The combined NII + health-insurance contribution for self-employed individuals uses **marginal banding** across three income bands (not a flat split). The combined rates below already fold in the health-insurance component: | Income band (monthly) | Combined NII rate | Notes | |-----------------------|-------------------|-------| | Up to 60% of average wage (≈ ₪6,331/month) | **5.97%** (reduced rate) | First band | | 60%–100% of average wage (≈ ₪6,331 → ₪10,551/month) | **17.83%** (full rate) | Second band | | 100% of average wage up to the income cap (≈ ₪10,551 → ₪45,075/month) | **17.83%** (full rate, continues) | Third band | | Above the income cap (בסיס הכנסה המרבי, ≈ ₪45,075/month) | **0%** | No NII on income above the cap | Bands are **marginal**: each rate applies only to the income within its band. The reduced 5.97% rate applies to the portion up to 60% of the average wage; the full 17.83% applies to the portion between 60% of average wage and the income cap; income above the cap is not charged. ```sql -- NII rates + thresholds stored in KV: nii_rates:{year} (alongside BoI rates) -- Keys: reduced_rate, full_rate, band1_monthly_ils (60% avg wage), -- avg_wage_monthly_ils, income_cap_monthly_ils -- Rates and thresholds update annually — store per-year, never hard-code. ``` --- ## Report UI `/reports/bituach-leumi?year=2026`: ``` ┌──────────────────────────────────────────────────────────────┐ │ Bituach Leumi — Annual Income Report 2026 [Export Excel] │ │ │ │ Income │ │ ─────────────────────────────────────────────────────────── │ │ Gross revenue (issued invoices, excl. VAT): ₪ 398,800 │ │ Less: Deductible expenses: (₪ 55,000) │ │ Less: Contractor payouts: (₪ 48,000) │ │ Less: Depreciation (manual entry): (₪ 8,000) │ │ ─────────────────────────────────────────────────────────── │ │ Estimated net income for NII: ₪ 287,800 │ │ Monthly average: ₪ 23,983 │ │ │ │ Estimated NII Contributions │ │ ─────────────────────────────────────────────────────────── │ │ National insurance (estimated): ₪ 27,400 │ │ Health insurance (estimated): ₪ 14,390 │ │ ─────────────────────────────────────────────────────────── │ │ Total NII contributions (estimate): ₪ 41,790 │ │ │ │ ⓘ This is an estimate. NII contributions are calculated │ │ based on your actual declared income. Consult your │ │ accountant for the exact calculation. │ │ │ │ Depreciation adjustment (optional) │ │ Add manual depreciation deduction: ₪ [8,000___] │ │ (NII accepts equipment depreciation per ITA rules) │ └──────────────────────────────────────────────────────────────┘ ``` --- ## Data Sources | Report line | Data source | |-------------|-------------| | Gross revenue | `SUM(invoices.total - invoices.vat_amount)` WHERE `status NOT IN ('DRAFT', 'SENT', 'VOID')` AND `tax_issue_date` IN year (excl. VAT) | | Deductible expenses | `SUM(expenses.amount - expenses.vat_amount)` WHERE `status = 'COMPLETED'` AND `vat_deductible = true` AND `expense_date` IN year (excl. VAT) | | Contractor payouts | `SUM(payout_bills.net_amount)` WHERE `status = 'PAID'` AND `paid_at` IN year | | Depreciation | Manual entry by user (not tracked in Zync; user enters estimate) | | Net income | gross - expenses - payouts - depreciation | --- ## NII Contribution Calculation ```ts // packages/reports/src/nii-estimate.ts // Proper marginal banding for self-employed NII (2026 rates). // Rates/thresholds are loaded per-year from KV: nii_rates:{year}. function estimateNIIContributions(annualNetIncome: number, rates: NIIRates): NIIEstimate { const monthlyIncome = annualNetIncome / 12 // Monthly thresholds (from nii_rates:{year}): const band1 = rates.band1_monthly_ils // ≈ 6_331 (60% of average wage) const cap = rates.income_cap_monthly_ils // ≈ 45_075 (בסיס הכנסה המרבי) const reducedRate = rates.reduced_rate // 0.0597 const fullRate = rates.full_rate // 0.1783 // Marginal banding on monthly income, then annualise. const inReduced = Math.min(monthlyIncome, band1) const inFull = Math.max(0, Math.min(monthlyIncome, cap) - band1) // Income above the cap is not charged. const monthlyContribution = inReduced * reducedRate + inFull * fullRate const total = Math.round(monthlyContribution * 12) // The combined rate already includes the health-insurance component; // split is reported for display only, proportional to the band rates. const healthInsurance = Math.round(total * (rates.health_share ?? 0.0)) // optional display split return { national_insurance: total - healthInsurance, health_insurance: healthInsurance, total } } ``` > **Rates and thresholds update annually** — store in KV `nii_rates:{year}` alongside the BoI rates. Never hard-code; the calculation reads the year's row. --- ## Advance Payments Tracking Many self-employed individuals pay NII contributions in monthly advances (as set by NII). Zync lets them track payments made: ```sql CREATE TABLE nii_advance_payments ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE, user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, year INTEGER NOT NULL, month INTEGER NOT NULL CHECK (month BETWEEN 1 AND 12), amount NUMERIC(12,2) NOT NULL, paid_at DATE NOT NULL, notes TEXT, created_at TIMESTAMPTZ DEFAULT NOW(), UNIQUE (tenant_id, user_id, year, month) -- one advance payment per month per user ); ``` Displayed in the report as "NII advances paid YTD: ₪X" with a comparison to the estimate. ### Advances tab UI The **NII Advances** tab lists recorded advances for the selected year and provides an inline entry form to log/edit them: ``` ┌──────────────────────────────────────────────────────────────┐ │ NII Advances — 2026 │ │ │ │ Log advance payment │ │ ─────────────────────────────────────────────────────────── │ │ Month [ March ▾ ] Amount ₪ [3,482____ ] │ │ Paid on [ 2026-03-15 ▾ ] Notes [ optional________ ] │ │ [ Add advance ] │ │ ─────────────────────────────────────────────────────────── │ │ Month Amount Paid on Notes │ │ ─────────────────────────────────────────────────────────── │ │ January ₪3,482 2026-01-14 — [Edit][✕] │ │ February ₪3,482 2026-02-15 — [Edit][✕] │ │ March ₪3,482 2026-03-15 — [Edit][✕] │ │ ─────────────────────────────────────────────────────────── │ │ Advances paid YTD: ₪10,446 │ └──────────────────────────────────────────────────────────────┘ ``` - **Add advance** → `POST /api/nii-advances` with `{ year, month, amount, paid_at, notes }`. The `UNIQUE (tenant_id, user_id, year, month)` constraint means re-submitting an existing month is rejected with a 409; the form then switches that row to edit mode (`PATCH /api/nii-advances/:id`). - **Edit** loads the row's values back into the form (pre-filled), submitting as `PATCH`. - **✕** deletes the row (`DELETE /api/nii-advances/:id`) after a confirm. - The **Month** dropdown lists only months not yet recorded for the year (the rest are disabled, pointing the user to Edit). --- ## Excel Export The Excel export contains: 1. **Summary tab** — the main report figures (as shown in UI) 2. **Invoices tab** — all qualifying invoices with number, date, customer, amount (net of VAT) 3. **Expenses tab** — all deductible expenses with date, category, vendor, amount (net of VAT) 4. **Payouts tab** — contractor payouts 5. **NII Advances tab** — recorded advance payments > All five tabs are written through the **shared financial export writer** (`financial-statements` spec 170): each sheet sets `rightToLeft = true` + a Hebrew-capable font so Hebrew headers render correctly in Excel, and every string cell beginning with `= + - @ \t \r` is `'`-prefixed to prevent spreadsheet formula injection from vendor/customer free-text. --- ## API ``` GET /api/reports/bituach-leumi → NII annual income report data query: { year, depreciation_deduction?: number } Response: { year, gross_revenue_net_vat, deductible_expenses, contractor_payouts, depreciation_deduction, net_income, nii_contributions: { national_insurance, health_insurance, total }, advances_paid: { total, by_month: [{ month, amount }] } } Requires: reports:read GET /api/reports/bituach-leumi/xlsx → Excel download query: { year, depreciation_deduction? } Requires: reports:export GET /api/nii-advances?year= POST /api/nii-advances → log advance payment PATCH /api/nii-advances/:id → edit DELETE /api/nii-advances/:id → delete ``` --- ## Architecture Decisions | Decision | Choice | Reason | |----------|--------|--------| | Estimate only | Not official calculation | NII calculates contributions based on declared income on the official form; Zync provides the input data and an estimate; actual liability may differ | | Depreciation as manual entry | Not auto-calculated | Equipment depreciation requires knowing asset purchase dates, useful life, and ITA depreciation schedules — not tracked in Zync; manual entry is the pragmatic solution | | NII rates in system_config | Not hardcoded | NII updates rates periodically; admin update without deployment required | | Advance payments tracking | Optional side table | Not all freelancers track advances in Zync; the annual summary is the primary value; advance tracking is additive | | All tiers | Not Business+ | Freelancers (the primary users of this report) are typically on the Freelancer tier; this is a core compliance need for IL self-employed; gating behind Business+ would be a barrier to the primary audience |