---
name: Salla & Zid (Saudi E-commerce)
priority: 2
keywords: salla, salla.sa, salla store, zid, زد, سلة, متجر سلة, متجر زد, online store, متجر إلكتروني, ecommerce, online shop, sa ecom, متجر الكتروني سعودي
---

# Salla & Zid — Saudi E-commerce APIs

## متى تستخدم
أي شيء في متجر Salla أو Zid — products, orders, customers, shipping, refunds, broadcast notifications.

## Salla
Auth: OAuth2 access token من Salla Partners. Base: `https://api.salla.dev/admin/v2`
```bash
# آخر الطلبات
exec_command "curl -s -H 'Authorization: Bearer $SALLA_TOKEN' -H 'Accept: application/json' \
  'https://api.salla.dev/admin/v2/orders?per_page=20'"

# تفاصيل طلب
exec_command "curl -s -H 'Authorization: Bearer $SALLA_TOKEN' \
  'https://api.salla.dev/admin/v2/orders/$ORDER_ID'"

# تحديث حالة الطلب
exec_command "curl -s -X PUT -H 'Authorization: Bearer $SALLA_TOKEN' -H 'Content-Type: application/json' \
  -d '{\"slug\":\"shipped\",\"note\":\"شُحن عبر سمسا\"}' \
  'https://api.salla.dev/admin/v2/orders/$ORDER_ID/status'"

# قائمة المنتجات
exec_command "curl -s -H 'Authorization: Bearer $SALLA_TOKEN' \
  'https://api.salla.dev/admin/v2/products?per_page=50'"

# تحديث مخزون
exec_command "curl -s -X PUT -H 'Authorization: Bearer $SALLA_TOKEN' -H 'Content-Type: application/json' \
  -d '{\"quantity\":50}' \
  'https://api.salla.dev/admin/v2/products/$PRODUCT_ID/quantity'"

# قائمة العملاء
exec_command "curl -s -H 'Authorization: Bearer $SALLA_TOKEN' \
  'https://api.salla.dev/admin/v2/customers?per_page=50'"
```

## Zid
Auth: OAuth2. Base: `https://api.zid.sa/v1`
```bash
# الطلبات
exec_command "curl -s -H 'Authorization: $ZID_TOKEN' -H 'X-Manager-Token: $ZID_MANAGER_TOKEN' \
  'https://api.zid.sa/v1/managers/store/orders'"

# المنتجات
exec_command "curl -s -H 'Authorization: $ZID_TOKEN' -H 'X-Manager-Token: $ZID_MANAGER_TOKEN' \
  'https://api.zid.sa/v1/products'"

# تحديث طلب لحالة "تم الشحن"
exec_command "curl -s -X PUT -H 'Authorization: $ZID_TOKEN' -H 'X-Manager-Token: $ZID_MANAGER_TOKEN' -H 'Content-Type: application/json' \
  -d '{\"order_status\":{\"code\":\"shipped\"}}' \
  'https://api.zid.sa/v1/managers/store/orders/$ORDER_ID/status'"
```

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

### 1. WhatsApp → Order tracking
العميل يرسل "وين طلبي #12345" عبر WhatsApp.
```bash
# اقرأ من Salla
ORDER=$(curl -s -H 'Authorization: Bearer $SALLA_TOKEN' "https://api.salla.dev/admin/v2/orders/12345")
# استخرج status + tracking + ETA
# رد بقالب موجز:
"طلبك #12345:
✅ شُحن أمس عبر سمسا
📦 رقم التتبع: SMSA-XXX
📅 التسليم المتوقع: بعد بكرة
🔗 https://www.smsaexpress.com/sa/track?tracking=XXX"
```

### 2. تنبيه المالك بطلبات جديدة
```bash
# webhook من Salla → Muassis → notify المالك
"📦 طلب جديد!
العميل: أحمد محمد
المبلغ: 450 ر.س
المنتجات: عطر العود (×2)
الحالة: pending payment"
```

### 3. مزامنة Salla → ERP (Zoho Books / QuickBooks)
- Webhook على Salla `order.created`.
- Muassis يستلم → ينشئ invoice في Zoho تلقائياً.
- يرد على الـwebhook بالـinvoice number.

### 4. Abandoned cart recovery
- Pull `orders` بحالة `abandoned` كل 6 ساعات.
- Send WhatsApp: "أحمد، نسيت سلتك! استكمل خلال 24 ساعة وعندك خصم 10% بكود SAVE10."

## التكامل مع شحن (Saudi)
- **سمسا (SMSA)**: API tracking link `https://www.smsaexpress.com/sa/track?tracking=<awb>`
- **أرامكس**: `https://www.aramex.com/track/results?ShipmentNumber=<awb>`
- **البريد السعودي (SPL)**: `https://splonline.com.sa/Track/<awb>`
- **DHL**: `https://www.dhl.com/sa-en/home/tracking.html?tracking-id=<awb>`

## أمثلة
- "كم طلب اليوم في Salla" → GET orders بـcreated_at = today.
- "حدّث مخزون منتج العود إلى 50" → PUT /products/$ID/quantity.
- "ابعث للعميل رابط التتبع" → اقرأ tracking من order، نسّق رابط، استدعِ `whatsapp_send`.
- "زامن منتجات Zid مع Salla" → loop: read Zid products → upsert Salla.

## القواعد الذهبية
- ❌ **ممنوع** تغيير حالة طلب لـ"مكتمل" بدون تأكيد فعلي للتسليم — يكسر سياسة الإرجاع.
- ❌ **لا تحذف منتج** بدون مراجعة الـorders المرتبطة.
- ✅ **خزّن webhook events** في `<dataDir>/webhooks/` للـaudit log.
- ✅ **استخدم rate limit** (Salla: 50 req/min، Zid: 100 req/min) — تجنب الـ429.
