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

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

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

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

X-Syncanix-Intent: base64url(JSON({ "payload": <obj>, "signature": "<hex>" }))
payload   = { toolCallId, tenantId, userId?, method, path, issuedAt, expiresAt, requiresStepUp? }
signature = hex(HMAC-SHA256(JSON(payload), secret))

toolCallId

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

tenantId

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

userId

المستخدم النهائي المسجَّل الذي يتصرف المساعد باسمه. غائب في الاستدعاءات بلا سياق مستخدم.

method, path

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

issuedAt, expiresAt

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

requiresStepUp

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

تعيد إخفاقات التحقق 403 مع سبب مقروء آليًا — أحد: missing-header وmalformed وbad-signature وexpired وmethod-mismatch وpath-mismatch. الأسباب متطابقة في كل حزم SDK.

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

عندما يتصرف المساعد باسم مستخدم مسجَّل، يغطي دليل التصرف باسم المستخدم المسار من البداية إلى النهاية. على مستوى العقد، يلاحظ خادمك أمرين بالضبط: حقل userId في الحمولة يسمي المستخدم المتصرَّف باسمه، وإجراءات الكتابة لا تصل إلا بعد أن يجتاز Syncanix بوابة التأكيد لديه.

يبقى التخويل لك: عامل userId بوصفه الهوية التي تُخوِّل على أساسها — تمامًا كما لو أن ذلك المستخدم استدعى نقطة النهاية مباشرة. يخوّل Syncanix أن الاستدعاء كان مقصودًا؛ ويخوّل خادمك ما يحق لذلك المستخدم فعله.

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

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

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