Zero-dependency utilities for Albanian fiscalization (Law 87/2019 "On the invoice and the circulation monitoring system") and payroll: NIPT/NUIS validation, TVSH (VAT) math, fiscal invoice totals with the per-rate VAT breakdown every fiscalized invoice must report, and gross↔net salary / profit-tax math over a verified, dated rates config. Also available as an for AI agents.
Built and maintained by Square Software, a software company in Tirana that ships fiscalization integrations for POS, ERP and e-commerce systems. These are the same pure functions that power our free online tools:
every calculator as a tool for AI agents — see mcp/
Docker
docker run --rm squaresoftware/fiskalizimi --help
the CLI, no runtime to install
npm install fiskalizimi-utils
# or straight from GitHub:
npm install github:square-al/fiskalizimi-utils
Usage
Validate a NIPT / NUIS
import { validateNipt } from 'fiskalizimi-utils'
const res = validateNipt(' m5 1418-039h ') // separators + case are normalized
res.valid // true
res.normalized // 'M51418039H'
res.parts // { prefix: 'M', digits: '51418039', checkLetter: 'H' }
validateNipt('M5141803OH')
// { valid: false, issues: ['digits-not-numeric'], likelyTypo: true } ← O vs 0
Format-level validation only (letter A–M + 8 digits + control letter). A well-formed NIPT is not necessarily registered — check existence in the official registry (QKB), e.g. https://opencorporates.al/sq/nipt/m51418039h.
Every number comes from AL_2026 — a dated config verified against tatime.gov.al on 2026-06-29 — and none are hard-coded in the functions. Read AL_2026.notes for the disclosed approximation in the 50,000–60,000 ALL/month band.
MCP server
mcp/ wraps all of the above as an MCP server (al.square/fiskalizimi) so AI agents can validate a NIPT, total an invoice or compute a net salary without a network call: validate_nipt, add_vat, extract_vat, invoice_totals, net_salary, gross_salary_from_net, profit_tax, tax_rates. Claude Desktop users install the .mcpb from the latest release; any stdio client can run node mcp/dist/main.js. Details in mcp/README.md.
Python
The Python package is a faithful port with the payroll calculators added, and it
carries the dated rates config the square.al calculators
read:
A parity test suite generates fixtures from this TypeScript source and asserts
the Python implementation against them — down to the half-up rounding JavaScript
does and Python does not — so the two packages cannot silently diverge.
Regenerate the fixtures with npx tsx scripts/gen-parity-fixture.mjs.
Every subcommand takes --json. nipt exits non-zero on a bad format, so it
composes in shell scripts.
Open data
dataset/ publishes the same figures as a
Frictionless data package under CC-BY-4.0:
income-tax and profit-tax bands, contribution rates and their base window, VAT
rates, the minimum wage, and the filing deadlines — one row per band, rates as
decimal fractions. It is generated from the library
(cd dataset && PYTHONPATH=../python/src python3 generate.py), so the data and
the code cannot drift apart.
Shqip
Mjete TypeScript pa varësi për fiskalizimin shqiptar: verifikim i formatit të NIPT/NUIS, llogaritje TVSH-je (shto/hiq nga një vlerë) dhe totalet e faturës me TVSH-në e ndarë sipas normës — ashtu siç e raporton një faturë e fiskalizuar. I njëjti kod që fuqizon llogaritësit tanë falas. Për integrime fiskalizimi në sistemet tuaja, shihni square.al.
Accuracy
The AL-2026 rates config was confirmed against
tatime.gov.al on 2026-06-29 and carries
verified = true. Two limitations are disclosed in the config's own notes
field: the personal-income-tax bracket model is a deliberate approximation of the
official schedule inside the ~50,000–60,000 ALL/month transitional band, and the
severance figures are orientues values from the Labor Code's general
principles rather than a statutory table. See
Accuracy & limitations.
Rates and rules change; confirm with the tax authority before invoicing. Nothing
here is tax or legal advice.
No network calls, no dependencies, side-effect free — safe for browser and Node.
Tests: npm test (TypeScript) and
cd python && PYTHONPATH=src python -m unittest discover -s tests -t tests (104 tests).
Contributing
Bug reports and pull requests are welcome, on the
issue tracker and against
main respectively. Read CONTRIBUTING.md first: it explains the
process and the two rules that decide whether a change is accepted, namely zero runtime
dependencies and a cited legal source for every rate or formula change. Tests are
required in the same pull request as the functionality they cover.
For a wrong number, the fastest report to act on gives the exact inputs, the output you
got, the output you expected, and the legal basis for expecting it.
CodeQL runs over the TypeScript and Python sources on every push, every pull request,
and weekly.
Releasing
See PUBLISHING.md. Tagging vX.Y.Z publishes to PyPI and JSR
over OIDC with no stored tokens and attaches the MCP bundle to the GitHub release;
the MCP registry entry is then refreshed with mcp-publisher publish.