Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

Feature/Adding BIN/IIN fiscal configuration for KZT / Kazakhstan (#1015)

Alatau-AS71cd5b79d6e2
diff --git a/backend/app/fiscal/jurisdictions/kz.toml b/backend/app/fiscal/jurisdictions/kz.toml
index e559749c..70d9080d 100644
--- a/backend/app/fiscal/jurisdictions/kz.toml
+++ b/backend/app/fiscal/jurisdictions/kz.toml
@@ -1,6 +1,5 @@
-# Kazakhstan BIN (legal entities) and IIN (individuals) share both the
-# length and the check algorithm, so one validator serves both. The two-pass
-# weights are the published KZ scheme; a 10 from either pass means the
-# number was never issued.
+# Kazakhstan. The electronic invoice (ЭСФ / ESF) is issued by VAT-registered
+# businesses. BIN identifies legal entities and IIN identifies individuals;
+# both are twelve digits and share one checksum scheme.
code = "KZ"
kinds = ['kz_biniin']
diff --git a/backend/app/fiscal/validators.py b/backend/app/fiscal/validators.py
index 6309b6d1..9b277121 100644
--- a/backend/app/fiscal/validators.py
+++ b/backend/app/fiscal/validators.py
@@ -373,8 +373,15 @@ def validate_ru_inn(value: str) -> str | None:
return None
return "length"
-def validate_kz_biniin(value:str) -> str | None:
- """Kazakhstan BIN/IIN: twelve digits, mod-11 check digit."""
+def validate_kz_biniin(value: str) -> str | None:
+ """Validate a Kazakhstani BIN or IIN.
+
+ BIN (legal entities) and IIN (individuals) share the same 12-digit length
+ and the same published checksum scheme, so one validator serves both. The
+ scheme is two-pass: each pass uses a different weight vector, and the
+ weighted sum modulo 11 is the check digit. A result of 10 from either
+ pass means the number was never issued and the code is rejected.
+ """
if not value.isdigit():
return "invalid"
if len(value) != 12:
diff --git a/backend/tests/test_fiscal_validators_intl.py b/backend/tests/test_fiscal_validators_intl.py
index b0361854..61825816 100644
--- a/backend/tests/test_fiscal_validators_intl.py
+++ b/backend/tests/test_fiscal_validators_intl.py
@@ -32,6 +32,8 @@ REAL_DOCUMENTS = [
("ch_uid", "CHE116281710", "Nestlé"),
("ch_uid", "116281710", "Nestlé, prefix omitted"),
("ru_inn", "7707083893", "Sberbank"),
+ ("kz_biniin", "971240001315", "Kaspi Bank"),
+ ("kz_biniin", "130940003374", "Bolashak project LLP"),
("au_abn", "51824753556", "the Australian Taxation Office"),
("ro_cui", "14399840", "a Romanian company"),
]
@@ -48,6 +50,7 @@ CHECKED = {
"cz_ico",
"ch_uid",
"ru_inn",
+ "kz_biniin",
"au_abn",
"ro_cui",
}
@@ -87,6 +90,21 @@ def test_a_russian_inn_has_two_lengths():
assert VALIDATORS["ru_inn"]("77070838931") == "length"
+def test_a_kazakhstani_biniin_has_twelve_digits():
+ """Both BIN and IIN share same twelve digits, so anything else is rejected."""
+ assert VALIDATORS["kz_biniin"]("131240011813") is None
+ assert VALIDATORS["kz_biniin"]("05094000284") == "length" # 11
+ assert VALIDATORS["kz_biniin"]("0509400028481") == "length" # 13
+ assert VALIDATORS["kz_biniin"]("97124000131a") == "invalid" # non-digit
+
+
+def test_a_kazakhstani_biniin_that_passes_only_the_second_checksum():
+ """A value satisfying only the second pass; without it that branch is
+ untested and a regression there would silently reject real users."""
+ assert VALIDATORS["kz_biniin"]("971240004316") is None
+ assert VALIDATORS["kz_biniin"]("950640000959") is None
+
+
# ---------------------------------------------------------------------------
# shape-only validators: assert the gap deliberately
# ---------------------------------------------------------------------------
diff --git a/frontend/src/locales/de.json b/frontend/src/locales/de.json
index 858d6bc3..0f73184f 100644
--- a/frontend/src/locales/de.json
+++ b/frontend/src/locales/de.json
@@ -2069,6 +2069,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/el.json b/frontend/src/locales/el.json
index 5aef30ab..8de8dd1e 100644
--- a/frontend/src/locales/el.json
+++ b/frontend/src/locales/el.json
@@ -2068,6 +2068,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.json
index a74622eb..2f6e076c 100644
--- a/frontend/src/locales/en.json
+++ b/frontend/src/locales/en.json
@@ -2068,6 +2068,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/es.json b/frontend/src/locales/es.json
index 39454f69..094c8ab3 100644
--- a/frontend/src/locales/es.json
+++ b/frontend/src/locales/es.json
@@ -2072,6 +2072,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/fr.json b/frontend/src/locales/fr.json
index 903598ad..dbd2bce7 100644
--- a/frontend/src/locales/fr.json
+++ b/frontend/src/locales/fr.json
@@ -2072,6 +2072,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/hi.json b/frontend/src/locales/hi.json
index be043e30..d203a845 100644
--- a/frontend/src/locales/hi.json
+++ b/frontend/src/locales/hi.json
@@ -2068,6 +2068,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/it.json b/frontend/src/locales/it.json
index 916db87f..52b51cf4 100644
--- a/frontend/src/locales/it.json
+++ b/frontend/src/locales/it.json
@@ -2072,6 +2072,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/ja.json b/frontend/src/locales/ja.json
index cbacd44f..7eae6272 100644
--- a/frontend/src/locales/ja.json
+++ b/frontend/src/locales/ja.json
@@ -2068,6 +2068,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/nl.json b/frontend/src/locales/nl.json
index 491fe40d..2a9f7635 100644
--- a/frontend/src/locales/nl.json
+++ b/frontend/src/locales/nl.json
@@ -2070,6 +2070,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "herberg",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/pl.json b/frontend/src/locales/pl.json
index 04d3eb71..b20b75ca 100644
--- a/frontend/src/locales/pl.json
+++ b/frontend/src/locales/pl.json
@@ -2163,6 +2163,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.json
index 25aed392..39148a2f 100644
--- a/frontend/src/locales/pt-BR.json
+++ b/frontend/src/locales/pt-BR.json
@@ -2072,6 +2072,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/pt-PT.json b/frontend/src/locales/pt-PT.json
index 0df8c804..47ad59b0 100644
--- a/frontend/src/locales/pt-PT.json
+++ b/frontend/src/locales/pt-PT.json
@@ -2072,6 +2072,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/ru.json b/frontend/src/locales/ru.json
index 537c06dc..883fbb9f 100644
--- a/frontend/src/locales/ru.json
+++ b/frontend/src/locales/ru.json
@@ -2085,6 +2085,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/sk.json b/frontend/src/locales/sk.json
index 32dba5c0..966a8599 100644
--- a/frontend/src/locales/sk.json
+++ b/frontend/src/locales/sk.json
@@ -2192,6 +2192,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",
diff --git a/frontend/src/locales/uk.json b/frontend/src/locales/uk.json
index 9b3b44e2..95afa408 100644
--- a/frontend/src/locales/uk.json
+++ b/frontend/src/locales/uk.json
@@ -2085,6 +2085,7 @@
"ro_cui": "CUI",
"ch_uid": "UID",
"inn": "INN",
+ "kz_biniin": "BIN/IIN",
"edrpou": "EDRPOU",
"cuit": "CUIT",
"rfc": "RFC",