وثائق ربط المتاجر والمنصات (Waselha Merchant API)

مرحباً بك في بوابة مطوري منصة وصلها. يوفر هذا الدليل الفني واجهة ربط برمجية قوية وآمنة تتيح للتجار والمطورين إمكانية ربط متاجرهم الإلكترونية (مثل WooCommerce، Shopify، Magento) لتوليد بوالص الشحن وإرسال الشحنات وتتبعها تلقائياً بالكامل.

الرابط الأساسي للـ API: https://api.wsalha.com/

1. المصادقة والأمان

تتم جميع العمليات البرمجية بأمان من خلال إرسال مفتاح الربط الخاص بك في ترويسات الطلب (Headers) لكل طلب HTTP. يمكنك توليد مفتاح الربط من لوحة تحكم متجر التاجر تحت تبويب الربط البرمجي (API).

يجب إرسال الترويسة التالية مع كل طلب:

X-API-Key: wsalha_live_your_actual_api_key_goes_here
Content-Type: application/json

2. الأخطاء والردود الموحدة

جميع الردود ترجع بتنسيق JSON موحد لتبسيط المعالجة البرمجية:

الرد الناجح (Success)
{
  "success": true,
  "data": {
    "trackingNumber": "WSL100239",
    "status": "Created"
  }
}
الرد الفاشل (Failure)
{
  "success": false,
  "error": {
    "code": "INVALID_GOVERNORATE",
    "message": "المحافظة المحددة غير نشطة."
  }
}
POST

حساب تكلفة الشحن المتوقعة

يستخدم لمعرفة رسوم التوصيل والحد الأدنى المسموح به للتوصيل وعمولة الدفع عند الاستلام (COD Fee) للزبون قبل تأكيد الطلب.

POST /v1/shipments/calculate-fee
مثال للـ Payload المرسل:
{
  "governorateId": "85ef056b-a25e-4efb-9529-67a80b8529aa",
  "districtId": "8db3e33e-1175-47e1-8409-d4ee4d4f8fb2",
  "codAmount": 1500.00
}
POST

إنشاء شحنة جديدة

يستخدم لتسجيل طلب التوصيل في نظام وصلها تلقائياً وطباعة البوليسة للتاجر.

POST /v1/shipments
مثال للـ Payload المرسل:
{
  "customerName": "أحمد محمد",
  "customerPhone": "01098765432",
  "governorateId": "85ef056b-a25e-4efb-9529-67a80b8529aa",
  "districtId": "8db3e33e-1175-47e1-8409-d4ee4d4f8fb2",
  "deliveryAddress": "12 شارع عباس العقاد، مدينة نصر، القاهرة",
  "productDescription": "ساعة ذكية وسماعة لاسلكية",
  "isFragile": true,
  "codAmount": 2500.00,
  "shippingFee": 50.00,
  "shippingPayer": 1, // 1: Merchant, 2: Recipient
  "deliverySpeed": 1  // 1: Standard, 2: Express
}
GET

تتبع الشحنة

يستعلم عن تفاصيل الشحنة وحالتها الحالية وسجل تتبع التغييرات برقم التتبع.

GET /v1/shipments/{trackingNumber}
GET

تحميل بوليسة الشحن (Label)

يرجع رابطاً مباشراً لطباعة أو تنزيل بوليسة الشحن الرسمية للشحنة بصيغة PDF لوضعها على الطرد.

GET /v1/shipments/{shipmentId}/label

3. إشعارات المتاجر وتأمين التوقيع (Webhooks)

عندما تقوم بتسجيل رابط الويبهوك الخاص بك، سيقوم سيرفر وصلها بإرسال طلب HTTP POST آمن لمتجرك في كل مرة تتغير فيها حالة الشحنة.

التحقق من التوقيع الأمني (Security Signature):

لمنع أي محاولة هجوم أو انتحال شخصية، نقوم بإرسال توقيع رقمي مشفر في الترويسة X-Wsalha-Signature. يتم حساب هذا التوقيع باستخدام خوارزمية SHA256 HMAC مستخدماً سرّ التوقيع المخصص والمشترك للرابط (Webhook Secret).

مثال بلغة PHP للتحقق من التوقيع بمتجرك:
<?php
// 1. استقبل محتوى الطلب
$payload = file_get_contents('php://input');

// 2. اقرأ التوقيع من الـ Header
$headers = getallheaders();
$receivedSignature = isset($headers['X-Wsalha-Signature']) ? $headers['X-Wsalha-Signature'] : '';

// 3. احسب التوقيع المتوقع باستخدام السر المشترك الخاص بك
$secretKey = "YOUR_SHARED_WEBHOOK_SIGNING_SECRET";
$expectedSignature = hash_hmac('sha256', $payload, $secretKey);

// 4. تأكد من تطابقهما التام
if (hash_equals($expectedSignature, $receivedSignature)) {
    // الطلب آمن وصادر من سيرفر وصلها فعلاً! قم بتحديث الحالة داخلياً
    $data = json_decode($payload, true);
    http_response_code(200);
} else {
    // الطلب غير مصرح أو مشبوه! ارفضه فوراً
    http_response_code(401);
}