الإصدارات والإهمال

أين يقيم الإصدار

الإصدار مقطع في المسار، وهو المكان الوحيد الذي يظهر فيه:

https://api.zelnum.com/api/v1

يوجد إصدار حيّ واحد. وهويته في مستند OpenAPI هي 1.0.0؛ أما مقطع المسار v1 فهو ما تستهدفه. ولا تكرّر أجسام الاستجابة إصدارًا عن قصد، فلا يوجد حقل ثانٍ يجب مزامنته.

كيف تُصنَّف التغييرات

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

تحمّل قيم التعداد غير المعروفة

تشمل التغييرات الإضافية أعضاء جديدة في تعدادات قائمة. والعميل الذي يفرّع استقصائيًا على status أو error_code أو billing_status ويرفع استثناءً عند قيمة غير معروفة سينكسر عند تغيير كان غير كاسر بحسب السياسة.

تعامل مع القيمة غير المعروفة كحالة مختلفة لكن صالحة: سجّلها، وارجع إلى المعالجة العامة لتلك الفئة من النتائج. وأأمن افتراضي لـ error_code غير معروف هو ما يمنحه هذا التوثيق لـ internal_error — فالنتيجة غير مؤكدة، فأعد المحاولة بالمفتاح نفسه Idempotency-Key.

عندما يتغيّر التوثيق

يُصحَّح التوثيق في مكانه عندما يكون سلوك الـ API قد وُصف خطأً. فتلك تغيير في التوثيق، لا في العقد: فالـ API لم يتحرك، بل الوصف. ولأن التصحيح هو بالضبط الحدث الذي لا يمكنك رؤيته في مدخل سجل تغييرات من قبيل “لم يتغيّر شيء”، تُدرَج التصحيحات صراحةً في سجل التغييرات.

وإذا غيّر تصحيح شيئًا كنت قد بنيت عليه، فإنه يظهر هناك كملاحظة لا كتعديل صامت.

سياسة الإهمال

عند إهمال عملية تُوسم بـ deprecated: true في مستند OpenAPI، ويوثّق هذا الموقع البديل. وتظل العملية تعمل خلال فترة الإشعار، وتُذكر فترة الإشعار حيث يُعلن الإهمال.

لا يأتي الإهمال في الإصدار نفسه الذي يُقدَّم فيه بديله. فكلاهما حيّ في آن واحد، لتنتقل وفق جدولك أنت لا أثناء حادثة.

حالة الإهمال الوحيدة الحالية

أُبقي على POST /v1/realtime/detect للعملاء السابقين للإصدار، وهو موسوم كمهمَل في العقد. وينبغي للتكاملات الجديدة استخدام نقاط النهاية الخاصة بكل سلسلة.

إنها إعادة تسمية لا إعادة تصميم — فجسم الطلب والاستجابة بالشكل نفسه:

	القديم	الحالي
نقطة النهاية	POST /v1/realtime/detect	POST /v1/realtime/check/phone أو POST /v1/realtime/check/email
السلسلة	مضمّنة ضمنيًا في المنتجات التي ترسلها	صريحة في المسار، ويجب أن تطابقها
حقل المنتجات	products (اسم بديل)	product_ids
Idempotency-Key	مطلوب	مطلوب

الترحيل تغيير من سطرين:

# Before
curl -X POST "https://api.zelnum.com/api/v1/realtime/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","products":[47]}'

# After — the series moves into the path and the field is renamed
curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","product_ids":[47]}'

إرسال product_ids وproducts معًا في طلب واحد يُرفض بـ 400 invalid_realtime_request، فلا يجوز خلطهما خلال طرح تدريجي.

لا تاريخ إيقاف منشور

يوسم العقد نقطة النهاية كمهمَلة لكنه لا يحمل بعد تاريخ إزالة، فلا يستطيع هذا التوثيق ذكره. رحّل الآن — فالتغيير مسار واسم حقل، ولا سلوك لإعادة اختباره.

التالي

• OpenAPI — العقد القابل للقراءة آليًا، بما في ذلك علامة deprecated
• سجل التغييرات — ما تغيّر ومتى