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

القسم الحالي: المحافظ

البدء

أنشئ حساباً واحصل على مفتاح 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 اللحظي

استخدم قنوات الأسعار والصفقات وعمق السوق المتدفقة عندما لا تعود الطلبات المتكررة (polling) كافية.

المصادقة

تتطلب جميع طلبات 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

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

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

ChatGPT

سهمك مدرج في دليل إضافات ChatGPT. أضفه من الصفحة العامة.

يلزمك حساب مطوّر في سهمك ومفتاح API. أنشئ حساباً أو افتح مفاتيح API إن كان لديك حساب.

أضف سهمك إلى ChatGPT

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

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

مثال:

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

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

Claude.ai

سهمك مدرج في دليل Claude. أضفه من الصفحة العامة.

يلزمك حساب مطوّر في سهمك ومفتاح API. أنشئ حساباً أو افتح مفاتيح API إن كان لديك حساب.

أضف سهمك إلى Claude

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

مثال:

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

Claude Code (CLI)

اربط Claude Code (CLI) بسهمك عبر الإنترنت. من دون تثبيت 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 على جهازك

محلي

ثبّت حزمة 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

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

نقطة النهاية

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 إذا لم يكن مزاد الافتتاح أو الإغلاق منعقداً الآن، وتبقى 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}/ للحصول على سعر شركة واحدة.

نقطة النهاية

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

المعاملات

(*) مطلوب

المعامل	النوع	القيم المسموحة
symbols *	string	رموز مفصولة بفاصلة
identifiers	string	أسماء شركات مفصولة بفاصلة
data_mode	string	`realtimedelayed` افتراضي الباقة إذا تُرك فارغاً

استخدم إما الرموز أو الأسماء، وليس كليهما.

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 رمزاً. إذا أرسلت عدداً أكبر، فستتضمن الاستجابة أيضاً 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	رمز السهم
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

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

نقطة النهاية

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

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

نقطة النهاية

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

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

نقطة النهاية

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

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

نقطة النهاية

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

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

نقطة النهاية

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

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

نقطة النهاية

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
}

عرض خطأ نقطة النهاية (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	رمز السهم
levels	integer	1-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 }
  ],
  "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.

نقطة النهاية

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
    }
  ],
  "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	رمز السهم

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-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	`1d1w1m30m60m` الافتراضي 1d
limit	integer	الافتراضي 500، والحد الأقصى 2000
offset	integer	الافتراضي 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-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
    }
  ]
}

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

30m/60m تستخدم الصفوف طابعاً زمنياً بصيغة ISO في date وتتضمن turnover, is_final, partial، و trade_count. number_of_trades اسم بديل مؤقت لنفس القيمة.
1d/1w/1m تستخدم الصفوف تاريخاً في date وتتضمن turnover. trade_count يُضمَّن عندما تتوفر أعداد صفقات الإغلاق.
Weekly and monthly trade_count هي مجموع أعداد الصفقات اليومية المتاحة في الأسبوع وفق ISO أو في الشهر الميلادي.
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	رمز السهم
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 تُحل إلى 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, semanticsوسياق التقارير العامة في 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
    }
  ],
  "semantics": {
    "income": "annual_full_year",
    "cashflow": "annual_full_year",
    "balance": "year_end_snapshot"
  },
  "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	رمز السهم
history	string	`latest3y5y10ymax` الافتراضي latest
period	string	`annualquarterly` الافتراضي annual
metrics	string	`coreextended` الافتراضي core
meta	string	`minimalextended` الافتراضي minimal

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

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	رموز مفصولة بفاصلة
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).
مفاتيح النسب ديناميكية، لذا اعرض كائنات النسب ديناميكياً.

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

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

GET /dividends/{symbol}/

Starter+

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

نقطة النهاية

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+

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

ملاحظة

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

نقطة النهاية

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

المحافظ

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

GET/POST /portfolios/

Free

إنشاء المحافظ وإدارتها ضمن حدود الباقة.

نقطة النهاية

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/{id}/transactions/

Free

إضافة العمليات إلى السجل المحاسبي (إيداع، شراء، بيع، توزيعات، رسوم، سحب).

نقطة النهاية

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	رسوم اختيارية

ملاحظة

النظام يعمل بسجل متسلسل (append-only)، ويمكن عكس آخر عملية فقط.

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

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

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

ربط مساحة العمل اختياري. ينشئ طبقة تشغيلية للمراقبة والتنبيهات، بينما يبقى نموذج المحفظة المحاسبي مستقلاً.

افتح المحافظ من لوحة المطور

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,
    "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-07-09T09:30:40+00:00",
    "market_session": "REGULAR",
    "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-07-09T09:30:41.114000+00:00",
  "latency_ms": 14
}

مزاد الافتتاح والإغلاق

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

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 القيمة الافتراضية 50 (الحد الأقصى 200).

رسالة اللقطة

200 OKapplication/json

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

رسالة الصفقة

200 OKapplication/json

{
  "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 اللحظي - عمق السوق

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

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.
التحديثات التالية تأتي برسالة 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
    }
  ],
  "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": 20,
  "timestamp": "2026-07-09T15:05:37.872738+00:00"
}

أوامر السوق

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

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
name	string	تسمية اختيارية

مطلوب: 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	رمز السهم
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

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

ابدأ بنطاق رموز محدود وحدود واضحة.
استخدم فترات تهدئة لتقليل ضوضاء الإشعارات.
تحقق في بيئة الاختبار قبل تفعيل قواعد الإنتاج.
condition مطلوب مع price_alert؛ أما أنواع الأحداث الموثقة الأخرى فتطبّعه تلقائياً.
يجب أن تتجاوز حدود النسب 1.0. والحد الأقصى للحركة الكبيرة هو 10% في TASI و30% في NOMU.
once القيمة الافتراضية 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	`activepausedall`

الاستعلام: 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 أو التنبيه لهذا الحساب.

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

429RATE_LIMITED / detail

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

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

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

json

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

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

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

حدود الطلبات

تُحدد معدلات الوصول إلى API حسب باقتك. يوجد نوعان من الحدود: الحصة اليومية وحد الذروة (burst) لكل دقيقة.

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

الباقة	الحد اليومي	حد الذروة	مفاتيح 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، القيمة error.code RATE_LIMITED تغطي حد الذروة على الحافة وحصة التطبيق أو حده. حصة التطبيق تُبقي أيضاً نص detail في المستوى الأعلى. التزم بـ Retry-After عند توفرها.

رموز الأخطاء

تستخدم الواجهة رموز حالة 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 عند توفرها، ثم حاول لاحقاً.

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

json

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

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

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

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

json

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

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

json

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

المفتاح غير المرفق أو المرفوض، والحصة اليومية، وحد الدقيقة، وحد عنوان IP، والحد الأمني المؤقت تتضمن الآن error.code وتُبقي detail. في تجاوز الحصة 429 يبقى upgrade بجانب error.

json

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

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

→ السابقأحداث الأسهم

التالي ←الأسهم