مرجع الواجهة البرمجية العامة

الغرض من هذه الواجهة

واجهة KayanOS البرمجية العامة هي واجهة خادم إلى خادم ذات إصدار محدد للسجلات التي أتاحتها المؤسسة عمداً. تصلح لتكامل مضبوط، مثل نظام تقارير لمركز خدمة يقرأ سجلات طلب خدمة مواطن المسموح بها أو يحدّث سجلاً معتمداً بحساب خدمة مُدار. ليست وسيلة لتجاوز الأدوار أو النطاقات أو رؤية الحقول أو قواعد الاعتماد أو البوابة العامة للنموذج. يعمل الرمز باسم العضو مالكه: لا يستطيع التكامل إلا تنفيذ أفعال الكيان ورؤية بيانات السجل/الحقل التي يملكها ذلك العضو. عامل كل رمز كبيان اعتماد عالي الحساسية. إرشاد أمان الواجهة العامة في KayanOS دون بيانات اعتماد.

إرشاد أمان الواجهة العامة في KayanOS دون بيانات اعتماد.

قبل إرسال طلب

على مالك المؤسسة أو المسؤول الذي يملك صلاحية رموز الواجهة المناسبة إتمام القائمة التالية:

من إعداد الكيان، فعّل الكيان للواجهة العامة. يعيد الكيان غير المفعّل ENTITY_NOT_FOUND عبر هذه الواجهة حتى لو كان موجوداً داخلياً.
امنح مالك الرمز أقل الأفعال اللازمة للكيان: list وcreate وupdate و/أو delete. تظل النطاقات منطبقة على السجلات الفعلية.
راجع الحقول. يُحذف الحقل المحمي بفعل قراءة ما لم يملك مالك الرمز ذلك الفعل، كما لا يصلح للترشيح أو الفرز عبر v1.
أنشئ رمزاً مسمىً له مالك وغرض وقرار انتهاء ومالك للتدوير/الإلغاء. احفظ السر الذي يظهر لمرة واحدة في مدير أسرار معتمد، لا في كود المتصفح أو نموذج أو قالب مستند أو تذكرة أو لقطة شاشة.
ابدأ بطلب للقراءة فقط على سجل غير إنتاجي معتمد لا يحوي بيانات شخصية. احتفظ بقيمة x-request-id مع دليل اختبار التكامل.

يبدأ تنسيق الرمز بـkayan_v1_؛ وهذا تنسيق تعريف فقط وليس منحاً للصلاحية. يمكن لرمز يبدو صحيحاً أن يكون منتهياً أو ملغى أو مملوكاً لعضو غير نشط أو غير قادر على الوصول إلى كيان.

عنوان الأساس والإصدار والتوثيق

استخدم مضيف KayanOS للمؤسسة المستهدفة ومسار الأساس v1:

export KAYANOS_API_BASE_URL="https://<your-kayanos-host>/api/v1"
export KAYANOS_API_TOKEN="kayan_v1_<token-id>_<secret>"

يستخدم كل طلب رمز Bearer. لا تضع الرمز في عنوان URL أو سلسلة الاستعلام.

curl --request GET "$KAYANOS_API_BASE_URL/me" \
  --header "Authorization: Bearer $KAYANOS_API_TOKEN" \
  --header "Accept: application/json" \
  --header "X-Request-Id: csr-integration-check-001"

يعيد الخادم معرف الطلب المرسل أو ينشئ واحداً عند غيابه. احتفظ به عند الإبلاغ عن فشل. تستخدم الاستجابات الناجحة غلاف data، وتستخدم الأخطاء غلاف error.

{
  "data": {
    "organizationId": "…",
    "member": { "id": "…", "name": "مالك التكامل", "email": null },
    "token": { "id": "…", "name": "تقارير-مركز-الخدمة", "tokenHint": "…" }
  }
}

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "This token cannot access the entity.",
    "requestId": "csr-integration-check-001"
  }
}

خريطة نقاط النهاية

الطريقة	المسار	الاستخدام
`GET`	`/me`	تأكيد المؤسسة وهوية الرمز والمالك قبل تشغيل التكامل.
`GET`	`/entities`	اكتشاف الكيانات المفعلة للواجهة التي يملك هذا الرمز فعلاً واحداً مفيداً عليها على الأقل.
`GET`	`/entities/:entityKey`	فحص الحقول المرئية وقدرات الرمز `list/create/update/delete`.
`GET`	`/entities/:entityKey/records`	جلب صفحة من السجلات القابلة للقراءة.
`POST`	`/entities/:entityKey/records/query`	الجلب بمرشح JSON وفرز ومؤشر وبحث.
`GET`	`/entities/:entityKey/records/:recordId`	قراءة سجل واحد واستلام `ETag` الخاص به.
`POST`	`/entities/:entityKey/records`	إنشاء سجل واحد من جسم `{ "data": { … } }`.
`PATCH`	`/entities/:entityKey/records/:recordId`	تحديث سجل واحد بقيمة `If-Match` حالية.
`DELETE`	`/entities/:entityKey/records/:recordId`	حذف سجل واحد بقيمة `If-Match` حالية.

استبدل :entityKey بمفتاح الكيان العائد من الاكتشاف، لا بعنوان عرض مترجم. واستبدل :recordId بمعرف سجل الواجهة؛ لا يلزم بادئة الكيان الداخلية، إن وُجدت، في هذا العنوان.

اكتشف العقد الفعلي أولاً

لا تخمن مفاتيح الحقول ولا تفترض أن كياناً داخلياً متاح. ابدأ بالاكتشاف واحفظ النتيجة مع إعداد التكامل.

curl "$KAYANOS_API_BASE_URL/entities/service_requests" \
  --header "Authorization: Bearer $KAYANOS_API_TOKEN"

تتضمن النتيجة بيانات الحقول المرئية وخريطة صلاحيات. تعني صلاحية false أن التكامل لا يجوز أن يحاول ذلك الفعل؛ وليست دعوة لإعادة المحاولة بمرشح أوسع. عندما يملك الحقل قيد قراءة، قد يغيب عن قائمة الحقول ولا يجوز استخدامه في الترشيح أو الفرز عبر الواجهة العامة.

جلب السجلات والبحث والترشيح وتقسيم الصفحات

يقبل الجلب بـGET معاملات limit وcursor وsort وsearch. حجم الصفحة الافتراضي 100 والحد الأعلى 500. والفرز الافتراضي الأحدث أولاً حسب created. يستخدم فرز سلسلة الاستعلام قيم field:direction مفصولة بفواصل.

curl "$KAYANOS_API_BASE_URL/entities/service_requests/records?limit=25&sort=created:desc,request_id:asc&search=CSR-2026" \
  --header "Authorization: Bearer $KAYANOS_API_TOKEN"

تحتوي الاستجابة على items وnextCursor. عامل nextCursor كقيمة معتمة: أرسلها كما هي مع الاستعلام المنطقي نفسه. لا تنشئ مؤشراً يدوياً ولا تفكّه لمنطق الأعمال ولا تعِد استخدامه مع فرز/مرشح تغيّر.

{
  "data": {
    "items": [
      {
        "id": "9d…",
        "entityKey": "service_requests",
        "created": "2026-07-12T09:30:00.000Z",
        "updated": "2026-07-12T09:32:00.000Z",
        "versionId": "17",
        "data": { "request_id": "CSR-2026-00042", "status": "closed" }
      }
    ],
    "nextCursor": "…"
  }
}

استخدم POST /records/query عندما يكون مرشح JSON أوضح أو أطول من عنوان URL. رشح وفرز الحقول القابلة للاستعلام العام فقط. مرشح المساواة البسيط مصفوفة من ثلاثة عناصر؛ وتستخدم المرشحات المركبة مصفوفتَي and أوor.

{
  "where": {
    "and": [
      ["status", "eq", "closed"],
      ["service_centre", "eq", "central"]
    ]
  },
  "sort": [{ "field": "created", "direction": "desc" }],
  "limit": 25,
  "search": "CSR-2026"
}

المرشح أو المؤشر أو الحد أو كائن الفرز غير الصالح، أو الحقل المحمي/غير القابل للاستعلام، مشكلة يجب تصحيحها في العميل. ضيّق الطلب وقارن مفاتيح الحقول بـGET /entities/:entityKey؛ ولا تعد إلى جمع كل السجلات.

أنشئ السجلات عن قصد

يتطلب الإنشاء كائناً تحوي قيمته data كائناً آخر. تستمر قواعد التحقق من جانب الخادم وصلاحيات الكيان والحقول المطلوبة وقواعد دورة الحياة والتحقق من تكرار التسمية.

curl --request POST "$KAYANOS_API_BASE_URL/entities/service_requests/records" \
  --header "Authorization: Bearer $KAYANOS_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "request_id": "CSR-2026-00042",
      "service_centre": "central",
      "status": "received"
    }
  }'

يعيد الإنشاء الناجح 201 وغلاف السجل القابل للقراءة وETag عند وجود إصدار للسجل. وقد يعيد الإنشاء CREATED_RECORD_NOT_READABLE إذا استطاع مالك الرمز الإنشاء لكنه لا يستطيع قراءة السجل الجديد. عالج تصميم الصلاحية قبل افتراض فشل التكامل أو إعادة محاولة الإنشاء.

حدّث واحذف باستخدام ETag

اقرأ السجل قبل تغييره أو حذفه. تحمل استجابة القراءة ترويسة ETag المشتقة من إصدار السجل. أرسل القيمة نفسها تماماً في If-Match عند PATCH أوDELETE.

curl --include "$KAYANOS_API_BASE_URL/entities/service_requests/records/<record-id>" \
  --header "Authorization: Bearer $KAYANOS_API_TOKEN"

curl --request PATCH "$KAYANOS_API_BASE_URL/entities/service_requests/records/<record-id>" \
  --header "Authorization: Bearer $KAYANOS_API_TOKEN" \
  --header 'If-Match: "17"' \
  --header "Content-Type: application/json" \
  --data '{ "data": { "status": "decision_review" } }'

ترويسة If-Match إلزامية. يعيد غيابها 428 PRECONDITION_REQUIRED، ويعيد إصدار قديم 412 PRECONDITION_FAILED. تقبل الواجهة If-Match: * لكنها تتجاوز مقارنة الإصدار عمداً. استخدمها فقط عندما يقبل مالك تكامل موثق الكتابة فوق التغييرات المتزامنة؛ في سير العمل الخدمي العادي استخدم ETag الدقيق وأعد القراءة عند 412. يعيد الحذف { "id", "entityKey", "deleted": true } فقط بعد فحوص الصلاحية والإصدار نفسها. ليست هذه نقطة حذف جماعي. أنشئ عملية مراجعة واحتفاظ قبل منح رمز فعل delete.

الحدود والترويسات وإعادة المحاولة

القيم الافتراضية المنشورة هي 60 محاولة توثيق لكل عنوان IP في الدقيقة و600 طلب لكل رمز في الدقيقة. يمكن للنشر تغييرها، لذا اقرأ ترويسات الاستجابة بدلاً من تثبيت رقم في العميل:

الترويسة	المعنى
`x-request-id`	معرف ربط الطلب.
`x-ratelimit-limit`	حد النافذة الحالي المطبق على الطلب.
`x-ratelimit-remaining`	الطلبات المتبقية في النافذة الحالية.
`x-ratelimit-reset`	وقت إعادة تعيين النافذة بثواني Unix.
`retry-after`	عدد الثواني للانتظار عندما يعيد الخادم `429`.
`etag`	إصدار السجل الحالي بعد قراءة أو إنشاء أو تحديث سجل واحد عند توافره.

عند 429 انتظر على الأقل عدد ثواني retry-after وطبّق تراجعاً محدوداً. وعند 412 أعد قراءة السجل وقارن تغيير الأعمال ثم قرر إن كان التحديث ما زال صحيحاً. لا تعِد إنشاء أو حذفاً بشكل أعمى بعد مهلة: حدد أولاً هل نجح الطلب الأصلي باستخدام معرف آمن أو تسوية يراجعها المالك.

مرجع الحالات والأخطاء

الحالة	الرمز المعتاد	المعنى والخطوة التالية
`400`	`INVALID_BODY` و`INVALID_FILTERS` و`INVALID_LIMIT` و`INVALID_CURSOR` و`INVALID_SORT` و`FIELD_NOT_QUERYABLE`	صحح طلب العميل أو اختيار الحقل.
`401`	`INVALID_TOKEN` و`TOKEN_REVOKED` و`TOKEN_EXPIRED` و`OWNER_INACTIVE`	دوّر/أعد تفويض الرمز عبر مالكه؛ لا تكشف السر الفاشل.
`403`	`PERMISSION_DENIED` و`CREATED_RECORD_NOT_READABLE`	راجع أفعال المالك والنطاقات ووصول الحقول وقواعد دورة الحياة.
`404`	`ENTITY_NOT_FOUND` و`RECORD_NOT_FOUND`	أكد مفتاح الكيان المفعّل للواجهة ومعرف سجل قابل للقراءة.
`409`	`DUPLICATE_LABEL` و`PARENT_REFERENCE`	سوِّ تعارض الأعمال بدلاً من إعادة محاولة البيانات نفسها.
`412`	`PRECONDITION_FAILED`	أعد قراءة السجل وحل التحديث المتزامن.
`428`	`PRECONDITION_REQUIRED`	أرسل `If-Match` مع `PATCH` أو`DELETE`.
`429`	`RATE_LIMITED`	احترم `retry-after` وخفف ضغط الطلبات.
`500`	`SERVER_ERROR`	احتفظ بمعرف الطلب وسياق طلب منقح ثم صعّد المشكلة.

مثال تكامل عملي: تقارير الطلبات المغلقة

لتكامل تقارير مركز خدمة:

تفعّل المؤسسة service_requests فقط للواجهة العامة وتمنح عضواً للتقارير فعل list في نطاق مركز الخدمة المناسب.
يستدعي التكامل /me عند البدء، ويحفظ تلميح الرمز ومعرف الطلب في سجل تشغيلي محمي، ويتوقف إذا كانت المؤسسة أو المالك غير متوقعين.
يستعلم عن status = closed ومركز الخدمة المعتمد بالحد 25، ثم يتبع nextCursor حتى اكتمال نافذة التقرير.
يحتفظ فقط بالحقول المعادة المطلوبة للتقرير، ولا يستنتج أو يجلب حقول مواطن أو مالية أو موظفين مخفية.
إذا احتاج إلى تحديث حقل تديره التقارير، يقرأ السجل أولاً ويرسل ETag المعاد ثم يرسل تحديث { "data": { … } } ضيقاً. عند 412 يعيد القراءة ويطلب من مالك التكامل حسم الحالة المتغيرة.

وهذا يمنح المديرية حد تكامل قابل للتتبع من دون تحويل رمز الواجهة إلى تصدير شامل للبيانات.

قائمة الأمان والإصدار

استخدم رمزاً مسمىً واحداً لكل تكامل ولكل بيئة، ولا تشارك رمز شخص بين خدمات.
امنح المالك أقل أفعال ونطاقات للكيانات، واختبر الرفض قصداً مثلما تختبر الوصول الناجح.
اضبط تاريخ انتهاء ما لم تبرر متطلبات خدمة موثقة وعملية تدوير رمزاً بلا انتهاء.
احفظ الأسرار في مخزن أسرار خادمي معتمد فقط. لا تشحنها في عميل ويب أو جوال.
ألغ الرمز فوراً عند مغادرة مالكه أو تغير غرضه أو الاشتباه بتعرضه؛ الإلغاء يوقف عمله فوراً.
سجّل نقطة النهاية والحالة ومعرف الطلب واسم/تلميح الرمز ومرجع سجل منقحاً، لا ترويسة Authorization ولا الرمز الكامل ولا حمولة حساسة.
اختبر على سجل غير إنتاجي معتمد قبل تفعيل كتابات مجدولة في الإنتاج.

استكشاف الأخطاء وإصلاحها

العرض	ما يجب فحصه	المعالجة
يعيد `/me` حالة `401`	مخطط Authorization وحالة الرمز وانتهاؤه وحالة دخول المالك	أنشئ/دوّر رمزاً عبر المالك؛ لا تلصق سراً فعلياً في طلب دعم.
يغيب كيان عن `/entities`	إعداد الواجهة العامة وفعل واحد مفيد للمالك على الأقل	فعّل الكيان الصادر الصحيح وامنح أقل فعل/نطاق لازم.
يغيب حقل أو يحدث `FIELD_NOT_QUERYABLE`	بيانات الكيان وسياسة فعل قراءة الحقل	استخدم حقلاً مسموحاً أو غيّر وصول الحقل عبر الحوكمة المعتمدة؛ لا تتجاوزه بطلب أوسع.
`403` على سجل موجود داخلياً	دور المالك والنطاق وقاعدة دورة الحياة ورؤية السجل	اختبر بنطاق مالك الرمز المقصود وصحح تصميم الصلاحية.
`412` عند التحديث/الحذف	`ETag` الحالي مقابل الترويسة المحفوظة	أعد القراءة وسوِّ تغيير الأعمال ثم أرسل `If-Match` دقيقاً جديداً.
`429` متكرر	ترويسات الحد والعمال المتزامنون	خفف التزامن واحترم `retry-after` واستخدم المؤشرات.

لغة التعبيرات

مرجع دوال التعبيرات

المرجع العملي

مرجع الواجهة البرمجية العامة

الغرض من هذه الواجهة

قبل إرسال طلب

عنوان الأساس والإصدار والتوثيق

خريطة نقاط النهاية

اكتشف العقد الفعلي أولاً

جلب السجلات والبحث والترشيح وتقسيم الصفحات

أنشئ السجلات عن قصد

حدّث واحذف باستخدام ETag

الحدود والترويسات وإعادة المحاولة

مرجع الحالات والأخطاء

مثال تكامل عملي: تقارير الطلبات المغلقة

قائمة الأمان والإصدار

استكشاف الأخطاء وإصلاحها

أدلة ذات صلة

​الغرض من هذه الواجهة

​قبل إرسال طلب

​عنوان الأساس والإصدار والتوثيق

​خريطة نقاط النهاية

​اكتشف العقد الفعلي أولاً

​جلب السجلات والبحث والترشيح وتقسيم الصفحات

​أنشئ السجلات عن قصد

​حدّث واحذف باستخدام ETag

​الحدود والترويسات وإعادة المحاولة

​مرجع الحالات والأخطاء

​مثال تكامل عملي: تقارير الطلبات المغلقة

​قائمة الأمان والإصدار

​استكشاف الأخطاء وإصلاحها

​أدلة ذات صلة

الغرض من هذه الواجهة

قبل إرسال طلب

عنوان الأساس والإصدار والتوثيق

خريطة نقاط النهاية

اكتشف العقد الفعلي أولاً

جلب السجلات والبحث والترشيح وتقسيم الصفحات

أنشئ السجلات عن قصد

حدّث واحذف باستخدام ETag

الحدود والترويسات وإعادة المحاولة

مرجع الحالات والأخطاء

مثال تكامل عملي: تقارير الطلبات المغلقة

قائمة الأمان والإصدار

استكشاف الأخطاء وإصلاحها

أدلة ذات صلة