freekassa-no-off 2.0.0

Полнофункциональная Python библиотека для работы с платежной системой FreeKassa

FreeKassa Python Library

Профессиональная Python библиотека для работы с платежной системой FreeKassa.

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

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

📦 Установка

pip install freekassa-no-off

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

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

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

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

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='[e-mail]',
    ip='192.168.1.1',
    amount=1000.00,
    currency='RUB'
)

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

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

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 - Обработка уведомлений

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:

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)

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

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='[e-mail]'
)

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

🔔 Webhook (freekassa.sci)

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

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)

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

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)

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

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

Исключения

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)
• ✅ Безопасное хранение секретов (не логируются)

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

# Запуск всех тестов
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

🔗 Ссылки

• Документация FreeKassa
• Личный кабинет
• Техподдержка

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

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

---

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