انتقل إلى المحتوى
Sursa Developers

عنوان API والبيئات

لواجهة Sursa API عنوان خاص بها، منفصل عن العنوان الذي يفتح به الناس Sursa في المتصفح. وتبدأ كل المسارات بالجزء /v1.

أين يعمل Sursaعنوان APIهذه البوابة
سحابة Sursahttps://api.sursa.comhttps://developers.sursa.com
نسختك المثبتةالعنوان https://api.<your domain>، كما يضبطه المشرف لديكالمسار /developers/ على عنوان API
نسختك المثبتة بلا عنوان API منفصلالعنوان الرئيسي للتثبيتالمسار /developers/ على العنوان الرئيسي

لا يخدم عنوان API سوى واجهة API: لا صفحة تسجيل دخول عليه، ولا ملفات تعريف ارتباط، ولا واجهة ويب. وكل طلب تجري مصادقته عبر مفتاح API أو رمز وصول OAuth. قد تخدم العنوانَ عدة خوادم خلف موزِّع أحمال، ولا يحتاج تكاملك إلى معرفة عددها.

التكاملات التي تستدعي واجهة API على العنوان الرئيسي (مثل https://app.sursa.com/v1) تبقى عاملة. انظر الانتقال إلى عنوان API لمعرفة الفروق القليلة وخطوات الانتقال.

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

ابنِ كل طلب من عنوان URL أساسي واحد في إعداداتك، فتعمل الشيفرة نفسها مع أي بيئة:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

استخدم HTTPS فقط، ولا تدع المفتاح يظهر في سجلات الطلبات التي ترسلها.

الإصدار والمواصفة

تبيّن العملية GET /v1/health هل العنوان يعمل، وتعيد إصدار Sursa الذي يخدمه. وهي تجيب بلا مفتاح، فيمكنك استخدامها في المراقبة:

curl https://api.sursa.com/v1/health
{"ok": true, "version": "v1.4.0"}

هذا إصدار Sursa، لا إصدار واجهة API. أما إصدار واجهة API فهو الحقل info.version في مواصفتها. ومواصفة OpenAPI 3.1 لواجهة API منشورة على العنوان نفسه، بلا مصادقة:

المسارالمحتوى
GET /openapi.jsonالمواصفة العامة، مع هذا العنوان في servers.
GET /v1/openapi-public.jsonالمواصفة نفسها. تدعم ETag وIf-None-Match.

استخدمها لتوليد عميل، أو لاستيراد واجهة API إلى أداة مثل Postman، أو للتحقق في خط التكامل المستمر (CI) من أن تكاملك لا يستخدم إلا عمليات الإصدار الذي تتوقعه. ومرجع API في هذه البوابة مبني من الملف نفسه.

الاختبار

ليس في Sursa وضع اختبار منفصل: كل طلب بمفتاح يعمل على البيانات الحقيقية لمؤسسته. للتطوير والاختبار بأمان:

  • أنشئ مفتاحًا منفصلًا للتطوير بأضيق دور ونطاقات صلاحيات يحتاج إليها العمل.
  • اكتب في مجموعة مخصصة، مثل sandbox، لا يراها إلا فريقك، واحذفها حين تنتهي.
  • إذا كانت لدى شركتك مؤسسة أو نسخة مثبتة منفصلة من Sursa للاختبار، فوجّه إليها عنوان URL الأساسي والمفتاح. ولا يتغيّر شيء آخر في شيفرتك.
  • اجعل إعادة المحاولة آمنة من البداية: أرسل الترويسة Idempotency-Key مع كل طلب POST وPATCH.

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

متطلبات الشبكة

  • اتصال HTTPS صادر (المنفذ 443) من خوادمك إلى عنوان API.
  • اسمح باسم المضيف بدل عناوين IP ثابتة في قواعد جدار الحماية حيث تسمح شبكتك بذلك: فالخوادم خلف العنوان قد تتغير مع إضافة سعة.
  • يمكن لتطبيقات المتصفح استدعاء واجهة API مباشرة: تسمح الاستجابات بأي أصل (Access-Control-Allow-Origin: *) بلا ملفات تعريف ارتباط. وتذكّر أن المفتاح المستخدم في المتصفح مرئي لمستخدم ذلك المتصفح.