freekassa-no-off 3.0.0
Полнофункциональная Python библиотека для работы с платежной системой FreeKassa
License: MIT
Requires Python: >=3.7
Keywords: freekassa, payment, gateway, api, sci, webhook, russia

# FreeKassa Python Library

Профессиональная Python библиотека для работы с платежной системой [FreeKassa](https://freekassa.net).

[![Python](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## ✨ Особенности

- 🏗️ **Профессиональная архитектура** - модульная структура с разделением на компоненты
- ✅ **100% покрытие API** - все методы FreeKassa API v1
- 🔒 **Безопасность** - валидация данных, проверка подписей и IP
- 📝 **Type hints** - полная типизация для IDE
- 🧪 **Тестирование** - unit тесты для всех компонентов
- 📚 **Документация** - подробные docstrings и примеры
- 🚀 **Production-ready** - готово к использованию в продакшене

## 📦 Установка

```bash
pip install freekassa-no-off
```

Или из исходников:

```bash
git clone https://github.com/nloveuser/freekassa-no-off.git
cd freekassa-no-off
pip install -e .
```

## 🚀 Быстрый старт

### API - Создание заказа

```python
from freekassa import FreeKassaAPI, FreeKassaCurrency

api = FreeKassaAPI(
    shop_id=777,
    api_key='your_api_key'
)

order = api.create_order(
    currency_id=FreeKassaCurrency.VISA_RUB,
    email='customer@example.com',
    ip='192.168.1.1',
    amount=1000.00,
    currency='RUB'
)

print(f"Ссылка на оплату: {order['location']}")
```

### SCI - Платежная форма

```python
from freekassa import FreeKassaSCI

sci = FreeKassaSCI(
    merchant_id=777,
    secret_word='secret_word_1',
    secret_word_2='secret_word_2'
)

# Генерация URL
payment_url = sci.generate_payment_url(
    amount=1500.00,
    currency='RUB',
    order_id='ORDER-12345'
)

# Или HTML формы
html_form = sci.generate_payment_form_html(
    amount=1500.00,
    currency='RUB',
    order_id='ORDER-12345',
    button_text='Оплатить заказ'
)
```

### Webhook - Обработка уведомлений

```python
from freekassa import FreeKassaSCI, FreeKassaWebhookHandler

sci = FreeKassaSCI(777, 'secret1', 'secret2')
handler = FreeKassaWebhookHandler(sci)

# В вашем веб-обработчике
notification = handler.handle_notification(
    request_data=request.POST,
    client_ip=request.remote_addr,
    verify_ip=True
)

print(f"Оплачен заказ: {notification['merchant_order_id']}")
print(f"Сумма: {notification['amount']}")

# Вернуть 'YES' для подтверждения
return handler.get_success_response()
```

## 📁 Структура проекта

```
freekassa-no-off/
├── src/
│   └── freekassa/
│       ├── __init__.py          # Главный модуль
│       ├── exceptions.py        # Исключения
│       │
│       ├── api/                 # API клиент
│       │   ├── __init__.py
│       │   ├── base.py          # Базовый клиент
│       │   ├── client.py        # Главный клиент
│       │   ├── orders.py        # Методы заказов
│       │   ├── withdrawals.py   # Методы выплат
│       │   └── info.py          # Информационные методы
│       │
│       ├── sci/                 # SCI формы и webhook
│       │   ├── __init__.py
│       │   ├── forms.py         # Генерация форм
│       │   └── webhook.py       # Обработка уведомлений
│       │
│       ├── models/              # Модели данных
│       │   ├── __init__.py
│       │   ├── currency.py      # Валюты
│       │   └── status.py        # Статусы и периоды
│       │
│       └── utils/               # Утилиты
│           ├── __init__.py
│           ├── crypto.py        # Криптография
│           └── validators.py    # Валидация
│
├── tests/                       # Тесты
│   ├── __init__.py
│   └── test_all.py
│
├── examples/                    # Примеры
│   ├── basic_usage.py
│   ├── flask_integration.py
│   └── django_integration.py
│
├── docs/                        # Документация
├── setup.py                     # Установка
├── pyproject.toml              # Конфигурация проекта
├── requirements.txt            # Зависимости
├── README.md                   # Этот файл
├── LICENSE                     # MIT License
└── CHANGELOG.md                # История изменений
```

## 📚 Документация

### Модули

#### 🔌 API (`freekassa.api`)

Работа с REST API FreeKassa:

```python
from freekassa import FreeKassaAPI

api = FreeKassaAPI(shop_id=777, api_key='key')

# Заказы
order = api.create_order(...)
orders = api.get_orders(order_status=1)
refund = api.refund_order(order_id=123)

# Выплаты
withdrawal = api.create_withdrawal(...)
withdrawals = api.get_withdrawals()
currencies = api.get_withdrawal_currencies()

# Информация
balance = api.get_balance()
currencies = api.get_currencies()
status = api.check_currency_status(4)
shops = api.get_shops()
```

#### 🎨 SCI (`freekassa.sci`)

Генерация платежных форм:

```python
from freekassa import FreeKassaSCI

sci = FreeKassaSCI(777, 'secret1', 'secret2')

# URL для оплаты
url = sci.generate_payment_url(
    amount=1000.00,
    currency='RUB',
    order_id='ORDER-123',
    email='customer@example.com'
)

# HTML форма
html = sci.generate_payment_form_html(
    amount=1000.00,
    currency='RUB',
    order_id='ORDER-123',
    button_text='Оплатить'
)
```

#### 🔔 Webhook (`freekassa.sci`)

Обработка уведомлений:

```python
from freekassa import FreeKassaWebhookHandler

handler = FreeKassaWebhookHandler(sci)

notification = handler.handle_notification(
    request_data=request.POST,
    client_ip=request.remote_addr,
    verify_ip=True
)

# Обязательно вернуть 'YES'
return handler.get_success_response()
```

#### 💰 Модели (`freekassa.models`)

Константы и модели данных:

```python
from freekassa import FreeKassaCurrency, OrderStatus, RecurrentPeriod

# Валюты
FreeKassaCurrency.VISA_RUB        # 4
FreeKassaCurrency.BITCOIN         # 24
FreeKassaCurrency.SBP             # 42

# Статусы
OrderStatus.NEW                   # 0
OrderStatus.PAID                  # 1

# Периоды подписок
RecurrentPeriod.DAY              # "day"
RecurrentPeriod.MONTH            # "month"
```

#### 🛠️ Утилиты (`freekassa.utils`)

Вспомогательные функции:

```python
from freekassa.utils import (
    generate_md5_signature,
    generate_hmac_sha256_signature,
    validate_amount,
    validate_email,
    validate_ip
)
```

### Исключения

```python
from freekassa import FreeKassaException
from freekassa.exceptions import (
    FreeKassaAPIException,          # Ошибка API
    FreeKassaValidationException,   # Ошибка валидации
    FreeKassaSignatureException,    # Ошибка подписи
    FreeKassaIPException,           # Ошибка IP
    FreeKassaNetworkException       # Ошибка сети
)

try:
    order = api.create_order(...)
except FreeKassaValidationException as e:
    print(f"Ошибка валидации: {e}")
except FreeKassaAPIException as e:
    print(f"Ошибка API: {e}")
```

## 🔐 Безопасность

Библиотека включает:

- ✅ Автоматическую валидацию всех входных данных
- ✅ Проверку подписей (HMAC SHA256 для API, MD5 для SCI)
- ✅ Проверку IP адресов серверов FreeKassa
- ✅ Защиту от replay-атак (монотонный nonce)
- ✅ Безопасное хранение секретов (не логируются)

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

```bash
# Запуск всех тестов
python -m unittest discover tests

# Запуск конкретного теста
python -m unittest tests.test_all.TestFreeKassaAPI

# С подробным выводом
python -m unittest tests.test_all -v
```

## 📖 Примеры

См. папку `examples/` для подробных примеров:

- `basic_usage.py` - базовое использование
- `flask_integration.py` - интеграция с Flask
- `django_integration.py` - интеграция с Django
- `recurrent_payments.py` - рекуррентные платежи

## 🤝 Вклад в проект

Приветствуются pull requests! Для больших изменений сначала откройте issue.

## 📝 Лицензия

MIT License - см. файл [LICENSE](LICENSE)

## 🔗 Ссылки

- [Документация FreeKassa](https://docs.freekassa.net/)
- [Личный кабинет](https://merchant.freekassa.net/)
- [Техподдержка](https://freekassa.net/)

## ⭐ Поддержите проект

Если библиотека оказалась полезной, поставьте звезду на GitHub!

---

Создано с ❤️ для разработчиков Python