أول تسعيرة

في هذه الجولة سترسل طلب تسعير لطرد وزنه 2.5 كغ من الرياض إلى دبي، ثم نقرأ الاستجابة سطرًا سطرًا.

قبل أن تبدأ

تحتاج مفتاح API صالحًا — راجع صفحة المصادقة إن لم يكن جاهزًا لديك.

الطلب

نقطة النهاية هي POST /api/v1/rates وتستقبل المسار والطرود بوحدات موحّدة: الوزن بالكيلوغرام والأبعاد بالسنتيمتر. هذا هو الطلب كاملًا:

{
  "origin": { "country": "SA", "city": "Riyadh", "short_address": "RRDA2929" },
  "destination": { "country": "AE", "city": "Dubai", "line1": "Al Wasl Road 214" },
  "parcels": [
    { "weight_kg": 2.5, "length_cm": 30, "width_cm": 20, "height_cm": 15 }
  ],
  "declared_value": 450,
  "declared_value_currency": "SAR",
  "incoterm": "DAP",
  "hs_codes": ["330499"],
  "cod_amount": 0
}

أهم الحقول:

• origin / destination — بلد ومدينة كل طرف. العنوان المختصر RRDA2929 هو عنوان وطني سعودي للمنشأ.
• parcels — مصفوفة الطرود؛ يجوز أكثر من طرد في الطلب الواحد.
• declared_value — قيمة البضاعة المصرّح بها — تدخل في التأمين والتخليص للشحن الدولي.
• incoterm — شرط التسليم التجاري: DAP هنا يعني أن البائع يوصل والمشتري يتحمل رسوم الاستيراد.
• hs_codes — رموز النظام المنسق للبضاعة — 330499 هو رمز مستحضرات التجميل.

أرسل الطلب

curl -s -X POST "https://manfath.example/api/v1/rates" \
  -H "Authorization: Bearer $MANFATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "origin": { "country": "SA", "city": "Riyadh", "short_address": "RRDA2929" },
  "destination": { "country": "AE", "city": "Dubai", "line1": "Al Wasl Road 214" },
  "parcels": [
    { "weight_kg": 2.5, "length_cm": 30, "width_cm": 20, "height_cm": 15 }
  ],
  "declared_value": 450,
  "declared_value_currency": "SAR",
  "incoterm": "DAP",
  "hs_codes": ["330499"],
  "cod_amount": 0
}'

الاستجابة

تعيد الواجهة مصفوفة quotes فيها تسعيرة لكل خدمة مؤهلة للمسار. لمسار خليجي مثل هذا ستصلك تسعيرة سريع إكسبريس الخليجية:

{
  "quotes": [
    {
      "quote_id": "cmdg7f3k2a0001x8p9zr41mstq",
      "carrier": { "code": "SARIE", "name_ar": "سريع إكسبريس", "name_en": "Sarie Express" },
      "service": { "code": "EXP_GCC", "name_ar": "إكسبريس خليجي", "name_en": "GCC Express", "mode": "express" },
      "transit_days": { "min": 2, "max": 5 },
      "weights": {
        "actual_kg": 2.5,
        "volumetric_kg": 1.8,
        "chargeable_kg": 2.5,
        "volumetric_divisor": 5000,
        "weight_break_applied": "upto_5_kg"
      },
      "breakdown": [
        { "code": "base", "label_en": "Base charge", "label_ar": "الرسم الأساسي", "amount_sar": 15 },
        { "code": "weight_charge", "label_en": "Weight charge", "label_ar": "رسم الوزن", "amount_sar": 50 },
        { "code": "fuel_surcharge", "label_en": "Fuel surcharge", "label_ar": "رسم الوقود", "amount_sar": 9.75 },
        { "code": "vat", "label_en": "VAT 15%", "label_ar": "ضريبة القيمة المضافة 15%", "amount_sar": 11.21 }
      ],
      "total_sar": 85.96,
      "currency": "SAR",
      "expires_at": "2026-07-26T10:15:00+03:00"
    }
  ]
}

قراءة التسعيرة بندًا بندًا

التالي: أنشئ شحنة