مرجع واجهة برمجة التطبيقات في وقت التشغيل

ثلاثة عقود تربط Syncanix بخادمك العامل: ترويسة النية الموقّعة التي تخوّل كل استدعاء أداة، وحقول التصرف-باسم-المستخدم التي تحمل هوية المستخدم النهائي، وبيانات الشاهد التي تبلّغ عن أشكال واجهتك. هذه الصفحة مرجع على مستوى الحقول؛ أما الأدلة فتغطي المسارات.

التحقق من النية — ترويسة X-Syncanix-Intent

يحمل كل استدعاء أداة تُرسله Syncanix إلى خادمك نيّةً موقَّعة. يتحقّق SDK لديك (أو شيفرتك) من توقيع HMAC-SHA256 بسرّ المستأجِر، ويفحص الانتهاء، ويفحص تطابق الطريقة والمسار مع الطلب الفعلي — ثم يكشف الحمولة المفكوكة لمعالِجك. ويربط مغلَّف «التصرّف-كمستخدم» المُوثَّق إضافةً إلى ذلك العملية والجمهور ووسائط الاستدعاء ورقمًا عشوائيًا لاستخدام واحد.

X-Syncanix-Intent: base64url(JSON({ "payload": <obj>, "signature": "<hex>" }))
payload   = { v: 2, toolCallId, tenantId, sub, aud, operation, argsHash, nonce, issuedAt, expiresAt, requiresStepUp? }
signature = hex(HMAC-SHA256(JSON(payload), secret))

// v1 (legacy) payloads — { toolCallId, tenantId, userId?, method, path, issuedAt,
// expiresAt } with no "v" field — remain accepted during the dual-accept window.

مغلَّف v2 هو ما يجعل الاستدعاء المنطلق من المحادثة آمنًا للتنفيذ: فـ sub هو ذات التدقيق التي يجري الإجراء بهويتها، وaud يربط الرمز بواجهة API الخاصة بك كي لا يُعاد تشغيله ضد مستأجر آخر، وargsHash يثبّت الوسائط بعينها كي لا يُتلاعب بالجسم بعد التوقيع، وnonce أحادي الاستخدام يمنع إعادة تشغيل الرمز بكامله خلال مدة صلاحيته.

toolCallId

معرّف فريد لاستدعاء الأداة هذا — استخدمه مفتاح عدم تكرار عند إعادة التسليم.

tenantId

مساحة عمل Syncanix (المستأجر) التي يخصها الاستدعاء.

sub

المستخدم النهائي المسجَّل الدخول الذي يتصرّف المساعد لأجله، والذات الفاعلة التي يُخوَّل كل إجراء ويُدقَّق استنادًا إليها. إلزامي في مغلَّف v2.

aud

جمهور واجهة API لدى العميل الذي تُربَط به هذه النيّة — بحيث لا يعود فصل المستأجرين قائمًا على سرّ HMAC وحده. ارفض أي رمز ليس جمهوره (aud) جمهورَك.

operation

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

argsHash

بصمة SHA-256 بأحرف سداسية عشرية صغيرة لوسائط الاستدعاء بعد توحيد صيغتها. أعد حسابها من جسم الطلب وارفض عند عدم التطابق — فهذا يغلق إعادة التشغيل بالتلاعب في الجسم.

nonce

قيمة لاستخدام واحد يسجّلها المتحقِّق لديك ويرفض قبولها مرتين، بما يغلق إعادة التشغيل ضمن مدة الصلاحية (TTL).

issuedAt, expiresAt

طابعا Unix زمنيان يحدّان عمر النية. تُرفض النيات المنتهية.

requiresStepUp (optional)

صحيح عندما يتطلب الإجراء تحققًا مشددًا حديثًا. ارفض ما لم تكن بوابة التحقق المشدد لديك قد عملت.

تظل رموز v1 القديمة — بلا حقل v، وتربط الطريقة والمسار فقط مع userId اختياري — مقبولةً خلال نافذة القبول المزدوج أثناء الطرح، كي تواصل الخوادم الخلفية المتكاملة أصلًا التحقق بينما تقوم أنت بالترقية. أما الرموز الجديدة فتُسَكّ بصيغة v2.

تُعيد إخفاقات التحقّق رمز 403 مع سبب قابل للقراءة آليًا مثل missing-header أو malformed أو bad-signature أو expired أو method-mismatch أو path-mismatch؛ ويضيف ربط «التصرّف-كمستخدم» الأقوى فحوص العملية والوسائط والجمهور وإعادة التشغيل. وتُستخدم سلاسل الأسباب نفسها عبر كل الـ SDKs.

التصرف باسم المستخدم — ما يلاحظه خادمك

عندما يتصرّف المساعد نيابةً عن مستخدم مسجَّل الدخول، تغطّي دليل التصرف باسم المستخدم التدفّق الكامل. وعلى مستوى العقد، يلاحظ خادمك شيئين بالضبط: حمولة النيّة تُسمّي المستخدم الفاعل (sub في مغلَّف «التصرّف-كمستخدم» المُوثَّق؛ وuserId في مغلَّف مجهول قديم)، وإجراءات الكتابة لا تصل إلا بعد أن تُشغِّل Syncanix بوابة التأكيد.

يبقى التفويض لك: عامِل ذات المستخدم الفاعل (sub) كالهوية التي تفوّض عليها — تمامًا كما لو أن ذلك المستخدم استدعى نقطة النهاية مباشرةً. تفوّض Syncanix أن الاستدعاء كان مقصودًا؛ وخادمك يفوّض ما يجوز لذلك المستخدم فعله.

الشاهد — مراسل المخططات في وقت التشغيل

يراقب وسيط الشاهد حركة واجهتك للحفاظ على دقة كتالوج القدرات. لكل طلب واستجابة ملحوظين يستنتج واصف شكل — البنية من دون القيم: القيم العددية والنصية تبلّغ عن نوعها فقط (string وnumber وinteger وboolean وnull)، والمصفوفات عن شكل عناصرها، والكائنات عن أشكال خصائصها. وتُدمج أشكال الطريقة/المسار نفسيهما عبر الملاحظات.

تمر القيم بالتنقيح قبل الاستنتاج، فلا يرى المستنتِج سلاسل حساسة أبدًا؛ وتنهار البنى المتباينة أو الفارغة إلى unknown بدل التخمين.