# ملف OpenAPI لواجهة مُجيب البرمجية

> ملف OpenAPI لواجهة مُجيب البرمجية يصف كل طلب ومعامل وحقل وخطأ. حمّله واستورده في أداة اختبار الطلبات، أو ولّد منه عميلًا بلغتك، أو تحقّق به من الردود.

ملف OpenAPI لواجهة مُجيب البرمجية يصف الطلبات الخمسة، وكل معامل فيها، وكل حقل في ردودها مع نوعه وهل يمكن أن يكون `null`، وكل خطأ، بصيغة OpenAPI `3.1`. حمّله من [openapi.json](https://docs.mujib.ai/openapi.json) واستورده في الأداة التي تستخدمها.

## ما الذي يصفه ملف OpenAPI؟

يصف الملف الواجهة كاملة كما تعمل اليوم:

- **الخادم:** `https://api.mujib.ai`، والمسارات تبدأ بـ `/api/v1`.
- **المصادقة:** طريقتان، الترويسة `Authorization: Bearer mjb_live_…` أو الترويسة `X-Api-Key`.
- **الطلبات الخمسة** بمعرّفاتها في الملف (`operationId`):

| `operationId` | الطلب | المرجع |
| --- | --- | --- |
| `getMe` | `GET /api/v1/me` | [اختبار المفتاح](https://docs.mujib.ai/developers/api-me/) |
| `listContacts` | `GET /api/v1/contacts` | [قائمة العملاء](https://docs.mujib.ai/developers/api-contacts/) |
| `getContact` | `GET /api/v1/contacts/{id}` | [عميل واحد](https://docs.mujib.ai/developers/api-contact/) |
| `listBookings` | `GET /api/v1/bookings` | [قائمة الحجوزات](https://docs.mujib.ai/developers/api-bookings/) |
| `getBooking` | `GET /api/v1/bookings/{id}` | [حجز واحد](https://docs.mujib.ai/developers/api-booking/) |

- **المعاملات:** كل معامل بنوعه وحدوده وقيمته الافتراضية، مثل `limit` و`cursor` و`since` و`from` و`to` و`status`.
- **الردود:** كل حقل بنوعه، والحقول التي قد تأتي `null`، والقيم الممكنة لـ `status` و`stage` و`source`، مع أمثلة ببيانات مختلَقة.
- **الأخطاء:** شكل الخطأ الموحّد `{ "error": { "code", "message" } }` والردود 400 و401 و403 و404 و429 و500.
- **الترويسات:** `X-RateLimit-Limit` و`X-RateLimit-Remaining` و`X-RateLimit-Reset` و`Retry-After` و`Cache-Control`.

## كيف أستخدم الملف؟

استورده في أداتك أو ولّد منه كودًا، فلا تكتب وصف الواجهة بيدك.

1. حمّل [openapi.json](https://docs.mujib.ai/openapi.json).
2. استورده في أداة اختبار الطلبات التي تستخدمها، فتظهر لك الطلبات الخمسة جاهزة.
3. ضع مفتاحك في إعدادات المصادقة في الأداة، بطريقة `Bearer`، لا في الرابط.
4. أرسل `getMe` أولًا لتتأكد أن المفتاح يعمل.

ويمكنك أيضًا:

- **توليد عميل بلغتك:** أي مولّد يقرأ OpenAPI `3.1` يكتب لك الدوال والأنواع من الملف.
- **التحقق من الردود في اختباراتك:** المخطّطات (schemas) في الملف تمنع الحقول غير الموثّقة، فتعرف إذا وصلك ما لم تتوقعه.

> **لا تضع مفتاحًا حقيقيًا في ملف مشترك**
>
> إذا حفظت إعدادات الأداة في ملف يشاركه فريقك، فاترك المفتاح في متغير بيئة لا في الملف نفسه.
## ما الإصدار الذي يصفه الملف؟

يصف الملف الإصدار الأول من الواجهة، الذي تبدأ مساراته بـ `/api/v1`. ويحمل الحقل `info.version` تاريخ آخر تغيير بصيغة ISO، وهو التاريخ نفسه في [سجل تغييرات API](https://docs.mujib.ai/developers/changelog/)، فإذا تغيّر التاريخ فراجع السجل لتعرف ما الجديد.

## ما الذي لا يصفه الملف؟

يصف الملف الطلبات التي ترسلها أنت إلى الواجهة فقط.

- أحداث [Webhooks](https://docs.mujib.ai/developers/webhooks/) التي يرسلها مُجيب إلى رابطك، وطريقة التحقق من توقيعها، لها صفحاتها.
- [خادم MCP](https://docs.mujib.ai/developers/mcp/) الذي يربط ChatGPT وClaude بحسابك له صفحته.
- صفحات لوحة التحكم وطلباتها الداخلية ليست جزءًا من الواجهة العامة، فلا تبنِ عليها.

## الأسئلة الشائعة

### هل الملف مكتوب بيد أم مولَّد؟

مكتوب بيد ليطابق الواجهة كما تعمل، وكل حقل فيه منقول من الكود الذي يبني الردود.

### هل يصف الملف Webhooks أيضًا؟

لا. يصف الطلبات التي ترسلها أنت إلى الواجهة. أحداث Webhooks وتوقيعها في صفحاتها.

### كيف أعرف أن الملف تغيّر؟

يحمل الحقل info.version تاريخ آخر تغيير، وهو التاريخ نفسه في سجل تغييرات الواجهة.

---

المصدر: https://docs.mujib.ai/developers/openapi/ · آخر تحديث: 2026-11-04