tks-api-official 1.0.3
A powerful customs calculation API for vehicles with currency conversion.
Requires Python: >=3.7

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

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

Эта библиотека — идеальное решение для физических и юридических лиц, которые хотят сэкономить время и избежать ошибок при таможенном расчёте. С её помощью вы можете узнать полную стоимость растаможки вашего автомобиля всего за несколько шагов.

---

## Возможности TKS-API

- **Автоматический расчёт пошлин и сборов**: Метод выбирается на основе параметров автомобиля.
- **Гибкость конфигурации**: Легко адаптируется к изменениям тарифов.
- **Поддержка всех типов автомобилей**: Легковые, грузовые, гибридные и электромобили.
- **Актуальные курсы валют**: Интеграция с [currency-converter-free](https://pypi.org/project/currency-converter-free/) для конвертации стоимости авто.
- **Простая интеграция**: Подходит для малого бизнеса, таможенных брокеров и крупных импортеров.

---

## Установка

Чтобы установить библиотеку, выполните:

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

---

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

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

```python
from tks_api_official.calc import CustomsCalculator

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

# Установка параметров автомобиля
calculator.set_vehicle_details(
    age="5-7",                  # Возраст автомобиля: "new", "1-3", "3-5", "5-7", "over_7"
    engine_capacity=2000,       # Объём двигателя в см³
    engine_type="gasoline",     # Тип двигателя: "gasoline", "diesel", "electric", "hybrid"
    power=150,                  # Мощность двигателя в л.с.
    price=100000,               # Стоимость автомобиля
    owner_type="individual",    # Тип импортёра: "individual" или "company"
    currency="USD"              # Валюта стоимости автомобиля
)

# Расчёт платежей по ETC
etc_results = calculator.calculate_etc()
calculator.print_table("ETC")

# Расчёт платежей по CTP
ctp_results = calculator.calculate_ctp()
calculator.print_table("CTP")
```

---

## Параметры класса `CustomsCalculator`

### Метод `set_vehicle_details`

- **`age`** (`str`)  
  Возможные значения:
  - `"new"`: Новый автомобиль.
  - `"1-3"`: Возраст от 1 до 3 лет.
  - `"3-5"`: Возраст от 3 до 5 лет.
  - `"5-7"`: Возраст от 5 до 7 лет.
  - `"over_7"`: Старше 7 лет.

- **`engine_capacity`** (`int`)  
  Объём двигателя в кубических сантиметрах (см³).

- **`engine_type`** (`str`)  
  Возможные значения:
  - `"gasoline"`: Бензиновый двигатель.
  - `"diesel"`: Дизельный двигатель.
  - `"electric"`: Электромобиль.
  - `"hybrid"`: Гибридный двигатель.

- **`power`** (`int`)  
  Мощность двигателя в лошадиных силах (л.с.).

- **`price`** (`float`)  
  Стоимость автомобиля.

- **`owner_type`** (`str`)  
  Возможные значения:
  - `"individual"`: Физическое лицо.
  - `"company"`: Юридическое лицо.

- **`currency`** (`str`)  
  Код валюты стоимости автомобиля, например:
  - `"USD"`: Доллары США.
  - `"EUR"`: Евро.
  - `"KRW"`: Южнокорейская вона.
  - `"RUB"`: Российский рубль.

---

## Параметры конфигурации (config.yaml)

### Пример конфигурации

```yaml
tariffs:
  base_clearance_fee: 3100  # Таможенная пошлина за оформление (руб.)
  base_util_fee: 20000  # Утилизационный сбор (руб.)
  etc_util_coeff_base: 1.5  # Коэффициент утилизационного сбора для ETC
  ctp_util_coeff_base: 1.2  # Коэффициент утилизационного сбора для CTP
  excise_rates:
    gasoline: 58  # Акциз для бензиновых двигателей (руб./л.с.)
    diesel: 58  # Акциз для дизельных двигателей (руб./л.с.)
    electric: 0  # Для электромобилей акциз отсутствует
    hybrid: 58  # Акциз для гибридных двигателей (руб./л.с.)
  recycling_factors:
    default:
      gasoline: 1.0
      diesel: 1.1
      electric: 0.3
      hybrid: 0.9
    adjustments:
      "5-7":
        gasoline: 0.26
        diesel: 0.26
        electric: 0.26
        hybrid: 0.26
  age_groups:
    overrides:
      "5-7":
        gasoline:
          rate_per_cc: 4.8  # Ставка (евро/см³)
          min_duty: 0  # Минимальная ставка
        diesel:
          rate_per_cc: 5.0
          min_duty: 0
        electric:
          rate_per_cc: 0
          min_duty: 1000
        hybrid:
          rate_per_cc: 2.0
          min_duty: 2500
```

### Основные параметры конфигурации

- **`base_clearance_fee`**: Таможенная пошлина за оформление.
- **`base_util_fee`**: Утилизационный сбор.
- **`etc_util_coeff_base`**: Коэффициент для расчёта утилизационного сбора по ETC.
- **`ctp_util_coeff_base`**: Коэффициент для расчёта утилизационного сбора по CTP.
- **`excise_rates`**: Ставки акциза для различных типов двигателей.
- **`recycling_factors`**: Коэффициенты утилизационного сбора.
- **`age_groups`**: Индивидуальные тарифы для автомобилей разных возрастов.

---

## Тестирование библиотеки

Для запуска тестов:

```bash
pytest tests
```

---

## Лицензия

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

---

## Контакты

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