مرجع الواجهة

صفحات هذا القسم مولّدة من وثيقة OpenAPI الخاصة بالنظام نفسه، فهي تصف الواجهة كما هي فعلًا لا كما تذكّرها أحد. وكل صفحة عملية واحدة: معاملاتها وجسم طلبها واستجاباتها ومثال جاهز للتشغيل.

صفحات العمليات مكتوبة بالإنجليزية لأنها مولّدة حرفيًّا من الوثيقة.

قبل قراءة أي نقطة نهاية

ثلاثة أمور تصحّ على كل عملية هنا، ولذلك لا تتكرّر في كل صفحة:

• المسارات مطلقة. /api/public/properties هو المسار كاملًا؛ وعنوان الواجهة الأساسي من تبويب «اربط موقعك» ينتهي بـ /api أصلًا، فتنادي `${API}/public/properties`.
• الترويسات. تعلن كل عملية X-Site وX-Api-Key؛ وعمليات الكتابة الخمس المحميّة تعلن كذلك X-Turnstile-Token. انظر تعريف موقعك والمفاتيح وCORS.
• الغلاف. الاستجابات مغلّفة بـ { success, data, message? }، مع pagination بجوار data في القوائم المقسّمة. والمخطّطات أدناه تصف الحمولة — أي ما تجده داخل data. انظر البداية السريعة.

الوثيقة الخام

يقدّم نظامك الوثيقة نفسها على GET <host>/public-openapi.json — بلا مصادقة وبلا مسارات موظّفين. وجّه إليها مولّد عميل، أو قارن بين إصدارين لترى ما تغيّر.

يغطّي هذا المرجع الواجهة العامّة وحدها. كل ما يستطيع زائر مسجّل فعله موجود فيه؛ ولا شيء ممّا يستطيع موظّف النظام فعله.