| Name | kat-bulgaria JSON |
| Version |
3.2.0
JSON |
| download |
| home_page | None |
| Summary | A library to check for existing obligations from KAT Bulgaria |
| upload_time | 2025-07-19 09:30:55 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT |
| keywords |
kat
mvr
bulgaria
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
httpx
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## KAT България - Python пакет за програмна проверка за задължения към КАТ
[](https://pypi.org/project/kat-bulgaria/)
[](https://sonarcloud.io/summary/overall?id=Nedevski_py_kat_bulgaria&branch=master)
Този пакет позволява да се извършват лесни програмни проверки за налични глоби към [МВР](https://e-uslugi.mvr.bg/services/kat-obligations).
Цялата библиотека е обикновен wrapper около официалната система. Библиотеката **НЕ** запазва или логва вашите данни никъде. Данните са директно предадени на системата на МВР
Причината да създам този пакет е че системата на МВР понякога е нестабилна и хвърля различни видове грешки и timeouts. С негова помощ се стандартизират и валидират отговорите от системата и се извличат данни във формат, готов за употреба, или в случай на грешки - биват извлечени категорияи на грешката и смислено съобщение за грешка.
---
Ако харесвате работата ми, почерпете ме с 1 бира в Ko-Fi:
[](https://ko-fi.com/nedevski/tip)
---
## Инсталиране
```shell
pip install kat_bulgaria
```
## Примерен скрипт:
Добавил съм примерен работещ скрипт в репото - [`sample_usage_script.py`](sample_usage_script.py).
Преди да се изпълни скрипта, обновете примерните данни с реални ваши такива.
```python
# Проверка за физически лица - лична карта:
obligations = await KatApiClient().get_obligations_individual(
egn="валидно_егн",
identifier_type=PersonalDocumentType.NATIONAL_ID,
identifier="номер_лична_карта"
)
print(f"Брой задължения - ФЛ/ЛК: {len(obligations)}\n")
print(f"Raw JSON: {obligations}\n")
```
```python
# Проверка за физически лица - шофьорска книжка:
obligations = await KatApiClient().get_obligations_individual(
egn="валидно_егн",
identifier_type=PersonalDocumentType.DRIVING_LICENSE,
identifier="номер_шофьорска_книжка"
)
print(f"Брой задължения - ФЛ/ШК: {len(obligations)}\n")
print(f"Raw JSON: {obligations}\n")
```
```python
# Проверка за юридически лица - лична карта:
obligations = await KatApiClient().get_obligations_business(
egn="валидно_егн",
govt_id="номер_лична_карта",
bulstat="валиден_булстат"
)
print(f"Брой задължения - ЮЛ: {len(obligations)}\n")
print(f"Raw JSON: {obligations}\n")
```
## API отговори:
Примерни API отговори може да бъдат намерени в `/tests/fixtures`.
Старая се да документирам всички API отговори до които имам достъп в [това issue](https://github.com/Nedevski/py_kat_bulgaria/issues/2) с набавяне на по-голям сет тестови данни.
Ако някой има активни глоби, бих се радвал да получа целия JSON отговор от системата на МВР. Можете да го добавите в коментар в issue-то линкнато по-горе.
Можете да си набавите JSON-а, като копирате адреса отдолу и замените `EGN_GOES_HERE` и `LICENSE_GOES_HERE` с вашите ЕГН и номер на шофьорска книжка.
https://e-uslugi.mvr.bg/api/Obligations/AND?obligatedPersonType=1&additinalDataForObligatedPersonType=1&mode=1&obligedPersonIdent=EGN_GOES_HERE&drivingLicenceNumber=LICENSE_GOES_HERE
Силно препоръчително е преди публикуване да заредите JSON-a в тесктов едитор и да редактирате всички ваши лични данни в него.
Raw data
{
"_id": null,
"home_page": null,
"name": "kat-bulgaria",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "kat, mvr, bulgaria",
"author": null,
"author_email": "Nikola Nedevski <nikola.nedevski@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/89/6b/cb8c6a96efbab2aee1b3bb83e0fcddabd7690e0bf674e36d432ef82739df/kat_bulgaria-3.2.0.tar.gz",
"platform": null,
"description": "## KAT \u0411\u044a\u043b\u0433\u0430\u0440\u0438\u044f - Python \u043f\u0430\u043a\u0435\u0442 \u0437\u0430 \u043f\u0440\u043e\u0433\u0440\u0430\u043c\u043d\u0430 \u043f\u0440\u043e\u0432\u0435\u0440\u043a\u0430 \u0437\u0430 \u0437\u0430\u0434\u044a\u043b\u0436\u0435\u043d\u0438\u044f \u043a\u044a\u043c \u041a\u0410\u0422\n\n[](https://pypi.org/project/kat-bulgaria/)\n\n\n\n[](https://sonarcloud.io/summary/overall?id=Nedevski_py_kat_bulgaria&branch=master)\n\n\n\u0422\u043e\u0437\u0438 \u043f\u0430\u043a\u0435\u0442 \u043f\u043e\u0437\u0432\u043e\u043b\u044f\u0432\u0430 \u0434\u0430 \u0441\u0435 \u0438\u0437\u0432\u044a\u0440\u0448\u0432\u0430\u0442 \u043b\u0435\u0441\u043d\u0438 \u043f\u0440\u043e\u0433\u0440\u0430\u043c\u043d\u0438 \u043f\u0440\u043e\u0432\u0435\u0440\u043a\u0438 \u0437\u0430 \u043d\u0430\u043b\u0438\u0447\u043d\u0438 \u0433\u043b\u043e\u0431\u0438 \u043a\u044a\u043c [\u041c\u0412\u0420](https://e-uslugi.mvr.bg/services/kat-obligations).\n\n\u0426\u044f\u043b\u0430\u0442\u0430 \u0431\u0438\u0431\u043b\u0438\u043e\u0442\u0435\u043a\u0430 \u0435 \u043e\u0431\u0438\u043a\u043d\u043e\u0432\u0435\u043d wrapper \u043e\u043a\u043e\u043b\u043e \u043e\u0444\u0438\u0446\u0438\u0430\u043b\u043d\u0430\u0442\u0430 \u0441\u0438\u0441\u0442\u0435\u043c\u0430. \u0411\u0438\u0431\u043b\u0438\u043e\u0442\u0435\u043a\u0430\u0442\u0430 **\u041d\u0415** \u0437\u0430\u043f\u0430\u0437\u0432\u0430 \u0438\u043b\u0438 \u043b\u043e\u0433\u0432\u0430 \u0432\u0430\u0448\u0438\u0442\u0435 \u0434\u0430\u043d\u043d\u0438 \u043d\u0438\u043a\u044a\u0434\u0435. \u0414\u0430\u043d\u043d\u0438\u0442\u0435 \u0441\u0430 \u0434\u0438\u0440\u0435\u043a\u0442\u043d\u043e \u043f\u0440\u0435\u0434\u0430\u0434\u0435\u043d\u0438 \u043d\u0430 \u0441\u0438\u0441\u0442\u0435\u043c\u0430\u0442\u0430 \u043d\u0430 \u041c\u0412\u0420\n\n\u041f\u0440\u0438\u0447\u0438\u043d\u0430\u0442\u0430 \u0434\u0430 \u0441\u044a\u0437\u0434\u0430\u043c \u0442\u043e\u0437\u0438 \u043f\u0430\u043a\u0435\u0442 \u0435 \u0447\u0435 \u0441\u0438\u0441\u0442\u0435\u043c\u0430\u0442\u0430 \u043d\u0430 \u041c\u0412\u0420 \u043f\u043e\u043d\u044f\u043a\u043e\u0433\u0430 \u0435 \u043d\u0435\u0441\u0442\u0430\u0431\u0438\u043b\u043d\u0430 \u0438 \u0445\u0432\u044a\u0440\u043b\u044f \u0440\u0430\u0437\u043b\u0438\u0447\u043d\u0438 \u0432\u0438\u0434\u043e\u0432\u0435 \u0433\u0440\u0435\u0448\u043a\u0438 \u0438 timeouts. \u0421 \u043d\u0435\u0433\u043e\u0432\u0430 \u043f\u043e\u043c\u043e\u0449 \u0441\u0435 \u0441\u0442\u0430\u043d\u0434\u0430\u0440\u0442\u0438\u0437\u0438\u0440\u0430\u0442 \u0438 \u0432\u0430\u043b\u0438\u0434\u0438\u0440\u0430\u0442 \u043e\u0442\u0433\u043e\u0432\u043e\u0440\u0438\u0442\u0435 \u043e\u0442 \u0441\u0438\u0441\u0442\u0435\u043c\u0430\u0442\u0430 \u0438 \u0441\u0435 \u0438\u0437\u0432\u043b\u0438\u0447\u0430\u0442 \u0434\u0430\u043d\u043d\u0438 \u0432\u044a\u0432 \u0444\u043e\u0440\u043c\u0430\u0442, \u0433\u043e\u0442\u043e\u0432 \u0437\u0430 \u0443\u043f\u043e\u0442\u0440\u0435\u0431\u0430, \u0438\u043b\u0438 \u0432 \u0441\u043b\u0443\u0447\u0430\u0439 \u043d\u0430 \u0433\u0440\u0435\u0448\u043a\u0438 - \u0431\u0438\u0432\u0430\u0442 \u0438\u0437\u0432\u043b\u0435\u0447\u0435\u043d\u0438 \u043a\u0430\u0442\u0435\u0433\u043e\u0440\u0438\u044f\u0438 \u043d\u0430 \u0433\u0440\u0435\u0448\u043a\u0430\u0442\u0430 \u0438 \u0441\u043c\u0438\u0441\u043b\u0435\u043d\u043e \u0441\u044a\u043e\u0431\u0449\u0435\u043d\u0438\u0435 \u0437\u0430 \u0433\u0440\u0435\u0448\u043a\u0430.\n\n---\n\n\u0410\u043a\u043e \u0445\u0430\u0440\u0435\u0441\u0432\u0430\u0442\u0435 \u0440\u0430\u0431\u043e\u0442\u0430\u0442\u0430 \u043c\u0438, \u043f\u043e\u0447\u0435\u0440\u043f\u0435\u0442\u0435 \u043c\u0435 \u0441 1 \u0431\u0438\u0440\u0430 \u0432 Ko-Fi:\n\n[](https://ko-fi.com/nedevski/tip)\n\n---\n\n## \u0418\u043d\u0441\u0442\u0430\u043b\u0438\u0440\u0430\u043d\u0435\n\n```shell\npip install kat_bulgaria\n```\n\n## \u041f\u0440\u0438\u043c\u0435\u0440\u0435\u043d \u0441\u043a\u0440\u0438\u043f\u0442:\n\n\u0414\u043e\u0431\u0430\u0432\u0438\u043b \u0441\u044a\u043c \u043f\u0440\u0438\u043c\u0435\u0440\u0435\u043d \u0440\u0430\u0431\u043e\u0442\u0435\u0449 \u0441\u043a\u0440\u0438\u043f\u0442 \u0432 \u0440\u0435\u043f\u043e\u0442\u043e - [`sample_usage_script.py`](sample_usage_script.py).\n\n\u041f\u0440\u0435\u0434\u0438 \u0434\u0430 \u0441\u0435 \u0438\u0437\u043f\u044a\u043b\u043d\u0438 \u0441\u043a\u0440\u0438\u043f\u0442\u0430, \u043e\u0431\u043d\u043e\u0432\u0435\u0442\u0435 \u043f\u0440\u0438\u043c\u0435\u0440\u043d\u0438\u0442\u0435 \u0434\u0430\u043d\u043d\u0438 \u0441 \u0440\u0435\u0430\u043b\u043d\u0438 \u0432\u0430\u0448\u0438 \u0442\u0430\u043a\u0438\u0432\u0430.\n\n```python\n# \u041f\u0440\u043e\u0432\u0435\u0440\u043a\u0430 \u0437\u0430 \u0444\u0438\u0437\u0438\u0447\u0435\u0441\u043a\u0438 \u043b\u0438\u0446\u0430 - \u043b\u0438\u0447\u043d\u0430 \u043a\u0430\u0440\u0442\u0430:\nobligations = await KatApiClient().get_obligations_individual(\n egn=\"\u0432\u0430\u043b\u0438\u0434\u043d\u043e_\u0435\u0433\u043d\",\n identifier_type=PersonalDocumentType.NATIONAL_ID,\n identifier=\"\u043d\u043e\u043c\u0435\u0440_\u043b\u0438\u0447\u043d\u0430_\u043a\u0430\u0440\u0442\u0430\"\n)\nprint(f\"\u0411\u0440\u043e\u0439 \u0437\u0430\u0434\u044a\u043b\u0436\u0435\u043d\u0438\u044f - \u0424\u041b/\u041b\u041a: {len(obligations)}\\n\")\nprint(f\"Raw JSON: {obligations}\\n\")\n```\n\n```python\n# \u041f\u0440\u043e\u0432\u0435\u0440\u043a\u0430 \u0437\u0430 \u0444\u0438\u0437\u0438\u0447\u0435\u0441\u043a\u0438 \u043b\u0438\u0446\u0430 - \u0448\u043e\u0444\u044c\u043e\u0440\u0441\u043a\u0430 \u043a\u043d\u0438\u0436\u043a\u0430:\nobligations = await KatApiClient().get_obligations_individual(\n egn=\"\u0432\u0430\u043b\u0438\u0434\u043d\u043e_\u0435\u0433\u043d\",\n identifier_type=PersonalDocumentType.DRIVING_LICENSE,\n identifier=\"\u043d\u043e\u043c\u0435\u0440_\u0448\u043e\u0444\u044c\u043e\u0440\u0441\u043a\u0430_\u043a\u043d\u0438\u0436\u043a\u0430\"\n)\nprint(f\"\u0411\u0440\u043e\u0439 \u0437\u0430\u0434\u044a\u043b\u0436\u0435\u043d\u0438\u044f - \u0424\u041b/\u0428\u041a: {len(obligations)}\\n\")\nprint(f\"Raw JSON: {obligations}\\n\")\n```\n\n```python\n# \u041f\u0440\u043e\u0432\u0435\u0440\u043a\u0430 \u0437\u0430 \u044e\u0440\u0438\u0434\u0438\u0447\u0435\u0441\u043a\u0438 \u043b\u0438\u0446\u0430 - \u043b\u0438\u0447\u043d\u0430 \u043a\u0430\u0440\u0442\u0430:\nobligations = await KatApiClient().get_obligations_business(\n egn=\"\u0432\u0430\u043b\u0438\u0434\u043d\u043e_\u0435\u0433\u043d\",\n govt_id=\"\u043d\u043e\u043c\u0435\u0440_\u043b\u0438\u0447\u043d\u0430_\u043a\u0430\u0440\u0442\u0430\",\n bulstat=\"\u0432\u0430\u043b\u0438\u0434\u0435\u043d_\u0431\u0443\u043b\u0441\u0442\u0430\u0442\"\n)\nprint(f\"\u0411\u0440\u043e\u0439 \u0437\u0430\u0434\u044a\u043b\u0436\u0435\u043d\u0438\u044f - \u042e\u041b: {len(obligations)}\\n\")\nprint(f\"Raw JSON: {obligations}\\n\")\n```\n\n## API \u043e\u0442\u0433\u043e\u0432\u043e\u0440\u0438:\n\n\u041f\u0440\u0438\u043c\u0435\u0440\u043d\u0438 API \u043e\u0442\u0433\u043e\u0432\u043e\u0440\u0438 \u043c\u043e\u0436\u0435 \u0434\u0430 \u0431\u044a\u0434\u0430\u0442 \u043d\u0430\u043c\u0435\u0440\u0435\u043d\u0438 \u0432 `/tests/fixtures`.\n\n\u0421\u0442\u0430\u0440\u0430\u044f \u0441\u0435 \u0434\u0430 \u0434\u043e\u043a\u0443\u043c\u0435\u043d\u0442\u0438\u0440\u0430\u043c \u0432\u0441\u0438\u0447\u043a\u0438 API \u043e\u0442\u0433\u043e\u0432\u043e\u0440\u0438 \u0434\u043e \u043a\u043e\u0438\u0442\u043e \u0438\u043c\u0430\u043c \u0434\u043e\u0441\u0442\u044a\u043f \u0432 [\u0442\u043e\u0432\u0430 issue](https://github.com/Nedevski/py_kat_bulgaria/issues/2) \u0441 \u043d\u0430\u0431\u0430\u0432\u044f\u043d\u0435 \u043d\u0430 \u043f\u043e-\u0433\u043e\u043b\u044f\u043c \u0441\u0435\u0442 \u0442\u0435\u0441\u0442\u043e\u0432\u0438 \u0434\u0430\u043d\u043d\u0438.\n\n\u0410\u043a\u043e \u043d\u044f\u043a\u043e\u0439 \u0438\u043c\u0430 \u0430\u043a\u0442\u0438\u0432\u043d\u0438 \u0433\u043b\u043e\u0431\u0438, \u0431\u0438\u0445 \u0441\u0435 \u0440\u0430\u0434\u0432\u0430\u043b \u0434\u0430 \u043f\u043e\u043b\u0443\u0447\u0430 \u0446\u0435\u043b\u0438\u044f JSON \u043e\u0442\u0433\u043e\u0432\u043e\u0440 \u043e\u0442 \u0441\u0438\u0441\u0442\u0435\u043c\u0430\u0442\u0430 \u043d\u0430 \u041c\u0412\u0420. \u041c\u043e\u0436\u0435\u0442\u0435 \u0434\u0430 \u0433\u043e \u0434\u043e\u0431\u0430\u0432\u0438\u0442\u0435 \u0432 \u043a\u043e\u043c\u0435\u043d\u0442\u0430\u0440 \u0432 issue-\u0442\u043e \u043b\u0438\u043d\u043a\u043d\u0430\u0442\u043e \u043f\u043e-\u0433\u043e\u0440\u0435.\n\n\u041c\u043e\u0436\u0435\u0442\u0435 \u0434\u0430 \u0441\u0438 \u043d\u0430\u0431\u0430\u0432\u0438\u0442\u0435 JSON-\u0430, \u043a\u0430\u0442\u043e \u043a\u043e\u043f\u0438\u0440\u0430\u0442\u0435 \u0430\u0434\u0440\u0435\u0441\u0430 \u043e\u0442\u0434\u043e\u043b\u0443 \u0438 \u0437\u0430\u043c\u0435\u043d\u0438\u0442\u0435 `EGN_GOES_HERE` \u0438 `LICENSE_GOES_HERE` \u0441 \u0432\u0430\u0448\u0438\u0442\u0435 \u0415\u0413\u041d \u0438 \u043d\u043e\u043c\u0435\u0440 \u043d\u0430 \u0448\u043e\u0444\u044c\u043e\u0440\u0441\u043a\u0430 \u043a\u043d\u0438\u0436\u043a\u0430.\n\nhttps://e-uslugi.mvr.bg/api/Obligations/AND?obligatedPersonType=1&additinalDataForObligatedPersonType=1&mode=1&obligedPersonIdent=EGN_GOES_HERE&drivingLicenceNumber=LICENSE_GOES_HERE\n\n\u0421\u0438\u043b\u043d\u043e \u043f\u0440\u0435\u043f\u043e\u0440\u044a\u0447\u0438\u0442\u0435\u043b\u043d\u043e \u0435 \u043f\u0440\u0435\u0434\u0438 \u043f\u0443\u0431\u043b\u0438\u043a\u0443\u0432\u0430\u043d\u0435 \u0434\u0430 \u0437\u0430\u0440\u0435\u0434\u0438\u0442\u0435 JSON-a \u0432 \u0442\u0435\u0441\u043a\u0442\u043e\u0432 \u0435\u0434\u0438\u0442\u043e\u0440 \u0438 \u0434\u0430 \u0440\u0435\u0434\u0430\u043a\u0442\u0438\u0440\u0430\u0442\u0435 \u0432\u0441\u0438\u0447\u043a\u0438 \u0432\u0430\u0448\u0438 \u043b\u0438\u0447\u043d\u0438 \u0434\u0430\u043d\u043d\u0438 \u0432 \u043d\u0435\u0433\u043e.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A library to check for existing obligations from KAT Bulgaria",
"version": "3.2.0",
"project_urls": {
"Donate": "https://ko-fi.com/nedevski/tip",
"Homepage": "https://github.com/Nedevski/py_kat_bulgaria",
"Issues": "https://github.com/Nedevski/py_kat_bulgaria/issues",
"Repository": "https://github.com/Nedevski/py_kat_bulgaria.git"
},
"split_keywords": [
"kat",
" mvr",
" bulgaria"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0d9f2bd37f2ecfc76bdfbe93ca1c9c1967ebfef917aa7beb4d619807cc50321e",
"md5": "6eadb4b58a0a73b4dc2899e2f0836829",
"sha256": "0ca84eda74dd429c0f15cb67123dc0eb3fb156e3cd25fbd433eddb889f59a8fe"
},
"downloads": -1,
"filename": "kat_bulgaria-3.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6eadb4b58a0a73b4dc2899e2f0836829",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 8899,
"upload_time": "2025-07-19T09:30:53",
"upload_time_iso_8601": "2025-07-19T09:30:53.783351Z",
"url": "https://files.pythonhosted.org/packages/0d/9f/2bd37f2ecfc76bdfbe93ca1c9c1967ebfef917aa7beb4d619807cc50321e/kat_bulgaria-3.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "896bcb8c6a96efbab2aee1b3bb83e0fcddabd7690e0bf674e36d432ef82739df",
"md5": "63df6a632794cc4794b3c12d2f53b572",
"sha256": "c71e4a4f316341487c1a6c81703cfab8979efbc78c888892d4990ab3aa408943"
},
"downloads": -1,
"filename": "kat_bulgaria-3.2.0.tar.gz",
"has_sig": false,
"md5_digest": "63df6a632794cc4794b3c12d2f53b572",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 11409,
"upload_time": "2025-07-19T09:30:55",
"upload_time_iso_8601": "2025-07-19T09:30:55.215535Z",
"url": "https://files.pythonhosted.org/packages/89/6b/cb8c6a96efbab2aee1b3bb83e0fcddabd7690e0bf674e36d432ef82739df/kat_bulgaria-3.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 09:30:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Nedevski",
"github_project": "py_kat_bulgaria",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "httpx",
"specs": [
[
">=",
"0.28.1"
]
]
}
],
"lcname": "kat-bulgaria"
}
