التنقل في التوثيق

تعرض الآن: عمق السوق

البدء

أنشئ حساباً واحصل على مفتاح API ثم نفّذ طلبك الأول. بعد ذلك يمكنك الانتقال من نقاط REST الأساسية إلى حزم التطوير والأتمتة والبث اللحظي مع نمو منتجك.

ابدأ من هنا

الطلب الأول

احصل خلال دقائق على سعر لحظي لسهم سعودي باستخدام رمزه.

البناء

واجهة API الأساسية

الأسهم والصفقات وعمق السوق وملخصات السوق والبيانات التاريخية وبيانات الشركات والقوائم المالية.

لحظي

WebSocket

قنوات الأسهم والصفقات وعمق السوق، وحدود الاشتراك، ومعالجة إعادة الاتصال والأخطاء.

التنبيهات وWebhooks

سير عمل الإشعارات

Webhooks للأحداث وقواعدها وسلوك التسليم وحدوده.

بدء سريع

أنشئ حساباً مجانياً
احصل على مفتاح API من لوحة التحكم
نفّذ أول طلب API
تصفح أمثلة الكود على GitHub

عنوان API الأساسي

text

https://api.sahmk.sa/api/v1

ستستمر عمليات التكامل الحالية التي تستخدم app.sahmk.sa في العمل.

طلبك الأول

curl -X GET "https://api.sahmk.sa/api/v1/quote/2222/" \
     -H "X-API-Key: YOUR_API_KEY"

الأمثلة الكاملة متاحة على GitHub ←

يستخدم مسار السعر رمز السهم. إذا احتجت إلى مطابقة الاسم أو الاسم البديل، فأرسله عبر معامل الاستعلام identifier.

الاستجابة المتوقعة

json

{
  "symbol": "2222",
  "name_en": "Saudi Arabian Oil Co",
  "price": 26.6,
  "change_percent": 0.0,
  "volume": 6601208,
  "updated_at": "2026-08-12T12:20:00+00:00",
  "is_delayed": false
}

نجاح: لقد حصلت الآن على بيانات مباشرة للسوق السعودي من سهمك. يمكنك بعد ذلك استخدام SDK لتكامل أسرع، أو استكشاف نقاط النهاية الأساسية، أو الانتقال إلى WebSocket عند الحاجة إلى تحديثات متدفقة.

ملاحظة حول الالتباس: إذا طابق المعرّف أكثر من شركة، فأرسل رمز التداول الدقيق لإزالة الالتباس.

الخطوة التالية لعمليات البيانات: استخدم مركز البيانات من لوحة التحكم عندما تحتاج إلى تصدير مجمّع أو سير عمل منظم لمجموعات البيانات.

استخدم حزمة التطوير

ابدأ باستخدام Python SDK أو CLI لتقليل الكود التمهيدي.

طوّر باستخدام REST

أضف الأسعار وملخصات السوق وبيانات الشركات والبيانات التاريخية.

انتقل إلى WebSocket اللحظي

استخدم قنوات الأسعار والصفقات وعمق السوق المتدفقة عندما لا يعود الاستعلام الدوري كافياً.

المصادقة

تتطلب جميع طلبات API المصادقة باستخدام مفتاح API. أرسل مفتاحك في X-API-Key .

http

X-API-Key: YOUR_API_KEY

أنواع مفاتيح API:

shmk_live_* - مفاتيح الإنتاج
shmk_test_* - مفاتيح الاختبار (تمنح الوصول إلى البيانات نفسها، ويُحتسب استخدامها ضمن الحصة اليومية المشتركة للحساب)

curl -X GET "https://api.sahmk.sa/api/v1/quote/2222/" \
     -H "X-API-Key: YOUR_API_KEY"

حزمة Python وواجهة الأوامر

ابدأ هنا إذا أردت أسرع طريق من مفتاح API إلى تكامل يعمل فعلياً. تمنحك حزمة SDK الرسمية عميلاً أبسط، بينما تفيد CLI في الاختبارات والعروض والأدوات المؤتمتة.

bash

pip install -U sahmk
export SAHMK_API_KEY="your_api_key"
sahmk quote "Saudi Aramco"

إذا لم تجد محلياً ميزة موثقة حديثاً في SDK/CLI، فنفّذ pip install -U sahmk للترقية.

حزمة Python:

python

from sahmk import SahmkClient

client = SahmkClient(api_key="YOUR_API_KEY")

directory = client.companies(search="aramco", market="TASI", limit=20, offset=0)
symbol = directory["results"][0]["symbol"]

print(client.quote("أرامكو السعودية"))

إذا لم تكن واثقاً من رمز الإدخال، فاستدعِ client.companies(...) أولاً لاكتشاف رمز صالح قبل استدعاءات السعر أو الشركة.

استخدم هذا الخيار عندما: تريد كوداً تمهيدياً أقل من REST الخام، أو سير عمل مضبوط الأنواع في Python، أو وصولاً سريعاً من سطر الأوامر إلى الأسعار وبيانات السوق.

تقبل دوال الأسعار معرّفات متعددة: الرمز أو الاسم العربي أو الإنجليزي أو الاسم البديل. استخدم الرمز عندما يكون المعرّف ملتبساً.

الأمثلة الكاملة: github.com/sahmk-sa/sahmk-python

الذكاء الاصطناعي والوكلاء

استخدم سهمك داخل Claude Desktop وCursor والعملاء الآخرين المتوافقين مع MCP. وللاستخدام المباشر من الوكلاء، استخدم خادم MCP لاستدعاء الأدوات و/api-docs.mdللتوثيق القابل للقراءة آلياً.

bash

pip install -U sahmk-mcp

إذا رفضت أدوات MCP معاملات أحدث، مثل خيارات الفترة التاريخية، فنفّذ pip install -U sahmk-mcp ثم أعد تشغيل عميل MCP.

الحزمة: pypi.org/project/sahmk-mcp · درس البدء السريع مع MCP

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMK_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

أضف إلى ملف مشروعك .cursor/mcp.json

json

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMK_API_KEY": "your_api_key_here"
      }
    }
  }
}

استخدم هذا الخيار عندما: يريد فريقك إتاحة سهمك داخل سير عمل الذكاء الاصطناعي أو مساعدي البحث أو أدوات الوكلاء دون بناء طبقة تكامل إضافية.

استخدم companies_list لاكتشاف الرموز قبل أدوات الأسعار باستخدام search وmarket وlimit وoffset.

الأسهم

احصل على أسعار وبيانات التداول الحالية لشركة واحدة أو عدة شركات. راجع WebSocket اللحظي للحصول على تحديثات متدفقة.

GET /quote/{symbol}/

Free

احصل على السعر الحالي وبيانات التداول لرمز سهم واحد.

نقطة النهاية

https://api.sahmk.sa/api/v1/quote/2222/?identifier=أرامكو

المعاملات

(*) مطلوب

المعامل	النوع	مثال
symbol *	string	2222
identifier	string	أرامكو
data_mode	string	delayed

استخدم symbol عندما تكون مطابقة المعرّف ملتبسة.
data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.

توفر البيانات حسب الباقة:

Free / Starter:أسعار متأخرة (نحو 15 دقيقة)
Pro+:أسعار لحظية

200 OKapplication/json

{
  "symbol": "2222",
  "name": "أرامكو السعودية",
  "name_en": "Saudi Arabian Oil Co",
  "price": 26.6,
  "change": 0.0,
  "change_percent": 0.0,
  "open": 26.6,
  "high": 26.68,
  "low": 26.52,
  "previous_close": 26.6,
  "volume": 6601208,
  "value": 175637052.96,
  "bid": 26.6,
  "bid_size": 9181,
  "ask": 26.62,
  "ask_size": 38155,
  "liquidity": {
    "inflow_value": 99498351.21,
    "inflow_volume": 3739041,
    "inflow_trades": 4858,
    "outflow_value": 76138701.51,
    "outflow_volume": 2862167,
    "outflow_trades": 3472,
    "net_value": 23359649.699999988
  },
  "updated_at": "2026-08-12T12:20:00+00:00",
  "is_delayed": false,
  "resolved_instrument": {
    "input": "أرامكو",
    "symbol": "2222",
    "name": "أرامكو",
    "match_type": "alias_exact",
    "confidence": "high"
  }
}

عرض خطأ عدم توفر بيانات السعر مؤقتاً

json

{
  "error": {
    "code": "PRICE_DATA_TEMPORARILY_UNAVAILABLE",
    "message": "Price data for '2222' is temporarily unavailable. Please retry shortly."
  }
}

GET /quotes/

Starter+

احصل على أسعار عدة شركات في طلب واحد. يتطلب ذلك باقة Starter أو أعلى.

الخيار البديل للباقة المجانية: GET /quote/{symbol}/ للحصول على سعر شركة واحدة.

نقطة النهاية

https://api.sahmk.sa/api/v1/quotes/?symbols=2222,1120

المعاملات

(*) مطلوب

المعامل	النوع	مثال
symbols *	string	2222,1120
identifiers	string	أرامكو، الراجحي
data_mode	string	delayed

استخدم إما symbols أو identifiers، وليس كليهما.
data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.

200 OKapplication/json

{
  "quotes": [
    {
      "symbol": "2222",
      "name": "شركة الزيت العربية السعودية",
      "name_en": "Saudi Arabian Oil Co",
      "price": 26.6,
      "change": 0.0,
      "change_percent": 0.0,
      "high": 26.68,
      "low": 26.52,
      "bid": 26.6,
      "ask": 26.62,
      "bid_size": 9181,
      "ask_size": 38155,
      "volume": 6601208,
      "net_liquidity": 23359649.699999988,
      "updated_at": "2026-08-12T13:00:00+00:00",
      "is_delayed": false
    },
    {
      "symbol": "1120",
      "name": "مصرف الراجحي",
      "name_en": "Al Rajhi Banking & Investment Corp SJSC",
      "price": 64.05,
      "change": -0.05,
      "change_percent": -0.08,
      "high": 64.3,
      "low": 63.7,
      "bid": 63.95,
      "ask": 64.05,
      "bid_size": 15,
      "ask_size": 43300,
      "volume": 3775688,
      "net_liquidity": -47806410.94999999,
      "updated_at": "2026-08-12T13:00:00+00:00",
      "is_delayed": false
    }
  ],
  "count": 2,
  "max_symbols": 50,
  "requested_count": 2
}

حدود الطلبات المجمّعة

يقتصر الطلب على 50 رمزاً. إذا أرسلت عدداً أكبر، فستتضمن الاستجابة أيضاً truncated: true و warning يوضح أنه تمت معالجة أول 50 رمزاً فقط.

مطابقة المعرّفات

عند استخدام identifiers ، تتضمن الاستجابة أيضاً كائن resolution يحتوي على requested_count, resolved_count, ambiguous، و not_found.

هل تحتاج إلى الرموز؟ استخدم GET /companies/

قواعد سريعة: استخدم معاملات المسار لمورد واحد (مثل /quote/{symbol}/)، واستخدم معاملات الاستعلام لتصفية القوائم (مثل /events/?symbol=2222&limit=20). جُمعت أخطاء HTTP/API الشائعة في قسم رموز الأخطاء.

الصفقات

احصل على أحدث صفقات رمز معين. راجع WebSocket اللحظي للتحديثات المتدفقة.

GET /market/trades/{symbol}/

Pro+

اجلب أحدث صفقات رمز واحد، مرتبة من الأحدث.

نقطة النهاية

https://api.sahmk.sa/api/v1/market/trades/2222/?limit=1

المعاملات

(*) مطلوب

المعامل	النوع	مثال
symbol *	string	2222
limit	integer	5

limit القيمة الافتراضية to 50 (الحد الأقصى 200). تُرتب النتائج من الأحدث.

200 OKapplication/json

{
  "symbol": "2222",
  "updated_at": "2026-08-12T12:19:10+00:00",
  "count": 1,
  "events": [
    {
      "event_time": "2026-08-12T12:19:10+00:00",
      "price": 26.6,
      "quantity": 20,
      "value": 532.0,
      "side": "buy"
    }
  ],
  "summary": {
    "event_count": 1,
    "trade_quantity": 20,
    "trade_value": 532.0,
    "latest_event_time": "2026-08-12T12:19:10+00:00"
  }
}

عرض أخطاء نقطة النهاية

json

{
  "error": {
    "code": "INVALID_SYMBOL",
    "message": "Stock symbol '9999' not found."
  }
}

{
  "error": {
    "code": "INVALID_LIMIT",
    "message": "limit must be a valid integer."
  }
}

السوق

احصل على بيانات السوق الشاملة، بما فيها قيم المؤشرات وأبرز التحركات وأداء القطاعات.

GET /market/summary/?index=TASI

Free

احصل على قيمة مؤشر السوق وحجم التداول واتجاه السوق.

نقطة النهاية

https://api.sahmk.sa/api/v1/market/summary/?index=TASI

المعاملات

(*) مطلوب

المعامل	النوع	مثال
index	string	TASI
data_mode	string	delayed

القيم المدعومة: TASI, NOMU. القيمة الافتراضية TASI.
data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.

200 OKapplication/json

{
  "index": "TASI",
  "is_delayed": false,
  "timestamp": "2026-08-12T12:20:00+00:00",
  "index_value": 10844.12,
  "index_change": 10.94,
  "index_change_percent": 0.1,
  "total_volume": 256387075,
  "advancing": 141,
  "declining": 112,
  "unchanged": 17,
  "market_mood": "Bullish"
}

GET /market/gainers/?limit=1&index=TASI

Free

احصل على أكثر الأسهم ارتفاعاً حسب نسبة التغير.

نقطة النهاية

https://api.sahmk.sa/api/v1/market/gainers/?limit=1&index=TASI

المعاملات

(*) مطلوب

المعامل	النوع	مثال
index	string	TASI
limit	number	1
data_mode	string	delayed

data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.

200 OKapplication/json

{
  "index": "TASI",
  "is_delayed": false,
  "gainers": [
    {
      "symbol": "6040",
      "name": "شركة تبوك للتنمية الزراعية",
      "name_en": "Tabuk Agriculture Development C",
      "price": 9.13,
      "change": 0.83,
      "change_percent": 10.0,
      "volume": 4846179,
      "updated_at": "2026-08-12T13:00:00+00:00"
    }
  ],
  "count": 1
}

GET /market/losers/?limit=1&index=TASI

Free

احصل على أكثر الأسهم انخفاضاً حسب نسبة التغير.

نقطة النهاية

https://api.sahmk.sa/api/v1/market/losers/?limit=1&index=TASI

المعاملات

(*) مطلوب

المعامل	النوع	مثال
index	string	TASI
limit	number	1
data_mode	string	delayed

data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.

200 OKapplication/json

{
  "index": "TASI",
  "is_delayed": false,
  "losers": [
    {
      "symbol": "4011",
      "name": "شركة لازوردي للمجوهرات",
      "name_en": "L'azurde Company for Jewelry SJSC",
      "price": 10.43,
      "change": -0.47,
      "change_percent": -4.31,
      "volume": 369026,
      "updated_at": "2026-08-12T13:00:00+00:00"
    }
  ],
  "count": 1
}

GET /market/volume/?limit=1&index=TASI

Free

احصل على أعلى الأسهم حسب حجم التداول.

نقطة النهاية

https://api.sahmk.sa/api/v1/market/volume/?limit=1&index=TASI

المعاملات

(*) مطلوب

المعامل	النوع	مثال
index	string	TASI
limit	number	1
data_mode	string	delayed

data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.

200 OKapplication/json

{
  "index": "TASI",
  "is_delayed": false,
  "stocks": [
    {
      "symbol": "6015",
      "name": "شركة أمريكانا للمطاعم العالمية بي إل سي - شركة أجنبية",
      "name_en": "AMERICANA",
      "price": 2.38,
      "change": 0.07,
      "change_percent": 3.03,
      "volume": 22562421,
      "updated_at": "2026-08-12T13:00:00+00:00"
    }
  ],
  "count": 1
}

GET /market/value/?limit=1&index=TASI

Free

احصل على أعلى الأسهم حسب قيمة التداول بالريال السعودي.

نقطة النهاية

https://api.sahmk.sa/api/v1/market/value/?limit=1&index=TASI

المعاملات

(*) مطلوب

المعامل	النوع	مثال
index	string	TASI
limit	number	1
data_mode	string	delayed

data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.

200 OKapplication/json

{
  "index": "TASI",
  "is_delayed": false,
  "stocks": [
    {
      "symbol": "2380",
      "name": "شركة رابغ للتكرير والبتروكيماويات",
      "name_en": "Rabigh Refining and Petrochemic",
      "price": 17.6,
      "change": 0.51,
      "change_percent": 2.98,
      "volume": 14502060,
      "value": 257478357.3,
      "updated_at": "2026-08-12T13:00:00+00:00"
    }
  ],
  "count": 1
}

GET /market/sectors/?index=TASI

Free

احصل على أداء القطاعات وإحصاءاتها.

نقطة النهاية

https://api.sahmk.sa/api/v1/market/sectors/?index=TASI

المعاملات

(*) مطلوب

المعامل	النوع	مثال
index	string	TASI
data_mode	string	delayed

data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.

200 OKapplication/json

{
  "index": "TASI",
  "is_delayed": false,
  "sectors": [
    {
      "sector_name": "Insurance",
      "sector_name_ar": "التأمين",
      "change_percent": 1.49,
      "avg_change_percent": 0.02,
      "volume": 9819397,
      "num_stocks": 26
    }
  ],
  "count": 20
}

عرض خطأ نقطة النهاية (index غير صالح)

json

{
  "error": {
    "code": "INVALID_INDEX",
    "message": "Invalid index 'XYZ'. Supported values: TASI, NOMU."
  }
}

عمق السوق

احصل على لقطات عمق دفتر الأوامر لرمز معين مع التحكم في عدد المستويات. راجع WebSocket اللحظي للتحديثات المتدفقة.

GET /market/depth/{symbol}/

Pro+

اجلب لقطات عمق السوق لرمز معين بعدد المستويات المطلوب.

متطلبات الوصول

يلزم اشتراك Pro أو أعلى، كما يجب تفعيل وصول عمق السوق عبر REST لحسابك. أهلية الباقة وحدها لا تفعّل صلاحية بيانات السوق هذه.

نقطة النهاية

https://api.sahmk.sa/api/v1/market/depth/2222/?levels=5

المعاملات

(*) مطلوب

المعامل	النوع	مثال
symbol *	string	2222
levels	integer	5 (or any numeric value)

اختر العمق الذي تحتاجه باستخدام levels (عادةً 5 أو حتى 20). قد يكون العمق المعاد أقل بحسب صلاحيتك وتوفر بيانات السوق حالياً.

توفر البيانات حسب الباقة:

Pro:مؤهل لأفضل 5 مستويات من العمق. طلب الوصول
Business+:مؤهل لبيانات Premium لأفضل 20 مستوى من العمق. طلب الوصول

200 OKapplication/json

{
  "symbol": "2222",
  "updated_at": "2026-08-12T12:19:54.982770+00:00",
  "session": "atc",
  "book_state": "normal",
  "levels": 5,
  "best_bid": 26.6,
  "best_ask": 26.62,
  "spread": 0.02,
  "spread_bps": 7.52,
  "total_bid_quantity_top5": 241514,
  "total_ask_quantity_top5": 491802,
  "total_bid_quantity": 241514,
  "total_ask_quantity": 491802,
  "level_imbalance": -0.3413,
  "level_imbalance_top5": -0.3413,
  "bids": [
    { "level": 0, "price": 26.6, "quantity": 9181, "order_count": 18 },
    { "level": 1, "price": 26.58, "quantity": 228, "order_count": 3 },
    { "level": 2, "price": 26.56, "quantity": 13363, "order_count": 34 },
    { "level": 3, "price": 26.54, "quantity": 4133, "order_count": 21 },
    { "level": 4, "price": 26.52, "quantity": 214609, "order_count": 120 }
  ],
  "asks": [
    { "level": 0, "price": 26.62, "quantity": 38155, "order_count": 17 },
    { "level": 1, "price": 26.64, "quantity": 25208, "order_count": 12 },
    { "level": 2, "price": 26.66, "quantity": 17877, "order_count": 36 },
    { "level": 3, "price": 26.68, "quantity": 203743, "order_count": 53 },
    { "level": 4, "price": 26.7, "quantity": 206819, "order_count": 72 }
  ],
  "entitled_levels": 5
}

ملاحظات تقديم بيانات العمق

تعيد API أفضل لقطة متاحة وقت الطلب.
قد يكون العمق المعاد أقل من المطلوب بحسب الصلاحية وتوفر بيانات السوق حالياً.

عرض أخطاء نقطة النهاية

json

{
  "error": {
    "code": "DEPTH_NOT_AVAILABLE",
    "message": "No usable depth snapshot found for '2222'."
  }
}

{
  "error": {
    "code": "MARKET_DATA_ENTITLEMENT_REQUIRED",
    "message": "Market-depth access requires an approved entitlement."
  }
}

واجهات الشركات والرموز

اكتشف الرموز الصالحة واجلب معلومات تفصيلية عن الشركات.

GET /companies/

Free

دليل مبسط للشركات لاكتشاف الرموز قبل استدعاء نقاط نهاية الأسعار أو الشركات. يشمل الصكوك وأنواع الأدوات الأخرى عبر security_type.

نقطة النهاية

https://api.sahmk.sa/api/v1/companies/?search=aramco&market=TASI&limit=1&offset=0

المعاملات

(*) مطلوب

المعامل	النوع	مثال
search	string	aramco
market	string	TASI
limit	number	1
offset	number	0

200 OKapplication/json

{
  "results": [
    {
      "symbol": "2222",
      "name_ar": "أرامكو السعودية",
      "name_en": "SAUDI ARAMCO",
      "market": "TASI",
      "status": "active",
      "security_type": "Equity",
      "market_segment": "TASI",
      "is_etf": false
    }
  ],
  "count": 1,
  "total": 1,
  "limit": 1,
  "offset": 0
}

security_type القيم: Equity, Sukuk, ETF, Closed-End Fund, Unknown. Unknown تعني أن بيانات السوق الوصفية في المصدر غير مكتملة لذلك الرمز. تُضمّن أدوات الصكوك في استجابات الاكتشاف.

عرض الأخطاء

json

{
  "error": {
    "code": "INVALID_MARKET",
    "message": "market must be one of: TASI, NOMU."
  }
}

{
  "error": {
    "code": "INVALID_PARAM",
    "message": "limit and offset must be valid integers."
  }
}

GET /company/{symbol}/

Free

احصل على معلومات الشركة. تختلف الاستجابة بحسب الباقة.

البيانات المتاحة حسب الباقة:

Free:الاسم وsecurity_type وsector_name وsector_name_ar وmarket_id والوصف والموقع
Starter:+ الأساسيات الكاملة (PE وEPS والقيمة الدفترية وbeta ونطاقات الأسبوع والشهر و52w)
Pro+:+ المؤشرات الفنية والتقييم وإجماع المحللين

نقطة النهاية

https://api.sahmk.sa/api/v1/company/2222/

المعاملات

(*) مطلوب

المعامل	النوع	مثال
symbol *	string	2222

200 OKapplication/json

{
  "symbol": "2222",
  "name": "أرامكو السعودية",
  "name_en": "SAUDI ARAMCO",
  "current_price": 26.6,
  "is_delayed": false,
  "sector_name": "Energy",
  "sector_name_ar": "الطاقة",
  "market_id": "TASI",
  "security_type": "Equity",
  "description": "Saudi Arabian Oil Company operates as an integrated energy and chemical company in the Kingdom of Saudi Arabia and internationally. The company operates through two segments, Upstream and Downstream. The Upstream segment explores, develops, produces, and sells crude oil, condensate, natural gas, and natural gas liquids (NGLs). The Downstream segment produces various chemicals, such as aromatics, olefins, and polyolefins; polyols, isocyanates, and synthetic rubber; methanol, MTBE, glycols, linear alpha olefins, polyethylene, polypropylene, polyethylene terephthalate, polyvinyl chloride, polystyrene, polycarbonate, and engineering thermoplastics and their blends; and lubricants and base oils, as well as engages in the refining and petrochemicals, retail operations, distribution, supply and trading, and power generation. It also markets and distributes hydrocarbons, petroleum products; and trades crude oil, refined petroleum, and liquid chemical products. In addition, the company develops, manufactures, and markets high-performance rubber; and provides crude oil storage, investment, consulting, information technology, personnel and other support, agri-nutrients, purchasing, engineering, benefits administration, oil field, insurance, pipeline transport, vendor sourcing, marketing and sales support, financing, support, and marine management and transportation services. Further, it engages in aircraft operations and leasing; aviation; sports club; retail fuel marketing and operations; investment management of post-employment benefit plans; wholesale fuel operations; importing and exporting refined products and crude oil; and real estate holdings. Additionally, the company engages in prospecting, exploring, drilling, processing, manufacturing, refining, extracting, and marketing hydrocarbon substances. The company was founded in 1933 and is headquartered in Dhahran, the Kingdom of Saudi Arabia.",
  "website": "https://www.aramco.com",
  "country": "Saudi Arabia",
  "currency": "SAR",
  
  "fundamentals": {
    "market_cap": 6437200000000.0,
    "pe_ratio": 15.65,
    "forward_pe": 15.93,
    "eps": 1.6998,
    "eps_ttm": 1.6998,
    "basic_eps": 1.4382,
    "diluted_eps": null,
    "book_value": 6.49,
    "price_to_book": 4.1,
    "beta": 0.01,
    "shares_outstanding": 242000000000,
    "float_shares": 6014547000,
    "week_high": 26.86,
    "week_low": 26.5,
    "month_high": 27.26,
    "month_low": 26.12,
    "fifty_two_week_high": 27.96,
    "fifty_two_week_low": 23.04
  },
  
  "technicals": {
    "rsi_14": 57.45,
    "macd_line": 0.0187,
    "macd_signal": 0.027,
    "macd_histogram": -0.0084,
    "fifty_day_average": 26.53,
    "technical_strength": 0.0,
    "price_direction": "متذبذب",
    "updated_at": "2026-08-12T12:45:00.690083+00:00"
  },
  
  "valuation": {
    "fair_price": 24.71,
    "fair_price_confidence": 0.95,
    "calculated_at": "2026-08-11T21:00:00.010275+00:00"
  },
  
  "analysts": {
    "target_mean": 30.12,
    "target_median": 29.8,
    "target_high": 35.0,
    "target_low": 26.8,
    "consensus": "buy",
    "consensus_score": 2.11,
    "num_analysts": 18
  }
}

security_type متاح في Free+ ويستخدم القيم نفسها التي يستخدمها GET /companies/: Equity, Sukuk, ETF, Closed-End Fund, or Unknown عندما تكون بيانات السوق الوصفية في المصدر غير مكتملة.

البيانات التاريخية

استخدم بيانات OHLCV التاريخية — الافتتاح والأعلى والأدنى والإغلاق والحجم — للتحليل الفني والاختبارات التاريخية.

GET /historical/{symbol}/

Starter+

احصل على بيانات الأسعار التاريخية لسهم.

نقطة النهاية

https://api.sahmk.sa/api/v1/historical/2222/?interval=1d&from=2024-01-01&to=2026-01-01&limit=1&offset=0

المعاملات

(*) مطلوب

المعامل	النوع	مثال
symbol *	string	2222, TASI, or NOMU
from	string	2024-01-01
to	string	2026-01-01
interval	string	1d
limit	integer	1
offset	integer	0

symbol: يقبل رمز سهم أو رمز المؤشر TASI أو NOMU. from: القيمة الافتراضية قبل نحو 30 يوماً. to: القيمة الافتراضية هي اليوم. interval: 1d, 1w, 1m, 30m, 60m (الافتراضي 1d). limit: الافتراضي 500 والحد الأقصى 2000. offset: الافتراضي 0.

البيانات المتاحة حسب الباقة:

Free:لا تتوفر بيانات تاريخية
Starter:1d, 1w, 1m
Pro:فترات Starter بالإضافة إلى 60m حتى 90 يوماً
Business:فترات Starter بالإضافة إلى 30m حتى 6 أشهر، بالإضافة إلى 60m حتى سنة واحدة
Enterprise:يتوفر افتراضياً ما تتيحه باقة Business، ويمكن الاتفاق على مدد احتفاظ وفترات وخيارات تسليم مخصصة

إذا تجاوزت الفترة أو النطاق الزمني المطلوب حدود باقتك، فستعيد API الخطأ 403 PLAN_LIMIT.

هل تحتاج إلى سير عمل عملي لبيانات اليوم الواحد؟ راجع بيانات اليوم الواحد مع سهمك (SDK + MCP).

200 OKapplication/json

{
  "symbol": "2222",
  "interval": "1d",
  "source": "historical_eod",
  "is_intraday": false,
  "is_final": true,
  "partial": false,
  "latest_bar_at": "2024-01-01",
  "from": "2024-01-01",
  "to": "2026-01-01",
  "limit": 1,
  "offset": 0,
  "total": 500,
  "count": 1,
  "has_more": true,
  "data": [
    {
      "date": "2024-01-01",
      "open": 33.0,
      "high": 33.15,
      "low": 32.9,
      "close": 33.05,
      "volume": 12123324,
      "adjusted_close": 33.05
    }
  ]
}

صيغة صف الشمعة

30m/60m تستخدم الصفوف طابعاً زمنياً بصيغة ISO في date وتتضمن is_final, partial، و number_of_trades.
1d/1w/1m تستخدم الصفوف تاريخاً في date.
adjusted_close يطابق close للسجلات اللاحقة لمارس 2024 ولسجلات اليوم الواحد.
ما دام has_more يساوي true، فاطلب الصفحة التالية باستخدام offset + limit.

البيانات المالية

احصل على قوائم الدخل والميزانية والتدفقات النقدية بصيغة منظمة للشركات السعودية المدرجة.

GET /financials/{symbol}/

Starter+

نقطة النهاية

https://api.sahmk.sa/api/v1/financials/1120/?period=annual&history=1y&metrics=extended

المعاملات

(*) مطلوب

المعامل	النوع	مثال
symbol *	string	1120
type	string	all
period	string	quarterly
history	string	latest
metrics	string	extended
result	string	series
limit	integer	4 (max 20)

type: القيم المتاحة income وbalance وcashflow وall. period: القيم المتاحة annual وquarterly وauto. history: القيم المتاحة 1y و3y و5y و10y وmax. metrics: القيم المتاحة core وextended. result: القيم المتاحة series وlatest. العلامات الاختيارية: limit: الافتراضي 4 (والحد الأقصى 20). include_future_placeholders=1, include_partial=1.

ملاحظات السلوك

period=auto تُحل إلى annual عندما تكون أحدث سنة مالية مكتملة، وإلا فتُحل إلى quarterly.
ينبغي لعملاء Starter طلب period=annual صراحةً؛ وإذا كانت auto تُحل إلى quarterly فستعيد API 403 PLAN_LIMIT.
يعيد السجل السنوي السنوات المالية المكتملة افتراضياً؛ استخدم include_partial=1 لتضمين صف السنة الحالية غير المكتملة أو منذ بداية السنة.
يعيد الوضع الربعي أحدث الأرباع المتاحة افتراضياً.
result=latest يتبع الدقة المحددة أو المحلولة؛ وفي الوضع السنوي يعيد أحدث سنة مكتملة افتراضياً ما لم include_partial=1 يُستخدم.
تبقى قيمة API الافتراضية period=annual للحفاظ على التوافق السابق.
تُعاد القوائم في مصفوفات مثل income_statements, balance_sheets، و cash_flows.
تتضمن الاستجابات أيضاً symbol, statement_periodوسياق التقارير العامة في reporting.

البيانات المتاحة حسب الباقة:

Starter:قوائم سنوية؛ اطلب period=annual صراحةً. تدعم خيارات السجل حتى 3 سنوات، ويحافظ الطلب دون خيارات على الاستجابة الموسعة القديمة ذات الصفوف الأربعة.
Pro/Business:بيانات ربع سنوية وموسعة ونطاقات 5Y/10Y/max وعروض كاملة
Enterprise:مجموعة خصائص مالية وصلاحيات وصول مخصصة حسب الاتفاق

مثال على الاستجابة

200 OKapplication/json

{
  "symbol": "1120",
  "statement_period": "annual",
  "income_statements": [
    {
      "report_date": "2025-12-31",
      "statement_period": "annual",
      "fiscal_year": 2025,
      "quarters_reported": 4,
      "quarters_covered": 4,
      "is_full_year": true,
      "total_revenue": 39093965000.0,
      "gross_profit": 6730335.0,
      "operating_income": null,
      "net_income": 24791754000.0
    }
  ],
  "balance_sheets": [
    {
      "report_date": "2025-12-31",
      "statement_period": "annual",
      "fiscal_year": 2025,
      "quarters_reported": 4,
      "quarters_covered": 4,
      "is_full_year": true,
      "total_assets": 1043268297000.0,
      "total_liabilities": 900355952000.0,
      "stockholders_equity": 142912345000.0,
      "total_debt": null
    }
  ],
  "cash_flows": [
    {
      "report_date": "2025-12-31",
      "statement_period": "annual",
      "fiscal_year": 2025,
      "quarters_reported": 4,
      "quarters_covered": 4,
      "is_full_year": true,
      "operating_cash_flow": -22373072000.0,
      "investing_cash_flow": -1564467000.0,
      "financing_cash_flow": 36302349000.0,
      "free_cash_flow": null
    }
  ],
  "reporting": {
    "reporting_cadence": "quarterly",
    "quarterly_income_convention": "mixed"
  }
}

التحليلات

قارن نسب الشركات وحللها باستخدام نقاط نهاية تحليلية موجزة.

GET /analytics/ratios/{symbol}/

Starter+

النسب المالية لرمز واحد.

نقطة النهاية

https://api.sahmk.sa/api/v1/analytics/ratios/1120/?history=latest&period=quarterly&metrics=extended

المعاملات

(*) مطلوب

المعامل	النوع	مثال
symbol *	string	1120
history	string	5y
period	string	quarterly
metrics	string	extended
meta	string	extended

history: القيم latest و3y و5y و10y وmax (الافتراضي latest). period: القيم annual وquarterly (الافتراضي annual). metrics: القيم core وextended (الافتراضي core). meta: القيمة minimal افتراضياً أو extended.

البيانات المتاحة حسب الباقة:

Free:لا يتوفر وصول إلى التحليلات
Starter:أحدث بيانات + annual + core فقط
Pro/Business:جميع خيارات النسب (history وperiod وmetrics)
Enterprise:خصائص نسب وصلاحيات وصول مخصصة حسب الاتفاق

200 OKapplication/json

{
  "symbol": "1120",
  "ratios": [
    {
      "report_date": "2026-06-30",
      "statement_period": "quarterly",
      "fiscal_year": 2026,
      "fiscal_quarter": 2,
      "ratios": {
        "roe": 4.6,
        "roa": 0.66,
        "net_margin": 64.42,
        "revenue_growth_yoy": 13.35,
        "net_income_growth_yoy": 14.0,
        "asset_turnover": 0.0103
      },
      "key_metrics": {
        "total_revenue": 10884480000.0,
        "net_income": 7012137000.0,
        "operating_cash_flow": 10379536000.0,
        "total_assets": 1054772497000.0,
        "stockholders_equity": 152416762000.0
      }
    }
  ],
  "meta": {
    "period": "quarterly",
    "metrics": "extended",
    "warnings": [
      "Some metrics unavailable"
    ]
  }
}

GET /analytics/compare/

Starter+

قارن لقطات النسب بين عدة رموز.

نقطة النهاية

https://api.sahmk.sa/api/v1/analytics/compare/?symbols=1120&metrics=extended

المعاملات

(*) مطلوب

المعامل	النوع	مثال
symbols *	string	1120,1180,1010,2222
metrics	string	extended
meta	string	extended

symbols مطلوب كقيم مفصولة بفواصل (مثال 1120,1180,1010). metrics: القيمة core أو extended (الافتراضي core). meta: القيمة minimal افتراضياً أو extended.

البيانات المتاحة حسب الباقة:

Starter:حتى 3 رموز + مقاييس core فقط
Pro:حتى 10 رموز + مقاييس core/extended
Business:حتى 20 رمزاً + مقاييس core/extended
Enterprise:حدود رموز وخصائص مقارنة مخصصة حسب الاتفاق

200 OKapplication/json

{
  "results": [
    {
      "symbol": "1120",
      "company_name": "مصرف الراجحي",
      "sector_name": "Banks",
      "sector_name_ar": "البنوك",
      "market_id": "TASI",
      "market_cap": 384600000000.0,
      "current_price": 64.05,
      "ratios": {
        "roe": 9.48,
        "roa": 1.37,
        "net_margin": 67.49,
        "asset_turnover": 0.0203
      },
      "key_metrics": {
        "total_revenue": 21412480000.0,
        "net_income": 14452137000.0,
        "total_assets": 1054772497000.0,
        "stockholders_equity": 152416762000.0
      }
    }
  ],
  "count": 1,
  "meta": {
    "period": "annual",
    "metrics": "extended",
    "warnings": [
      "Some metrics unavailable"
    ]
  }
}

نصائح التكامل

البيانات الوصفية الافتراضية مختصرة: meta.period, meta.metrics, meta.warnings.
استخدم meta=extended لحقول إضافية (النسب: coverage, periods_available, quality, partial_context؛ صفوف المقارنة: coverage).
مفاتيح النسب ديناميكية، لذا اعرض كائنات النسب ديناميكياً.

توزيعات الأرباح

اعرض سجل توزيعات الأرباح والتوزيعات القادمة والعائد المتحرك للسهم.

GET /dividends/{symbol}/

Starter+

احصل على سجل توزيعات الأرباح ومعلومات العائد.

نقطة النهاية

https://api.sahmk.sa/api/v1/dividends/2222/?limit=1

المعاملات

(*) مطلوب

المعامل	النوع	مثال
symbol *	string	2222
limit	number	1

200 OKapplication/json

{
  "symbol": "2222",
  "current_price": 26.6,
  "trailing_12m_yield": 5.07,
  "trailing_12m_dividends": 1.3491,
  "payments_last_year": 4,
  "upcoming": [
    {
      "value": 0.3393,
      "period": "Q2",
      "eligibility_date": "2026-08-19",
      "distribution_date": "2026-08-27"
    }
  ],
  "history": [
    {
      "value": 0.3393,
      "value_percent": null,
      "period": "Q2",
      "fiscal_year": "2026",
      "announcement_date": "2026-08-04",
      "eligibility_date": "2026-08-19",
      "distribution_date": "2026-08-27"
    }
  ]
}

أحداث الأسهم

احصل على ملخصات مولدة بالذكاء الاصطناعي لأهم أحداث الأسهم وأخبارها.

GET /events/

Pro+

احصل على أحداث الأسهم مع تحليل مولد بالذكاء الاصطناعي.

ملاحظة

أنواع الأحداث مكتوبة بأحرف كبيرة UPPERCASE، مثل FINANCIAL_REPORT وDIVIDEND_ANNOUNCEMENT.

نقطة النهاية

https://api.sahmk.sa/api/v1/events/?symbol=4190&importance=IMPORTANT&limit=1

المعاملات

(*) مطلوب

المعامل	النوع	مثال
symbol	string	4190
type	string	FINANCIAL_REPORT
importance	string	IMPORTANT
limit	number	1
offset	number	0

القيمة الافتراضية لـlimit هي 20 (والحد الأقصى 100)، والقيمة الافتراضية لـoffset هي 0.

200 OKapplication/json

{
  "events": [
    {
      "symbol": "4190",
      "stock_name": "مكتبة جرير",
      "event_type": "MARKET_EXPANSION",
      "importance": "important",
      "sentiment": "positive",
      "description": "افتتحت مكتبة جرير معرضاً جديداً بمطار الملك فهد الدولي في الدمام، وهو المعرض التاسع والستون داخل المملكة، ويعد الخامس خلال عام 2026، باستثمارات بلغت 2 مليون ريال سعودي.",
      "event_date": "2026-08-10",
      "article_date": "2026-08-10T13:14:06.653295+00:00",
      "created_at": "2026-08-10T13:14:10.917105+00:00"
    }
  ],
  "count": 1,
  "total": 78,
  "limit": 1,
  "offset": 0,
  "has_more": true,
  "available_types": [
    "FINANCIAL_REPORT", "DIVIDEND_ANNOUNCEMENT", "STOCK_SPLIT",
    "MERGER_ACQUISITION", "MANAGEMENT_CHANGE", "NEW_LISTING",
    "DELISTING", "REGULATORY_ACTION", "PRODUCT_LAUNCH",
    "PARTNERSHIP", "LEGAL_ISSUE", "MARKET_EXPANSION",
    "RESTRUCTURING", "EARNINGS_SURPRISE", "INSIDER_TRADING",
    "ANALYST_RATING_CHANGE", "CAPITAL_INCREASE", "SHAREHOLDER_MEETING", "OTHER"
  ]
}

available_types: قائمة يحددها الخادم وقد تتوسع في الإصدارات القادمة.

importance: critical, important, regular

sentiment: very_positive, positive, slightly_positive, neutral, slightly_negative, negative, very_negative

WebSocket اللحظي - الأسهم

استقبل تحديثات أسعار الأسهم لحظياً عبر قناة الأسهم.

WS /ws/v1/stocks/

Pro+

قناة أسعار لحظية لتحديثات الأسهم المباشرة.

نقطة النهاية

wss://api.sahmk.sa/ws/v1/stocks/?api_key=YOUR_API_KEY

رسالة الاتصال

json

{
  "type": "connected",
  "plan": "business",
  "delivery_profile": "business_standard",
  "limits": {
    "max_symbols_per_connection": 120,
    "max_symbols_per_call": 40,
    "stream_modes": ["standard"]
  },
  "message": "Connected to SAHMK real-time stock stream",
  "timestamp": "2026-07-09T15:05:37.749535+00:00"
}

إجراءات العميل

json

{"action":"subscribe","symbols":["2222","1120"]}
{"action":"unsubscribe","symbols":["1120"]}
{"action":"ping"}
{"action":"subscribe","symbols":["*"]} // Enterprise only

رسالة السعر

200 OKapplication/json

{
  "type": "quote",
  "symbol": "2222",
  "mode": "standard",
  "data": {
    "price": 25.86,
    "bid": 25.84,
    "bid_size": 79,
    "ask": 25.88,
    "ask_size": 188
  },
  "timestamp": "2026-07-09T15:05:41.114000+00:00",
  "latency_ms": 14
}

WebSocket اللحظي - الصفقات

استقبل الصفقات المباشرة عبر قناة الصفقات. تتلقى الاشتراكات التي تحدد الرموز رسالة subscribed تأكيد، ثم رسالة trades_snapshot لكل رمز جديد مشترك، تتبعها تحديثات trade اللحظية.

WS /ws/v1/market/trades/

Pro+

قناة صفقات لحظية لتحديثات التداول المباشرة.

نقطة النهاية

wss://api.sahmk.sa/ws/v1/market/trades/?api_key=YOUR_API_KEY

اختياري: أضف symbol=2222 للاشتراك التلقائي عند الاتصال.

رسالة الاتصال

json

{
  "type": "connected",
  "channel": "trades",
  "plan": "pro",
  "delivery_profile": "standard",
  "limits": {
    "max_symbols_per_connection": 60,
    "max_symbols_per_call": 20,
    "snapshot_limit_max": 200
  },
  "message": "Connected to SAHMK real-time trades stream",
  "timestamp": "2026-07-28T09:31:58.197050+00:00"
}

إجراءات العميل

json

{"action":"subscribe","symbols":["2222","1120"]}
{"action":"unsubscribe","symbols":["1120"]}
{"action":"snapshot","symbol":"2222","limit":50}
{"action":"ping"}
{"action":"subscribe","symbols":["*"]} // Enterprise only

اللقطة limit الافتراضي to 50 (الحد الأقصى 200).

رسالة اللقطة

200 OKapplication/json

{
  "type": "trades_snapshot",
  "symbol": "2222",
  "updated_at": "2026-07-28T09:31:55+00:00",
  "count": 2,
  "events": [
    {
      "event_time": "2026-07-28T09:31:55+00:00",
      "price": 26.3,
      "quantity": 40,
      "value": 1052.0,
      "side": "buy"
    },
    {
      "event_time": "2026-07-28T09:31:47+00:00",
      "price": 26.3,
      "quantity": 5000,
      "value": 131500.0,
      "side": "sell"
    }
  ],
  "summary": {
    "event_count": 2,
    "trade_quantity": 5040,
    "trade_value": 132552.0,
    "latest_event_time": "2026-07-28T09:31:55+00:00"
  },
  "timestamp": "2026-07-28T09:31:58.300000+00:00"
}

رسالة الصفقة

200 OKapplication/json

{
  "type": "trade",
  "symbol": "2222",
  "event_time": "2026-07-28T09:31:58+00:00",
  "price": 26.32,
  "quantity": 10,
  "value": 263.2,
  "side": "buy",
  "market_session": "REGULAR",
  "timestamp": "2026-07-28T09:31:58.774829+00:00"
}

WebSocket اللحظي - عمق السوق

استقبل تحديثات عمق أوامر الشراء والبيع مستوى بمستوى عبر قناة عمق السوق.

WS /ws/v1/market/depth/

Pro+

قناة عمق سوق لحظية لبث مستويات أوامر الشراء والبيع.

نقطة النهاية

wss://api.sahmk.sa/ws/v1/market/depth/?api_key=YOUR_API_KEY

توفر البيانات حسب الباقة:

Pro:مؤهل لعمق أفضل 5 مستويات. طلب الوصول
Business+:مؤهل لبيانات عمق Premium لأفضل 20 مستوى. طلب الوصول

رسالة الاتصال

json

{
  "type": "connected",
  "channel": "depth",
  "symbol": null,
  "plan": "enterprise",
  "entitled_levels": 20,
  "limits": {
    "max_symbols_per_connection": 200,
    "max_symbols_per_call": 20,
    "wildcard_allowed": true
  },
  "timestamp": "2026-07-09T15:05:37.840967+00:00"
}

اختياري: أضف symbol=2222 لتلقي connected تتبعها لقطة أولية depth_snapshot.

إجراءات العميل

json

{"action":"snapshot","symbol":"2222","levels":5}
{"action":"subscribe","symbols":["2222","1120"],"levels":20}
{"action":"unsubscribe","symbols":["1120"]}
{"action":"ping"}
{"action":"subscribe","symbols":["*"],"levels":20} // Enterprise only

استخدم symbols للاشتراك وإلغائه. ولطلبات الرمز الواحد، يقبل الخادم أيضاً symbol.

ترتيب رسائل عمق السوق

الرموز المحددة: رسالة depth_snapshot لكل رمز، ثم subscribed.
رمز البدل لباقة Enterprise: subscribed أولاً، ثم دفعة اللقطات الأولية.
تحديثات العمق المستمرة هي أيضاً رسائل depth_snapshot ..

رسالة تأكيد الاشتراك

json

{
  "type": "subscribed",
  "symbols": ["1120", "2222"],
  "total": 2,
  "limit": 200
}

رسالة لقطة عمق السوق

200 OKapplication/json

{
  "type": "depth_snapshot",
  "symbol": "2222",
  "available": true,
  "updated_at": "2026-07-09T15:05:37.840967+00:00",
  "session": "postmarket",
  "book_state": "normal",
  "levels": 20,
  "best_bid": 26.68,
  "best_ask": 26.72,
  "spread": 0.04,
  "spread_bps": 14.99,
  "total_bid_quantity_top5": 29085,
  "total_ask_quantity_top5": 504644,
  "total_bid_quantity": 29085,
  "total_ask_quantity": 504644,
  "level_imbalance": -0.891,
  "level_imbalance_top5": -0.891,
  "bids": [
    {
      "level": 0,
      "price": 26.68,
      "quantity": 79,
      "order_count": 10
    }
  ],
  "asks": [
    {
      "level": 0,
      "price": 26.72,
      "quantity": 41188,
      "order_count": 38
    }
  ],
  "entitled_levels": 20,
  "timestamp": "2026-07-09T15:05:37.872738+00:00"
}

WebSocket اللحظي - الأخطاء

تعامل مع أعطال WebSocket عبر غلاف خطأ موحد. استخدم رمز الإغلاق لتصنيف الخطأ، وأحدث error.code/details لتحديد الإجراء المناسب.

رموز أخطاء WebSocket

WS_INTERNAL_ERROR4000

أوقف عطل داخلي في الاتصال عملية الإعداد.

الإجراء: أعد المحاولة بتراجع أسي محدود مع تأخير عشوائي.

WS_AUTH_OR_ACCESS4401 / 4403MARKET_DATA_ENTITLEMENT_*

تمنع مشكلة في وصول الحساب أو صلاحياته الوصول إلى البث.

الإجراء: يعني 4401 تصحيح مصادقة مفتاح API، ويعني 4403 تصحيح صلاحية الحساب أو الباقة. لا تُعِد الاتصال تلقائياً.

WS_RATE_LIMIT4429DEPTH_WS_*_LIMIT / *_RATE_LIMITED

تم تجاوز حدود الاتصال أو الاشتراك أو الإجراءات.

الإجراء: أعد المحاولة بتراجع وتأخير عشوائي، والتزم بقيمة retry_after_seconds في أحدث تفاصيل الخطأ عند توفرها.

WS_INVALID_REQUESTINVALID_JSON / UNKNOWN_ACTION / SYMBOL_REQUIRED and lowercase variants

حمولة غير صالحة أو إجراء غير مدعوم.

الإجراء: الرموز خاصة بكل قناة وحساسة لحالة الأحرف. صحح الحمولة وأعد الإجراء؛ ويبقى الاتصال مفتوحاً عادةً.

ضوابط تعدد الاتصالات

افتح الاتصالات بفاصل 200–400 مللي ثانية بدلاً من تشغيلها دفعة واحدة.
ضع محاولات إعادة الاتصال في طابور موحد لكل مفتاح API.
تجنب عواصف إعادة الاتصال المتزامنة عند افتتاح السوق.

الاتصال خارج ساعات التداول

يمكنك إبقاء اتصالات WebSocket مفتوحة خارج ساعات السوق. لا تقطع سهمك اتصالات العملاء عمداً عند إغلاق السوق. واصل إرسال ping كل 30 ثانية، وأعد الاتصال عند الحاجة بتراجع أسي محدود وتأخير عشوائي، ثم استعد الاشتراكات بعد كل اتصال. قد لا تصل أحداث سوق عندما يكون السوق غير نشط.

غلاف الخطأ

json

{
  "type": "error",
  "code": "ERROR_CODE",
  "message": "Human-readable message",
  "details": {}
}

WebSocket اللحظي - الحدود

قارن حدود الباقات بين قنوات الأسهم والصفقات وعمق السوق اللحظية. استخدم قيم connected.limits بوصفها المرجع الفعلي أثناء التشغيل.

حدود الاشتراك في قناة عمق السوق

الباقة	مستويات العمق المتاحة	الحد الأقصى للرموز في الاتصال	الحد الأقصى للرموز في الطلب	الاشتراك في الكل (*)
Pro	5	60	20	لا
Business	20	120	40	لا
Enterprise	20	200	حتى 100	نعم

حدود الاشتراك في قناة الأسهم

الباقة	الحد الأقصى للرموز في الاتصال	الحد الأقصى للرموز في الطلب	الاشتراك في الكل (*)
Pro	60	20	لا
Business	120	40	لا
Enterprise	200	حتى 100	نعم

حدود الاشتراك في قناة الصفقات

الباقة	الحد الأقصى للرموز في الاتصال	الحد الأقصى للرموز في الطلب	الاشتراك في الكل (*)
Pro	60	20	لا
Business	120	40	لا
Enterprise	200	حتى 100	نعم

التنبيهات وWebhooks - Webhooks للأحداث

سجّل نقاط نهاية webhooks وتحقق منها قبل تفعيل قواعد التنبيه.

POST /api/v1/webhooks/

Pro+

أنشئ وجهة webhook للتنبيهات وإشعارات webhooks.

نقطة النهاية

https://api.sahmk.sa/api/v1/webhooks/

المعاملات

(*) مطلوب

المعامل	النوع	مثال
url *	string	https://example.com/hooks/sahmk
name	string	Trading Production Hook

تستخدم المصادقة X-API-Key: YOUR_API_KEY.

مطلوب: url (عنوان وجهة HTTPS)
اختياري: name (اسم وصفي)
التحقق: تُرسل مصافحة تحقق عند الإنشاء؛ ويتطلب النجاح HTTP 200.
التعامل مع السر: signing_secret يُعاد عند الإنشاء فقط، ولا يُضمّن في استجابات القائمة أو الجلب.

200 OKapplication/json

{
  "id": 19,
  "url": "https://example.com/hooks/sahmk",
  "name": "Trading Production Hook",
  "signing_secret": "xxxxxxxxxxxxxxxx",
  "is_verified": false,
  "is_active": true,
  "created_at": "2026-05-08T13:30:12+03:00"
}

الخطوة التالية: تابع إلى التحقق من التوقيع ودورة حياة التسليم للاستعداد للإنتاج.

التنبيهات وWebhooks - مرجع الحمولة

تستخدم عمليات تسليم webhooks غلافاً قياسياً واحداً لجميع أنواع الأحداث اللحظية، سواء أُنشئت القواعد من لوحة التحكم أو عبر API.

Webhook Event Envelope

Pro+

البنية القياسية للحمولة لدى مستهلكي webhooks.

json

{
  "event_id": "9a6b8f22-2d1d-4b3f-b75f-7f9d5f101234",
  "event_type": "large_move",
  "symbol": "2222",
  "detected_at": "2026-05-08T13:48:22+03:00",
  "severity": "warning",
  "title": "Large move detected",
  "summary": "Price moved more than configured threshold in the selected window.",
  "metrics": {
    "price": 25.86,
    "pct_change": 3.4,
    "volume": 9803705,
    "value": 252308343.0,
    "avg_volume": 8243000,
    "reference_value": 245000000.0,
    "rolling_volume_baseline": 4100000,
    "rolling_value_baseline": 120000000.0,
    "baseline_source": "rolling_window",
    "baseline_sample_count": 30,
    "volume_baseline_sample_count": 30,
    "value_baseline_sample_count": 30,
    "high": 25.86,
    "low": 25.60,
    "change": 0.85,
    "window": "15m",
    "threshold": 3.0
  },
  "conditions_matched": {
    "window": "15m",
    "operator": "abs>=",
    "observed_pct_change": 3.4,
    "threshold_pct": 3.0,
    "baseline_price": 25.01,
    "current_price": 25.86
  },
  "correlation_id": "large_move:2222:29650608",
  "version": "v1",
  "destination": {
    "type": "webhook",
    "webhook_id": 19,
    "webhook_url": "https://example.com/hooks/sahmk"
  }
}

event_id
event_type
symbol
detected_at
severity
title, summary

metrics
conditions_matched
correlation_id
version
destination

مهم

تستخدم مطابقة نسبة القيمة في unusual_value_traded خط أساس متحركاً لقيمة التداول (value / rolling_value_baseline)، وليس reference_value.

للتوافق المستقبلي، ينبغي للعملاء تجاهل المفاتيح غير المعروفة والاعتماد على الحقول المطلوبة في المستوى الأعلى.

التنبيهات وWebhooks - قواعد الأحداث

حدد ظروف السوق والإجراءات التي تشغل تسليم webhooks. يمكنك إنشاء القواعد من لوحة التحكم أو برمجياً عبر API.

مرجع لوحة التحكم وأنواع الأحداث

يمكنك إنشاء التنبيهات وإدارتها من لوحة المطور. لمرجع أنواع الأحداث والشروط الكامل، راجع أنواع الأحداث وشروطها.

POST /api/v1/alerts/

Pro+

أنشئ قاعدة تنبيه تشغل تسليم webhooks عند تحقق الشروط.

نقطة النهاية

https://api.sahmk.sa/api/v1/alerts/

المعاملات

(*) مطلوب

المعامل	النوع	مثال
symbol *	string	2222
event_type *	string	large_move
condition	string	pct_change_abs_gte
value *	number	3.0
webhook_id	number	19
destination	object	{ "type": "webhook", "webhook_id": 19 }
config	object	{ "window": "15m" }
once	boolean	true (default)

إرشادات تصميم القواعد

ابدأ بنطاق رموز محدود وحدود واضحة.
استخدم فترات تهدئة لتقليل ضوضاء الإشعارات.
تحقق في بيئة الاختبار قبل تفعيل قواعد الإنتاج.
condition مطلوب مع price_alert؛ أما أنواع الأحداث الموثقة الأخرى فتطبّعه تلقائياً.
يجب أن تتجاوز حدود النسب 1.0. والحد الأقصى للحركة الكبيرة هو 10% في TASI و30% في NOMU.
once القيمة الافتراضية to true. تضبطه الأمثلة على false صراحةً لإنشاء قواعد متكررة، ولذلك تعرض استجاباتها fire_once: false.

200 OKapplication/json

{
  "id": 57,
  "workspace_id": null,
  "symbol": "2222",
  "event_type": "large_move",
  "target_scope_type": "single_symbol",
  "target_scope_id": null,
  "symbols": ["2222"],
  "evaluated_symbol_rules": 1,
  "condition": "pct_change_abs_gte",
  "value": "3.0",
  "config": {
    "window": "5m",
    "destination": { "type": "webhook", "webhook_id": 19 }
  },
  "fire_once": false,
  "webhook_id": 19,
  "webhook_url": "https://example.com/hooks/sahmk",
  "destination": { "type": "webhook", "webhook_id": 19 },
  "status": "active",
  "last_triggered_at": null,
  "total_triggers": 0,
  "created_at": "2026-05-08T13:36:45+03:00"
}

GET /api/v1/alerts/

Pro+

اعرض القواعد الحالية وصفّها اختيارياً حسب الحالة.

نقطة النهاية

https://api.sahmk.sa/api/v1/alerts/?status=active

المعاملات

(*) مطلوب

المعامل	النوع	مثال
status	string	active

الاستعلام: status=active|paused|all
قيم الحالة: active, paused, triggered
المطابقة: once يطابق fire_once.

200 OKapplication/json

{
  "alerts": [
    {
      "id": 57,
      "workspace_id": null,
      "symbol": "2222",
      "event_type": "large_move",
      "target_scope_type": "single_symbol",
      "target_scope_id": null,
      "symbols": ["2222"],
      "evaluated_symbol_rules": 1,
      "condition": "pct_change_abs_gte",
      "value": "3.0",
      "config": {
        "window": "5m",
        "destination": { "type": "webhook", "webhook_id": 19 }
      },
      "status": "active",
      "fire_once": false,
      "webhook_id": 19,
      "webhook_url": "https://example.com/hooks/sahmk",
      "destination": { "type": "webhook", "webhook_id": 19 },
      "last_triggered_at": null,
      "total_triggers": 0,
      "created_at": "2026-05-08T13:36:45+03:00"
    }
  ]
}

التنبيهات وWebhooks - أنواع الأحداث وشروطها

أنواع الأحداث المدعومة ومحددات الشروط الأساسية لضبط القواعد.

التوفر

الأنواع المتاحة عموماً هي price_alert, large_move, abnormal_volume, and unusual_value_traded. الأنواع الإضافية في الجدول أدناه متاحة فقط للحسابات المشمولة في الإطلاق المحدود.

نوع الحدث	الشروط
price_alert	price_above, price_below, pct_change
large_move	pct_change_abs_gte
abnormal_volume	ratio_gte
unusual_value_traded	ratio_gte
large_executed_trade	ratio_gte
trade_burst	ratio_gte
traded_value_surge	ratio_gte
top5_depth_imbalance	ratio_gte
spread_widening	ratio_gte
top5_liquidity_withdrawal	ratio_gte

عقود conditions_matched

يُعبّر عن اختلافات بنية كل حدث أساساً في conditions_matched.

json

{
  "price_alert": {
    "operator": ">",
    "observed": 26.1,
    "threshold": 26.0
  },
  "large_move": {
    "window": "15m",
    "operator": "abs>=",
    "observed_pct_change": 3.4,
    "threshold_pct": 3.0,
    "baseline_price": 25.01,
    "current_price": 25.86
  },
  "abnormal_volume": {
    "event_type": "abnormal_volume",
    "operator": ">=",
    "metric": "volume_ratio",
    "current_value": 9803705,
    "baseline_value": 4100000,
    "ratio": 2.39,
    "threshold": 2.0
  },
  "unusual_value_traded": {
    "event_type": "unusual_value_traded",
    "operator": ">=",
    "metric": "value_ratio",
    "current_value": 252308343.0,
    "baseline_value": 120000000.0,
    "ratio": 2.1,
    "threshold": 2.0
  }
}

ترميز الأرقام هو JSON number وليس string. ratio and observed_pct_change تُقربان إلى 4 منازل عشرية.

التنبيهات وWebhooks - التحقق من التوقيع

تحقق من توقيع كل طلب webhook قبل معالجة الأحداث في الإنتاج.

استخدم سر التوقيع الخاص بنقطة النهاية والمعاد عند إنشاء وجهة webhook.

تتضمن ترويسات التسليم X-SAHMK-Signature, X-SAHMK-Event, and X-SAHMK-Event-Id.

تتضمن كل عملية تسليم X-SAHMK-Signature.
يُنشأ التوقيع باستخدام HMAC-SHA256 على الحمولة القياسية.
ارفض التوقيعات غير المطابقة باستخدام HTTP 401.

text

# Header format:
# X-SAHMK-Signature: t=<unix_ts>,v1=<hex_hmac>

timestamp, received = parse_signature_header(request.headers["X-SAHMK-Signature"])
canonical_json = json.dumps(payload, sort_keys=True, separators=(",", ":"))
signed_payload = f"{timestamp}.{canonical_json}"
computed = HMAC_SHA256(signing_secret, signed_payload)

if computed != received:
    return 401

process_event(payload)

يُضمّن الطابع الزمني في ترويسة التوقيع. ينبغي للمستقبلين تطبيق تحقق من النافذة الزمنية للحماية من إعادة الإرسال.

التنبيهات وWebhooks - رموز الأخطاء

تعامل مع فشل تسليم webhooks باستخدام مستهلكين آمنين لإعادة المحاولة ومطابقة واضحة للحالات.

إرشادات تشغيلية

تعامل مع محاولات التسليم بوصفها قابلة للتكرار الآمن؛ فقد يتكرر التسليم عند إعادة المحاولة.
أعد 2xx سريعاً بعد الحفظ الدائم، وعالج الأعمال الثقيلة بشكل غير متزامن.
تتبع معرفات التسليم وأسباب الفشل للدعم والمطابقة.

400INVALID_PARAM

حقل حمولة غير صالح أو خيار استعلام غير مدعوم.

الإجراء: صحح حمولة الطلب وأعد المحاولة.

401AUTH_REQUIRED

ترويسة X-API-Key مفقودة.

الإجراء: أضف مفتاح API نشطاً وأعد المحاولة.

403PLAN_LIMIT / FEATURE_DISABLED

لا تملك الباقة صلاحية الميزة أو تم بلوغ الحدود.

الإجراء: رقِّ الباقة أو عدّل الاستخدام.

404NOT_FOUND

لم يتم العثور على مورد webhook أو التنبيه لهذا الحساب.

الإجراء: تحقق من معرف المورد وسياق الملكية.

429detail

تم بلوغ حد الاندفاع أو الحصة؛ التزم بـRetry-After عند توفره.

الإجراء: تراجع وأعد المحاولة مع تأخير عشوائي.

صيغة استجابة الخطأ

json

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}

أخطاء WebSocket اللحظية

لرموز إغلاق WebSocket وسلوك إعادة الاتصال وإرشادات المعالجة، راجع WebSocket اللحظي - الأخطاء.

حدود الطلبات

تُحدد معدلات الوصول إلى API حسب باقتك. يوجد نوعان من الحدود: الحصة اليومية وحد الاندفاع لكل دقيقة.

مقارنة الباقات كاملة

الباقة	الحد اليومي	حد الاندفاع	مفاتيح API	WebSocket	Webhooks للأحداث	قواعد الأحداث
Free	100/day	10/min	1	✗	0	0
Starter	5,000/day	100/min	3	✗	0	0
Pro	50,000/day	500/min	10	✓	3	10
Business	150,000/day	1,000/min	30	✓	10	50
Enterprise	مخصص	مخصص	مخصص	✓	مخصص	مخصص

الحصص اليومية مشتركة على مستوى الحساب، بما في ذلك مفاتيح Live وTest. لا يؤدي تدوير المفتاح أو إلغاؤه إلى إنشاء حصة يومية جديدة.

الحماية من الاندفاع: لمنع إساءة الاستخدام وحماية الاستقرار، يُطبق حد الدقيقة على مستوى مفتاح API والحساب معاً. تعيد الطلبات التي تتجاوز الحدود HTTP 429. تُصفّر الحدود اليومية عند منتصف الليل بتوقيت Asia/Riyadh ‏(UTC+3). تعتمد حدود Enterprise على العقد، وقد تكون حصصاً شهرية أو مرتبطة بالموارد.

ترويسات حدود الطلبات

تتضمن معظم استجابات /api/v1/* الناجحة X-RateLimit-Limit, X-RateLimit-Remaining، و X-RateLimit-Reset.

X-RateLimit-Reset هو طابع Unix الزمني لمنتصف الليل التالي بتوقيت Asia/Riyadh. تُفرض الحصة اليومية على الحساب كله وعبر جميع المفاتيح. لكن X-RateLimit-Remaining يُحسب حالياً من المفتاح المستخدم للطلب، ولذلك قد يكون أعلى من الحصة الحقيقية المتبقية للحساب عند استخدام عدة مفاتيح.

قد تحذف الوكلاء الطرفية الترويسات. استخدم HTTP 429 وقيمة الاستجابة detail، و Retry-After عند توفرها بوصفها عقد الحد البديل.

رموز الأخطاء

تستخدم الواجهة رموز حالة HTTP القياسية وتعيد أخطاء منظمة بصيغة JSON.

رموز أخطاء HTTP

400INVALID_ROUTE

تم استخدام مسار نقطة نهاية خاطئ، وتعيد API اقتراحاً للمسار الصحيح.

401detail

ترويسة X-API-Key مفقودة.

403detail

صيغة مفتاح API غير صالحة، أو أن المفتاح غير صالح أو ملغى.

403PLAN_LIMIT

تتطلب نقطة النهاية باقة أعلى (مثلاً تتطلب البيانات التاريخية Starter+، أو طُلبت تركيبات مالية أعلى ضمن Starter).

404INVALID_SYMBOL

لم يتم العثور على رمز التداول.

404 / 409INVALID_IDENTIFIER / AMBIGUOUS_IDENTIFIER

لم تتم مطابقة استعلام المعرّف، أو طابق عدة شركات.

429detail

تم بلوغ حد يومي أو حد اندفاع أو حد IP أو حد أمني مؤقت.

500SERVER_ERROR

خطأ داخلي في الخادم. أعد المحاولة أو تواصل مع الدعم.

قد تصل بعض الحسابات المجانية الجديدة مؤقتاً إلى حد أمني. عند حدوث ذلك تعيد API HTTP 429 مع detail يحتوي على Temporary security limit reached. التزم بقيمة Retry-After عند توفرها، ثم حاول لاحقاً.

خطأ تكامل شائع: استدعاء GET /api/v1/quote/batch/ يعيد 400 INVALID_ROUTE مع إرشاد للمسار الصحيح.

json

{
  "error": {
    "code": "INVALID_ROUTE",
    "message": "Did you mean /api/v1/quotes/?symbols=2222,1120 ?"
  }
}

صيغ استجابات الأخطاء

تستخدم أخطاء التحقق والبحث في نقاط النهاية عادةً كائن error منظماً:

json

{
  "error": {
    "code": "INVALID_SYMBOL",
    "message": "Stock symbol '9999' not found."
  }
}

تستخدم أخطاء المصادقة والحد قيمة detail نصية في المستوى الأعلى:

json

{
  "detail": "Request was throttled. Expected available in 60 seconds."
}

آخر تحديث في ١٣ أغسطس ٢٠٢٦

→ السابقالصفقات

التالي ←السوق