کتابخانه رسمی پایتون برای تعامل با درگاه خدمات پرداخت و موتور تطبیق هوشمند تراکنش‌های پولک (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]برای راه‌اندازی آسان و بدون نیاز به پاس دادن توکن‌ها درون کد برنامه‌نویسی، می‌توانید متغیرهای محیطی زیر را تنظیم کنید:
export POOLAK_BOT_TOKEN="your_bot_token_here"
export POOLAK_PARTNER_TOKEN="your_partner_token_here" # اختیاری
export POOLAK_BASE_URL="https://api.poolak.ir" # اختیاری برای تغییر درگاه سروربرای ایجاد تراکنش، به شناسه کارت بانکی فعال خود (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}")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}")استفاده از کلاس 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())یکی از ویژگی‌های قدرتمند سرویس پولک، ردیابی زنده وضعیت تراکنش‌ها بدون ارسال کوئری‌های مکرر به شبکه است. به دو روش می‌توانید منتظر تایید تراکنش بمانید:
این متد تا زمانی که خریدار تراکنش را با موفقیت واریز نکند، برنامه را متوقف نگه می‌دارد (تا سقف زمان مشخص‌شده برای انقضا):
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())اگر نیاز دارید تا وضعیت تغییرات را به صورت واکنشی پایش کنید، می‌توانید رویدادها را استریم کنید:
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())اگر می‌خواهید اطلاعات پرداخت‌ها را مستقیماً بر روی وب‌سایت خود دریافت کنید، می‌توانید از روتر اختصاصی پولک استفاده کنید. این روتر به طور خودکار صحت امضای ارسالی از سرور پولک را بررسی می‌کند و در صورت صحت، عملیات را در پس‌زمینه اجرا می‌نماید:
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")خطاهای مربوط به ارتباط با درگاه در استثناهای ساختاریافته دسته‌بندی شده‌اند تا کنترل جریان برنامه آسان‌تر باشد:
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 منتشر شده است. استفاده و تغییر در آن برای عموم توسعه‌دهندگان آزاد است.