fk-net 0.1.1

Library for using service https://docs.freekassa.net/

freekassa

Установка

pip install fk-net

Использование API

from fk_net import Freekassa


SHOP_ID = ''
API_KEY = ''
fk = Freekassa(shop_id=SHOP_ID, api_key=API_KEY)

Запрос баланса

fk.get_balance() 

    {
        "type": "success",
        "balance": 
        [
            {
                "currency": "RUB",
                "value": 743.43
            }
        ]
    }

Список заявок

list = fk.get_orders()

Фильтрация:

• order_id: int = None,
• payment_id: str = None,
• order_status: int = None,
• date_from: datetime.datetime = None,
• date_to: datetime.datetime = None,
• page: int = None

    {
        "type": "success",
        "pages": 12,
        "orders": 
            [
                {
                "merchant_order_id": "Order #123",
                "fk_order_id": 652367,
                "amount": 100.12,
                "currency": "RUB",
                "email": "[e-mail]",
                "account": "5555555555554444",
                "date": "2021-03-29 12:28:24",
                "status": 1
                }
            ]
    }

Получить название статуса:

from freekassa_ru import get_order_label

print(get_order_label(order.get('status')))

Создать заказ и получить ссылку на оплату

payment_system_id = 1
email = '[e-mail]'
ip = '0.0.0.0'
amount = 110.20
list = fk.create_order(payment_system_id, email, ip, amount)

Параметры:

• payment_system_id: int, ID платежной системы
• email: str, Электронный адрес плательщика
• ip: str, IP плательщика
• amount: float, сумма платежа
• currency_code: str = 'RUB', символьный код валюты оплаты
• payment_id: str = None, Номер заказа в Вашем магазине
• tel: str = None, телефон плательщика
• success_url: str = None, Переопределение урла успеха (для включения данного параметра обратитесь в поддержку)
• failure_url: str = None, Переопределение урла ошибки (для включения данного параметра обратитесь в поддержку)
• notification_url: str = None, Переопределение урла уведомлений (для включения данного параметра обратитесь в поддержку)

    {
        "type": "success",
        "orderId": 123,
        "orderHash": "bd4161db429848651499aabcb1d89330",
        "location": "https://pay.freekassa.net/form/123/bd4161db429848651499aabcb1d89330"
    }

Возврат заказа

order_id = 123
nonce = 1648590400
payment_id = '1234567890'
fk.refund_order(order_id, nonce, payment_id)

Список выплат

fk.get_withdrawals()

Фильтры аналогичные списку заявок

Создать выплату

payment_system_id = 1
amount = 110.20
account = '5500000000000004'
fk.create_withdrawal(self, payment_system_id: int, account: str, amount: float)

Параметры:

• payment_system_id: int, ID платежной системы
• account: str, Кошелек для зачисления средств (при выплате на FKWallet вывод осуществляется только на свой аккаунт)
• amount: float, сумма платежа
• currency_code: str = 'RUB', символьный код валюты оплаты
• payment_id: str = None, Номер заказа в Вашем магазине

    {
      "type": "success",
      "data": {
        "id": 185
        }
    }

Получение списка доступных платежных систем

fk.get_payment_systems() 

  {
    "type": "success",
    "currencies": [
        {
        "id": 4,
        "name": "VISA",
        "currency": "RUB",
        "is_enabled": 1,
        "is_favorite": 0
        }
    ]
}

Проверка доступности платежной системы для оплаты

payment_system_id = 1
fk.check_payment_system(payment_system_id)

  {
      "type": "success"
  }

Получение списка доступных платежных систем для вывода

fk.get_payment_systems_for_withdrawal() 

{
  "type": "success",
  "currencies": [
    {
      "id": 4,
      "name": "VISA",
      "min": 100,
      "max": 15000,
      "currency": "RUB",
      "can_exchange": 1
    }
  ]
}

Получение списка Ваших магазинов

fk.get_shops() 

{
  "type": "success",
  "shops": [
    {
      "id": 777,
      "name": "Рога и копыта",
      "url": "https://horns-and-hooves.ru"
    }
  ]
}

Обработка ответа о платеже

  from freekassa_ru import Notification
  
  SECRET_KEY_2 = ''
  ip = '0.0.0.0' # IP, с которого пришел запрос
  data = request.GET # или request.POST в зависимости от настроек магазина
  notification = Notification(data=data, secret2=SECRET_KEY_2, ip=ip)
  notification.check() # Проверка IP и подписи
  payment_id = notification.payment_id # получение ID заказа на сайте продавца для изменения статуса оплаты

Обработка ошибок

from freekassa_ru import FreekassaError, FreekassaAuthError, FreekassaNotificationError

try:
    fk.get_balance()
except FreekassaError as e:
    print(e) # Ошибка выполнения запроса
except FreekassaAuthError as e:
    print(e) # Ошибка авторизации API
    
try:
    notification.check()
except FreekassaNotificationError as e:
    print(e) # Ошибка проверки оповещения о платеже

CI/CD (GitHub Actions): Автоматический релиз и публикация в PyPI

• Workflow создаёт GitHub Release и публикует пакет в PyPI после push/merge в master.
• Версия берётся из setup.cfg ([metadata] version). При изменении версии создаётся/обновляется тег v<version>.

Настройка

• Добавьте секрет PYPI_API_TOKEN в репозитории GitHub: Settings → Secrets and variables → Actions → New repository secret.
  • Значение: PyPI API token (pypi-...).
• Убедитесь, что setup.cfg содержит актуальную версию.

Как работает

• Триггеры: push в ветку master и ручной запуск (workflow_dispatch).
• Шаги:
  • Читает версию из setup.cfg.
  • Создаёт (или переиспользует) тег v<version> и GitHub Release.
  • Собирает дистрибутив (wheel + sdist), прикрепляет файлы к релизу.
  • Публикует в PyPI (если задан секрет PYPI_API_TOKEN).

Файл workflow: .github/workflows/release.yml.