---
name: Shipping & Logistics (Saudi)
priority: 2
keywords: smsa, سمسا, aramex, أرامكس, saudi post, البريد السعودي, splonline, dhl, fedex, shipping, شحن, تتبع, tracking, awb, رقم تتبع, التوصيل, delivery, packaging
---

# Saudi Shipping APIs — SMSA / Aramex / SPL / DHL

## متى تستخدم
أي شيء يخص الشحنات: إنشاء AWB، تتبع، حساب التكلفة، إصدار pickup، فلترة شركات لـzip code معين.

## SMSA Express (الأشهر محلياً للـSMB)
Auth: API key (B2B). Base: `https://track.smsaexpress.com/SECOM/SMSAwebService.asmx`
```bash
# تتبع (مجاني، لا يحتاج auth)
exec_command "curl -s 'https://track.smsaexpress.com/portal/Track.aspx?awbNo=$AWB_NUMBER'"

# AWB creation (B2B account)
exec_command "curl -s -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'PassKey=$SMSA_KEY' \
  -d 'RefNo=ORDER123' \
  -d 'SentDate=2026-05-08' \
  -d 'IdNo=1234567890' \
  -d 'CName=Ahmed Saudi' \
  -d 'CCity=Riyadh' \
  -d 'CMobile=0501234567' \
  -d 'CntCode=SA' \
  -d 'CWeight=2' \
  -d 'CCOD=0' \
  'https://track.smsaexpress.com/SECOM/SMSAwebService.asmx/addShipWithRef'"
```

## Aramex
Auth: WSDL/SOAP أو REST (الأحدث). REST Base: `https://ws.dev.aramex.net` (sandbox).
```bash
# تتبع
exec_command "curl -s 'https://www.aramex.com/track/results?ShipmentNumber=$AWB'"

# REST shipment creation (يحتاج credentials)
exec_command "curl -s -X POST -H 'Content-Type: application/json' \
  -d '{\"ClientInfo\":{\"UserName\":\"$ARAMEX_USER\",\"Password\":\"$ARAMEX_PASS\",\"Version\":\"v1.0\",\"AccountNumber\":\"$ARAMEX_ACCT\",\"AccountPin\":\"$ARAMEX_PIN\",\"AccountEntity\":\"RUH\",\"AccountCountryCode\":\"SA\"},\"Shipments\":[{...}]}' \
  'https://ws.dev.aramex.net/ShippingAPI.V2/Shipping/Service_1_0.svc/json/CreateShipments'"
```

## البريد السعودي — Saudi Post (SPL)
- URL تتبع: `https://splonline.com.sa/Track/$AWB`
- API: محدودة للـpartners (Wasel, etc.)

## DHL Express
Auth: API key + secret. Base: `https://express.api.dhl.com/mydhlapi`
```bash
# تتبع
exec_command "curl -s -H 'DHL-API-Key: $DHL_KEY' \
  'https://api-eu.dhl.com/track/shipments?trackingNumber=$AWB'"

# Rate quote
exec_command "curl -s -X POST -H 'DHL-API-Key: $DHL_KEY' -H 'Content-Type: application/json' \
  -d '{\"customerDetails\":{\"shipperDetails\":{\"postalCode\":\"11564\",\"cityName\":\"Riyadh\",\"countryCode\":\"SA\"},\"receiverDetails\":{\"postalCode\":\"10001\",\"cityName\":\"New York\",\"countryCode\":\"US\"}},\"plannedShippingDateAndTime\":\"2026-05-10T13:00:00 GMT+03:00\",\"unitOfMeasurement\":\"metric\",\"isCustomsDeclarable\":true,\"packages\":[{\"weight\":2,\"dimensions\":{\"length\":30,\"width\":20,\"height\":10}}]}' \
  'https://express.api.dhl.com/mydhlapi/rates'"
```

## أنماط شائعة

### "تتبع الطلب #12345" (multi-carrier)
```python
def detect_carrier(awb: str) -> str:
    if awb.startswith('SA'):  return 'smsa'
    if len(awb) == 10 and awb.isdigit(): return 'aramex'
    if awb.startswith('RR'):  return 'splonline'
    if awb.startswith('DHL') or len(awb) == 10: return 'dhl'
    return 'unknown'

# ابني URL مناسب وافتحه أو scrape
```

### "أنشئ AWB لطلب جديد"
1. اختر carrier حسب الـorigin/destination.
2. تأكد من أبعاد/وزن العميل.
3. احسب الـCOD (cash on delivery) لو الطلب فلوس.
4. POST shipment، خذ AWB.
5. حدّث الـorder في Salla/Zid/Shopify بـtracking.
6. ابعث للعميل الـAWB + تتبع URL.

### "كم تكلفة الشحن من جدة لحمص"
DHL/Aramex rate quote بـorigin/destination.

### Saudi domestic shipping rates (تقريبية، 2026)
| الوزن | SMSA | Aramex | SPL |
|---|---|---|---|
| 0-1 kg | 25 ر.س | 30 ر.س | 22 ر.س |
| 1-3 kg | 35 ر.س | 45 ر.س | 30 ر.س |
| 3-5 kg | 50 ر.س | 60 ر.س | 45 ر.س |
| COD حد | 5,000 ر.س | 10,000 ر.س | 3,000 ر.س |

## SLA متوقعة
- **داخل المدينة**: 24-48 ساعة (SMSA, Aramex)
- **بين المدن (نفس المنطقة)**: 2-3 أيام
- **مدن بعيدة (مثلاً جدة-تبوك)**: 3-5 أيام
- **دولي (DHL Express)**: 2-5 أيام

## أمثلة
- "تتبع SMSA-XYZ123" → افتح URL أو curl، استخرج status.
- "أنشئ شحنة لـorder #5000 من Salla عبر SMSA" → اقرأ order, POST AWB, update Salla.
- "كم تكلفة شحن 2 كيلو من الرياض إلى جدة" → جدول أو rate quote API.

## القواعد الذهبية
- ❌ **ممنوع** إنشاء AWB بدون موافقة المالك على التكلفة (لو > 100 ر.س).
- ✅ **حدّث الـorder بـtracking** فوراً بعد إنشاء AWB.
- ✅ **ابعث للعميل** الـAWB + رابط تتبع + ETA.
- ✅ **متابعة الـshipments العالقة** أكثر من 5 أيام — اعمل query يومياً، نبّه المالك.
