nalogovich 1.0.0__tar.gz

nalogovich-1.0.0/.github/workflows/ci-cd.yml

@@ -0,0 +1,50 @@
+name: CI & CD
+
+on:
+  push:
+    branches: [ main ]
+    tags: [ 'v*' ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Ruff
+        run: pip install ruff
+
+      - name: Run Ruff check
+        run: ruff check .
+
+      - name: Run Ruff format check
+        run: ruff format --check .
+
+  publish:
+    name: Publish to PyPI
+    needs: lint
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.8"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

nalogovich-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

nalogovich-1.0.0/.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+mkdocs:
+   configuration: mkdocs.yml
+
+python:
+   install:
+   - requirements: docs/requirements.txt
+

nalogovich-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ramedon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nalogovich-1.0.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: nalogovich
+Version: 1.0.0
+Summary: Wrapper for integration with the 'Мой налог' API service
+Author-email: Ramedon <info@ramed.one>
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.13.2
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-dateutil>=2.9.0.post0
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Requires-Dist: ruff>=0.1.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# Nalogovich
+### Асинхронная Python библиотека (SDK) для API "Мой Налог" (ЛК НПД)
+
+[![PyPI version](https://img.shields.io/pypi/v/nalogovich.svg)](https://pypi.org/project/nalogovich/)
+[![Python versions](https://img.shields.io/pypi/pyversions/nalogovich.svg)](https://pypi.org/project/nalogovich/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CodeFactor](https://www.codefactor.io/repository/github/ramedon1/nalogovich/badge)](https://www.codefactor.io/repository/github/ramedon1/nalogovich)
+
+**Nalogovich** - библиотека для интеграции с сервисом "Мой Налог". Идеально подходит для автоматизации отчетности самозанятых, создания платежных ботов в Telegram или CRM-систем.
+
+[Документация](https://nalogovich.readthedocs.io/ru/latest/) | [Сообщить об ошибке](https://github.com/Ramedon1/nalogovich/issues)
+
+---
+## 📦 Установка
+
+```bash
+pip install nalogovich
+```
+Или через современный менеджер пакетов [uv](https://github.com/astral-sh/uv):
+```bash
+uv add nalogovich
+```
+
+## 🚀 Быстрый старт
+
+Создание чека за 1 минуту:
+
+```python
+import asyncio
+from nalogovich.lknpd import NpdClient
+
+async def main():
+    async with NpdClient(inn="123456789012", password="your_password") as client:
+        await client.auth()
+        
+        # Создаем новый чек
+        receipt = await client.create_ticket(
+            name="Консультационные услуги",
+            amount=1500,
+            quantity=1
+        )
+        
+        print(f"Чек создан! URL: {receipt.url}")
+        
+        # Получаем список последних операций
+        checks = await client.get_checks(limit=5)
+        print(f"Последние операции: {len(checks.content)}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```

nalogovich-1.0.0/README.md

@@ -0,0 +1,51 @@
+# Nalogovich
+### Асинхронная Python библиотека (SDK) для API "Мой Налог" (ЛК НПД)
+
+[![PyPI version](https://img.shields.io/pypi/v/nalogovich.svg)](https://pypi.org/project/nalogovich/)
+[![Python versions](https://img.shields.io/pypi/pyversions/nalogovich.svg)](https://pypi.org/project/nalogovich/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CodeFactor](https://www.codefactor.io/repository/github/ramedon1/nalogovich/badge)](https://www.codefactor.io/repository/github/ramedon1/nalogovich)
+
+**Nalogovich** - библиотека для интеграции с сервисом "Мой Налог". Идеально подходит для автоматизации отчетности самозанятых, создания платежных ботов в Telegram или CRM-систем.
+
+[Документация](https://nalogovich.readthedocs.io/ru/latest/) | [Сообщить об ошибке](https://github.com/Ramedon1/nalogovich/issues)
+
+---
+## 📦 Установка
+
+```bash
+pip install nalogovich
+```
+Или через современный менеджер пакетов [uv](https://github.com/astral-sh/uv):
+```bash
+uv add nalogovich
+```
+
+## 🚀 Быстрый старт
+
+Создание чека за 1 минуту:
+
+```python
+import asyncio
+from nalogovich.lknpd import NpdClient
+
+async def main():
+    async with NpdClient(inn="123456789012", password="your_password") as client:
+        await client.auth()
+        
+        # Создаем новый чек
+        receipt = await client.create_ticket(
+            name="Консультационные услуги",
+            amount=1500,
+            quantity=1
+        )
+        
+        print(f"Чек создан! URL: {receipt.url}")
+        
+        # Получаем список последних операций
+        checks = await client.get_checks(limit=5)
+        print(f"Последние операции: {len(checks.content)}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```

nalogovich-1.0.0/docs/api/client.md

@@ -0,0 +1,70 @@
+# NpdClient
+
+**`NpdClient`** — основной класс для взаимодействия с API "Мой Налог" (lknpd.nalog.ru).
+
+Класс предоставляет асинхронный интерфейс для:
+
+- 🔐 Авторизации и управления сессией
+- 🧾 Создания и управления чеками
+- 💰 Работы со счетами на оплату  
+- 📊 Получения статистики и истории операций
+
+---
+
+## Быстрый старт
+
+```python
+from nalogovich import NpdClient
+
+async with NpdClient(inn="ваш_инн", password="ваш_пароль") as client:
+    # Авторизация
+    await client.auth()
+    
+    # Создание чека
+    income = await client.create_check(
+        name="Консультация",
+        amount=5000.00
+    )
+    print(f"Чек создан: {income.receipt_id}")
+```
+
+---
+
+## Основные группы методов
+
+### 🔐 Авторизация
+- [`auth()`](#nalogovich.lknpd.NpdClient.auth) — авторизация через ЛК ФЛ
+- [`re_auth()`](#nalogovich.lknpd.NpdClient.re_auth) — обновление токена
+
+### 🧾 Работа с чеками
+- [`create_check()`](#nalogovich.lknpd.NpdClient.create_check) — создание чека (регистрация дохода)
+- [`cancel_check()`](#nalogovich.lknpd.NpdClient.cancel_check) — аннулирование чека
+- [`get_checks()`](#nalogovich.lknpd.NpdClient.get_checks) — получение списка чеков
+- [`create_check_from_bill()`](#nalogovich.lknpd.NpdClient.create_check_from_bill) — создание чека из оплаченного счёта
+
+### 💰 Работа со счетами
+- [`create_bill()`](#nalogovich.lknpd.NpdClient.create_bill) — создание счёта на оплату
+- [`get_bills()`](#nalogovich.lknpd.NpdClient.get_bills) — получение списка счетов
+- [`approve_bill()`](#nalogovich.lknpd.NpdClient.approve_bill) — подтверждение оплаты счёта
+- [`cancel_bill()`](#nalogovich.lknpd.NpdClient.cancel_bill) — аннулирование счёта
+- [`update_bill_payment_info()`](#nalogovich.lknpd.NpdClient.update_bill_payment_info) — обновление платёжной информации счёта
+
+### 📊 Дополнительно
+- [`get_payment_types()`](#nalogovich.lknpd.NpdClient.get_payment_types) — список реквизитов для оплаты
+
+---
+
+## Справочник методов
+
+::: nalogovich.lknpd.NpdClient
+    options:
+      show_root_heading: false
+      show_source: false
+      heading_level: 3
+      members_order: source
+      group_by_category: true
+      show_category_heading: true
+      show_signature_annotations: true
+      separate_signature: true
+      merge_init_into_class: true
+      docstring_section_style: list

nalogovich-1.0.0/docs/api/enums.md

@@ -0,0 +1,266 @@
+# Перечисления (Enums)
+
+Все перечисления используются для указания типов, статусов и других параметров.
+
+---
+
+## PaymentType
+
+Тип оплаты при создании чека.
+
+::: nalogovich.enums.PaymentType
+    options:
+      show_root_heading: false
+      heading_level: 4
+      show_docstring_description: false
+
+**Значения:**
+
+- `CASH` — наличный расчёт или оплата картой
+- `ACCOUNT` — безналичный расчёт (на счёт)
+
+**Пример:**
+
+```python
+from nalogovich.enums import PaymentType
+
+income = await client.create_check(
+    name="Консультация",
+    amount=5000.00,
+    payment_type=PaymentType.CASH
+)
+```
+
+---
+
+## SortBy
+
+Параметры сортировки для списка чеков.
+
+::: nalogovich.enums.SortBy
+    options:
+      show_root_heading: false
+      heading_level: 4
+      show_docstring_description: false
+
+**Значения:**
+
+- `operation_time_asc` — по дате (старые → новые)
+- `operation_time_desc` — по дате (новые → старые) ⭐ *по умолчанию*
+- `total_amount_asc` — по сумме (возрастание)
+- `total_amount_desc` — по сумме (убывание)
+
+**Пример:**
+
+```python
+from nalogovich.enums import SortBy
+
+response = await client.get_checks(
+    sort_by=SortBy.total_amount_desc
+)
+```
+
+---
+
+## ReceiptType
+
+Тип чека при фильтрации.
+
+::: nalogovich.enums.ReceiptType
+    options:
+      show_root_heading: false
+      heading_level: 4
+      show_docstring_description: false
+
+**Значения:**
+
+- `REGISTERED` — действующие чеки
+- `CANCELLED` — аннулированные чеки
+
+**Пример:**
+
+```python
+from nalogovich.enums import ReceiptType
+
+# Только действующие чеки
+response = await client.get_checks(
+    receipt_type=ReceiptType.REGISTERED
+)
+```
+
+---
+
+## BuyerType
+
+Тип покупателя/клиента.
+
+::: nalogovich.enums.BuyerType
+    options:
+      show_root_heading: false
+      heading_level: 4
+      show_docstring_description: false
+
+**Значения:**
+
+- `PERSON` — физическое лицо
+- `COMPANY` — юридическое лицо
+- `FOREIGN_AGENCY` — иностранная организация
+
+**Пример:**
+
+```python
+from nalogovich.enums import BuyerType
+
+# Только чеки от юр. лиц
+response = await client.get_checks(
+    buyer_type=BuyerType.COMPANY
+)
+```
+
+---
+
+## CommentReturn
+
+Причина аннулирования чека.
+
+::: nalogovich.enums.CommentReturn
+    options:
+      show_root_heading: false
+      heading_level: 4
+      show_docstring_description: false
+
+**Значения:**
+
+- `wrong_receipt` — "Чек сформирован ошибочно"
+- `receipt_return` — "Чек возвращен"
+
+**Пример:**
+
+```python
+from nalogovich.enums import CommentReturn
+
+await client.cancel_check(
+    receipt_uuid="200bzznrt0",
+    comment=CommentReturn.wrong_receipt
+)
+```
+
+---
+
+## InvoicePaymentType
+
+Способ оплаты для счёта.
+
+::: nalogovich.enums.InvoicePaymentType
+    options:
+      show_root_heading: false
+      heading_level: 4
+      show_docstring_description: false
+
+**Значения:**
+
+- `PHONE` — оплата по номеру телефона (СБП)
+- `ACCOUNT` — оплата на расчётный счёт
+
+**Пример:**
+
+```python
+from nalogovich.enums import InvoicePaymentType
+
+invoice = await client.create_bill(
+    name="Услуга",
+    amount=10000.00,
+    client_name="Клиент",
+    payment_type=InvoicePaymentType.PHONE,  # СБП
+    phone="+79001234567",
+    bank_name="Сбербанк"
+)
+```
+
+---
+
+## InvoiceClientType
+
+Тип клиента для счёта.
+
+::: nalogovich.enums.InvoiceClientType
+    options:
+      show_root_heading: false
+      heading_level: 4
+      show_docstring_description: false
+
+**Значения:**
+
+- `FROM_INDIVIDUAL` — физическое лицо
+- `FROM_LEGAL_ENTITY` — юридическое лицо или ИП
+- `FROM_FOREIGN_AGENCY` — иностранная организация
+
+**Пример:**
+
+```python
+from nalogovich.enums import InvoiceClientType
+
+invoice = await client.create_bill(
+    name="Услуга",
+    amount=10000.00,
+    client_name="ООО Ромашка",
+    client_inn="7743013902",  # Обязательно для юр. лиц
+    client_type=InvoiceClientType.FROM_LEGAL_ENTITY,
+    payment_type=InvoicePaymentType.PHONE,
+    phone="+79001234567"
+)
+```
+
+---
+
+## InvoiceStatus
+
+Статус счёта.
+
+::: nalogovich.enums.InvoiceStatus
+    options:
+      show_root_heading: false
+      heading_level: 4
+      show_docstring_description: false
+
+**Значения:**
+
+- `CREATED` — создан
+- `TO_PAYMENT` — к оплате
+- `PAID` — оплачен
+- `FUND_RECEIVED` — средства получены
+- `PAID_WITH_RECEIPT` — оплачен с чеком
+- `PAID_WITHOUT_RECEIPT` — оплачен без чека
+- `CANCELLED` — аннулирован
+- `ERROR` — ошибка
+- `ALL` — все статусы (для фильтрации)
+
+**Пример:**
+
+```python
+from nalogovich.enums import InvoiceStatus
+
+# Получить только оплаченные счета
+response = await client.get_bills(
+    status=InvoiceStatus.PAID
+)
+```
+
+---
+
+## IncomeType
+
+Тип клиента для доходов (аналогично `InvoiceClientType`).
+
+::: nalogovich.enums.IncomeType
+    options:
+      show_root_heading: false
+      heading_level: 4
+      docstring_section_style: list
+      show_docstring_description: false
+
+**Значения:**
+
+- `FROM_INDIVIDUAL` — от физического лица
+- `FROM_LEGAL_ENTITY` — от юридического лица или ИП
+- `FROM_FOREIGN_AGENCY` — от иностранной организации

nalogovich-1.0.0/docs/api/exceptions.md

@@ -0,0 +1,154 @@
+# Исключения
+
+Nalogovich использует собственные исключения для обработки ошибок.
+
+---
+
+## NPDError
+
+Базовое исключение для всех ошибок библиотеки.
+
+::: nalogovich.exeptions.NPDError
+    options:
+      show_root_heading: false
+      heading_level: 4
+      docstring_section_style: list
+
+**Использование:**
+
+```python
+from nalogovich.exeptions import NPDError
+
+try:
+    # Ваш код
+    pass
+except NPDError as e:
+    print(f"Ошибка библиотеки: {e}")
+```
+
+---
+
+## ValidationError
+
+Ошибка валидации входных данных перед отправкой на сервер.
+
+::: nalogovich.exeptions.ValidationError
+    options:
+      show_root_heading: false
+      heading_level: 4
+      docstring_section_style: list
+
+**Когда возникает:**
+
+- Не указаны обязательные параметры
+- Неправильный формат данных
+- Логические ошибки в параметрах
+
+**Пример:**
+
+```python
+from nalogovich.exeptions import ValidationError
+
+try:
+    # Не указано ни name/amount, ни services
+    income = await client.create_check(
+        payment_type=PaymentType.CASH
+    )
+except ValidationError as e:
+    print(f"Ошибка валидации: {e}")
+    # Вывод: Необходимо указать либо (name и amount), либо список services
+```
+
+**Другие примеры:**
+
+```python
+# Для СБП не указан номер телефона
+try:
+    invoice = await client.create_bill(
+        name="Услуга",
+        amount=5000.00,
+        payment_type=InvoicePaymentType.PHONE,
+        # phone не указан!
+        bank_name="Сбербанк"
+    )
+except ValidationError as e:
+    print(e)  # ValidationError о необходимости указать phone
+```
+
+---
+
+## ApiError
+
+Ошибка, возвращённая сервером API ФНС.
+
+::: nalogovich.exeptions.ApiError
+    options:
+      show_root_heading: false
+      heading_level: 4
+      docstring_section_style: list
+
+**Атрибуты:**
+
+- `message` (str) — текст ошибки
+- `status_code` (int) — HTTP код ответа
+- `response_data` (Any) — данные ответа от сервера
+
+**Пример обработки:**
+
+```python
+from nalogovich.exeptions import ApiError
+
+try:
+    checks = await client.get_checks()
+except ApiError as e:
+    print(f"Ошибка API: {e}")
+    print(f"HTTP код: {e.status_code}")
+    print(f"Данные ответа: {e.response_data}")
+    
+    if e.status_code == 500:
+        print("Проблемы на стороне сервера ФНС")
+    elif e.status_code == 404:
+        print("Ресурс не найден")
+```
+
+---
+
+## AuthenticationError
+
+Ошибка авторизации.
+
+::: nalogovich.exeptions.AuthenticationError
+    options:
+      show_root_heading: false
+      heading_level: 4
+      docstring_section_style: list
+
+**Атрибуты:**
+
+- `message` (str) — текст ошибки
+- `status_code` (int) — HTTP код ответа (по умолчанию 401)
+- `response_data` (Any) — данные ответа от сервера
+
+**Когда возникает:**
+
+- Неверный ИНН или пароль (422)
+- Неавторизован (401)
+- Доступ запрещён (403)
+
+**Пример обработки:**
+
+```python
+from nalogovich.exeptions import AuthenticationError
+
+try:
+    await client.auth()
+except AuthenticationError as e:
+    if e.status_code == 422:
+        print("❌ Неверный ИНН или пароль")
+    elif e.status_code == 401:
+        print("❌ Неавторизован. Проверьте учетные данные")
+    elif e.status_code == 403:
+        print("❌ Доступ запрещён. Возможно, аккаунт заблокирован")
+    
+    print(f"Детали: {e.response_data}")
+```