Poolak SDK 🪙

کتابخانه رسمی پایتون برای تعامل با درگاه خدمات پرداخت و موتور تطبیق هوشمند تراکنش‌های پولک (Poolak).

این کیت توسعه نرم‌افزار (SDK) به شما اجازه می‌دهد تا به سادگی تراکنش‌های مالی را در پروژه‌های خود (نظیر ربات‌های تلگرامی، سیستم‌های مالی و وب‌سایت‌ها) ثبت، پیگیری و از طریق استریم زنده یا روترهای وب‌هوک هوشمند پایش کنید.

قابلیت‌های برجسته

• کلاینت‌های همگام و ناهمگام (Sync/Async): پشتیبانی کامل از برنامه‌نویسی غیرهمزمان با AsyncPoolak و همزمان با Poolak بر پایه کتابخانه قدرتمند httpx.
• مدیریت خودکار ارزها: تعریف مستقیم مبالغ با کلاس‌های Toman یا Rial و مدیریت هوشمند تبدیل واحدها قبل از ارسال به درگاه.
• استریم زنده وضعیت تراکنش‌ها (SSE): امکان رصد و دریافت آنی وضعیت تراکنش‌ها بدون نیاز به کوئری‌های تکراری (Polling).
• پلاگین آماده وب‌هوک برای FastAPI: دارای روتر توکار جهت دریافت امن اعلان‌های وب‌هوک پرداخت همراه با اعتبارسنجی خودکار امضای هَش‌شده (HMAC-SHA256).
• اعتبارسنجی قوی با Pydantic: استفاده از Pydantic نسخه ۲ برای مدل‌سازی و بررسی دقیق داده‌ها قبل و بعد از ارسال به سرور.

نصب و راه‌اندازی

شما می‌توانید بسته اصلی کتابخانه را با دستور زیر نصب کنید:

pip install poolak

اگر قصد دارید از افزونه وب‌هوک این کتابخانه برای هماهنگی با فریم‌ورک FastAPI استفاده کنید، آن را با دستور زیر نصب نمایید تا ابزارهای موردنیاز FastAPI نیز به طور خودکار دریافت شوند:

pip install poolak[fastapi]

تنظیمات محیطی (Environment Variables)

برای راه‌اندازی آسان و بدون نیاز به پاس دادن توکن‌ها درون کد برنامه‌نویسی، می‌توانید متغیرهای محیطی زیر را تنظیم کنید:

export POOLAK_BOT_TOKEN="your_bot_token_here"
export POOLAK_PARTNER_TOKEN="your_partner_token_here" # اختیاری
export POOLAK_BASE_URL="https://api.poolak.ir" # اختیاری برای تغییر درگاه سرور

شروع سریع (Quick Start)

برای ایجاد تراکنش، به شناسه کارت بانکی فعال خود (destination_card_id) نیاز دارید. در ابتدا می‌توانید لیست کارت‌های فعال خود را دریافت کنید:

۱. دریافت لیست کارت‌های بانکی فعال

from poolak import Poolak

with Poolak(bot_token="your_bot_token") as client:
    cards = client.get_cards()
    for card in cards:
        print(f"بانک: {card.bank.name} | شماره کارت: {card.card_number} | شناسه کارت: {card.id}")

۲. ثبت تراکنش به صورت همگام (Synchronous)

from poolak import Poolak, Toman

# ثبت یک تراکنش جدید با واحد تومان
with Poolak(bot_token="your_bot_token") as client:
    try:
        transaction = client.create_transaction(
            order_id="order_10024",
            amount=Toman(10000), # مقداردهی با تومان (به طور خودکار به ریال تبدیل می‌شود)
            destination_card_id="وارد کنید card.id شناسه کارت خود را از بخش قبلی"
        )
        print(f"تراکنش با شناسه {transaction.id} ثبت شد. مبلغ نهایی ریال: {transaction.final_amount}")
    except Exception as e:
        print(f"خطا در ثبت تراکنش: {e}")

۳. اجرای ناهمگام (Asynchronous)

استفاده از کلاس AsyncPoolak به همراه ساختار async with برای پروژه‌های ناهمگام (نظیر ربات‌های تلگرامی پیشرفته):

import asyncio
from poolak import AsyncPoolak, Toman

async def main():
    async with AsyncPoolak() as client: # خواندن خودکار توکن از متغیر محیطی
        # ایجاد تراکنش
        transaction = await client.create_transaction(
            order_id="order_10025",
            amount=Toman(5000),
            destination_card_id="8f90b1c0-0000-0000-0000-000000000000"
        )
        print(f"تراکنش ثبت شد: {transaction.id}")

        # بررسی آنی وضعیت تراکنش
        status = await client.check_transaction(transaction_id=transaction.id)
        print(f"وضعیت فعلی: {status.status}")

asyncio.run(main())

ردیابی آنی پرداخت‌ها (Real-time Payment Tracking)

یکی از ویژگی‌های قدرتمند سرویس پولک، ردیابی زنده وضعیت تراکنش‌ها بدون ارسال کوئری‌های مکرر به شبکه است. به دو روش می‌توانید منتظر تایید تراکنش بمانید:

متد معلق‌کننده (Blocking)

این متد تا زمانی که خریدار تراکنش را با موفقیت واریز نکند، برنامه را متوقف نگه می‌دارد (تا سقف زمان مشخص‌شده برای انقضا):

import asyncio
from poolak import AsyncPoolak

async def main():
    async with AsyncPoolak() as client:
        print("در حال انتظار برای پرداخت...")
        status = await client.wait_for_payment(
            transaction_id="8f90b1c0-0000-0000-0000-000000000000",
            timeout=900 # حداکثر زمان انتظار به ثانیه
        )
        print(f"پرداخت با وضعیت خاتمه یافت: {status}")

asyncio.run(main())

استریم زنده رویدادها (Stream)

اگر نیاز دارید تا وضعیت تغییرات را به صورت واکنشی پایش کنید، می‌توانید رویدادها را استریم کنید:

import asyncio
from poolak import AsyncPoolak

async def main():
    async with AsyncPoolak() as client:
        async for event in client.stream_transaction("8f90b1c0-0000-0000-0000-000000000000"):
            print(f"رویداد جدید دریافت شد: {event.status}")

asyncio.run(main())

یکپارچه‌سازی وب‌هوک با FastAPI

اگر می‌خواهید اطلاعات پرداخت‌ها را مستقیماً بر روی وب‌سایت خود دریافت کنید، می‌توانید از روتر اختصاصی پولک استفاده کنید. این روتر به طور خودکار صحت امضای ارسالی از سرور پولک را بررسی می‌کند و در صورت صحت، عملیات را در پس‌زمینه اجرا می‌نماید:

from fastapi import FastAPI
from poolak.contrib.fastapi import PoolakWebhookRouter

app = FastAPI()

# تعریف وب‌هوک با کلید رمز وب‌هوک دریافت شده از پنل پولک
webhook_router = PoolakWebhookRouter(webhook_secret="your_webhook_secret_key")

@webhook_router.on_paid()
async def handle_payment_event(payload: dict):
    # این تابع زمانی که واریز تایید شد در پس‌زمینه صدا زده می‌شود
    transaction_id = payload.get("transaction_id")
    order_id = payload.get("order_id")
    final_amount = payload.get("final_amount")
    print(f"پرداخت موفق تایید شد! شماره سفارش: {order_id}، مبلغ: {final_amount}")

# اضافه کردن روتر به اپلیکیشن وب
app.include_router(webhook_router, prefix="/webhooks/poolak")

مدیریت خطاها (Error Handling)

خطاهای مربوط به ارتباط با درگاه در استثناهای ساختاریافته دسته‌بندی شده‌اند تا کنترل جریان برنامه آسان‌تر باشد:

from poolak import (
    Poolak, 
    Toman,
    AuthenticationError,
    ValidationError,
    RateLimitError,
    APIResponseError
)

try:
    with Poolak() as client:
        client.create_transaction("order_12", Toman(100), "invalid_card_id")
except AuthenticationError as e:
    print(f"خطای تایید هویت یا توکن نامعتبر: {e}")
except ValidationError as e:
    print(f"خطای اعتبارسنجی مقادیر ارسالی: {e}")
except RateLimitError as e:
    print(f"محدودیت درخواست‌های مکرر به سرور: {e}")
except APIResponseError as e:
    print(f"خطای پاسخ سرور: {e}")

سایر متدها و ابزارهای کمکی

علاوه بر متدهای اصلی، SDK قابلیت‌های زیر را نیز ارائه می‌دهد:

• دریافت وضعیت کیف پول (get_wallet_status): مشاهده موجودی، طرح فعال و تراکنش‌های باقیمانده.
• تایید دستی تراکنش (manual_verify): امکان تطبیق دستی یک تراکنش تعلیق شده با یک پیامک واریز یتیم (Orphan).
• دریافت پیامک‌های یتیم (get_orphans): استعلام پیامک‌هایی که به دلیل عدم تطبیق خودکار سیستمی، در دیتابیس یتیم مانده‌اند.

توسعه و اجرای تست‌ها

جهت اجرای آزمون‌های واحد و ارزیابی صحت کارکرد ابزار بر روی سیستم خود، ابتدا نیازمندی‌های توسعه را نصب کرده و دستور زیر را در مسیر ریشه پروژه اجرا کنید:

pytest

لایسنس

این پروژه تحت مجوز LICENSE منتشر شده است. استفاده و تغییر در آن برای عموم توسعه‌دهندگان آزاد است.