> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> اربط تكاملاً خادمياً بسجلات KayanOS المفعلة صراحةً، مع وصول محدود وترقيم صفحات وتحديثات آمنة عند التزامن.

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

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

ليست وسيلة لتجاوز الأدوار أو النطاقات أو رؤية الحقول أو قواعد الاعتماد أو البوابة العامة للنموذج. يعمل الرمز باسم العضو مالكه: لا يستطيع التكامل إلا تنفيذ أفعال الكيان ورؤية بيانات السجل/الحقل التي يملكها ذلك العضو. عامل كل رمز كبيان اعتماد عالي الحساسية.

![إرشاد أمان الواجهة العامة في KayanOS دون بيانات اعتماد.](https://kayanos.app/docs-images/ar/reference/public-api.png)

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

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

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

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

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

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

```bash theme={null}
export KAYANOS_API_BASE_URL="https://<your-kayanos-host>/api/v1"
export KAYANOS_API_TOKEN="kayan_v1_<token-id>_<secret>"
```

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

```bash theme={null}
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`.

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

```json theme={null}
{
  "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` بمعرف سجل الواجهة؛ لا يلزم بادئة الكيان الداخلية، إن وُجدت، في هذا العنوان.

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

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

```bash theme={null}
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` مفصولة بفواصل.

```bash theme={null}
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` كقيمة معتمة: أرسلها كما هي مع الاستعلام المنطقي نفسه. لا تنشئ مؤشراً يدوياً ولا تفكّه لمنطق الأعمال ولا تعِد استخدامه مع فرز/مرشح تغيّر.

```json theme={null}
{
  "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`.

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

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

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

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

```bash theme={null}
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`.

```bash theme={null}
curl --include "$KAYANOS_API_BASE_URL/entities/service_requests/records/<record-id>" \
  --header "Authorization: Bearer $KAYANOS_API_TOKEN"
```

```bash theme={null}
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`                                                                                              | احتفظ بمعرف الطلب وسياق طلب منقح ثم صعّد المشكلة.            |

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

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

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

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

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

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

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

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

## أدلة ذات صلة

* [إدارة رموز الواجهة والواجهة العامة](/ar/administration/api-tokens-and-public-api)
* [الصلاحيات والإتاحة](/ar/reference/permissions-and-availability)
* [الكيانات](/ar/build/entities)
* [استكشاف الأخطاء وإصلاحها](/ar/reference/troubleshooting)