SAHMK
API للمطورين

البدء السريع بحزمة SAHMK Python SDK

ابدأ خلال دقائق باستخدام حزمة SAHMK الرسمية للغة Python. ثبّتها عبر pip، وصادق باستخدام مفتاح API، ثم اجلب بيانات أسهم تداول الفورية بنماذج منضبطة الأنواع وإكمال تلقائي داخل بيئة التطوير.

PythonSDKمبتدئقراءة 6 دقائق

1. التثبيت

ثبّت حزمة SAHMK Python SDK من PyPI:

bash
pip install -U sahmk

يتطلب Python 3.9 أو أحدث. تتضمن الحزمة مكتبة عميل Python وأداة sahmk CLI.

صفحة الحزمة الرسمية (سجل الإصدارات وبياناتها): pypi.org/project/sahmk.

2. المصادقة

تحتاج إلى مفتاح SAHMK API. احصل على مفتاحك المجاني عبر التسجيل هنا.

auth.py
from sahmk import SahmkClient

client = SahmkClient(api_key="your_api_key_here")

أو استخدم متغير بيئة:

auth_env.py
import os
from sahmk import SahmkClient

client = SahmkClient(api_key=os.environ["SAHMK_API_KEY"])

3. اجلب أول سعر سهم باستخدام المعرّف

اجلب سعر Aramco باستخدام أي معرّف مدعوم. نستخدم في هذا المثال الرمز 2222:

إذا لم تعرف الرمز الدقيق، فاستخدم client.companies(...) أولاً لتقليل أخطاء الرموز غير الصالحة.

bash
# Simple search
results = client.companies(search="aramco")
print(results["results"][0]["security_type"])  # Equity, Sukuk, ETF, Closed-End Fund, or Unknown

# Market filter (use NOMU market code)
nomu = client.companies(search="marketing", market="NOMU", limit=20, offset=0)
get_quote.py
from sahmk import SahmkClient

client = SahmkClient(api_key="your_api_key_here")

quote = client.quote("2222")

print(f"Company: {quote.name_en}")
print(f"Symbol:  {quote.symbol}")
print(f"Price:   {quote.price} SAR")
print(f"Change:  {quote.change} ({quote.change_percent}%)")
print(f"Volume:  {quote.volume:,}")
مثال على الاستجابة
Company: Saudi Arabian Oil Co
Symbol:  2222
Price:   25.86 SAR
Change:  0.18 (0.7%)
Volume:  9,803,705

تعيد الحزمة كائنات منضبطة الأنواع تدعم الوصول عبر الخصائص. وستحصل على إكمال تلقائي لكل حقل داخل بيئة التطوير.

تشمل المعرّفات المدعومة الرمز واسم الشركة بالعربية أو الإنجليزية والاسم البديل. وتظل الرموز مدعومة بالكامل.

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

بيانات السيولة

يتضمن كل سعر بيانات تدفق السيولة، وهي مفيدة لتتبع ضغط الشراء المؤسسي:

bash
quote = client.quote("2222")

if quote.liquidity:
    liq = quote.liquidity
    net = liq.net_value
    direction = "inflow" if net > 0 else "outflow"
    print(f"Net liquidity: {net:,.0f} SAR ({direction})")

ما زال الوصول بأسلوب القاموس مدعوماً

إذا كنت تفضل الوصول بأسلوب القاموس، فهو يعمل كما كان:

bash
quote = client.quote("2222")

# Both styles work
print(quote.price)        # attribute access
print(quote["price"])     # dict access
print(quote.get("price")) # .get() with default

الخاصية .raw تعطيك استجابة API الأصلية كقاموس عادي، وهي مفيدة للحفظ أو التمرير:

bash
import json
print(json.dumps(quote.raw, indent=2))

4. أسعار مجموعة أسهم (عدة أسهم)

اجلب عدة أسهم في طلب واحد (باقة Starter أو أعلى):

batch_quotes.py
result = client.quotes(["2222", "الراجحي", "stc"])

print(f"Fetched {result.count} quotes\n")
for q in result.quotes:
    print(f"{q.symbol}: {q.name_en} — {q.price} SAR ({q.change_percent:+.2f}%)")
مثال على الاستجابة
Fetched 3 quotes

2222: Saudi Arabian Oil Co — 25.86 SAR (+0.70%)
1120: Al Rajhi Banking & Investment Corp SJSC — 108.60 SAR (+0.18%)
4191: Maison Marketing Trade Group — 59.50 SAR (+8.97%)

الدالة quotes() تقبل حتى 50 معرّفاً وتُحتسب طلب API واحداً.

5. نظرة عامة على السوق

market_overview.py
# TASI index summary
market = client.market_summary(index="TASI")
print(f"TASI: {market.index_value} ({market.index_change_percent:+.2f}%)")
print(f"Delayed Feed: {market.is_delayed}")
print(f"Advancing: {market.advancing} | Declining: {market.declining}")
print(f"Mood: {market.market_mood}")

# Top gainers
gainers = client.gainers(limit=3)
print("\nTop Gainers:")
for s in gainers.stocks:
    print(f"  {s.symbol}: {s.name_en} +{s.change_percent}%")

# Top losers
losers = client.losers(limit=3)
print("\nTop Losers:")
for s in losers.stocks:
    print(f"  {s.symbol}: {s.name_en} {s.change_percent}%")

دوال السوق الأخرى: client.volume_leaders(), client.value_leaders(), client.sectors().

6. معالجة الأخطاء

توفر الحزمة أخطاء منظّمة يمكنك التقاطها وفحصها:

errors.py
from sahmk import SahmkClient, SahmkError, SahmkRateLimitError

client = SahmkClient(api_key="your_api_key_here")

try:
    quote = client.quote("INVALID")
except SahmkRateLimitError as e:
    print(f"Rate limited. Try again later. ({e.status_code})")
except SahmkError as e:
    print(f"API error: {e} (code: {e.error_code}, status: {e.status_code})")

تعيد الحزمة المحاولة تلقائياً عند الأخطاء المؤقتة (429 و5xx) باستخدام تراجع أُسّي، ويمكنك ضبط ذلك:

bash
client = SahmkClient(
    api_key="your_api_key_here",
    retries=5,              # max retry attempts (default: 3)
    backoff_factor=0.5,     # backoff multiplier (default: 0.3)
    retry_on_timeout=True,  # retry on timeouts (default: True)
)

7. الخطوات التالية

تعرّفت الآن إلى أساسيات الحزمة. إليك ما يمكنك استكشافه بعد ذلك:

  • →معلومات الشركة: client.company("2222") — المؤشرات الأساسية والفنية والتقييم وأهداف المحللين
  • →القوائم المالية: client.financials("2222") — قوائم الدخل والميزانيات والتدفقات النقدية (Starter+)
  • →توزيعات الأرباح: client.dividends("2222") — العائد وسجل الدفعات والتوزيعات القادمة (Starter+)
  • →الأحداث: client.events(symbol="2222") — ملخصات أحداث مولدة بالذكاء الاصطناعي (Pro+)
  • →البيانات التاريخية: client.historical("2222") — بيانات OHLCV بنطاقات زمنية وفواصل (Starter+)
  • →WebSocket: client.stream(["2222"], on_quote=callback) — بث الأسعار في الوقت الفعلي (Pro+)
  • →CLI: شغّل sahmk quote "Saudi Aramco" من الطرفية، من دون كتابة شيفرة

المصادر

الشيفرة المصدرية لحزمة SDKمرجع واجهة API

هل أنت جاهز للبناء؟

احصل على مفتاح API المجاني وابدأ البناء باستخدام SAHMK Python SDK. تشمل الباقة 100 طلب مجاني يومياً ولا تتطلب بطاقة ائتمانية.

احصل على مفتاح API المجانيعرض على GitHub

نشر بواسطة @sahmk_sa · مرخّص من تداول السعودية