تعرض الآن: مرجع الحمولة
البدء
أنشئ حساباً واحصل على مفتاح API ثم نفّذ طلبك الأول. بعد ذلك يمكنك الانتقال من نقاط REST الأساسية إلى حزم التطوير والأتمتة والبث اللحظي مع نمو منتجك.
ابدأ من هنا
الطلب الأول
احصل خلال دقائق على سعر لحظي لسهم سعودي باستخدام رمزه.
البناء
واجهة API الأساسية
الأسهم والصفقات وعمق السوق وملخصات السوق والبيانات التاريخية وبيانات الشركات والقوائم المالية.
لحظي
WebSocket
قنوات الأسهم والصفقات وعمق السوق، وحدود الاشتراك، ومعالجة إعادة الاتصال والأخطاء.
التنبيهات وWebhooks
سير عمل الإشعارات
Webhooks للأحداث وقواعدها وسلوك التسليم وحدوده.
بدء سريع
- أنشئ حساباً مجانياً
- احصل على مفتاح API من لوحة التحكم
- نفّذ أول طلب API
- تصفح أمثلة الكود على GitHub
عنوان API الأساسي
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.
الاستجابة المتوقعة
{
"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 عند الحاجة إلى تحديثات متدفقة.
ملاحظة حول الالتباس: إذا طابق المعرّف أكثر من شركة، فأرسل رمز التداول الدقيق لإزالة الالتباس.
الخطوة التالية لعمليات البيانات: استخدم مركز البيانات من لوحة التحكم عندما تحتاج إلى تصدير مجمّع أو سير عمل منظم لمجموعات البيانات.
المصادقة
تتطلب جميع طلبات API المصادقة باستخدام مفتاح API. أرسل مفتاحك في X-API-Key .
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 في الاختبارات والعروض والأدوات المؤتمتة.
pip install -U sahmk
export SAHMK_API_KEY="your_api_key"
sahmk quote "Saudi Aramco"إذا لم تجد محلياً ميزة موثقة حديثاً في SDK/CLI، فنفّذ pip install -U sahmk للترقية.
حزمة Python:
from sahmk import SahmkClient
client = SahmkClient(api_key="YOUR_API_KEY")
directory = client.companies(search="aramco", market="TASI", limit=20, offset=0)
symbol = directory["results"][0]["symbol"]
print(client.quote("أرامكو السعودية"))إذا لم تكن واثقاً من رمز الإدخال، فاستدعِ client.companies(...) أولاً لاكتشاف رمز صالح قبل استدعاءات السعر أو الشركة.
استخدم هذا الخيار عندما: تريد كوداً تمهيدياً أقل من REST الخام، أو سير عمل مضبوط الأنواع في Python، أو وصولاً سريعاً من سطر الأوامر إلى الأسعار وبيانات السوق.
تقبل دوال الأسعار معرّفات متعددة: الرمز أو الاسم العربي أو الإنجليزي أو الاسم البديل. استخدم الرمز عندما يكون المعرّف ملتبساً.
الأمثلة الكاملة: github.com/sahmk-sa/sahmk-python
الذكاء الاصطناعي والوكلاء
استخدم سهمك داخل Claude Desktop وCursor والعملاء الآخرين المتوافقين مع MCP. وللاستخدام المباشر من الوكلاء، استخدم خادم MCP لاستدعاء الأدوات و/api-docs.mdللتوثيق القابل للقراءة آلياً.
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
{
"mcpServers": {
"sahmk": {
"command": "sahmk-mcp",
"env": {
"SAHMK_API_KEY": "your_api_key_here"
}
}
}
}Cursor
أضف إلى ملف مشروعك .cursor/mcp.json
{
"mcpServers": {
"sahmk": {
"command": "sahmk-mcp",
"env": {
"SAHMK_API_KEY": "your_api_key_here"
}
}
}
}استخدم هذا الخيار عندما: يريد فريقك إتاحة سهمك داخل سير عمل الذكاء الاصطناعي أو مساعدي البحث أو أدوات الوكلاء دون بناء طبقة تكامل إضافية.
استخدم companies_list لاكتشاف الرموز قبل أدوات الأسعار باستخدام search وmarket وlimit وoffset.
الأسهم
احصل على أسعار وبيانات التداول الحالية لشركة واحدة أو عدة شركات. راجع WebSocket اللحظي للحصول على تحديثات متدفقة.
GET /quote/{symbol}/
Freeاحصل على السعر الحالي وبيانات التداول لرمز سهم واحد.
نقطة النهاية
https://api.sahmk.sa/api/v1/quote/2222/?identifier=أرامكو
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| symbol * | string | 2222 |
| identifier | string | أرامكو |
| data_mode | string | delayed |
استخدم symbol عندما تكون مطابقة المعرّف ملتبسة.data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.
توفر البيانات حسب الباقة:
- Free / Starter:أسعار متأخرة (نحو 15 دقيقة)
- Pro+:أسعار لحظية
{
"symbol": "2222",
"name": "أرامكو السعودية",
"name_en": "Saudi Arabian Oil Co",
"price": 26.6,
"change": 0.0,
"change_percent": 0.0,
"open": 26.6,
"high": 26.68,
"low": 26.52,
"previous_close": 26.6,
"volume": 6601208,
"value": 175637052.96,
"bid": 26.6,
"bid_size": 9181,
"ask": 26.62,
"ask_size": 38155,
"liquidity": {
"inflow_value": 99498351.21,
"inflow_volume": 3739041,
"inflow_trades": 4858,
"outflow_value": 76138701.51,
"outflow_volume": 2862167,
"outflow_trades": 3472,
"net_value": 23359649.699999988
},
"updated_at": "2026-08-12T12:20:00+00:00",
"is_delayed": false,
"resolved_instrument": {
"input": "أرامكو",
"symbol": "2222",
"name": "أرامكو",
"match_type": "alias_exact",
"confidence": "high"
}
}عرض خطأ عدم توفر بيانات السعر مؤقتاً
{
"error": {
"code": "PRICE_DATA_TEMPORARILY_UNAVAILABLE",
"message": "Price data for '2222' is temporarily unavailable. Please retry shortly."
}
}GET /quotes/
Starter+احصل على أسعار عدة شركات في طلب واحد. يتطلب ذلك باقة Starter أو أعلى.
الخيار البديل للباقة المجانية: GET /quote/{symbol}/ للحصول على سعر شركة واحدة.
نقطة النهاية
https://api.sahmk.sa/api/v1/quotes/?symbols=2222,1120
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| symbols * | string | 2222,1120 |
| identifiers | string | أرامكو، الراجحي |
| data_mode | string | delayed |
استخدم إما symbols أو identifiers، وليس كليهما.data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.
{
"quotes": [
{
"symbol": "2222",
"name": "شركة الزيت العربية السعودية",
"name_en": "Saudi Arabian Oil Co",
"price": 26.6,
"change": 0.0,
"change_percent": 0.0,
"high": 26.68,
"low": 26.52,
"bid": 26.6,
"ask": 26.62,
"bid_size": 9181,
"ask_size": 38155,
"volume": 6601208,
"net_liquidity": 23359649.699999988,
"updated_at": "2026-08-12T13:00:00+00:00",
"is_delayed": false
},
{
"symbol": "1120",
"name": "مصرف الراجحي",
"name_en": "Al Rajhi Banking & Investment Corp SJSC",
"price": 64.05,
"change": -0.05,
"change_percent": -0.08,
"high": 64.3,
"low": 63.7,
"bid": 63.95,
"ask": 64.05,
"bid_size": 15,
"ask_size": 43300,
"volume": 3775688,
"net_liquidity": -47806410.94999999,
"updated_at": "2026-08-12T13:00:00+00:00",
"is_delayed": false
}
],
"count": 2,
"max_symbols": 50,
"requested_count": 2
}حدود الطلبات المجمّعة
يقتصر الطلب على 50 رمزاً. إذا أرسلت عدداً أكبر، فستتضمن الاستجابة أيضاً truncated: true و warning يوضح أنه تمت معالجة أول 50 رمزاً فقط.
مطابقة المعرّفات
identifiers ، تتضمن الاستجابة أيضاً كائن resolution يحتوي على requested_count, resolved_count, ambiguous، و not_found.هل تحتاج إلى الرموز؟ استخدم GET /companies/
قواعد سريعة: استخدم معاملات المسار لمورد واحد (مثل /quote/{symbol}/)، واستخدم معاملات الاستعلام لتصفية القوائم (مثل /events/?symbol=2222&limit=20). جُمعت أخطاء HTTP/API الشائعة في قسم رموز الأخطاء.
الصفقات
احصل على أحدث صفقات رمز معين. راجع WebSocket اللحظي للتحديثات المتدفقة.
GET /market/trades/{symbol}/
Pro+اجلب أحدث صفقات رمز واحد، مرتبة من الأحدث.
نقطة النهاية
https://api.sahmk.sa/api/v1/market/trades/2222/?limit=1
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| symbol * | string | 2222 |
| limit | integer | 5 |
limit القيمة الافتراضية to 50 (الحد الأقصى 200). تُرتب النتائج من الأحدث.
{
"symbol": "2222",
"updated_at": "2026-08-12T12:19:10+00:00",
"count": 1,
"events": [
{
"event_time": "2026-08-12T12:19:10+00:00",
"price": 26.6,
"quantity": 20,
"value": 532.0,
"side": "buy"
}
],
"summary": {
"event_count": 1,
"trade_quantity": 20,
"trade_value": 532.0,
"latest_event_time": "2026-08-12T12:19:10+00:00"
}
}عرض أخطاء نقطة النهاية
{
"error": {
"code": "INVALID_SYMBOL",
"message": "Stock symbol '9999' not found."
}
}
{
"error": {
"code": "INVALID_LIMIT",
"message": "limit must be a valid integer."
}
}السوق
احصل على بيانات السوق الشاملة، بما فيها قيم المؤشرات وأبرز التحركات وأداء القطاعات.
GET /market/summary/?index=TASI
Freeاحصل على قيمة مؤشر السوق وحجم التداول واتجاه السوق.
نقطة النهاية
https://api.sahmk.sa/api/v1/market/summary/?index=TASI
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| index | string | TASI |
| data_mode | string | delayed |
القيم المدعومة: TASI, NOMU. القيمة الافتراضية TASI.data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.
{
"index": "TASI",
"is_delayed": false,
"timestamp": "2026-08-12T12:20:00+00:00",
"index_value": 10844.12,
"index_change": 10.94,
"index_change_percent": 0.1,
"total_volume": 256387075,
"advancing": 141,
"declining": 112,
"unchanged": 17,
"market_mood": "Bullish"
}GET /market/gainers/?limit=1&index=TASI
Freeاحصل على أكثر الأسهم ارتفاعاً حسب نسبة التغير.
نقطة النهاية
https://api.sahmk.sa/api/v1/market/gainers/?limit=1&index=TASI
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| index | string | TASI |
| limit | number | 1 |
| data_mode | string | delayed |
data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.
{
"index": "TASI",
"is_delayed": false,
"gainers": [
{
"symbol": "6040",
"name": "شركة تبوك للتنمية الزراعية",
"name_en": "Tabuk Agriculture Development C",
"price": 9.13,
"change": 0.83,
"change_percent": 10.0,
"volume": 4846179,
"updated_at": "2026-08-12T13:00:00+00:00"
}
],
"count": 1
}GET /market/losers/?limit=1&index=TASI
Freeاحصل على أكثر الأسهم انخفاضاً حسب نسبة التغير.
نقطة النهاية
https://api.sahmk.sa/api/v1/market/losers/?limit=1&index=TASI
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| index | string | TASI |
| limit | number | 1 |
| data_mode | string | delayed |
data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.
{
"index": "TASI",
"is_delayed": false,
"losers": [
{
"symbol": "4011",
"name": "شركة لازوردي للمجوهرات",
"name_en": "L'azurde Company for Jewelry SJSC",
"price": 10.43,
"change": -0.47,
"change_percent": -4.31,
"volume": 369026,
"updated_at": "2026-08-12T13:00:00+00:00"
}
],
"count": 1
}GET /market/volume/?limit=1&index=TASI
Freeاحصل على أعلى الأسهم حسب حجم التداول.
نقطة النهاية
https://api.sahmk.sa/api/v1/market/volume/?limit=1&index=TASI
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| index | string | TASI |
| limit | number | 1 |
| data_mode | string | delayed |
data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.
{
"index": "TASI",
"is_delayed": false,
"stocks": [
{
"symbol": "6015",
"name": "شركة أمريكانا للمطاعم العالمية بي إل سي - شركة أجنبية",
"name_en": "AMERICANA",
"price": 2.38,
"change": 0.07,
"change_percent": 3.03,
"volume": 22562421,
"updated_at": "2026-08-12T13:00:00+00:00"
}
],
"count": 1
}GET /market/value/?limit=1&index=TASI
Freeاحصل على أعلى الأسهم حسب قيمة التداول بالريال السعودي.
نقطة النهاية
https://api.sahmk.sa/api/v1/market/value/?limit=1&index=TASI
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| index | string | TASI |
| limit | number | 1 |
| data_mode | string | delayed |
data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.
{
"index": "TASI",
"is_delayed": false,
"stocks": [
{
"symbol": "2380",
"name": "شركة رابغ للتكرير والبتروكيماويات",
"name_en": "Rabigh Refining and Petrochemic",
"price": 17.6,
"change": 0.51,
"change_percent": 2.98,
"volume": 14502060,
"value": 257478357.3,
"updated_at": "2026-08-12T13:00:00+00:00"
}
],
"count": 1
}GET /market/sectors/?index=TASI
Freeاحصل على أداء القطاعات وإحصاءاتها.
نقطة النهاية
https://api.sahmk.sa/api/v1/market/sectors/?index=TASI
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| index | string | TASI |
| data_mode | string | delayed |
data_mode يدعم realtime, delayed. إذا لم تحدده، فسيُستخدم السلوك الافتراضي للباقة.
{
"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 غير صالح)
{
"error": {
"code": "INVALID_INDEX",
"message": "Invalid index 'XYZ'. Supported values: TASI, NOMU."
}
}عمق السوق
احصل على لقطات عمق دفتر الأوامر لرمز معين مع التحكم في عدد المستويات. راجع WebSocket اللحظي للتحديثات المتدفقة.
GET /market/depth/{symbol}/
Pro+اجلب لقطات عمق السوق لرمز معين بعدد المستويات المطلوب.
متطلبات الوصول
يلزم اشتراك Pro أو أعلى، كما يجب تفعيل وصول عمق السوق عبر REST لحسابك. أهلية الباقة وحدها لا تفعّل صلاحية بيانات السوق هذه.
نقطة النهاية
https://api.sahmk.sa/api/v1/market/depth/2222/?levels=5
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| symbol * | string | 2222 |
| levels | integer | 5 (or any numeric value) |
اختر العمق الذي تحتاجه باستخدام levels (عادةً 5 أو حتى 20). قد يكون العمق المعاد أقل بحسب صلاحيتك وتوفر بيانات السوق حالياً.
توفر البيانات حسب الباقة:
- Pro:مؤهل لأفضل 5 مستويات من العمق. طلب الوصول
- Business+:مؤهل لبيانات Premium لأفضل 20 مستوى من العمق. طلب الوصول
{
"symbol": "2222",
"updated_at": "2026-08-12T12:19:54.982770+00:00",
"session": "atc",
"book_state": "normal",
"levels": 5,
"best_bid": 26.6,
"best_ask": 26.62,
"spread": 0.02,
"spread_bps": 7.52,
"total_bid_quantity_top5": 241514,
"total_ask_quantity_top5": 491802,
"total_bid_quantity": 241514,
"total_ask_quantity": 491802,
"level_imbalance": -0.3413,
"level_imbalance_top5": -0.3413,
"bids": [
{ "level": 0, "price": 26.6, "quantity": 9181, "order_count": 18 },
{ "level": 1, "price": 26.58, "quantity": 228, "order_count": 3 },
{ "level": 2, "price": 26.56, "quantity": 13363, "order_count": 34 },
{ "level": 3, "price": 26.54, "quantity": 4133, "order_count": 21 },
{ "level": 4, "price": 26.52, "quantity": 214609, "order_count": 120 }
],
"asks": [
{ "level": 0, "price": 26.62, "quantity": 38155, "order_count": 17 },
{ "level": 1, "price": 26.64, "quantity": 25208, "order_count": 12 },
{ "level": 2, "price": 26.66, "quantity": 17877, "order_count": 36 },
{ "level": 3, "price": 26.68, "quantity": 203743, "order_count": 53 },
{ "level": 4, "price": 26.7, "quantity": 206819, "order_count": 72 }
],
"entitled_levels": 5
}ملاحظات تقديم بيانات العمق
- تعيد API أفضل لقطة متاحة وقت الطلب.
- قد يكون العمق المعاد أقل من المطلوب بحسب الصلاحية وتوفر بيانات السوق حالياً.
عرض أخطاء نقطة النهاية
{
"error": {
"code": "DEPTH_NOT_AVAILABLE",
"message": "No usable depth snapshot found for '2222'."
}
}
{
"error": {
"code": "MARKET_DATA_ENTITLEMENT_REQUIRED",
"message": "Market-depth access requires an approved entitlement."
}
}واجهات الشركات والرموز
اكتشف الرموز الصالحة واجلب معلومات تفصيلية عن الشركات.
GET /companies/
Freeدليل مبسط للشركات لاكتشاف الرموز قبل استدعاء نقاط نهاية الأسعار أو الشركات. يشمل الصكوك وأنواع الأدوات الأخرى عبر security_type.
نقطة النهاية
https://api.sahmk.sa/api/v1/companies/?search=aramco&market=TASI&limit=1&offset=0
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| search | string | aramco |
| market | string | TASI |
| limit | number | 1 |
| offset | number | 0 |
{
"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 تعني أن بيانات السوق الوصفية في المصدر غير مكتملة لذلك الرمز. تُضمّن أدوات الصكوك في استجابات الاكتشاف.
عرض الأخطاء
{
"error": {
"code": "INVALID_MARKET",
"message": "market must be one of: TASI, NOMU."
}
}
{
"error": {
"code": "INVALID_PARAM",
"message": "limit and offset must be valid integers."
}
}GET /company/{symbol}/
Freeاحصل على معلومات الشركة. تختلف الاستجابة بحسب الباقة.
البيانات المتاحة حسب الباقة:
- Free:الاسم وsecurity_type وsector_name وsector_name_ar وmarket_id والوصف والموقع
- Starter:+ الأساسيات الكاملة (PE وEPS والقيمة الدفترية وbeta ونطاقات الأسبوع والشهر و52w)
- Pro+:+ المؤشرات الفنية والتقييم وإجماع المحللين
نقطة النهاية
https://api.sahmk.sa/api/v1/company/2222/
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| symbol * | string | 2222 |
{
"symbol": "2222",
"name": "أرامكو السعودية",
"name_en": "SAUDI ARAMCO",
"current_price": 26.6,
"is_delayed": false,
"sector_name": "Energy",
"sector_name_ar": "الطاقة",
"market_id": "TASI",
"security_type": "Equity",
"description": "Saudi Arabian Oil Company operates as an integrated energy and chemical company in the Kingdom of Saudi Arabia and internationally. The company operates through two segments, Upstream and Downstream. The Upstream segment explores, develops, produces, and sells crude oil, condensate, natural gas, and natural gas liquids (NGLs). The Downstream segment produces various chemicals, such as aromatics, olefins, and polyolefins; polyols, isocyanates, and synthetic rubber; methanol, MTBE, glycols, linear alpha olefins, polyethylene, polypropylene, polyethylene terephthalate, polyvinyl chloride, polystyrene, polycarbonate, and engineering thermoplastics and their blends; and lubricants and base oils, as well as engages in the refining and petrochemicals, retail operations, distribution, supply and trading, and power generation. It also markets and distributes hydrocarbons, petroleum products; and trades crude oil, refined petroleum, and liquid chemical products. In addition, the company develops, manufactures, and markets high-performance rubber; and provides crude oil storage, investment, consulting, information technology, personnel and other support, agri-nutrients, purchasing, engineering, benefits administration, oil field, insurance, pipeline transport, vendor sourcing, marketing and sales support, financing, support, and marine management and transportation services. Further, it engages in aircraft operations and leasing; aviation; sports club; retail fuel marketing and operations; investment management of post-employment benefit plans; wholesale fuel operations; importing and exporting refined products and crude oil; and real estate holdings. Additionally, the company engages in prospecting, exploring, drilling, processing, manufacturing, refining, extracting, and marketing hydrocarbon substances. The company was founded in 1933 and is headquartered in Dhahran, the Kingdom of Saudi Arabia.",
"website": "https://www.aramco.com",
"country": "Saudi Arabia",
"currency": "SAR",
"fundamentals": {
"market_cap": 6437200000000.0,
"pe_ratio": 15.65,
"forward_pe": 15.93,
"eps": 1.6998,
"eps_ttm": 1.6998,
"basic_eps": 1.4382,
"diluted_eps": null,
"book_value": 6.49,
"price_to_book": 4.1,
"beta": 0.01,
"shares_outstanding": 242000000000,
"float_shares": 6014547000,
"week_high": 26.86,
"week_low": 26.5,
"month_high": 27.26,
"month_low": 26.12,
"fifty_two_week_high": 27.96,
"fifty_two_week_low": 23.04
},
"technicals": {
"rsi_14": 57.45,
"macd_line": 0.0187,
"macd_signal": 0.027,
"macd_histogram": -0.0084,
"fifty_day_average": 26.53,
"technical_strength": 0.0,
"price_direction": "متذبذب",
"updated_at": "2026-08-12T12:45:00.690083+00:00"
},
"valuation": {
"fair_price": 24.71,
"fair_price_confidence": 0.95,
"calculated_at": "2026-08-11T21:00:00.010275+00:00"
},
"analysts": {
"target_mean": 30.12,
"target_median": 29.8,
"target_high": 35.0,
"target_low": 26.8,
"consensus": "buy",
"consensus_score": 2.11,
"num_analysts": 18
}
}security_type متاح في Free+ ويستخدم القيم نفسها التي يستخدمها GET /companies/: Equity, Sukuk, ETF, Closed-End Fund, or Unknown عندما تكون بيانات السوق الوصفية في المصدر غير مكتملة.
البيانات التاريخية
استخدم بيانات OHLCV التاريخية — الافتتاح والأعلى والأدنى والإغلاق والحجم — للتحليل الفني والاختبارات التاريخية.
GET /historical/{symbol}/
Starter+احصل على بيانات الأسعار التاريخية لسهم.
نقطة النهاية
https://api.sahmk.sa/api/v1/historical/2222/?interval=1d&from=2024-01-01&to=2026-01-01&limit=1&offset=0
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| symbol * | string | 2222, TASI, or NOMU |
| from | string | 2024-01-01 |
| to | string | 2026-01-01 |
| interval | string | 1d |
| limit | integer | 1 |
| offset | integer | 0 |
symbol: يقبل رمز سهم أو رمز المؤشر TASI أو NOMU. from: القيمة الافتراضية قبل نحو 30 يوماً. to: القيمة الافتراضية هي اليوم. interval: 1d, 1w, 1m, 30m, 60m (الافتراضي 1d). limit: الافتراضي 500 والحد الأقصى 2000. offset: الافتراضي 0.
البيانات المتاحة حسب الباقة:
- Free:لا تتوفر بيانات تاريخية
- Starter:
1d,1w,1m - Pro:فترات Starter بالإضافة إلى
60mحتى 90 يوماً - Business:فترات Starter بالإضافة إلى
30mحتى 6 أشهر، بالإضافة إلى60mحتى سنة واحدة - Enterprise:يتوفر افتراضياً ما تتيحه باقة Business، ويمكن الاتفاق على مدد احتفاظ وفترات وخيارات تسليم مخصصة
إذا تجاوزت الفترة أو النطاق الزمني المطلوب حدود باقتك، فستعيد API الخطأ 403 PLAN_LIMIT.
هل تحتاج إلى سير عمل عملي لبيانات اليوم الواحد؟ راجع بيانات اليوم الواحد مع سهمك (SDK + MCP).
{
"symbol": "2222",
"interval": "1d",
"source": "historical_eod",
"is_intraday": false,
"is_final": true,
"partial": false,
"latest_bar_at": "2024-01-01",
"from": "2024-01-01",
"to": "2026-01-01",
"limit": 1,
"offset": 0,
"total": 500,
"count": 1,
"has_more": true,
"data": [
{
"date": "2024-01-01",
"open": 33.0,
"high": 33.15,
"low": 32.9,
"close": 33.05,
"volume": 12123324,
"adjusted_close": 33.05
}
]
}صيغة صف الشمعة
30m/60mتستخدم الصفوف طابعاً زمنياً بصيغة ISO فيdateوتتضمنis_final,partial، وnumber_of_trades.1d/1w/1mتستخدم الصفوف تاريخاً فيdate.adjusted_closeيطابقcloseللسجلات اللاحقة لمارس 2024 ولسجلات اليوم الواحد.- ما دام
has_moreيساوي true، فاطلب الصفحة التالية باستخدامoffset + limit.
البيانات المالية
احصل على قوائم الدخل والميزانية والتدفقات النقدية بصيغة منظمة للشركات السعودية المدرجة.
GET /financials/{symbol}/
Starter+نقطة النهاية
https://api.sahmk.sa/api/v1/financials/1120/?period=annual&history=1y&metrics=extended
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| symbol * | string | 1120 |
| type | string | all |
| period | string | quarterly |
| history | string | latest |
| metrics | string | extended |
| result | string | series |
| limit | integer | 4 (max 20) |
type: القيم المتاحة income وbalance وcashflow وall. period: القيم المتاحة annual وquarterly وauto. history: القيم المتاحة 1y و3y و5y و10y وmax. metrics: القيم المتاحة core وextended. result: القيم المتاحة series وlatest. العلامات الاختيارية: limit: الافتراضي 4 (والحد الأقصى 20). include_future_placeholders=1, include_partial=1.
ملاحظات السلوك
period=autoتُحل إلىannualعندما تكون أحدث سنة مالية مكتملة، وإلا فتُحل إلىquarterly.- ينبغي لعملاء Starter طلب
period=annualصراحةً؛ وإذا كانتautoتُحل إلى quarterly فستعيد API403 PLAN_LIMIT. - يعيد السجل السنوي السنوات المالية المكتملة افتراضياً؛ استخدم
include_partial=1لتضمين صف السنة الحالية غير المكتملة أو منذ بداية السنة. - يعيد الوضع الربعي أحدث الأرباع المتاحة افتراضياً.
result=latestيتبع الدقة المحددة أو المحلولة؛ وفي الوضع السنوي يعيد أحدث سنة مكتملة افتراضياً ما لمinclude_partial=1يُستخدم.- تبقى قيمة API الافتراضية
period=annualللحفاظ على التوافق السابق. - تُعاد القوائم في مصفوفات مثل
income_statements,balance_sheets، وcash_flows. - تتضمن الاستجابات أيضاً
symbol,statement_periodوسياق التقارير العامة فيreporting.
البيانات المتاحة حسب الباقة:
- Starter:قوائم سنوية؛ اطلب period=annual صراحةً. تدعم خيارات السجل حتى 3 سنوات، ويحافظ الطلب دون خيارات على الاستجابة الموسعة القديمة ذات الصفوف الأربعة.
- Pro/Business:بيانات ربع سنوية وموسعة ونطاقات 5Y/10Y/max وعروض كاملة
- Enterprise:مجموعة خصائص مالية وصلاحيات وصول مخصصة حسب الاتفاق
مثال على الاستجابة
{
"symbol": "1120",
"statement_period": "annual",
"income_statements": [
{
"report_date": "2025-12-31",
"statement_period": "annual",
"fiscal_year": 2025,
"quarters_reported": 4,
"quarters_covered": 4,
"is_full_year": true,
"total_revenue": 39093965000.0,
"gross_profit": 6730335.0,
"operating_income": null,
"net_income": 24791754000.0
}
],
"balance_sheets": [
{
"report_date": "2025-12-31",
"statement_period": "annual",
"fiscal_year": 2025,
"quarters_reported": 4,
"quarters_covered": 4,
"is_full_year": true,
"total_assets": 1043268297000.0,
"total_liabilities": 900355952000.0,
"stockholders_equity": 142912345000.0,
"total_debt": null
}
],
"cash_flows": [
{
"report_date": "2025-12-31",
"statement_period": "annual",
"fiscal_year": 2025,
"quarters_reported": 4,
"quarters_covered": 4,
"is_full_year": true,
"operating_cash_flow": -22373072000.0,
"investing_cash_flow": -1564467000.0,
"financing_cash_flow": 36302349000.0,
"free_cash_flow": null
}
],
"reporting": {
"reporting_cadence": "quarterly",
"quarterly_income_convention": "mixed"
}
}التحليلات
قارن نسب الشركات وحللها باستخدام نقاط نهاية تحليلية موجزة.
GET /analytics/ratios/{symbol}/
Starter+النسب المالية لرمز واحد.
نقطة النهاية
https://api.sahmk.sa/api/v1/analytics/ratios/1120/?history=latest&period=quarterly&metrics=extended
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| symbol * | string | 1120 |
| history | string | 5y |
| period | string | quarterly |
| metrics | string | extended |
| meta | string | extended |
history: القيم latest و3y و5y و10y وmax (الافتراضي latest). period: القيم annual وquarterly (الافتراضي annual). metrics: القيم core وextended (الافتراضي core). meta: القيمة minimal افتراضياً أو extended.
البيانات المتاحة حسب الباقة:
- Free:لا يتوفر وصول إلى التحليلات
- Starter:أحدث بيانات + annual + core فقط
- Pro/Business:جميع خيارات النسب (history وperiod وmetrics)
- Enterprise:خصائص نسب وصلاحيات وصول مخصصة حسب الاتفاق
{
"symbol": "1120",
"ratios": [
{
"report_date": "2026-06-30",
"statement_period": "quarterly",
"fiscal_year": 2026,
"fiscal_quarter": 2,
"ratios": {
"roe": 4.6,
"roa": 0.66,
"net_margin": 64.42,
"revenue_growth_yoy": 13.35,
"net_income_growth_yoy": 14.0,
"asset_turnover": 0.0103
},
"key_metrics": {
"total_revenue": 10884480000.0,
"net_income": 7012137000.0,
"operating_cash_flow": 10379536000.0,
"total_assets": 1054772497000.0,
"stockholders_equity": 152416762000.0
}
}
],
"meta": {
"period": "quarterly",
"metrics": "extended",
"warnings": [
"Some metrics unavailable"
]
}
}GET /analytics/compare/
Starter+قارن لقطات النسب بين عدة رموز.
نقطة النهاية
https://api.sahmk.sa/api/v1/analytics/compare/?symbols=1120&metrics=extended
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| symbols * | string | 1120,1180,1010,2222 |
| metrics | string | extended |
| meta | string | extended |
symbols مطلوب كقيم مفصولة بفواصل (مثال 1120,1180,1010). metrics: القيمة core أو extended (الافتراضي core). meta: القيمة minimal افتراضياً أو extended.
البيانات المتاحة حسب الباقة:
- Starter:حتى 3 رموز + مقاييس core فقط
- Pro:حتى 10 رموز + مقاييس core/extended
- Business:حتى 20 رمزاً + مقاييس core/extended
- Enterprise:حدود رموز وخصائص مقارنة مخصصة حسب الاتفاق
{
"results": [
{
"symbol": "1120",
"company_name": "مصرف الراجحي",
"sector_name": "Banks",
"sector_name_ar": "البنوك",
"market_id": "TASI",
"market_cap": 384600000000.0,
"current_price": 64.05,
"ratios": {
"roe": 9.48,
"roa": 1.37,
"net_margin": 67.49,
"asset_turnover": 0.0203
},
"key_metrics": {
"total_revenue": 21412480000.0,
"net_income": 14452137000.0,
"total_assets": 1054772497000.0,
"stockholders_equity": 152416762000.0
}
}
],
"count": 1,
"meta": {
"period": "annual",
"metrics": "extended",
"warnings": [
"Some metrics unavailable"
]
}
}نصائح التكامل
- البيانات الوصفية الافتراضية مختصرة:
meta.period,meta.metrics,meta.warnings. - استخدم
meta=extendedلحقول إضافية (النسب:coverage,periods_available,quality,partial_context؛ صفوف المقارنة:coverage). - مفاتيح النسب ديناميكية، لذا اعرض كائنات النسب ديناميكياً.
توزيعات الأرباح
اعرض سجل توزيعات الأرباح والتوزيعات القادمة والعائد المتحرك للسهم.
GET /dividends/{symbol}/
Starter+احصل على سجل توزيعات الأرباح ومعلومات العائد.
نقطة النهاية
https://api.sahmk.sa/api/v1/dividends/2222/?limit=1
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| symbol * | string | 2222 |
| limit | number | 1 |
{
"symbol": "2222",
"current_price": 26.6,
"trailing_12m_yield": 5.07,
"trailing_12m_dividends": 1.3491,
"payments_last_year": 4,
"upcoming": [
{
"value": 0.3393,
"period": "Q2",
"eligibility_date": "2026-08-19",
"distribution_date": "2026-08-27"
}
],
"history": [
{
"value": 0.3393,
"value_percent": null,
"period": "Q2",
"fiscal_year": "2026",
"announcement_date": "2026-08-04",
"eligibility_date": "2026-08-19",
"distribution_date": "2026-08-27"
}
]
}أحداث الأسهم
احصل على ملخصات مولدة بالذكاء الاصطناعي لأهم أحداث الأسهم وأخبارها.
GET /events/
Pro+احصل على أحداث الأسهم مع تحليل مولد بالذكاء الاصطناعي.
ملاحظة
أنواع الأحداث مكتوبة بأحرف كبيرة UPPERCASE، مثل FINANCIAL_REPORT وDIVIDEND_ANNOUNCEMENT.
نقطة النهاية
https://api.sahmk.sa/api/v1/events/?symbol=4190&importance=IMPORTANT&limit=1
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| symbol | string | 4190 |
| type | string | FINANCIAL_REPORT |
| importance | string | IMPORTANT |
| limit | number | 1 |
| offset | number | 0 |
القيمة الافتراضية لـlimit هي 20 (والحد الأقصى 100)، والقيمة الافتراضية لـoffset هي 0.
{
"events": [
{
"symbol": "4190",
"stock_name": "مكتبة جرير",
"event_type": "MARKET_EXPANSION",
"importance": "important",
"sentiment": "positive",
"description": "افتتحت مكتبة جرير معرضاً جديداً بمطار الملك فهد الدولي في الدمام، وهو المعرض التاسع والستون داخل المملكة، ويعد الخامس خلال عام 2026، باستثمارات بلغت 2 مليون ريال سعودي.",
"event_date": "2026-08-10",
"article_date": "2026-08-10T13:14:06.653295+00:00",
"created_at": "2026-08-10T13:14:10.917105+00:00"
}
],
"count": 1,
"total": 78,
"limit": 1,
"offset": 0,
"has_more": true,
"available_types": [
"FINANCIAL_REPORT", "DIVIDEND_ANNOUNCEMENT", "STOCK_SPLIT",
"MERGER_ACQUISITION", "MANAGEMENT_CHANGE", "NEW_LISTING",
"DELISTING", "REGULATORY_ACTION", "PRODUCT_LAUNCH",
"PARTNERSHIP", "LEGAL_ISSUE", "MARKET_EXPANSION",
"RESTRUCTURING", "EARNINGS_SURPRISE", "INSIDER_TRADING",
"ANALYST_RATING_CHANGE", "CAPITAL_INCREASE", "SHAREHOLDER_MEETING", "OTHER"
]
}available_types: قائمة يحددها الخادم وقد تتوسع في الإصدارات القادمة.
importance: critical, important, regular
sentiment: very_positive, positive, slightly_positive, neutral, slightly_negative, negative, very_negative
WebSocket اللحظي - الأسهم
استقبل تحديثات أسعار الأسهم لحظياً عبر قناة الأسهم.
WS /ws/v1/stocks/
Pro+قناة أسعار لحظية لتحديثات الأسهم المباشرة.
نقطة النهاية
wss://api.sahmk.sa/ws/v1/stocks/?api_key=YOUR_API_KEY
رسالة الاتصال
{
"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"
}إجراءات العميل
{"action":"subscribe","symbols":["2222","1120"]}
{"action":"unsubscribe","symbols":["1120"]}
{"action":"ping"}
{"action":"subscribe","symbols":["*"]} // Enterprise onlyرسالة السعر
{
"type": "quote",
"symbol": "2222",
"mode": "standard",
"data": {
"price": 25.86,
"bid": 25.84,
"bid_size": 79,
"ask": 25.88,
"ask_size": 188
},
"timestamp": "2026-07-09T15:05:41.114000+00:00",
"latency_ms": 14
}WebSocket اللحظي - الصفقات
استقبل الصفقات المباشرة عبر قناة الصفقات. تتلقى الاشتراكات التي تحدد الرموز رسالة subscribed تأكيد، ثم رسالة trades_snapshot لكل رمز جديد مشترك، تتبعها تحديثات trade اللحظية.
WS /ws/v1/market/trades/
Pro+قناة صفقات لحظية لتحديثات التداول المباشرة.
نقطة النهاية
wss://api.sahmk.sa/ws/v1/market/trades/?api_key=YOUR_API_KEY
اختياري: أضف symbol=2222 للاشتراك التلقائي عند الاتصال.
رسالة الاتصال
{
"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"
}إجراءات العميل
{"action":"subscribe","symbols":["2222","1120"]}
{"action":"unsubscribe","symbols":["1120"]}
{"action":"snapshot","symbol":"2222","limit":50}
{"action":"ping"}
{"action":"subscribe","symbols":["*"]} // Enterprise onlyاللقطة limit الافتراضي to 50 (الحد الأقصى 200).
رسالة اللقطة
{
"type": "trades_snapshot",
"symbol": "2222",
"updated_at": "2026-07-28T09:31:55+00:00",
"count": 2,
"events": [
{
"event_time": "2026-07-28T09:31:55+00:00",
"price": 26.3,
"quantity": 40,
"value": 1052.0,
"side": "buy"
},
{
"event_time": "2026-07-28T09:31:47+00:00",
"price": 26.3,
"quantity": 5000,
"value": 131500.0,
"side": "sell"
}
],
"summary": {
"event_count": 2,
"trade_quantity": 5040,
"trade_value": 132552.0,
"latest_event_time": "2026-07-28T09:31:55+00:00"
},
"timestamp": "2026-07-28T09:31:58.300000+00:00"
}رسالة الصفقة
{
"type": "trade",
"symbol": "2222",
"event_time": "2026-07-28T09:31:58+00:00",
"price": 26.32,
"quantity": 10,
"value": 263.2,
"side": "buy",
"market_session": "REGULAR",
"timestamp": "2026-07-28T09:31:58.774829+00:00"
}دروس ذات صلة
WebSocket اللحظي - عمق السوق
استقبل تحديثات عمق أوامر الشراء والبيع مستوى بمستوى عبر قناة عمق السوق.
WS /ws/v1/market/depth/
Pro+قناة عمق سوق لحظية لبث مستويات أوامر الشراء والبيع.
نقطة النهاية
wss://api.sahmk.sa/ws/v1/market/depth/?api_key=YOUR_API_KEY
توفر البيانات حسب الباقة:
- Pro:مؤهل لعمق أفضل 5 مستويات. طلب الوصول
- Business+:مؤهل لبيانات عمق Premium لأفضل 20 مستوى. طلب الوصول
رسالة الاتصال
{
"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.
إجراءات العميل
{"action":"snapshot","symbol":"2222","levels":5}
{"action":"subscribe","symbols":["2222","1120"],"levels":20}
{"action":"unsubscribe","symbols":["1120"]}
{"action":"ping"}
{"action":"subscribe","symbols":["*"],"levels":20} // Enterprise onlyاستخدم symbols للاشتراك وإلغائه. ولطلبات الرمز الواحد، يقبل الخادم أيضاً symbol.
ترتيب رسائل عمق السوق
- الرموز المحددة: رسالة
depth_snapshotلكل رمز، ثمsubscribed. - رمز البدل لباقة Enterprise:
subscribedأولاً، ثم دفعة اللقطات الأولية. - تحديثات العمق المستمرة هي أيضاً رسائل
depth_snapshot..
رسالة تأكيد الاشتراك
{
"type": "subscribed",
"symbols": ["1120", "2222"],
"total": 2,
"limit": 200
}رسالة لقطة عمق السوق
{
"type": "depth_snapshot",
"symbol": "2222",
"available": true,
"updated_at": "2026-07-09T15:05:37.840967+00:00",
"session": "postmarket",
"book_state": "normal",
"levels": 20,
"best_bid": 26.68,
"best_ask": 26.72,
"spread": 0.04,
"spread_bps": 14.99,
"total_bid_quantity_top5": 29085,
"total_ask_quantity_top5": 504644,
"total_bid_quantity": 29085,
"total_ask_quantity": 504644,
"level_imbalance": -0.891,
"level_imbalance_top5": -0.891,
"bids": [
{
"level": 0,
"price": 26.68,
"quantity": 79,
"order_count": 10
}
],
"asks": [
{
"level": 0,
"price": 26.72,
"quantity": 41188,
"order_count": 38
}
],
"entitled_levels": 20,
"timestamp": "2026-07-09T15:05:37.872738+00:00"
}WebSocket اللحظي - الأخطاء
تعامل مع أعطال WebSocket عبر غلاف خطأ موحد. استخدم رمز الإغلاق لتصنيف الخطأ، وأحدث error.code/details لتحديد الإجراء المناسب.
رموز أخطاء WebSocket
WS_INTERNAL_ERROR4000أوقف عطل داخلي في الاتصال عملية الإعداد.
الإجراء: أعد المحاولة بتراجع أسي محدود مع تأخير عشوائي.
WS_AUTH_OR_ACCESS4401 / 4403MARKET_DATA_ENTITLEMENT_*تمنع مشكلة في وصول الحساب أو صلاحياته الوصول إلى البث.
الإجراء: يعني 4401 تصحيح مصادقة مفتاح API، ويعني 4403 تصحيح صلاحية الحساب أو الباقة. لا تُعِد الاتصال تلقائياً.
WS_RATE_LIMIT4429DEPTH_WS_*_LIMIT / *_RATE_LIMITEDتم تجاوز حدود الاتصال أو الاشتراك أو الإجراءات.
الإجراء: أعد المحاولة بتراجع وتأخير عشوائي، والتزم بقيمة retry_after_seconds في أحدث تفاصيل الخطأ عند توفرها.
WS_INVALID_REQUESTINVALID_JSON / UNKNOWN_ACTION / SYMBOL_REQUIRED and lowercase variantsحمولة غير صالحة أو إجراء غير مدعوم.
الإجراء: الرموز خاصة بكل قناة وحساسة لحالة الأحرف. صحح الحمولة وأعد الإجراء؛ ويبقى الاتصال مفتوحاً عادةً.
ضوابط تعدد الاتصالات
- افتح الاتصالات بفاصل 200–400 مللي ثانية بدلاً من تشغيلها دفعة واحدة.
- ضع محاولات إعادة الاتصال في طابور موحد لكل مفتاح API.
- تجنب عواصف إعادة الاتصال المتزامنة عند افتتاح السوق.
الاتصال خارج ساعات التداول
يمكنك إبقاء اتصالات WebSocket مفتوحة خارج ساعات السوق. لا تقطع سهمك اتصالات العملاء عمداً عند إغلاق السوق. واصل إرسال ping كل 30 ثانية، وأعد الاتصال عند الحاجة بتراجع أسي محدود وتأخير عشوائي، ثم استعد الاشتراكات بعد كل اتصال. قد لا تصل أحداث سوق عندما يكون السوق غير نشط.
غلاف الخطأ
{
"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.
نموذج لوحة التحكم وAPI
/api/v1/webhooks/ and /api/v1/alerts/). ينتج المساران غلاف تسليم webhook نفسه.Webhooks للأحداث
سجّل وجهات آمنة وتحقق من نقاط نهاية التسليم.
قواعد الأحداث
حدد الرموز والحدود وشروط التشغيل.
دورة حياة التسليم
تتبع الحالات من الانتظار إلى التسليم أو الفشل.
مرجع الحمولة
غلاف الحدث القياسي وعقد الحقول.
التحقق من التوقيع
تحقق من توقيعات webhooks قبل المعالجة.
سجل الأحداث
راجع نتائج التسليم ومحاولات الإعادة.
أنواع الأحداث وشروطها
راجع أنواع الأحداث المدعومة وبُنى conditions_matched.
رموز الأخطاء
استخدم ربط الرموز بالإجراءات لاستكشاف مشكلات التكامل.
التنبيهات وWebhooks - Webhooks للأحداث
سجّل نقاط نهاية webhooks وتحقق منها قبل تفعيل قواعد التنبيه.
POST /api/v1/webhooks/
Pro+أنشئ وجهة webhook للتنبيهات وإشعارات webhooks.
نقطة النهاية
https://api.sahmk.sa/api/v1/webhooks/
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| url * | string | https://example.com/hooks/sahmk |
| name | string | Trading Production Hook |
تستخدم المصادقة X-API-Key: YOUR_API_KEY.
- مطلوب:
url(عنوان وجهة HTTPS) - اختياري:
name(اسم وصفي) - التحقق: تُرسل مصافحة تحقق عند الإنشاء؛ ويتطلب النجاح HTTP 200.
- التعامل مع السر:
signing_secretيُعاد عند الإنشاء فقط، ولا يُضمّن في استجابات القائمة أو الجلب.
{
"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
Pro+البنية القياسية للحمولة لدى مستهلكي webhooks.
{
"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_idevent_typesymboldetected_atseveritytitle,summary
metricsconditions_matchedcorrelation_idversiondestination
مهم
unusual_value_traded خط أساس متحركاً لقيمة التداول (value / rolling_value_baseline)، وليس reference_value.للتوافق المستقبلي، ينبغي للعملاء تجاهل المفاتيح غير المعروفة والاعتماد على الحقول المطلوبة في المستوى الأعلى.
التنبيهات وWebhooks - قواعد الأحداث
حدد ظروف السوق والإجراءات التي تشغل تسليم webhooks. يمكنك إنشاء القواعد من لوحة التحكم أو برمجياً عبر API.
مرجع لوحة التحكم وأنواع الأحداث
يمكنك إنشاء التنبيهات وإدارتها من لوحة المطور. لمرجع أنواع الأحداث والشروط الكامل، راجع أنواع الأحداث وشروطها.
POST /api/v1/alerts/
Pro+أنشئ قاعدة تنبيه تشغل تسليم webhooks عند تحقق الشروط.
نقطة النهاية
https://api.sahmk.sa/api/v1/alerts/
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| symbol * | string | 2222 |
| event_type * | string | large_move |
| condition | string | pct_change_abs_gte |
| value * | number | 3.0 |
| webhook_id | number | 19 |
| destination | object | { "type": "webhook", "webhook_id": 19 } |
| config | object | { "window": "15m" } |
| once | boolean | true (default) |
إرشادات تصميم القواعد
- ابدأ بنطاق رموز محدود وحدود واضحة.
- استخدم فترات تهدئة لتقليل ضوضاء الإشعارات.
- تحقق في بيئة الاختبار قبل تفعيل قواعد الإنتاج.
conditionمطلوب معprice_alert؛ أما أنواع الأحداث الموثقة الأخرى فتطبّعه تلقائياً.- يجب أن تتجاوز حدود النسب 1.0. والحد الأقصى للحركة الكبيرة هو 10% في TASI و30% في NOMU.
onceالقيمة الافتراضية totrue. تضبطه الأمثلة علىfalseصراحةً لإنشاء قواعد متكررة، ولذلك تعرض استجاباتهاfire_once: false.
{
"id": 57,
"workspace_id": null,
"symbol": "2222",
"event_type": "large_move",
"target_scope_type": "single_symbol",
"target_scope_id": null,
"symbols": ["2222"],
"evaluated_symbol_rules": 1,
"condition": "pct_change_abs_gte",
"value": "3.0",
"config": {
"window": "5m",
"destination": { "type": "webhook", "webhook_id": 19 }
},
"fire_once": false,
"webhook_id": 19,
"webhook_url": "https://example.com/hooks/sahmk",
"destination": { "type": "webhook", "webhook_id": 19 },
"status": "active",
"last_triggered_at": null,
"total_triggers": 0,
"created_at": "2026-05-08T13:36:45+03:00"
}GET /api/v1/alerts/
Pro+اعرض القواعد الحالية وصفّها اختيارياً حسب الحالة.
نقطة النهاية
https://api.sahmk.sa/api/v1/alerts/?status=active
المعاملات
(*) مطلوب
| المعامل | النوع | مثال |
|---|---|---|
| status | string | active |
- الاستعلام:
status=active|paused|all - قيم الحالة:
active,paused,triggered - المطابقة:
onceيطابقfire_once.
{
"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.
{
"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 - دورة حياة التسليم
راقب حالات الانتظار والتسليم والفشل وإعادة المحاولة للحصول على رؤية تشغيلية.
Delivery Lifecycle
Pro+حالات دورة الحياة الحالية وتسلسل إعادة المحاولة لعمليات تسليم webhooks.
تدفق الحالة: pending -> retrying -> delivered أو dead_letter.
تأخير إعادة المحاولة: 2s, 10s, 60s.
المحاولات: 4 إجمالاً (محاولة أولى + 3 محاولات إعادة)، دون تأخير عشوائي.
سبب إعادة المحاولة: تُعاد جميع النتائج غير 2xx، بما فيها 4xx و5xx وانتهاء المهلة وأخطاء الاتصال، حتى استنفاد المحاولات.
التعطيل التلقائي: بعد 3 عمليات تسليم فاشلة متتالية، يُعطل webhook. عالج مشكلة الوجهة وتحقق منها مجدداً قبل استخدام القواعد المرتبطة.
استخدم event_id و correlation_id للتتبع من البداية إلى النهاية.
لا تتوفر حالياً نقطة نهاية عامة لإعادة تشغيل الأحداث غير المسلمة.
مكان الإدارة
التنبيهات وWebhooks - التحقق من التوقيع
تحقق من توقيع كل طلب webhook قبل معالجة الأحداث في الإنتاج.
استخدم سر التوقيع الخاص بنقطة النهاية والمعاد عند إنشاء وجهة webhook.
تتضمن ترويسات التسليم X-SAHMK-Signature, X-SAHMK-Event, and X-SAHMK-Event-Id.
- تتضمن كل عملية تسليم
X-SAHMK-Signature. - يُنشأ التوقيع باستخدام HMAC-SHA256 على الحمولة القياسية.
- ارفض التوقيعات غير المطابقة باستخدام HTTP 401.
# 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 - سجل الأحداث
استعلم عن نتائج التسليم الحديثة للمراقبة واستكشاف المشكلات.
Dashboard Event History
Pro+استخدم عرض السجل في لوحة المطور لمراجعة نتائج التسليم ومحاولات الإعادة.
- صفِّ حسب حالة التسليم ونوع الحدث وسياق مساحة العمل في لوحة التحكم.
- استخدم معرفات الأحداث ومعرفات الارتباط لتتبع التسليم من البداية إلى النهاية.
- السجل مخصص لسير عمل المراقبة واستكشاف المشكلات.
مساعدة
استخدم لوحة المطور - التنبيهات الذكية لمراجعة نتائج التسليم وحالات إعادة المحاولة.
التنبيهات وWebhooks - رموز الأخطاء
تعامل مع فشل تسليم webhooks باستخدام مستهلكين آمنين لإعادة المحاولة ومطابقة واضحة للحالات.
إرشادات تشغيلية
- تعامل مع محاولات التسليم بوصفها قابلة للتكرار الآمن؛ فقد يتكرر التسليم عند إعادة المحاولة.
- أعد 2xx سريعاً بعد الحفظ الدائم، وعالج الأعمال الثقيلة بشكل غير متزامن.
- تتبع معرفات التسليم وأسباب الفشل للدعم والمطابقة.
400INVALID_PARAMحقل حمولة غير صالح أو خيار استعلام غير مدعوم.
الإجراء: صحح حمولة الطلب وأعد المحاولة.
401AUTH_REQUIREDترويسة X-API-Key مفقودة.
الإجراء: أضف مفتاح API نشطاً وأعد المحاولة.
403PLAN_LIMIT / FEATURE_DISABLEDلا تملك الباقة صلاحية الميزة أو تم بلوغ الحدود.
الإجراء: رقِّ الباقة أو عدّل الاستخدام.
404NOT_FOUNDلم يتم العثور على مورد webhook أو التنبيه لهذا الحساب.
الإجراء: تحقق من معرف المورد وسياق الملكية.
429detailتم بلوغ حد الاندفاع أو الحصة؛ التزم بـRetry-After عند توفره.
الإجراء: تراجع وأعد المحاولة مع تأخير عشوائي.
صيغة استجابة الخطأ
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable message"
}
}أخطاء WebSocket اللحظية
حدود الطلبات
تُحدد معدلات الوصول إلى API حسب باقتك. يوجد نوعان من الحدود: الحصة اليومية وحد الاندفاع لكل دقيقة.
مقارنة الباقات كاملة
| الباقة | الحد اليومي | حد الاندفاع | مفاتيح API | WebSocket | Webhooks للأحداث | قواعد الأحداث |
|---|---|---|---|---|---|---|
| Free | 100/day | 10/min | 1 | ✗ | 0 | 0 |
| Starter | 5,000/day | 100/min | 3 | ✗ | 0 | 0 |
| Pro | 50,000/day | 500/min | 10 | ✓ | 3 | 10 |
| Business | 150,000/day | 1,000/min | 30 | ✓ | 10 | 50 |
| Enterprise | مخصص | مخصص | مخصص | ✓ | مخصص | مخصص |
الحصص اليومية مشتركة على مستوى الحساب، بما في ذلك مفاتيح Live وTest. لا يؤدي تدوير المفتاح أو إلغاؤه إلى إنشاء حصة يومية جديدة.
الحماية من الاندفاع: لمنع إساءة الاستخدام وحماية الاستقرار، يُطبق حد الدقيقة على مستوى مفتاح API والحساب معاً. تعيد الطلبات التي تتجاوز الحدود HTTP 429. تُصفّر الحدود اليومية عند منتصف الليل بتوقيت Asia/Riyadh (UTC+3). تعتمد حدود Enterprise على العقد، وقد تكون حصصاً شهرية أو مرتبطة بالموارد.
ترويسات حدود الطلبات
تتضمن معظم استجابات /api/v1/* الناجحة X-RateLimit-Limit, X-RateLimit-Remaining، و X-RateLimit-Reset.
X-RateLimit-Reset هو طابع Unix الزمني لمنتصف الليل التالي بتوقيت Asia/Riyadh. تُفرض الحصة اليومية على الحساب كله وعبر جميع المفاتيح. لكن X-RateLimit-Remaining يُحسب حالياً من المفتاح المستخدم للطلب، ولذلك قد يكون أعلى من الحصة الحقيقية المتبقية للحساب عند استخدام عدة مفاتيح.
قد تحذف الوكلاء الطرفية الترويسات. استخدم HTTP 429 وقيمة الاستجابة detail، و Retry-After عند توفرها بوصفها عقد الحد البديل.
رموز الأخطاء
تستخدم الواجهة رموز حالة HTTP القياسية وتعيد أخطاء منظمة بصيغة JSON.
رموز أخطاء HTTP
400INVALID_ROUTEتم استخدام مسار نقطة نهاية خاطئ، وتعيد API اقتراحاً للمسار الصحيح.
401detailترويسة X-API-Key مفقودة.
403detailصيغة مفتاح API غير صالحة، أو أن المفتاح غير صالح أو ملغى.
403PLAN_LIMITتتطلب نقطة النهاية باقة أعلى (مثلاً تتطلب البيانات التاريخية Starter+، أو طُلبت تركيبات مالية أعلى ضمن Starter).
404INVALID_SYMBOLلم يتم العثور على رمز التداول.
404 / 409INVALID_IDENTIFIER / AMBIGUOUS_IDENTIFIERلم تتم مطابقة استعلام المعرّف، أو طابق عدة شركات.
429detailتم بلوغ حد يومي أو حد اندفاع أو حد IP أو حد أمني مؤقت.
500SERVER_ERRORخطأ داخلي في الخادم. أعد المحاولة أو تواصل مع الدعم.
قد تصل بعض الحسابات المجانية الجديدة مؤقتاً إلى حد أمني. عند حدوث ذلك تعيد API HTTP 429 مع detail يحتوي على Temporary security limit reached. التزم بقيمة Retry-After عند توفرها، ثم حاول لاحقاً.
خطأ تكامل شائع: استدعاء GET /api/v1/quote/batch/ يعيد 400 INVALID_ROUTE مع إرشاد للمسار الصحيح.
{
"error": {
"code": "INVALID_ROUTE",
"message": "Did you mean /api/v1/quotes/?symbols=2222,1120 ?"
}
}صيغ استجابات الأخطاء
تستخدم أخطاء التحقق والبحث في نقاط النهاية عادةً كائن error منظماً:
{
"error": {
"code": "INVALID_SYMBOL",
"message": "Stock symbol '9999' not found."
}
}تستخدم أخطاء المصادقة والحد قيمة detail نصية في المستوى الأعلى:
{
"detail": "Request was throttled. Expected available in 60 seconds."
}آخر تحديث في