بوابة الربط البرمجي (SDK)

ادمج بوابة shrray.ly للنقاط في تطبيقاتك ومتاجر البرمجية

ما هي حزمة المطورين (Shrray SDK)؟

هي "حقيبة أدوات" برمجية جاهزة، صُممت لتبسيط عملية الربط التقني بين موقعك الخاص ومنظومة shrray.ly. توفر لك الحزمة كوداً آمناً لإرسال طلبات خصم النقاط (PTS) ومعالجة النتائج دون الحاجة لبناء نظام تشفير معقد من الصفر.

الفئات المستهدفة
  • أصحاب المتاجر: قبول الدفع بالنقاط مقابل المنتجات.
  • مطورو التطبيقات: شحن أرصدة المستخدمين داخل التطبيق.
  • المنصات الخدمية: ربط الاشتراكات بنظام نقاط شرّاي.
مميزات الحزمة
  • تشفير عالي: دعم كامل لتشفير البيانات بصيغة Base64.
  • دقة الوحدات: ضمان إرسال القيم بصيغة PTS المتوافقة.
  • سرعة الإنجاز: كلاسات PHP جاهزة للاستدعاء الفوري.
خارطة طريق المطور (3 خطوات):

1️⃣ ارفع مجلد php-sdk إلى خادمك الخاص.

2️⃣ استخدم example.php كنموذج لصفحة الدفع (Checkout).

3️⃣ خصص example-success.php لتحديث قاعدة بياناتك بعد تأكيد الدفع.

تنبيه هام (المادة 8): مفاتيح الربط البرمجي (Client ID & Secret) ستظهر في إعدادات متجرك فور اعتماد النشاط من قبل إدارة المنصة لضمان الامتثال القانوني.

1. تهيئة طلب خصم النقاط (example.php)

Logic: Create Payment

يستخدم هذا الكود لتوجيه العميل إلى منصة shrray.ly للموافقة على عملية خصم النقاط.

require 'vendor/autoload.php';

use PayMoney\Api\Payer;
use PayMoney\Api\Amount;
use PayMoney\Api\Transaction;
use PayMoney\Api\RedirectUrls;
use PayMoney\Api\Payment;

// تحديد وسيلة الدفع (شرّاي)
$payer = new Payer();
$payer->setPaymentMethod('shrray.ly'); 

// تحديد كمية النقاط (مثال: 50 PTS)
$amountIns = new Amount();
$amountIns->setTotal(50)->setCurrency('PTS'); 

$trans = new Transaction();
$trans->setAmount($amountIns);

$urls = new RedirectUrls();
$urls->setSuccessUrl('http://your-site.com/example-success.php')
     ->setCancelUrl('http://your-site.com/');

$payment = new Payment();
$payment->setCredentials([
    'client_id'     => 'CLIENT_ID_HERE', 
    'client_secret' => 'CLIENT_SECRET_HERE'
])
->setRedirectUrls($urls)
->setPayer($payer)
->setTransaction($trans);

try {
    $payment->create(); 
    header("Location: " . $payment->getApprovedUrl()); 
} catch (\Exception $ex) {
    print $ex->getMessage();
}

2. معالجة نتيجة الدفع (example-success.php)

Logic: Success Callback

يتم تنفيذ هذا الكود بعد عودة العميل بنجاح؛ حيث يتم فك تشفير البيانات وتأكيد رقم العملية.

if ($_GET) {
    // استقبال البيانات وفك تشفير Base64
    $encoded = json_encode($_GET);
    $decoded = json_decode(base64_decode($encoded), TRUE);

    if ($decoded["status"] == 200) {
        // تم خصم النقاط بنجاح: حدث قاعدة بياناتك هنا
        echo "تمت العملية بنجاح! رقم التتبع: " . $decoded["transaction_id"];
    } else {
        echo "فشلت العملية أو تم إلغاء الطلب.";
    }
}
تعليمات الاتصال التقنية:
  1. افتح ملف php-sdk/src/PayMoney/Rest/Connection.php.
  2. تأكد من تعديل ثابت BASE_URL ليشير إلى رابط المطور الرسمي: https://shrray.ly/developer.