platega-sdk 0.1.1

Асинхронный Python SDK для Platega Payment API

Platega SDK

Асинхронный Python SDK для работы с Platega Payment API.

🚀 Возможности

• ✅ Полная поддержка API - все эндпоинты Platega API
• ✅ Асинхронность - построен на httpx для высокой производительности
• ✅ Типизация - полная поддержка type hints и Pydantic моделей
• ✅ Обработка ошибок - детальные исключения для каждого типа ошибки
• ✅ Автоматические ретраи - настраиваемые повторные попытки при сбоях
• ✅ Webhook handler - готовый обработчик для колбэков
• ✅ Удобный API - интуитивно понятные методы
• ✅ Логирование - опциональное логирование всех запросов

📦 Установка

pip install platega-sdk

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

git clone https://github.com/ducklingsam/platega-sdk.git
cd platega-sdk
pip install -e .

🔧 Быстрый старт

Базовое использование

import asyncio
from platega import PlategaClient, PaymentMethod

async def main():
    # Инициализация клиента
    client = PlategaClient(
        merchant_id="your-merchant-id",
        secret="your-secret-key"
    )
    
    # Создание платежа
    transaction = await client.create_transaction(
        payment_method=PaymentMethod.SBP_QR,
        amount=1000.0,
        currency="RUB",
        description="Оплата заказа #123",
        return_url="https://example.com/success",
        failed_url="https://example.com/failed",
    )
    
    print(f"Ссылка для оплаты: {transaction.redirect}")
    print(f"ID транзакции: {transaction.transaction_id}")
    
    # Проверка статуса
    status = await client.get_transaction_status(transaction.transaction_id)
    print(f"Статус: {status.status}")
    
    await client.close()

asyncio.run(main())

С async context manager

async with PlategaClient(
    merchant_id="your-merchant-id",
    secret="your-secret-key"
) as client:
    transaction = await client.create_transaction(
        payment_method=PaymentMethod.CARDS_RUB,
        amount=5000.0,
        currency="RUB",
        description="Оплата картой",
        return_url="https://example.com/success",
        failed_url="https://example.com/failed",
    )
    # Клиент автоматически закроется

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

PlategaClient

Инициализация

client = PlategaClient(
    merchant_id="your-merchant-id",     # Обязательно: ваш MerchantId
    secret="your-secret-key",           # Обязательно: ваш API ключ
    base_url="https://app.platega.io",  # Опционально: базовый URL
    timeout=30.0,                       # Опционально: таймаут в секундах
    max_retries=3,                      # Опционально: количество ретраев
    retry_delay=1.0,                    # Опционально: задержка между ретраями
    enable_logging=False,               # Опционально: включить логи
)

Методы

create_transaction

Создание новой транзакции.

transaction = await client.create_transaction(
    payment_method=PaymentMethod.SBP_QR,  # Способ оплаты
    amount=1000.0,                         # Сумма
    currency="RUB",                        # Валюта
    description="Описание платежа",        # Назначение
    return_url="https://example.com/ok",   # URL успеха
    failed_url="https://example.com/fail", # URL ошибки
    payload="custom_data",                 # Опционально: доп. данные
)

Возвращает: CreateTransactionResponse

get_transaction_status

Получение статуса транзакции.

from uuid import UUID

status = await client.get_transaction_status(
    transaction_id=UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6")
)

Возвращает: TransactionStatusResponse

get_payment_method_rate

Получение курса обмена для платежного метода.

rate = await client.get_payment_method_rate(
    payment_method=PaymentMethod.SBP_QR,
    currency_from="RUB",
    currency_to="USDT",
)

Возвращает: PaymentMethodRateResponse

get_balance_unlock_operations

Получение конвертаций за период.

from datetime import datetime, timedelta

date_to = datetime.now()
date_from = date_to - timedelta(days=7)

conversions = await client.get_balance_unlock_operations(
    date_from=date_from,
    date_to=date_to,
    page=1,
    size=20,
)

Возвращает: Dict[str, Any]

PaymentMethod

Доступные способы оплаты:

from platega import PaymentMethod

PaymentMethod.SBP_QR                # 2 - СБП с QR-кодом
PaymentMethod.CARDS_RUB             # 10 - Российские карты
PaymentMethod.CARD_ACQUIRING        # 11 - Карточный эквайринг
PaymentMethod.INTERNATIONAL_ACQUIRING  # 12 - Международный эквайринг
PaymentMethod.CRYPTO                # 13 - Криптовалюта

Webhook Handler

Для обработки колбэков от Platega:

from platega import WebhookHandler

# Инициализация
webhook_handler = WebhookHandler(
    merchant_id="your-merchant-id",
    secret="your-secret-key",
    validate_auth=True,  # Проверять аутентификацию
)

# Пример с FastAPI
from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhook/platega")
async def platega_webhook(request: Request):
    headers = dict(request.headers)
    payload = await request.json()
    
    # Парсинг и валидация
    callback_data = webhook_handler.parse_callback(payload, headers)
    
    # Обработка
    if callback_data.status == "CONFIRMED":
        # Платеж подтвержден
        await process_payment(callback_data)
    elif callback_data.status == "CANCELED":
        # Платеж отменен
        await cancel_order(callback_data)
    
    return webhook_handler.create_success_response()

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

SDK предоставляет детальные исключения:

from platega import (
    PlategaError,           # Базовое исключение
    AuthenticationError,    # 401 - неверные credentials
    ValidationError,        # 400 - ошибка валидации
    NotFoundError,          # 404 - не найдено
    RateLimitError,         # 429 - лимит запросов
    ServerError,            # 5xx - ошибка сервера
    NetworkError,           # Проблемы с сетью
    WebhookValidationError, # Ошибка валидации webhook
)

try:
    transaction = await client.create_transaction(...)
except AuthenticationError as e:
    print(f"Проверьте credentials: {e.message}")
except ValidationError as e:
    print(f"Неверные данные: {e.message}")
    print(f"Детали: {e.response_data}")
except NetworkError as e:
    print(f"Проблемы с сетью: {e.message}")
except PlategaError as e:
    print(f"Общая ошибка: {e.message}")

⚙️ Продвинутое использование

Настройка ретраев

client = PlategaClient(
    merchant_id="your-merchant-id",
    secret="your-secret-key",
    max_retries=5,      # 5 попыток
    retry_delay=2.0,    # 2 секунды между попытками
    timeout=60.0,       # 60 секунд таймаут
)

Параллельное создание платежей

import asyncio

async def create_multiple_payments():
    async with PlategaClient(...) as client:
        tasks = [
            client.create_transaction(
                payment_method=PaymentMethod.SBP_QR,
                amount=100.0 * i,
                currency="RUB",
                description=f"Заказ #{i}",
                return_url="https://example.com/success",
                failed_url="https://example.com/failed",
            )
            for i in range(1, 6)
        ]
        
        transactions = await asyncio.gather(*tasks)
        return transactions

Логирование

import logging

# Настройка логирования
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

client = PlategaClient(
    merchant_id="your-merchant-id",
    secret="your-secret-key",
    enable_logging=True,  # Включить логи SDK
)

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

# Установка зависимостей для разработки
pip install -e ".[dev]"

# Запуск тестов
pytest

# С покрытием
pytest --cov=platega --cov-report=html

📝 Модели данных

Все ответы API валидируются через Pydantic модели:

• CreateTransactionResponse - результат создания транзакции
• TransactionStatusResponse - статус транзакции
• PaymentMethodRateResponse - курс обмена
• CallbackPayload - данные webhook

Полный список в platega/models.py.

🤝 Контрибьюция

Приветствуются pull request'ы! Для крупных изменений сначала откройте issue.