Metadata-Version: 2.1
Name: tks-api-official
Version: 1.0.2
Summary: A powerful customs calculation API for vehicles with currency conversion.
Home-page: https://github.com/markolofsen/tks-api
Author: Unrealos.com
Author-email: m@unrealos.com
Project-URL: Bug Tracker, https://github.com/markolofsen/tks-api/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: pyyaml
Requires-Dist: tabulate
Requires-Dist: currency-converter-free
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: unittest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: isort; extra == "dev"

# TKS-API: Калькулятор Таможенных Платежей для Автомобилей

**TKS-API** — это Python-библиотека для точного расчёта таможенных платежей при импорте автомобилей в Россию. С её помощью можно легко рассчитать такие ключевые параметры, как **таможенные пошлины**, **НДС**, **акциз**, и **утилизационный сбор**, используя два популярных метода: **ETC (Единая ставка)** и **CTP (Совокупный таможенный платёж)**. 

Библиотека идеально подходит как для физических лиц, импортирующих легковые автомобили, так и для юридических лиц, занимающихся поставками внедорожников, коммерческих и премиальных авто. Она автоматизирует процесс расчёта, учитывая актуальные курсы валют через интеграцию с [currency-converter-free](https://pypi.org/project/currency-converter-free/).

---

## Основные преимущества

- **Полная автоматизация расчёта**: Библиотека выбирает метод расчёта (ETC или CTP) в зависимости от параметров автомобиля.
- **Актуальные курсы валют**: Поддержка данных от Центрального Банка России и Европейского Центрального Банка.
- **Гибкая настройка**: Все ключевые параметры, включая ставки пошлин, коэффициенты и сборы, задаются через YAML-файл конфигурации.
- **Поддержка всех типов автомобилей**: Легковые автомобили, внедорожники, коммерческий транспорт.
- **Удобная интеграция**: Подходит для Python-проектов любого масштаба.

---

## Установка

Установите библиотеку с помощью команды:

```bash
pip install tks-api-official
```

---

## Как использовать

### Пример расчёта таможенных платежей

```python
from tks_api_official.calc import CustomsCalculator

# Инициализация калькулятора
calculator = CustomsCalculator("config.yaml")

# Установка параметров автомобиля
calculator.set_fields(
    price=7000000,              # Стоимость автомобиля
    currency="KRW",             # Валюта (например, Южнокорейская вона)
    volume_cc=2000,             # Объём двигателя (см³)
    power_hp=300,               # Мощность двигателя (л.с.)
    age_category="<3",          # Возраст автомобиля (например, менее 3 лет)
    engine_type="diesel",       # Тип двигателя: бензиновый или дизельный
    is_offroad=True,            # Является ли автомобиль внедорожником
    is_already_cleared=False,   # Указание, растаможен ли автомобиль
    importer_type="legal",      # Тип импортёра: физическое лицо или юридическое
)

# Расчёт платежей
calculator.calculate()

# Вывод результатов
calculator.print_table()
```

---

## Файл конфигурации (config.yaml)

Для настройки параметров расчёта используется YAML-файл. Пример файла:

```yaml
base_clearance_fee: 30000          # Базовый сбор за таможенное оформление (руб.)
base_util_fee: 20000              # Утилизационный сбор (руб.)
etc_euro_per_cc: 1.5              # ETC ставка для бензиновых двигателей (евро/см³)
etc_euro_per_cc_diesel: 2.0       # ETC ставка для дизельных двигателей (евро/см³)
etc_util_coeff_base: 0.26         # Базовый коэффициент утилизационного сбора для ETC
offroad_duty_extra_percent: 0.1   # Дополнительный сбор для внедорожников (+10%)
diesel_util_extra: 0.1            # Дополнительный коэффициент для дизельных двигателей
offroad_util_extra: 0.05          # Дополнительный коэффициент для внедорожников
ctp_base_duty_percent: 0.15       # Ставка пошлины для CTP (бензин)
ctp_base_duty_percent_diesel: 0.16 # Ставка пошлины для CTP (дизель)
ctp_excise_per_hp_benzin: 912     # Акциз на мощность (бензин) в рублях за л.с.
ctp_excise_per_hp_diesel: 1000    # Акциз на мощность (дизель) в рублях за л.с.
offroad_excise_extra: 0.1         # Дополнительный акциз для внедорожников (+10%)
vat_percent: 0.20                 # НДС (в процентах)
ctp_util_coeff_base: 15.03        # Коэффициент утилизационного сбора для CTP
```

---

## Как работает

1. **Установка параметров автомобиля**: Задаются такие параметры, как стоимость, объём двигателя, мощность, возраст и тип автомобиля.
2. **Расчёт пошлин**: Выбор между **ETC** (Единая ставка) и **CTP** (Совокупный таможенный платёж) осуществляется автоматически.
3. **Конвертация валют**: Стоимость автомобиля конвертируется в рубли с учётом текущего курса валют.
4. **Вывод результатов**: Полный расчёт таможенных сборов, включая НДС, акциз, пошлину и утилизационный сбор, выводится в виде таблицы.

---

## Тестирование

Для проверки корректности работы модуля выполните:

```bash
pytest tests
```

---

## Примеры сценариев

- **Физическое лицо**: Ввоз компактного автомобиля (до 1000 см³) через ETC.
- **Юридическое лицо**: Импорт внедорожников и коммерческого транспорта через CTP.
- **Поддержка экзотических валют**: Конвертация стоимости автомобиля из KRW, AED и других.

---

## Лицензия

Проект распространяется под лицензией MIT. Подробнее см. файл [LICENSE](LICENSE).

---

## Контакты

Разработка: [Unrealos.com](https://unrealos.com)  
Обратная связь: [m@unrealos.com](mailto:m@unrealos.com)  

---
