# سجل تغييرات API لواجهة مُجيب البرمجية

> سجل تغييرات API في مُجيب، بتاريخ كل تغيير في الواجهة البرمجية العامة منذ إطلاقها، وما الذي قد يحتاج إلى تعديل في برنامجك بعد كل تغيير.

سجل تغييرات API هذا يذكر كل تغيير في واجهة مُجيب البرمجية العامة (`/api/v1`) منذ إطلاقها، بتاريخه، الأحدث أولًا. لم يتغيّر أي مسار ولا اسم حقل منذ الإطلاق؛ التغييرات كلها في الأخطاء وترويسات حدود الطلبات.

## ما الذي تغيّر في واجهة مُجيب البرمجية؟

### 2026-11-04

- **ترويسات حد المفتاح في كل رد ناجح:** الترويسات `X-RateLimit-Limit` و`X-RateLimit-Remaining` في رد المفتاح الصالح تصف الآن حد المفتاح نفسه، بعد أن كانت قد تصف حد عنوان الشبكة. وتقول `X-RateLimit-Reset` الآن كم ثانية بقيت حتى تبدأ دقيقة المفتاح من جديد.
- **الخطأ 429 من حد عنوان الشبكة** يحمل الآن الرمز `RATE_LIMITED`، كخطأ حد المفتاح، بدل `BAD_REQUEST`.
- **المعرّف بصيغة غير صحيحة** في `GET /api/v1/contacts/{id}` و`GET /api/v1/bookings/{id}` يعود الآن بالخطأ 404 ورمز `NOT_FOUND`، كالمعرّف غير الموجود، بدل الخطأ 400.
- **التواريخ المستحيلة تُرفض بالخطأ 400:** يومٌ لا وجود له في `from` أو `to` (مثل `2026-02-31`)، أو `from` بعد `to`، أو لحظة في `since` من السنة `0000`. كان التاريخ المستحيل يعود بخطأ في الخادم، وكان `from` بعد `to` يعيد قائمة فارغة.
- **`GET /api/v1/bookings/{id}`** يعود الآن بالخطأ 404 للسجلات التاريخية المستوردة من سجل قديم، كما كانت القائمة تستبعدها من قبل.

### 2026-10-25

- **الخطأ 400 لمعامل غير صالح** يحمل الآن في `issues` أول 20 مشكلة فقط، ومعها `issueCount` بعدد المشكلات كلها.

### 2026-10-19

- **إطلاق الواجهة البرمجية العامة:** الطلبات الخمسة `GET /api/v1/me` و`GET /api/v1/contacts` و`GET /api/v1/contacts/{id}` و`GET /api/v1/bookings` و`GET /api/v1/bookings/{id}`.
- مفاتيح API للقراءة فقط تبدأ بـ `mjb_live_`، بصلاحيتين: `contacts.read` و`bookings.read`، تُرسَل في `Authorization: Bearer` أو `X-Api-Key`.
- 60 طلبًا في الدقيقة لكل مفتاح، والتقسيم إلى صفحات بالمؤشر `nextCursor`، وشكل خطأ موحّد `{ "error": { "code", "message" } }`.

## هل تحتاج هذه التغييرات إلى تعديل في برنامجي؟

غالبًا لا، إلا إذا كان برنامجك يبني على السلوك القديم في الحالات التالية:

- إذا كنت تعامل الخطأ 400 من طلب العنصر الواحد على أنه «معرّف غير صحيح»، فعامل الخطأ 404 بالطريقة نفسها.
- إذا كنت تفرّق بين خطأ الحد وغيره بالرمز `BAD_REQUEST`، فابنِ على `RATE_LIMITED` أو على رمز HTTP 429.
- إذا كنت ترسل `from` بعد `to` وتتوقع قائمة فارغة، فصحّح الترتيب، لأن الطلب يُرفض الآن بالخطأ 400.
- إذا كنت تحسب ما بقي من حدك من الترويسات، فهي الآن أرقام مفتاحك، و`X-RateLimit-Reset` يخبرك متى تبدأ الدقيقة من جديد.

## كيف أعرف أن الواجهة تغيّرت؟

يُسجَّل كل تغيير في هذه الصفحة بتاريخه، ويحمل [ملف OpenAPI](https://docs.mujib.ai/developers/openapi/) في الحقل `info.version` تاريخ آخر تغيير. قارن التاريخ الذي بنيت عليه بالتاريخ الحالي، وراجع ما بينهما هنا. وتفاصيل كل رمز خطأ في [الأخطاء وحدود الطلبات](https://docs.mujib.ai/developers/errors-limits/).

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

### هل يشمل هذا السجل تغييرات لوحة التحكم؟

لا. يشمل الواجهة البرمجية العامة فقط، أي الطلبات التي تبدأ بـ /api/v1. لتغييرات المنتج كله سجل خاص في المرجع.

### هل تغيّر مسار /api/v1 منذ الإطلاق؟

لا. ما زالت الطلبات الخمسة نفسها بالمسارات نفسها، وبالحقول نفسها في الردود.

### كيف أعرف أن ملف OpenAPI يطابق آخر تغيير؟

الحقل info.version في الملف يحمل تاريخ آخر تغيير في هذا السجل.

---

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