platega-sdk 0.1.2
Python SDK для Platega Payment API (sync + async)
License: MIT
Requires Python: >=3.8
Keywords: platega, payments, api, sdk, async

# Platega SDK

Неофициальный Python SDK для работы с [Platega Payment API](https://platega.io).

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

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

## Установка

```bash
pip install platega-sdk
```

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

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

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

### Синхронный клиент

```python
from platega import PlategaSyncClient, PaymentMethod

with PlategaSyncClient(
    merchant_id="your-merchant-id",
    secret="your-secret-key"
) as client:
    # Создание платежа
    transaction = 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 = client.get_transaction_status(transaction.transaction_id)
    print(f"Статус: {status.status}")
```

### Асинхронный клиент

```python
import asyncio
from platega import PlategaClient, PaymentMethod

async def main():
    async with PlategaClient(
        merchant_id="your-merchant-id",
        secret="your-secret-key"
    ) as client:
        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}")

asyncio.run(main())
```

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

### Инициализация клиента

Оба клиента (`PlategaClient` и `PlategaSyncClient`) принимают одинаковые параметры:

```python
client = PlategaSyncClient(
    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

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

```python
transaction = 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",                 # Опционально: доп. данные
)
```

#### get_transaction_status

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

```python
from uuid import UUID

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

#### get_payment_method_rate

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

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

#### get_balance_unlock_operations

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

```python
from datetime import datetime, timedelta

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

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

### PaymentMethod

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

```python
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:

```python
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()
```

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

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

try:
    transaction = client.create_transaction(...)
except AuthenticationError as e:
    print(f"Проверьте credentials: {e.message}")
except ValidationError as e:
    print(f"Неверные данные: {e.message}")
except PlategaError as e:
    print(f"Ошибка: {e.message}")
```

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

```bash
pip install -e ".[dev]"
pytest
pytest --cov=platega --cov-report=html
```

## Лицензия

MIT