مكتبة خادم إيصالات لـ Python

التثبيت

pip install esaalat

أنشئ الجلسة

from esaalat import EsaalatClient

# Reads ESAALAT_CLIENT_ID, ESAALAT_CLIENT_SECRET and ESAALAT_WEBHOOK_SECRET.
esaalat = EsaalatClient.from_env()

session = esaalat.create_session(order_id="order-12345", amount=5000)

session["session_token"]  # → open the checkout from your page
session["portal_url"]     # → or redirect the buyer straight to it

تحقق من الـ Webhook

from esaalat import EsaalatWebhookError

@app.post("/esaalat/webhooks")
def esaalat_webhook():
    try:
        event = esaalat.verify_webhook(
            request.data,                            # the RAW body
            request.headers["X-Esaalat-Signature"],
        )
    except EsaalatWebhookError:
        return "", 400                               # anything but 2xx retries

    if event["event"] == "payment.verified":
        release_order(event["order_id"])              # idempotent on intent_id
    return "", 200

ما تتولاه الحزمة عنك

• •رمز الوصول مخزّن — رمز واحد لكل عملية، يُجدَّد قبل دقيقة من exp داخل الـ JWT، فلا تبدأ طلباتك بالفشل عند انتهاء الساعة.
• •مفتاح التكرار تلقائي — مفتاح واحد لكل إنشاء، يُستخدم نفسه في كل محاولة إعادة: لا يمكن لـ 429 أو انتهاء المهلة أن ينشئ الطلب مرتين.
• •إعادة المحاولة — على 429 و5xx وفشل الشبكة، مع احترام Retry-After.
• •أخطاء مصنّفة — كل خطأ يحمل رمزاً وحالة HTTP والحقل المتسبب وأخطاء الحقول التي يعيدها الـ API.
• •لخادمك فقط — لا يصل إلى المتصفح إلا رمز الجلسة. أما سر العميل فيبقى على خادمك حيث يجب أن يكون.

الإعدادات

قبل أن تنطلق

• •الحزمة بلا أي تبعيّات: تستخدم urllib وhmac وjson من المكتبة القياسية.
• •سر العميل سر خادم. لا تستدعِه من متصفح ولا تضعه في تطبيق جوال.
• •المبالغ بالريال اليمني كأرقام صحيحة، وformat_amount(5000.5) يرفض قبل إرسال الطلب.