سجل التغييرات

تُدوَّن في هذه الصفحة التغييرات التي تطرأ على الـ API وعلى هذا التوثيق. تبدأ المدخلات من 2026-09-19: وكل ما تغيّر قبل وجود هذه الصفحة غير مدرج بأثر رجعي، فاعتبر المدخل الغائب “غير مدوَّن” لا “غير متغيّر”.

كيف تقرأه

النوع	المعنى
API	تغيّرت الخدمة — نقطة نهاية، أو حقل، أو حد.
العقد	تغيّر مستند OpenAPI المنشور.
المستندات	تغيّر التوثيق. والـ API لم يتحرك.
تصحيح	كان التوثيق يصف الـ API وصفًا خاطئًا.

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

2026-10-27 — مرجع رموز الدول

المستندات · إضافة

• صفحة رموز الدول قابلة للبحث تُدرج جميع رموز ISO 3166-1 alpha-2 المخصصة رسميًا، مرتبطة من نقاط النهاية التي تقبل حقل country.

2026-09-19 — إعادة هيكلة التوثيق ونشر العقد

المستندات · إضافة

• قسم مرجع: OpenAPI والإصدارات والإهمال والحالة والدعم والأمان والمعجم.
• أصبح مستند OpenAPI 3.1 منشورًا على https://docs.zelnum.com/openapi.yaml، وهو مرآة مطابقة بايت ببايت لنسخة المنصة، وقابل للاستيراد في Postman وInsomnia ومولّدات العملاء.
• أمثلة عملاء بـ Python وNode.js وPHP وGo لنمطي الفحص كليهما، إلى جانب أمثلة cURL القائمة. وكانت قائمة التنقل تعد بأمثلة SDK بينما لم يكن موجودًا سوى cURL.
• جداول استجابة حقلًا بحقل لفحص الوقت الفعلي، والإرسال الجماعي، وحالة المهمة، ونقاط نهاية النتائج.
• حاجزان جديدان في البناء: يفشل البناء الآن عند وجود جدول مشوّه في أي لغة، ويطابق كل نقطة نهاية يسمّيها هذا التوثيق مع مستند OpenAPI المضمَّن في الاتجاهين — فنقطة نهاية موثّقة يفتقر إليها العقد، ومسار في العقد لا يوثّقه أحد، كلاهما فشل.

العقد · إضافة

• مستند OpenAPI نفسه: 10 مسارات، و9 مخططات، وdeprecated: true على POST /v1/realtime/detect القديمة.

المستندات · تصحيحات

• كان الحقل الجماعي country موثّقًا كمطلوب في كل إرسال. وهو مطلوب لمنتجات الهاتف ويجب حذفه لمنتجات البريد الإلكتروني. وكما كان مكتوبًا، كانت منتجات البريد الإلكتروني الجماعية التسعة غير قابلة للإرسال — فكل طلب كان سيفشل في التحقق.
• كانت قاعدة الحجم الجماعي خاطئة. كانت تقول “من 1,000 إلى 2,000,000 رقم لكل طلب”. والقاعدة الحقيقية هي الحد الأدنى الخاص بالمنتج المختار — 500 أو 1,000 أو 2,000 — حتى حد أقصى للمنصة قدره 2,000,000. وقد استبعد الرقم القديم أحد عشر منتجًا حدها الأدنى 500.
• كان كتالوج الأخطاء يسرد أربعة رموز لا يعيدها الـ API أبدًا. فصفحة التوثيق القديمة للمنصة تسمّي not_found وresult_not_ready وresult_expired وvalidation_failed؛ ولا يُصدر التنفيذ أيًّا منها، ولا تحمل تلك الاستجابات حقل code إطلاقًا. ويسرد الجدول الآن الرموز الـ 22 التي يعيدها الـ API فعلًا، ويوثّق جدول ثانٍ الحالات بلا رمز — مع تحذير لكل من نقل تلك الفروع الأربعة.
• كانت أمثلة الاستجابة تفتقد حقولًا يعيدها الـ API فعلًا. series وcharged_amount وrefunded_amount في استجابات الوقت الفعلي؛ وidempotent_replay وrecovery_pending في الإرسالات الجماعية؛ وعشرة عدّادات لتقدّم المهمة منها submitted وprefiltered وdeduped وstage وlast_progress_at وfailure_message.
• كانت حدود المعدل تسمّي نقطة النهاية الخطأ. قال سطر الوقت الفعلي POST /v1/realtime/check/phone؛ والحد ينطبق على POST /v1/realtime/check/{series}، بما في ذلك البريد الإلكتروني.
• وُصفت ترويسات الاستجابة وصفًا خاطئًا. كانت صفحة حدود المعدل توحي بأن مجموعة الترويسات كاملة تظهر على كل استجابة. وهي لا تفعل ذلك: فحاوية الوقت الفعلي لا تُبلّغ عند النجاح إلا عن X-RateLimit-Remaining ولا تُبلّغ أبدًا عن X-RateLimit-Limit، ولا يظهر X-RateLimit-Reset إلا على 429 عام أو خاص بالفحص. وتوضّح الصفحة الآن أي ترويسة تظهر وأين.
• وُصف نموذج المفتاح وصفًا خاطئًا. ادّعت صفحة الأمان أن الحساب يحمل مفتاحًا واحدًا في كل مرة. ويمكن للحساب أن يحمل عدة مفاتيح نشطة، وتُنشئها لوحة التحكم وتعيد توليدها وتحذفها فرادى — فالتدوير التدريجي بلا توقف ممكن، وإعادة التوليد في المكان هي الصيغة التي لا تداخل فيها. ويُبلّغ GET /v1/api-key عن أحدث مفتاح نشط لا عن جرد، ويُكتب last_used الخاص به مرة كل خمس دقائق على الأكثر.
• وُصف التمييز بين المعرّفات ومعرّفات slug وصفًا خاطئًا. قال المعجم إن خلط ID أو slug يُرفض بـ product_mode_not_supported. وفي نقاط نهاية الوقت الفعلي يُتحقق من product_ids كمصفوفة أعداد صحيحة، فيُرفض الـ slug أبكر بـ 400 invalid_realtime_request؛ أما 422 product_mode_not_supported فهو جواب نقطة النهاية الجماعية على منتج فوري.
• ناقضت صفحة تنسيق الاستجابة صفحة الرصيد في العملة. قالت إحداهما “عملة فوترة الحساب”، وقالت الأخرى USD. وكلتاهما تقول الآن USD، وهو ما يقوله العقد ونقطة نهاية الرصيد.
• ذُكرت وحدة تسعير بلا مصدر. وُصف الجماعي بأنه “يُسعَّر لكل 10,000 فحص”. والكتالوج لا يكشف أي تسعير، فأُزيل الادّعاء بدلًا من إبقائه.
• كان تصحيحان قد وصلا إلى الصفحات المكتوبة يدويًا فقط. صُحّح بيان العملة وادّعاء “لكل 10,000 فحص” في الصفحتين الإنجليزية والصينية المبسّطة، لكن جدول النصوص الذي يولّد اللغات السبع الأخرى كان لا يزال يحملهما، فواصلت سبع لغات نشر كليهما. وقد صُحّحا في الجدول أيضًا.
• كان /examples/ صفحة مختلفة في كل لغة. كانت الصفحة الإنجليزية مركز تنقّل قصيرًا بينما عرضت اللغات الثماني الأخرى جولة جماعية من خمس خطوات. وتطابق الإنجليزية الآن الجولة، فتحمل اللغات التسع المحتوى نفسه.

المستندات · إصلاحات

• فقدت جداول المعاملات عمود وصفها بصمت في اللغات المولَّدة السبع كلها. كان مساعد مشترك يصدر ترويسة من ثلاثة أعمدة لصفوف من أربع خلايا، وGFM يُسقط كل خلية بعد عرض الترويسة — ففي الإسبانية مثلًا ظهرت قيمة “Required” تحت عنوان “Description” واختفى الوصف نفسه، في ثلاث صفحات عبر سبع لغات. ويأخذ المساعد الآن شكل أعمدة صريحًا ويفشل البناء عند وجود صف مشوّه، ويعيد حاجز مرحلة dist فحص كل جدول مُصيَّر في كل لغة باستقلالية.
• كانت اللغات المولَّدة تعرض ترويسات أعمدة جدول المنتجات وملاحظته وسطر مزامنته بالإنجليزية، وكانت علامات backtick في الملاحظة تصل إلى المتصفح كمحارف حرفية. والآن تأتي نصوص المكوّنات من جدول النصوص المترجم، ويفشل البناء عند غياب ترجمة بدلًا من الرجوع إلى الإنجليزية.

الاشتراك في التغييرات

لا توجد تغذية بعد. وإلى أن توجد، فإن الإشارة الموثوقة هي العقد:

npm run openapi:check

في مهمة مجدولة — فهي تخرج برمز غير صفري لحظة اختلاف المستند المنشور عن النسخة التي ضمّنتها. راجع OpenAPI للرابطين.