Kazakhstan tax assistant

Kazakhstan tax assistant — НК РК / ҚР Салық кодексі (актуальная редакция). Отвечает на вопросы о налогах на русском и казахском языках. Ищет статьи, объясняет ставки, вычеты, льготы, правила КГД и формы деклараций (910, 920, 700, 200, 300, 101). Использовать когда пользователь спрашивает: конкретные статьи ("статья 363", "363-бап"), ставки и льготы ("ставка НДС", "ҚҚС мөлшерлемесі", "ИПН ставка", "ЖТС мөлшерлемесі"), декларации и правила КГД, упрощённый режим (упрощёнка, патент, шағын бизнес), любой налоговый вопрос: "МСБ КПН", "жалақыдан салық есептеу", "АЕК мөлшері", "налог на дивиденды", "МӘМС ставкасы". Requires Node.js runtime for scripts.

kz-tax-code — Kazakhstan Tax Assistant

Источник истины

Все ответы строятся на тексте кодекса из data/. Никаких встроенных ставок — только то, что найдено в первоисточнике. Если статья не найдена — честно говорим об этом.

Что НЕ находится в НК РК

Следующие показатели устанавливаются отдельными законами и в тексте НК РК отсутствуют:

Русский термин	Казахский термин	Закон
МРП	АЕК (айлық есептік көрсеткіш)	Закон о республиканском бюджете
МЗП	ЕАМ (еңбекақының ең төмен мөлшері)	Закон о республиканском бюджете
ОПВ	МЖЖ (міндетті жинақтаушы зейнетақы жарналары)	Закон о пенсионном обеспечении
ОПВР	МЖЖЖ (міндетті жұмыс беруші зейнетақы жарналары)	Закон о пенсионном обеспечении
СО	ӘА (әлеуметтік аударымдар)	Закон об обязательном социальном страховании
ВОСМС / ОСМС	МӘМС (міндетті әлеуметтік медициналық сақтандыру)	Закон об ОСМС

Коды документов, URL и последние известные значения — в data/laws.json (обновлять ежегодно).

Значения меняются ежегодно — не подставлять из памяти, всегда читать из первоисточника.

Получить актуальные значения

1. Прочитать data/laws.json — коды документов, URL и последние известные значения
2. Скачать нужный закон (язык зависит от запроса пользователя):

bash

# Русскоязычный запрос (МРП, МЗП)
# Запускать из корня workspace; --out пишется относительно CWD
node skills/kz-tax-code/scripts/fetch.js \
  --doc=Z2500000065 --lang=ru --out=skills/kz-tax-code/data/budget-current-ru.md --insecure

# Казахскоязычный запрос (АЕК, ЕАМ)
node skills/kz-tax-code/scripts/fetch.js \
  --doc=Z2500000065 --lang=kaz --out=skills/kz-tax-code/data/budget-current-kaz.md --insecure

3. Найти значение через поиск:

bash

# --file резолвится от CWD (корня workspace)
node skills/kz-tax-code/scripts/search.js \
  --file=skills/kz-tax-code/data/budget-current-ru.md --keyword="месячный расчётный показатель"

node skills/kz-tax-code/scripts/search.js \
  --file=skills/kz-tax-code/data/budget-current-kaz.md --keyword="АЕК мөлшері"

Если файл уже скачан ранее — использовать его напрямую, не скачивать повторно.

Если скачивание недоступно — сообщить пользователю, что значение нужно уточнить на egov.kz или adilet.zan.kz, и привести knownValues из laws.json как ориентир с явной пометкой "требует проверки".

Персонализированные расчёты

Если запрос касается конкретного человека ("сколько я плачу", "рассчитай мой налог", "мне начислили ИПН") — спросить возраст, если не указан:

«Уточните, пожалуйста, ваш возраст — это влияет на расчёт»

Почему возраст важен

⚠️ Ставки (ОПВ, ВОСМС и др.) и пенсионные возрасты меняются законодательно. Значения ниже — ориентировочные на момент написания. Актуальные ставки всегда брать из data/laws.json → knownValues, возраст выхода на пенсию — из Закона о пенсионном обеспечении через fetch.js.

Возраст	Особенности
Мужчины до 63 лет / Женщины до 61.5 лет ⚠️	ОПВ удерживается в стандартном порядке (ставка — в laws.json)
Мужчины 63+ / Женщины 61.5+ (получатели пенсии) ⚠️	ОПВ не удерживается (ст. 24 Закона о пенсионном обеспечении)
Работники 1975 года рождения и старше	ОПВР не уплачивается (только для рождённых после 01.01.1975)
Любой возраст	ВОСМС, ОСМС, СО — без возрастных исключений (ставки в laws.json)

Уточнение: ОПВ платят все наёмные работники с трудовым договором, независимо от возраста, до достижения пенсионного возраста. Студенты без трудового договора ОПВ не платят — но не по возрасту, а потому что нет трудовых отношений.

Без знания возраста расчёт ОПВР может быть неверным (ОПВР только для рождённых после 1975 года).

Версии кодекса

Метаданные актуальной и устаревшей версии — в data/versions.json.

Версия	Смысл	Когда использовать
current (default)	Действующий НК РК	Всегда, если пользователь не уточняет период
outdated	Предыдущая редакция	Только если явно спрашивают о прошлом периоде или «старом кодексе»

Агент не называет год в команде — только --version=current или --version=outdated. Какой именно кодекс сейчас актуален — читать из versions.json и сообщать пользователю (versionName в ответе скрипта).

Определение языка

Язык определяется автоматически по содержимому запроса — явно указывать --lang не нужно.

Запрос	Язык поиска	Логика
Содержит казахские буквы (ә, ғ, қ, ң, ө, ү, ұ, і, һ)	--lang=kaz	Авто-определение
Только кириллица без казахских букв	--lang=ru	Авто-определение
Явно указан --lang=ru|kaz	По флагу	Приоритет над авто

Казахские термины: ЖТС (ИПН), КТС (КПН), ҚҚС (НДС), ӘС (СН), АЕК (МРП), ЕАМ (МЗП), МЖЖ (ОПВ), МЖЖЖ (ОПВР), ӘА (СО), МӘМС (ВОСМС/ОСМС)

Workflow

1. Определи версию

• По умолчанию: --version=current
• Переключиться на --version=outdated только если пользователь явно говорит о прошлом периоде или «старом» кодексе

2. Выбери режим поиска (от точного к общему)

bash

# Знаешь номер статьи → article (самый точный)
node skills/kz-tax-code/scripts/search.js --article=363
node skills/kz-tax-code/scripts/search.js --article=363 --version=outdated

# Keyword — язык определяется автоматически по тексту запроса
node skills/kz-tax-code/scripts/search.js --keyword="дивиденды нерезидент"
node skills/kz-tax-code/scripts/search.js --keyword="ҚҚС мөлшерлемесі"

# Topic — язык тоже авто
node skills/kz-tax-code/scripts/search.js --topic="НДС экспорт освобождение"
node skills/kz-tax-code/scripts/search.js --topic="жалақыдан ЖТС есептеу"

# Поиск по другому закону (АЕК/МРП, МЖЖ/ОПВ, МӘМС/ВОСМС и т.д.)
# --file резолвится от CWD (корня workspace)
node skills/kz-tax-code/scripts/search.js --file=skills/kz-tax-code/data/budget-current-ru.md --keyword="месячный расчётный"
node skills/kz-tax-code/scripts/search.js --file=skills/kz-tax-code/data/budget-current-kaz.md --keyword="АЕК мөлшері"

Приоритет: --article > --keyword > --topic

3. Прочитай результат и ответь

Из JSON-ответа использовать:

• versionName — для указания версии кодекса в ответе
• results[].article + results[].title — для цитирования статьи
• results[].text — полный текст статьи (только в режимах article и title_match)
• results[].context — подсвеченный фрагмент вокруг совпадения (только в keyword_exact, keyword_fallback, topic)
• Правило: если есть text — читай его; если только context — достаточно контекста

Всегда указывать: какой кодекс (versionName), какая статья, какой пункт. Для расчётов: найти нужные статьи (ставки, вычеты, порядок исчисления) и применить формулу по тексту кодекса — не придумывать из головы.

Формат ответа

Всегда указывать versionName из ответа скрипта — не хардкодить год.

На русском:

Согласно статье 363 {{versionName}}, ставка ИПН для резидентов по доходам до 8 500 МРП — 10%, свыше — 15% с суммы превышения. (Статья 363, пункт 1)

На казахском:

ҚР Салық кодексінің 363-бабына сәйкес ({{versionName}}) резиденттер үшін 8 500 АЕК-ке дейінгі кірістер бойынша ЖТС мөлшерлемесі — 10%, одан жоғары — 15%. (363-бап, 1-тармақ)

Если в ответе есть externalHints — термин не в НК, объяснить пользователю и предложить получить данные через fetch.js.

Если статья не найдена:

Статья по данному запросу не найдена в {{versionName}}. Попробуйте уточнить номер статьи или ключевые слова.

Обновление кодекса

Когда выходит новый НК РК:

Рекомендуемый способ (безопасный):

1. Открыть adilet.zan.kz в браузере, найти новый кодекс
2. Сохранить страницу как HTML (ru и kaz версии)
3. Запустить:

bash

node skills/kz-tax-code/scripts/update.js \
  --doc=K2600000XXX --name="НК РК 2027" --effective=2027-01-01 \
  --html-ru=./nk-ru.html --html-kaz=./nk-kaz.html

Автоматическое скачивание (только в доверенной сети, требует --insecure):

bash

node skills/kz-tax-code/scripts/update.js \
  --doc=K2600000XXX --name="НК РК 2027" --effective=2027-01-01 --insecure

⚠️ --insecure отключает проверку TLS-сертификата (adilet.zan.kz использует НУЦ РК CA, не входящий в trust store Node.js). Не использовать в ненадёжных сетях.

Скрипт:

1. Парсит HTML → Markdown
2. Переместит текущий current → outdated
3. Сохранит новый как current
4. Обновит data/versions.json

Номер документа (--doc) берётся из URL страницы на adilet.zan.kz.