أحداث الأسهم

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

القسم الحالي: أحداث الأسهم

البدء

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

ابدأ من هنا

طلبك الأول

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

التطوير

خدمات 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 لتسهيل التكامل، أو استكشاف خدمات API الأخرى، أو استخدام WebSocket للحصول على تحديثات مستمرة للأسعار والصفقات وعمق السوق.

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

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

استخدم حزمة SDK

ابدأ باستخدام حزمة Python أو واجهة سطر الأوامر (CLI) لتسهيل التكامل وتقليل التعليمات البرمجية المطلوبة.

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

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

استخدم WebSocket للبيانات اللحظية

احصل على تحديثات مستمرة للأسعار والصفقات وعمق السوق دون الحاجة إلى إرسال طلبات متكررة عبر REST.

المصادقة

تتطلب جميع طلبات API استخدام مفتاح API للمصادقة. يجب تضمين المفتاح في ترويسة الطلب (Header) باسم 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(...) أولاً للبحث عنه قبل طلب بيانات الأسعار أو الشركة.

متى تستخدم هذه الحزمة؟ عندما ترغب في تسهيل التكامل مع API دون التعامل مباشرة مع طلبات REST، أو الاستفادة من أدوات Python، أو الوصول السريع إلى الأسعار وبيانات السوق عبر سطر الأوامر.

تقبل دوال جلب الأسعار عدة معرّفات، منها رمز السهم واسمه بالعربية أو الإنجليزية والأسماء البديلة. ويُفضّل استخدام رمز السهم لتجنب الالتباس عند تشابه الأسماء.

للمزيد من الأمثلة: github.com/sahmk-sa/sahmk-python

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

استخدم سهمك مع ChatGPT وClaude.ai وClaude Code عبر خادم MCP المستضاف، أو مع Claude Desktop وCursor عبر خادم MCP المحلي. يعتمد كلا الخيارين على اشتراكك الحالي في سهمك وصلاحيات حسابك وحدود الاستخدام المتاحة لك. لربط سهمك بأدوات ووكلاء الذكاء الاصطناعي، استخدم خادم MCP لاستدعاء أدوات سهمك، أو ملف/api-docs.mdللوصول إلى توثيق API بصيغة قابلة للقراءة آلياً.

ChatGPT

سهمك متاح في دليل إضافات ChatGPT، ويمكنك إضافته مباشرة من الدليل.

تحتاج إلى حساب مطوّر في سهمك ومفتاح API. يمكنك إنشاء حساب جديد أو الانتقال إلى صفحة مفاتيح API إذا كان لديك حساب بالفعل.

أضف سهمك إلى ChatGPT

افتح صفحة سهمك في دليل إضافات ChatGPT.
أضف سهمك إلى ChatGPT.
سجّل الدخول إلى حسابك في سهمك.
اختر مفتاح API ووافق على منح صلاحية الوصول.
ابدأ محادثة جديدة واختر @SAHMK.

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

مثال:

ما سعر سهم أرامكو الآن، وما حجم التداول وأفضل سعري طلب وعرض؟

الدليل الكامل: دليل البدء السريع مع MCP

Claude.ai

سهمك متاح في دليل إضافات Claude، ويمكنك إضافته مباشرة من الدليل.

أضف سهمك إلى Claude

افتح صفحة سهمك في دليل Claude.
سجّل الدخول إلى Claude وأضف سهمك.
سجّل الدخول إلى حسابك في سهمك.
اختر مفتاح API ووافق على منح صلاحية الوصول.
سيستخدم Claude أدوات سهمك تلقائياً أثناء المحادثة عند الحاجة إليها.

مثال:

ما سعر سهم أرامكو الآن، وما حجم التداول وأفضل سعري طلب وعرض؟

Claude Code (CLI)

اربط Claude Code بسهمك عبر خادم MCP المستضاف باستخدام HTTPS، دون الحاجة إلى تثبيت Python أو تشغيل خادم محلي.

أضف خادم MCP المستضاف:

bash

claude mcp add --transport http sahmk https://mcp.sahmk.sa/mcp

تحقق من إضافة الخادم:

bash

claude mcp list

نفّذ أمر الإضافة أعلاه في سطر الأوامر.
داخل جلسة Claude Code، استخدم /mcp لإكمال المصادقة عبر OAuth ومنح صلاحية الوصول إلى سهمك.
اختر مفتاح API الخاص بحسابك في سهمك عند مطالبتك بذلك.

يمكنك إضافة الخيار --scope user لإتاحة خادم MCP في جميع مشاريعك.

خادم MCP المحلي

محلي

ثبّت حزمة Python الخاصة بخادم MCP المحلي لاستخدامها مع Claude Desktop وCursor عبر بروتوكول stdio.

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

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

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* symbol	string	رمز السهم
identifier	string	اسم الشركة أو أحد أسمائها البديلة
data_mode	string	`realtimedelayed` عند عدم تحديد القيمة، يُستخدم الوضع الافتراضي للباقة

استخدم رمز السهم عند تشابه الأسماء أو تعذّر تحديد الشركة المطلوبة بدقة.

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

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,
  "trade_count": 8330,
  "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
  },
  "auction": {
    "phase": "opening",
    "price": 26.58,
    "price_updated_at": "2026-10-07T06:31:01+00:00",
    "volume": 11646,
    "volume_updated_at": "2026-10-07T06:31:01+00:00",
    "symbol_state": null,
    "symbol_session": "pre-open"
  },
  "updated_at": "2026-08-12T12:20:00+00:00",
  "is_delayed": false,
  "resolved_instrument": {
    "input": "أرامكو",
    "symbol": "2222",
    "name": "أرامكو",
    "match_type": "alias_exact",
    "confidence": "high"
  }
}

السعر الاسترشادي خلال المزاد

يتوفر حقل auction في استجابة سعر السهم الواحد، وطلب أسعار عدة أسهم، وقناة الأسهم عبر WebSocket.
تكون قيمة الحقل null خارج فترتي مزاد الافتتاح والإغلاق، وكذلك عند استخدام باقة توفر بيانات متأخرة.
يبقى price سعر آخر صفقة رسمية، ويظل updated_at وقت تلك الصفقة، دون أن تتغير قيمتهما نتيجة تحديثات المزاد.
يشير auction.phase إلى نوع المزاد: opening لمزاد الافتتاح وclosing لمزاد الإغلاق.

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

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}/ لطلب بيانات سهم واحد في كل مرة.

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* symbols	string	رموز الأسهم مفصولة بفواصل
identifiers	string	أسماء الشركات مفصولة بفواصل
data_mode	string	`realtimedelayed` عند عدم تحديد القيمة، يُستخدم الوضع الافتراضي للباقة

استخدم أحد المعاملين symbols أو identifiers فقط، وليس كليهما.

200 OKapplication/json

{
  "quotes": [
    {
      "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,
      "trade_count": 8330,
      "bid": 26.6,
      "ask": 26.62,
      "bid_size": 9181,
      "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
      },
      "net_liquidity": 23359649.699999988,
      "auction": {
        "phase": "opening",
        "price": 26.58,
        "price_updated_at": "2026-10-07T06:31:01+00:00",
        "volume": 11646,
        "volume_updated_at": "2026-10-07T06:31:01+00:00",
        "symbol_state": null,
        "symbol_session": "pre-open"
      },
      "updated_at": "2026-09-23T01:03:00+03: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,
      "open": 64.1,
      "high": 64.3,
      "low": 63.7,
      "previous_close": 64.1,
      "volume": 3775688,
      "value": 241832816.4,
      "trade_count": 4120,
      "bid": 63.95,
      "ask": 64.05,
      "bid_size": 15,
      "ask_size": 43300,
      "liquidity": {
        "inflow_value": 80000000,
        "inflow_volume": 1250000,
        "inflow_trades": 1800,
        "outflow_value": 127806410.94999999,
        "outflow_volume": 2525688,
        "outflow_trades": 2320,
        "net_value": -47806410.94999999
      },
      "net_liquidity": -47806410.94999999,
      "auction": null,
      "updated_at": "2026-09-23T01:03:00+03:00",
      "is_delayed": false
    }
  ],
  "count": 2,
  "max_symbols": 50,
  "requested_count": 2
}

حدود طلب الأسعار المتعددة

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

التعرّف على الشركات من أسمائها ورموزها

عند استخدام المعامل 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+

احصل على أحدث الصفقات المنفذة لسهم واحد، مرتبة من الأحدث إلى الأقدم.

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* symbol	string	رمز السهم
limit	integer	الافتراضي: 50، والحد الأقصى: 200

200 OKapplication/json

{
  "symbol": "2222",
  "updated_at": "2026-08-12T12:19:10+00:00",
  "count": 1,
  "events": [
    {
      "trade_seq": 204505,
      "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."
  }
}

الرقم التسلسلي للصفقة (trade_seq)

يُستخدم رمز السهم وتاريخ تنفيذ الصفقة المستخرج من event_time بتوقيت الرياض، إلى جانب الرقم التسلسلي trade_seq، لتحديد كل صفقة بشكل فريد.
قد يتكرر الرقم التسلسلي في جلسة تداول لاحقة.

السوق

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

GET /market/summary/?index=TASI

Free

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

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
index	string	`TASINOMU` الافتراضي: TASI
data_mode	string	`realtimedelayed` عند عدم تحديد القيمة، يُستخدم الوضع الافتراضي للباقة

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

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

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
index	string	`TASINOMU` الافتراضي: TASI
limit	number	عدد النتائج المطلوبة. الافتراضي 10، والحد الأقصى 50
data_mode	string	`realtimedelayed` عند عدم تحديد القيمة، يُستخدم الوضع الافتراضي للباقة

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

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

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
index	string	`TASINOMU` الافتراضي: TASI
limit	number	عدد النتائج المطلوبة. الافتراضي 10، والحد الأقصى 50
data_mode	string	`realtimedelayed` عند عدم تحديد القيمة، يُستخدم الوضع الافتراضي للباقة

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

احصل على قائمة الأسهم الأكثر تداولاً من حيث حجم التداول (عدد الأسهم المتداولة).

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
index	string	`TASINOMU` الافتراضي: TASI
limit	number	عدد النتائج المطلوبة. الافتراضي 10، والحد الأقصى 50
data_mode	string	`realtimedelayed` عند عدم تحديد القيمة، يُستخدم الوضع الافتراضي للباقة

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

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

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
index	string	`TASINOMU` الافتراضي: TASI
limit	number	عدد النتائج المطلوبة. الافتراضي 10، والحد الأقصى 50
data_mode	string	`realtimedelayed` عند عدم تحديد القيمة، يُستخدم الوضع الافتراضي للباقة

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

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

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
index	string	`TASINOMU` الافتراضي: TASI
data_mode	string	`realtimedelayed` عند عدم تحديد القيمة، يُستخدم الوضع الافتراضي للباقة

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
}

عرض الأخطاء الخاصة بهذا المسار (عند إدخال مؤشر غير صالح)

json

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

عمق السوق

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

GET /market/depth/{symbol}/

Pro+

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

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

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

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* symbol	string	رمز السهم
levels	integer	من 1 إلى 20

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

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

Pro: إمكانية الوصول إلى أفضل 5 مستويات من أوامر الشراء والبيع، بعد الموافقة على طلب الوصول
Business+: إمكانية الوصول إلى أفضل 20 مستوى من أوامر الشراء والبيع ضمن بيانات Premium، بعد الموافقة على طلب الوصول

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 }
  ],
  "market_order": {
    "bid_quantity": 79938,
    "bid_order_count": 22,
    "bid_updated_at": "2026-10-06T06:31:50+00:00",
    "ask_quantity": 87743,
    "ask_order_count": 11,
    "ask_updated_at": "2026-10-06T06:31:35+00:00"
  },
  "entitled_levels": 5
}

مستويات عمق السوق المتاحة

تعرض الاستجابة أحدث لقطة متاحة لدفتر الأوامر وقت تنفيذ الطلب.
قد يكون عدد المستويات المتاحة أقل من العدد المطلوب، بحسب باقتك ومستويات العرض والطلب المتوفرة في السوق.

أوامر السوق

يظهر الحقل market_order بشكل منفصل عن مستويات العرض والطلب المحددة بأسعار، وتكون قيمته null عندما لا توجد أوامر سوق بكميات موجبة في أي من الجانبين.
لا يُعد السعر 0 مستوى سعرياً فعلياً، ولذلك لا تُحتسب أوامر السوق ضمن أفضل سعر طلب أو عرض، أو الفارق بينهما، أو إجمالي الكميات في المستويات السعرية.
تُعاد بيانات دفتر الأوامر حتى إذا كانت تحتوي على أوامر سوق فقط، دون وجود مستويات سعرية.

عرض الأخطاء الخاصة بهذا المسار

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.

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
search	string	نص البحث
market	string	`TASINOMU`
limit	number	الافتراضي: 100، والحد الأقصى: 500
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,
      "isin": "SA14TG012N13"
    }
  ],
  "count": 1,
  "total": 1,
  "limit": 1,
  "offset": 0
}

أنواع الأوراق المالية (security_type):

يدعم الحقل security_type القيم التالية:

Equity: أسهم
Sukuk: صكوك
ETF: صناديق استثمار متداولة
Closed-End Fund: صناديق استثمار مغلقة
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: اسم الشركة، ورمز ISIN، ونوع الورقة المالية (security_type)، واسم القطاع بالعربية والإنجليزية (sector_name وsector_name_ar)، والسوق (market_id)، ووصف الشركة وموقعها الإلكتروني.
Starter: جميع بيانات الباقة المجانية، بالإضافة إلى المؤشرات المالية الأساسية مثل مكرر الربحية (P/E)، وربحية السهم (EPS)، والقيمة الدفترية، ومعامل بيتا (Beta)، ونطاقات الأسعار الأسبوعية والشهرية وخلال آخر 52 أسبوعاً.
Pro وما فوق: جميع بيانات Starter، بالإضافة إلى المؤشرات الفنية، وتقييم السهم، ومتوسط الأسعار المستهدفة وتوصيات المحللين.

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* symbol	string	رمز السهم

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",
  "isin": "SA14TG012N13",
  
  "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 بدءاً من الباقة المجانية، ويستخدم القيم نفسها الموجودة في خدمة GET /companies/:

Equity، Sukuk، ETF، Closed-End Fund، Unknown.

تشير القيمة Unknown إلى عدم اكتمال بيانات تصنيف الورقة المالية في المصدر.

البيانات التاريخية والفواصل اللحظية

احصل على بيانات الأسعار التاريخية والفواصل اللحظية (OHLCV)، التي تشمل أسعار الافتتاح والأعلى والأدنى والإغلاق وحجم التداول، عبر فواصل زمنية بالدقائق أو على أساس يومي وأسبوعي وشهري، لاستخدامها في التحليل الفني واختبار استراتيجيات التداول باستخدام البيانات التاريخية.

GET /historical/{symbol}/

Starter+

احصل على بيانات الأسعار التاريخية والفواصل اللحظية للسهم، بما في ذلك أسعار الافتتاح والأعلى والأدنى والإغلاق وحجم التداول (OHLCV).

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* symbol	string	رمز السهم أو TASI أو NOMU
from	string	تاريخ البداية بصيغة YYYY-MM-DD الافتراضي: قبل نحو 30 يوماً
to	string	تاريخ النهاية بصيغة YYYY-MM-DD الافتراضي: اليوم
interval	string	`1min5min15min30min60min1d1w1mo` الفاصل الزمني الافتراضي: 1d. تُدعم أيضاً القيم السابقة 30m بوصفها بديلاً لـ30min، و60m بوصفها بديلاً لـ60min، و1m بوصفها بديلاً لـ1mo. ويشير 1m إلى شهر واحد، وليس دقيقة واحدة.
limit	integer	الافتراضي: 500، والحد الأقصى: 2000
offset	integer	الافتراضي: 0. عدد الشموع التي يتم تجاوزها من بداية النتائج المرتبة زمنياً من الأقدم إلى الأحدث.

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

Free: لا تتوفر بيانات الأسعار التاريخية.
Starter: الفواصل اليومية (1d) والأسبوعية (1w) والشهرية (1mo).
Pro: جميع فواصل Starter، بالإضافة إلى فواصل 15 و30 و60 دقيقة، ببيانات تمتد حتى 90 يوماً تقويمياً لكل فاصل.
Business: جميع فواصل Pro، بالإضافة إلى فاصل 5 دقائق ببيانات تمتد حتى 90 يوماً تقويمياً. كما تتوفر بيانات تاريخية ممتدة لفواصل 15 و30 دقيقة حتى 6 أشهر تقويمية، ولفاصل 60 دقيقة حتى سنة تقويمية واحدة.
Enterprise: فواصل زمنية مخصصة، بما في ذلك فاصل الدقيقة الواحدة (1min) عند تفعيله، مع تحديد عمق البيانات التاريخية وفقاً للاتفاقية.

إذا طلبت فاصلاً زمنياً مدعوماً لكنه غير متاح ضمن باقتك، أو حددت نطاقاً زمنياً يتجاوز الحد المسموح به، فستُرجع الواجهة الخطأ 403 PLAN_LIMIT.أما عند إدخال قيمة غير مدعومة للفاصل الزمني، فستُرجع الخطأ 400.قد تختلف بداية توفر البيانات من سهم إلى آخر، وقد تكون الفترة التاريخية المتاحة أقصر من الحد الأقصى المسموح به في الباقة.تُحدَّث الشموع على الفواصل اللحظية خلال جلسات التداول بشكل لحظي، بينما تحدد حدود التغطية التاريخية المدة التي يمكنك استرجاع بياناتها.

هل ترغب في التعرف على كيفية استخدام الفواصل اللحظية عملياً؟ راجع دليل استخدام الفواصل اللحظية مع سهمك (SDK + MCP).

200 OKapplication/json

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

صيغة بيانات الشموع السعرية

الفواصل اللحظية (1min، 5min، 15min، 30min، 60min):

تتضمن كل شمعة طابعاً زمنياً بصيغة ISO في الحقل date، بالإضافة إلى الحقول turnover وtrade_count وis_final وpartial.

في فاصلَي 30min و60min، يتوفر الحقل number_of_trades مؤقتاً بوصفه اسماً بديلاً للحقل trade_count، ويحمل القيمة نفسها.

الفواصل اليومية والأسبوعية والشهرية (1d، 1w، 1mo):

يحتوي الحقل date على التاريخ فقط، دون الوقت، وتتضمن البيانات الحقل turnover. ويتوفر الحقل trade_count عند توفر عدد الصفقات في بيانات نهاية اليوم.

بالنسبة للفواصل الأسبوعية والشهرية، يُحسب trade_count بجمع أعداد الصفقات اليومية المتاحة خلال الأسبوع وفق معيار ISO، أو خلال الشهر الميلادي.

التوافق مع القيم السابقة:

تظل القيم 30m و60m و1m مدعومة بوصفها بدائل لـ30min و60min و1mo على التوالي. ويشير 1m إلى الفاصل الشهري، وليس فاصل الدقيقة الواحدة.

سعر الإغلاق المعدّل:

تتطابق قيمة adjusted_close مع close في السجلات اللاحقة لشهر مارس 2024، وكذلك في بيانات الفواصل اللحظية.

الانتقال بين صفحات النتائج:

عندما تكون قيمة has_more هي true، يمكنك طلب الصفحة التالية بزيادة offset بمقدار limit.

القوائم المالية

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

GET /financials/{symbol}/

Starter+

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* symbol	string	رمز السهم
type	string	`incomebalancecashflowall` الافتراضي: all
period	string	`annualquarterlyauto` الافتراضي: annual
history	string	`1y3y5y10ymax`
metrics	string	`coreextended`
result	string	`serieslatest` الافتراضي: series
limit	integer	الافتراضي: 4، والحد الأقصى: 20
include_partial	string	`01` الافتراضي: 0
include_future_placeholders	string	`01` الافتراضي: 0

ملاحظات حول آلية عمل الخدمة

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

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

Starter: القوائم المالية السنوية، مع ضرورة تحديد period=annual صراحةً. تتيح خيارات السجل التاريخي الوصول إلى بيانات تصل إلى 3 سنوات. وعند إرسال الطلب دون تحديد خيارات إضافية، تظل الاستجابة السابقة الموسعة المكونة من 4 سجلات متاحة للتوافق مع عمليات التكامل الحالية.
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
    }
  ],
  "semantics": {
    "income": "annual_full_year",
    "cashflow": "annual_full_year",
    "balance": "year_end_snapshot"
  },
  "reporting": {
    "reporting_cadence": "quarterly",
    "quarterly_income_convention": "mixed"
  }
}

التحليلات

قارن النسب والمؤشرات المالية للشركات المدرجة وحلّلها باستخدام خدمات API المخصصة للتحليل المالي والمقارنات.

GET /analytics/ratios/{symbol}/

Starter+

احصل على النسب والمؤشرات المالية لسهم معين.

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* symbol	string	رمز السهم
history	string	`latest3y5y10ymax` الافتراضي: latest
period	string	`annualquarterly` الافتراضي: annual
metrics	string	`coreextended` الافتراضي: core
meta	string	`minimalextended` الافتراضي: minimal

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

Free: لا تتوفر خدمة التحليلات المالية.
Starter: أحدث النسب المالية السنوية فقط، باستخدام history=latest وperiod=annual وmetrics=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+

قارن النسب والمؤشرات المالية لعدة شركات باستخدام أحدث البيانات المتاحة لكل شركة.

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* symbols	string	رموز الأسهم مفصولة بفواصل
metrics	string	`coreextended` الافتراضي: core
meta	string	`minimalextended` الافتراضي: minimal

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

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 لكل شركة.

تختلف الحقول المتاحة داخل كائن ratios بحسب البيانات والمؤشرات المتوفرة، لذلك يُفضّل أن يتعامل التطبيق مع هذه الحقول بشكل ديناميكي بدلاً من الاعتماد على قائمة ثابتة منها.

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

احصل على سجل توزيعات الأرباح النقدية للسهم، والتوزيعات القادمة، وعائد التوزيعات خلال آخر 12 شهراً.

GET /dividends/{symbol}/

Starter+

احصل على التوزيعات النقدية السابقة والقادمة للسهم، بالإضافة إلى معلومات عائد التوزيعات.

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* symbol	string	رمز السهم
limit	number	الافتراضي: 10، والحد الأقصى: 50

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+

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

ملاحظة

يجب كتابة قيم أنواع الأحداث (type) بالأحرف الإنجليزية الكبيرة (UPPERCASE)، مثل FINANCIAL_REPORT وDIVIDEND_ANNOUNCEMENT.

استخدم الأحرف الإنجليزية الكبيرة عند تصفية النتائج باستخدام importance، بينما تُعاد قيم هذا الحقل في الاستجابة بالأحرف الصغيرة.

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
symbol	string	رمز السهم
type	string	`FINANCIAL_REPORTDIVIDEND_ANNOUNCEMENTSTOCK_SPLITMERGER_ACQUISITIONMANAGEMENT_CHANGENEW_LISTINGDELISTINGREGULATORY_ACTIONPRODUCT_LAUNCHPARTNERSHIPLEGAL_ISSUEMARKET_EXPANSIONRESTRUCTURINGEARNINGS_SURPRISEINSIDER_TRADINGANALYST_RATING_CHANGECAPITAL_INCREASESHAREHOLDER_MEETINGOTHER`
importance	string	`CRITICALIMPORTANTREGULAR`
limit	number	الافتراضي: 20، والحد الأقصى: 100
offset	number	الافتراضي: 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: سلبي جداً

المحافظ

تتيح لك خدمة المحافظ في سهمك تسجيل العمليات المالية وتتبع المراكز الاستثمارية وأداء المحافظ من خلال سجل منظم للعمليات، مع إمكانية الوصول إليها عبر API أو لوحة تحكم المطورين.

GET/POST /portfolios/

Free

أنشئ محافظك الاستثمارية وأدرها وفقاً للحدود المتاحة في باقتك.

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* name	string	اسم المحفظة
description	string	وصف اختياري للمحفظة
workspace	number	معرّف مساحة العمل (اختياري)

200 OKapplication/json

{
  "id": 42,
  "owner_id": 1198,
  "workspace": null,
  "name": "Core Portfolio",
  "description": "Long-only Tadawul",
  "base_currency": "SAR",
  "metadata": {},
  "created_at": "2026-10-17T14:20:00Z",
  "updated_at": "2026-10-17T14:20:00Z"
}

POST /portfolios/{portfolio_id}/transactions/

Free

أضف العمليات المالية إلى سجل المحفظة، بما في ذلك الإيداعات وعمليات الشراء والبيع وتوزيعات الأرباح والرسوم والسحوبات.

مسار API

https://api.sahmk.sa/api/v1/portfolios/{portfolio_id}/transactions/

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* transaction_type	string	`depositbuyselldividendfeewithdrawal`
* amount_sar	number	قيمة العملية بالريال السعودي
symbol	string	رمز السهم، مطلوب لعمليات الشراء والبيع
quantity	number	عدد الأسهم، مطلوب لعمليات الشراء والبيع
unit_price_sar	number	سعر السهم الواحد في عمليات الشراء والبيع
fee_sar	number	رسوم العملية (اختياري)

ملاحظة

يُحتفظ بجميع العمليات في سجل لا يسمح بتعديل العمليات السابقة أو حذفها مباشرةً، ويمكن التراجع عن آخر عملية مسجلة فقط.

الحدود المتاحة حسب الباقة

Free: محفظة واحدة كحد أقصى، مع احتساب قيمة المحفظة باستخدام الأسعار المتأخرة، وعرض الأداء لفترة تصل إلى 30 يوماً.
Starter: حتى 3 محافظ، مع احتساب القيمة باستخدام الأسعار المتأخرة، وعرض الأداء لفترة تصل إلى سنة واحدة.
Pro: حتى 10 محافظ، مع احتساب القيمة باستخدام الأسعار اللحظية، وعرض الأداء لفترة تصل إلى 3 سنوات.
Business: حتى 50 محفظة، مع احتساب القيمة باستخدام الأسعار اللحظية، وإتاحة كامل سجل الأداء المتوفر.

التكامل مع مساحات العمل

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

الانتقال إلى المحافظ في لوحة التحكم

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

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

WS /ws/v1/stocks/

Pro+

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

مسار WebSocket

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 فقط.

رسالة تحديث السعر

رسالة WebSocketJSON

{
  "type": "quote",
  "symbol": "2222",
  "mode": "standard",
  "data": {
    "price": 25.86,
    "open": 25.4,
    "high": 25.9,
    "low": 25.2,
    "close": 25.86,
    "change": 0.86,
    "change_percent": 3.44,
    "previous_close": 25.0,
    "volume": 9803705,
    "value": 252308343.0,
    "trade_count": 12289,
    "bid": 25.84,
    "ask": 25.88,
    "bid_size": 79,
    "ask_size": 188,
    "liquidity": {
      "inflow_value": 154800000.0,
      "inflow_volume": 6000000,
      "outflow_value": 97508343.0,
      "outflow_volume": 3803705,
      "net_value": 57291657.0
    },
    "trade_time": "2026-10-06T12:00:00+00:00",
    "market_session": "pre-open",
    "auction": {
      "phase": "opening",
      "price": 25.9,
      "price_updated_at": "2026-10-07T06:31:01+00:00",
      "volume": 11646,
      "volume_updated_at": "2026-10-07T06:31:01+00:00",
      "symbol_state": null,
      "symbol_session": "pre-open"
    }
  },
  "timestamp": "2026-10-07T06:31:01.114000+00:00",
  "latency_ms": 14
}

السعر الاسترشادي خلال المزاد

يتضمن الحقل data.auction بيانات السعر والحجم الاسترشادي خلال مزاد الافتتاح أو الإغلاق، بالصيغة نفسها المستخدمة في استجابة أسعار الأسهم عبر REST.
تكون قيمة data.auction هي null خارج فترتي مزاد الافتتاح والإغلاق، وكذلك عند استخدام باقة توفر بيانات متأخرة.
يستمر الحقل data.price في عرض سعر آخر صفقة منفذة، ولا يتغير نتيجة تحديثات السعر الاسترشادي خلال المزاد.

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

احصل على بث لحظي للصفقات المنفذة عبر قناة الصفقات. عند الاشتراك باستخدام رموز أسهم محددة، تتلقى أولاً رسالة تأكيد الاشتراك (subscribed)، ثم رسالة تحتوي على أحدث الصفقات (trades_snapshot) لكل سهم تمت إضافته إلى الاشتراك، تليها تحديثات الصفقات اللحظية (trade) فور ورودها.

WS /ws/v1/market/trades/

Pro+

قناة للبث اللحظي للصفقات المنفذة في السوق السعودي.

مسار WebSocket

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 فقط.

عند طلب أحدث الصفقات باستخدام snapshot، يكون العدد الافتراضي 50 صفقة، والحد الأقصى 200 صفقة.

رسالة أحدث الصفقات (trades_snapshot)

رسالة WebSocketJSON

{
  "type": "trades_snapshot",
  "symbol": "2222",
  "updated_at": "2026-07-28T09:31:55+00:00",
  "count": 2,
  "events": [
    {
      "trade_seq": 204505,
      "event_time": "2026-07-28T09:31:55+00:00",
      "price": 26.3,
      "quantity": 40,
      "value": 1052.0,
      "side": "buy"
    },
    {
      "trade_seq": 204490,
      "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"
}

رسالة الصفقة اللحظية (trade)

رسالة WebSocketJSON

{
  "type": "trade",
  "symbol": "2222",
  "trade_seq": 204520,
  "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"
}

الرقم التسلسلي للصفقة (trade_seq)

يُستخدم رمز السهم وتاريخ تنفيذ الصفقة المستخرج من event_time بتوقيت الرياض، إلى جانب الرقم التسلسلي trade_seq، لتحديد كل صفقة بشكل فريد.
قد يتكرر الرقم التسلسلي في جلسة تداول لاحقة.

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

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

WS /ws/v1/market/depth/

Pro+

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

مسار WebSocket

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

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

Pro: إمكانية الوصول إلى أفضل 5 مستويات من أوامر الشراء والبيع، بعد الموافقة على طلب الوصول
Business+: إمكانية الوصول إلى أفضل 20 مستوى من أوامر الشراء والبيع ضمن بيانات Premium، بعد الموافقة على طلب الوصول

يتطلب الوصول إلى بيانات عمق السوق موافقة مسبقة، ولا يؤدي الاشتراك في باقة مؤهلة إلى تفعيل الخدمة تلقائياً.

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

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 فقط.

استخدم المعامل symbols عند الاشتراك في تحديثات سهم أو عدة أسهم أو إلغاء الاشتراك فيها. وللطلبات المتعلقة بسهم واحد، يقبل الخادم أيضاً المعامل symbol.

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

عند الاشتراك، تُرسل رسالة depth_snapshot لكل سهم أولاً، ثم رسالة تأكيد الاشتراك (subscribed).
بعد ذلك، تستمر تحديثات عمق السوق باستخدام رسائل من النوع نفسه (depth_snapshot).

رسالة تأكيد الاشتراك (subscribed)

json

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

رسالة بيانات عمق السوق (depth_snapshot)

رسالة WebSocketJSON

{
  "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
    }
  ],
  "market_order": {
    "bid_quantity": 79938,
    "bid_order_count": 22,
    "bid_updated_at": "2026-07-09T15:05:30+00:00",
    "ask_quantity": 87743,
    "ask_order_count": 11,
    "ask_updated_at": "2026-07-09T15:05:15+00:00"
  },
  "entitled_levels": 20,
  "timestamp": "2026-07-09T15:05:37.872738+00:00"
}

مصفوفتا bids وasks في المثال مختصرتان للإيضاح. عندما تكون قيمة levels هي 20، يمكن أن تتضمن الاستجابة حتى 20 مستوى سعرياً في كل جانب.

أوامر السوق

يتضمن الحقل market_order بيانات أوامر السوق بالصيغة نفسها المستخدمة في خدمة عمق السوق عبر REST.
تكون قيمة الحقل market_order هي null عندما لا توجد أوامر سوق بكميات موجبة في أي من جانبي الشراء والبيع.
لا يُعد السعر 0 مستوى سعرياً فعلياً، ولذلك لا تُحتسب أوامر السوق ضمن أفضل سعر طلب أو عرض، أو الفارق بينهما، أو إجمالي الكميات في المستويات السعرية.
تُرسل بيانات دفتر الأوامر حتى إذا كانت تحتوي على أوامر سوق فقط، دون وجود مستويات سعرية.

WebSocket اللحظي - معالجة الأخطاء

تعرّف على كيفية التعامل مع أخطاء WebSocket باستخدام بنية موحدة لرسائل الأخطاء. استخدم رمز إغلاق الاتصال لتحديد نوع المشكلة، ورمز الخطأ (error.code) وتفاصيله (error.details) في أحدث رسالة خطأ لتحديد الإجراء المناسب.

رموز أخطاء WebSocket

WS_INTERNAL_ERROR4000

حدث خطأ داخلي أثناء إنشاء الاتصال، مما أدى إلى تعذّر إكماله.

الإجراء المطلوب: أعد محاولة الاتصال مع زيادة مدة الانتظار تدريجياً وفق آلية التراجع الأسي (Exponential Backoff)، مع تحديد حد أقصى للانتظار وإضافة تفاوت عشوائي بين المحاولات (Jitter).

WS_AUTH_OR_ACCESS4401 / 4403

MARKET_DATA_ENTITLEMENT_*

تعذّر الوصول إلى البث بسبب مشكلة في المصادقة أو صلاحيات الحساب أو الاشتراك.

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

WS_RATE_LIMIT4429

DEPTH_WS_*_LIMIT / *_RATE_LIMITED

تم تجاوز أحد حدود الاستخدام المسموح بها، مثل عدد الاتصالات أو الاشتراكات أو معدل إرسال الأوامر.

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

WS_INVALID_REQUEST

INVALID_JSON / UNKNOWN_ACTION / SYMBOL_REQUIRED والقيم المقابلة المكتوبة بالأحرف الصغيرة

تم إرسال بيانات طلب غير صحيحة أو أمر غير مدعوم.

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

إرشادات إدارة الاتصالات المتعددة

افتح الاتصالات بشكل تدريجي، مع ترك فاصل زمني يتراوح بين 200 و400 مللي ثانية بين كل اتصال وآخر، بدلاً من فتحها جميعاً في الوقت نفسه.
نظّم محاولات إعادة الاتصال من خلال قائمة انتظار مشتركة لكل مفتاح API.
تجنّب إعادة إنشاء عدد كبير من الاتصالات في الوقت نفسه، خصوصاً عند افتتاح جلسة التداول.

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

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

استمر في إرسال أمر ping كل 30 ثانية للحفاظ على الاتصال، وأعد الاتصال عند الحاجة باستخدام آلية التراجع الأسي مع حد أقصى لمدة الانتظار وتفاوت عشوائي بين المحاولات.

بعد كل إعادة اتصال، أعد الاشتراك في رموز الأسهم المطلوبة.

قد لا تُرسل تحديثات جديدة لبيانات السوق خلال الفترات التي لا يشهد فيها السوق نشاطاً.

بنية رسالة الخطأ

json

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

WebSocket اللحظي - حدود الاستخدام

تُطبّق حدود الاتصالات المتزامنة بشكل مستقل على كل قناة من قنوات WebSocket (الأسهم، والصفقات، وعمق السوق). وتختلف هذه الحدود عن حدود الاشتراك المحددة لكل باقة، مثل الحد الأقصى لعدد رموز الأسهم في الاتصال الواحد، والحد الأقصى لعدد رموز الأسهم في طلب الاشتراك الواحد.

لا يؤدي الاشتراك في باقة مؤهلة إلى تفعيل جميع منتجات البيانات اللحظية تلقائياً، كما لا يمنح بالضرورة صلاحية عرض البيانات للمستخدمين النهائيين أو إعادة توزيعها. يمكنك تقديم طلب للوصول إلى المنتجات المطلوبة من صفحة «منتجات البيانات اللحظية»، والاطلاع على «سياسة الاستخدام التجاري» لمعرفة شروط الاستخدام والترخيص. كما توضح «شروط استخدام المطورين» ضوابط الاستخدام المسؤول لواجهات API.

عند عرض أي بيانات من سهمك، سواء كانت تاريخية أو متأخرة أو لحظية أو غيرها، يُشار إليها بأنها بيانات مقدمة من سهمك.

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

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

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

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

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

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

حدود الاتصالات المتزامنة

القناة	لكل مفتاح API	لكل حساب عبر جميع المفاتيح
الأسهم	20	40
الصفقات	20	40
عمق السوق	8	16

التنبيهات وWebhooks - إعداد Webhooks

سجّل عناوين استقبال إشعارات Webhook وتحقق من صلاحيتها قبل تفعيل قواعد التنبيه.

POST /api/v1/webhooks/

Pro+

أضف عنوان Webhook لاستقبال التنبيهات والإشعارات من سهمك.

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* url	string	رابط HTTPS لاستقبال الإشعارات
name	string	اسم وصفي اختياري

المعامل المطلوب: url — رابط HTTPS الذي يستقبل إشعارات Webhook.
المعامل الاختياري: name — اسم وصفي لتسهيل التعرف على عنوان الاستقبال.
التحقق من العنوان: عند إنشاء Webhook، يُرسل النظام طلب تحقق (Challenge) إلى العنوان المحدد. ويجب أن يستجيب الخادم برمز HTTP 200 لاجتياز التحقق.
مفتاح التوقيع السري: يُعاد الحقل signing_secret عند إنشاء Webhook فقط، ولا يظهر لاحقاً عند استعراض قائمة Webhooks أو طلب تفاصيل أحدها. احرص على حفظه بشكل آمن عند الإنشاء.

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"
}

الخطوة التالية: راجع قسمَي «التحقق من التوقيع» و«مراحل إرسال الإشعارات» لاستكمال إعداد Webhook للاستخدام الفعلي.

التنبيهات وWebhooks - بنية رسائل Webhook

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

Webhook Event Envelope

Pro+

تعرّف على البنية المعتمدة لرسائل Webhook والحقول التي تستقبلها تطبيقاتك عند إرسال التنبيهات.

رسالة WebhookJSON

{
  "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"
  }
}

مهم

عند التحقق من نسبة قيمة التداول في أحداث unusual_value_traded، تُحسب النسبة بقسمة قيمة التداول (value) على القيمة المرجعية للتداول المحسوبة خلال نافذة زمنية متحركة (rolling_value_baseline)، وليس باستخدام الحقل reference_value.

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

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

حدّد شروط السوق التي تؤدي إلى إطلاق التنبيهات وإرسال إشعارات Webhook عند تحققها. يمكنك إنشاء قواعد التنبيه من لوحة التحكم أو برمجياً عبر API.

إدارة التنبيهات وأنواع الأحداث

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

POST /api/v1/alerts/

Pro+

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

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
* symbol	string	رمز السهم
* event_type	string	`price_alertlarge_moveabnormal_volumeunusual_value_traded`
condition	string	`price_aboveprice_belowpct_changepct_change_abs_gteratio_gte` بحسب نوع الحدث
* value	number	القيمة التي يُقارن بها الشرط
webhook_id	number	معرّف Webhook
destination	object	كائن JSON يحدد وجهة إرسال التنبيه
config	object	كائن JSON يحتوي على إعدادات إضافية للقاعدة
once	boolean	`truefalse` الافتراضي: true

إرشادات إعداد قواعد التنبيه

ابدأ بتحديد عدد محدود من رموز الأسهم، واستخدم قيماً واضحة للشروط التي تؤدي إلى إطلاق التنبيهات.
استخدم فترات انتظار بين التنبيهات المتكررة (Cooldown) لتقليل الإشعارات غير الضرورية.
اختبر القواعد في بيئة اختبار قبل تفعيلها للاستخدام الفعلي.
يجب تحديد المعامل condition عند استخدام price_alert، بينما يتولى النظام توحيد قيم هذا المعامل تلقائياً لأنواع الأحداث الأخرى المدعومة.
يجب أن تكون قيم حدود النسب أكبر من 1.0. أما حدود التغير السعري الكبير (large_move)، فلا يمكن أن تتجاوز 10% في تاسي (TASI) و30% في نمو (NOMU).
القيمة الافتراضية للمعامل once هي true، أي أن القاعدة تُطلق التنبيه مرة واحدة. أما false فتسمح بتكرار التنبيه عند تحقق الشروط، مع مراعاة أي فترة انتظار بين التنبيهات، ولا تعني إطلاق التنبيه مع كل تحديث للسوق. وتستخدم الأمثلة القيمة 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+

استعرض قواعد التنبيه الحالية، مع إمكانية تصفية النتائج حسب حالة القاعدة.

مسار API

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المقبولة
status	string	`activepausedall`

تصفية النتائج: استخدم status=active أو status=paused أو status=all لتحديد القواعد التي تريد استعراضها. القيمة 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 و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
  }
}

تُعاد القيم الرقمية بصيغة number في JSON، وليس بصيغة string. وتُقرَّب قيمتا ratio وobserved_pct_change إلى أربع منازل عشرية.

التنبيهات وWebhooks - مراحل إرسال الإشعارات

تابع حالات إرسال إشعارات Webhook، بما في ذلك الإشعارات قيد الانتظار، والتي تم تسليمها بنجاح، ومحاولات إعادة الإرسال، والإشعارات التي تعذّر تسليمها.

Delivery Lifecycle

Pro+

تعرّف على حالات إرسال إشعارات Webhook وآلية إعادة المحاولة عند تعذّر التسليم.

تسلسل الحالات: pending → retrying → delivered أو dead_letter

فترات الانتظار بين المحاولات: 2s, 10s, 60s وتُطبَّق هذه المدد بين المحاولات المتتالية.

عدد المحاولات: 4 محاولات إجمالاً (محاولة أولى و3 محاولات إضافية)، دون إضافة تفاوت عشوائي.

حالات إعادة المحاولة: يُعاد إرسال الإشعار عند تلقي أي استجابة خارج نطاق 2xx، بما في ذلك أخطاء 4xx و5xx، وكذلك عند انتهاء مهلة الاستجابة أو حدوث خطأ في الاتصال، حتى استنفاد جميع المحاولات.

التعطيل التلقائي: عند فشل تسليم 3 إشعارات متتالية، يتم تعطيل Webhook تلقائياً. يجب معالجة المشكلة في عنوان الاستقبال وإعادة التحقق منه قبل استئناف استخدام قواعد التنبيه المرتبطة به.

استخدم event_id و correlation_id لتتبع الحدث والإشعارات المرتبطة به عبر مراحل المعالجة والإرسال.

لا تتوفر حالياً خدمة API عامة لإعادة إرسال الأحداث التي وصلت إلى الحالة dead_letter.

إدارة التنبيهات

يمكنك إعداد قواعد التنبيه وإدارة إشعارات Webhook من لوحة تحكم المطورين - التنبيهات الذكية.

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

تحقق من صحة التوقيع المرفق بكل طلب Webhook قبل معالجة الأحداث في بيئة الاستخدام الفعلي.

استخدم مفتاح التوقيع السري (signing_secret) الخاص بعنوان الاستقبال، والذي يُعاد عند إنشاء Webhook.

تتضمن ترويسات طلبات Webhook الحقول X-SAHMK-Signature وX-SAHMK-Event وX-SAHMK-Event-Id.

يتضمن كل طلب Webhook الترويسة X-SAHMK-Signature التي تحتوي على معلومات التوقيع.
يُنشأ التوقيع باستخدام خوارزمية HMAC-SHA256 بناءً على محتوى الرسالة بعد توحيد تنسيق JSON، بترتيب المفاتيح وإزالة المسافات الزائدة.
إذا لم يتطابق التوقيع المحسوب مع التوقيع المستلم، يجب رفض الطلب برمز الاستجابة 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)

الحماية من إعادة إرسال الطلبات

تتضمن ترويسة التوقيع طابعاً زمنياً (timestamp). يُنصح بالتحقق من أن الطابع الزمني يقع ضمن فترة زمنية مقبولة، للمساعدة في منع إعادة استخدام طلبات Webhook القديمة. يجب التحقق من صحة التوقيع والطابع الزمني قبل معالجة الحدث.

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

تعرّف على كيفية التعامل مع أخطاء إرسال إشعارات Webhook، مع ضمان إمكانية إعادة المحاولة بأمان وفهم رموز الأخطاء والإجراءات المناسبة لمعالجتها.

تنطبق رموز HTTP أدناه على طلبات API. أما إعادة إرسال إشعارات Webhook عند فشل التسليم، فتتبع سياسة مراحل إرسال الإشعارات.

إرشادات للتعامل مع الأخطاء

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

400INVALID_PARAM

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

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

401AUTH_REQUIRED

لم يتم تضمين الترويسة X-API-Key في الطلب.

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

403PLAN_LIMIT / FEATURE_DISABLED

الباقة الحالية لا تتيح الوصول إلى الميزة المطلوبة، أو تم الوصول إلى أحد حدود الاستخدام المسموح بها.

الإجراء المطلوب: راجع صلاحيات الباقة وحدود استخدامها، ثم قم بترقية الباقة أو تعديل الاستخدام حسب الحاجة.

404NOT_FOUND

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

الإجراء المطلوب: تحقق من صحة معرّف المورد ومن أنه مرتبط بالحساب المستخدم.

429RATE_LIMITED / detail

تتضمن الاستجابات برمز 429 القيمة RATE_LIMITED في الحقل error.code. وقد تتضمن الاستجابة أيضاً تفاصيل إضافية في الحقل detail عند تجاوز حصة استخدام التطبيق. عند توفر ترويسة Retry-After، التزم بمدة الانتظار المحددة فيها قبل إعادة المحاولة.

الإجراء المطلوب: أعد المحاولة بعد مدة انتظار متزايدة تدريجياً، مع إضافة تفاوت عشوائي بين المحاولات (Jitter).

بنية استجابة الخطأ

json

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

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

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

حدود الطلبات

تختلف حدود استخدام واجهة API بحسب باقتك، وتشمل نوعين من الحدود: الحصة اليومية للطلبات، والحد الأقصى لعدد الطلبات خلال الدقيقة الواحدة (Burst Limit).

قد تُطبّق هذه الحدود على مستوى مفتاح API أو الحساب أو عنوان IP. وللاطلاع على ضوابط الاستخدام المسؤول، راجع شروط استخدام المطورين.

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

الباقة	الحد اليومي للطلبات	الحد الأقصى للطلبات في الدقيقة	مفاتيح 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	حسب العقد	حسب العقد	حسب العقد	✓	حسب العقد	حسب العقد

الحصة اليومية للطلبات

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

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

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

تتضمن معظم الاستجابات الناجحة لمسارات /api/v1/* الترويسات التالية:

الترويسة	الوصف
X-RateLimit-Limit	الحد المسموح به للطلبات
X-RateLimit-Remaining	عدد الطلبات المتبقية وفقاً لطريقة احتساب الترويسة الحالية
X-RateLimit-Reset	وقت تجديد الحصة اليومية، بصيغة Unix Timestamp

يشير X-RateLimit-Reset إلى منتصف الليل التالي بتوقيت الرياض (Asia/Riyadh). رغم أن الحصة اليومية تُطبّق على الحساب بالكامل وتشمل جميع مفاتيح API، فإن قيمة X-RateLimit-Remaining تُحسب حالياً بناءً على المفتاح المستخدم في الطلب. لذلك، عند استخدام عدة مفاتيح، قد تعرض الترويسة عدداً من الطلبات المتبقية أكبر من الرصيد الفعلي المتاح للحساب.

قد تحذف بعض الخوادم الوسيطة (Proxy Servers) ترويسات حدود الطلبات من الاستجابة. عند تلقي استجابة برمز HTTP 429، تكون قيمة error.code هي RATE_LIMITED، سواء كان السبب تجاوز حدود الطلبات في الدقيقة على مستوى الخوادم الطرفية أو تجاوز حصة التطبيق أو أحد حدود استخدامه. وقد تتضمن أخطاء حدود التطبيق أيضاً الحقل detail في المستوى الأعلى من الاستجابة، لتوضيح سبب الخطأ. عند توفر الترويسة Retry-After، التزم بمدة الانتظار المحددة فيها قبل إعادة المحاولة.

رموز الأخطاء

تستخدم واجهة API رموز حالة HTTP القياسية للإشارة إلى نتائج الطلبات، وتُعيد رسائل الأخطاء بصيغة JSON منظمة توضح نوع الخطأ وسببه.

رموز أخطاء HTTP

400INVALID_ROUTE

تم استخدام مسار API غير صحيح. تتضمن الاستجابة اقتراحاً للمسار الصحيح.

401AUTH_REQUIRED

لم يتم تضمين الترويسة X-API-Key في الطلب. تحتوي الاستجابة على رمز الخطأ في error.code وتفاصيل إضافية في detail.

403INVALID_API_KEY

صيغة مفتاح API غير صحيحة، أو أن المفتاح المستخدم غير صالح أو تم إلغاؤه. تحتوي الاستجابة على error.code وdetail.

403PLAN_LIMIT

تتطلب الخدمة المطلوبة باقة أعلى من الباقة الحالية، مثل الوصول إلى البيانات التاريخية الذي يتطلب Starter أو أعلى، أو طلب مجموعات من البيانات المالية غير متاحة ضمن باقة Starter.

404INVALID_SYMBOL

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

404 / 409INVALID_IDENTIFIER / AMBIGUOUS_IDENTIFIER

تعذّر العثور على شركة تطابق المعرّف المُدخل، أو أن المعرّف يطابق أكثر من شركة، مما يتطلب تحديد الشركة المطلوبة بشكل أدق.

429RATE_LIMITED(حدود الخوادم الطرفية)

تم تجاوز الحد المسموح به لمعدل الطلبات أو الاتصالات على مستوى خادم Nginx، قبل وصول الطلب إلى التطبيق. تتضمن الاستجابة error.code وerror.message.

429RATE_LIMITED(حدود التطبيق)

تم تجاوز الحصة اليومية، أو الحد الأقصى للطلبات في الدقيقة، أو أحد حدود الاستخدام المرتبطة بعنوان IP، أو تم تطبيق حد أمني مؤقت. تتضمن الاستجابة error.code وdetail.

500SERVER_ERROR

حدث خطأ داخلي في الخادم. أعد المحاولة، أو تواصل مع فريق الدعم إذا استمرت المشكلة.

الحدود الأمنية المؤقتة للحسابات الجديدة

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

مثال على استخدام مسار API غير صحيح: من الأخطاء الشائعة عند التكامل استدعاء المسار GET /api/v1/quote/batch/. في هذه الحالة، تُعيد واجهة API الخطأ 400 INVALID_ROUTE، مع اقتراح المسار الصحيح.

json

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

تتضمن الاستجابات الناتجة عن عدم إرفاق مفتاح API (401)، أو استخدام مفتاح غير صالح أو مُلغى (403)، أو تجاوز حصة الاستخدام أو حدود الطلبات (429)، الحقلين error.code وerror.message، مع الاحتفاظ بالحقل detail. وعند تجاوز حصة الاستخدام اليومية (429)، يظهر الكائن upgrade إلى جانب الكائن error في الاستجابة.

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

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

json

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

عند تجاوز الحد المسموح به لمعدل الطلبات على مستوى Nginx، يُعاد الخطأ HTTP 429 قبل معالجة الطلب داخل التطبيق. في هذه الحالة، تكون قيمة الترويسة Retry-After هي 1، وتُستخدم بنية الاستجابة نفسها على النطاقين api.sahmk.sa وapp.sahmk.sa:

json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Request rate limit exceeded. Please retry shortly."
  }
}

تتضمن استجابات الأخطاء المتعلقة بمفتاح API المفقود أو المرفوض، والحصة اليومية، وحدود الطلبات في الدقيقة، وحدود عنوان IP، والقيود الأمنية المؤقتة، رمز الخطأ في error.code مع الاحتفاظ بالحقل detail. وعند تجاوز حصة الاستخدام اليومية، يظهر الكائن upgrade إلى جانب الكائن error.

json

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "A valid X-API-Key is required."
  },
  "detail": "A valid X-API-Key is required."
}

آخر تحديث في ٢٣ أكتوبر ٢٠٢٦

→ السابقتوزيعات الأرباح

التالي ←المحافظ