# الإصدارات والتغييرات

إصدار الواجهة جزء من المسار: `https://api.saei.automize.sa/v1`. داخل `v1` لا نجري إلا تغييرات لا تكسر تكاملًا صحيحًا:

- نقاط جديدة، وحقول طلب اختيارية جديدة، وحقول استجابة جديدة، وأنواع أحداث جديدة، ورموز أخطاء جديدة، وقيم جديدة في الحقول الموثّقة بأنها قابلة للتوسع (مثل `type`)؛
- رسائل أخطاء أوضح (اعتمد على `code` لا على `message`).

اكتب تكاملك ليتحمل ذلك: تجاهل الحقول التي لا تعرفها، وتعامل مع `status` أو نوع حدث غير معروف دون أن يتعطل.

التغيير الكاسر يأتي في إصدار جديد (`v2`) ويبقى `v1` يعمل. وقبل حذف أي شيء من `v1` تحصل على إشعار قبل ستة أشهر على الأقل، وترويستَي `Deprecation` و`Sunset` في الاستجابات المتأثرة، وبند في سجل التغييرات.

لحمولات الويب هوك إصدار خاص بها في `version` (حاليًا `"2"`). وداخل الإصدار الواحد تُضاف الحقول فقط.

كل تغيير في الواجهة مدوَّن في [سجل التغييرات](/docs/changelog).