Metadata-Version: 2.4
Name: platega-sdk
Version: 0.1.1
Summary: Асинхронный Python SDK для Platega Payment API
Author-email: ODBO <me@odbo.tech>
License: MIT
Project-URL: Homepage, https://github.com/ducklingsam/platega-sdk
Project-URL: Documentation, https://github.com/ducklingsam/platega-sdk/blob/main/README.md
Project-URL: Repository, https://github.com/ducklingsam/platega-sdk
Project-URL: Issues, https://github.com/ducklingsam/platega-sdk/issues
Keywords: platega,payments,api,sdk,async
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"

# Platega SDK

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```python
from uuid import UUID

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

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

##### get_payment_method_rate

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

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

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

##### get_balance_unlock_operations

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

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

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

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

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

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

```python
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}")
```

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

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

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

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

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

### Логирование

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

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

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

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

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

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

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

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

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

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

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