OpenAPI

كل نقطة نهاية في هذا التوثيق منشورة أيضًا كمستند OpenAPI 3.1 قابل للقراءة آليًا، لتشغيل أدواتك من العقد بدلًا من نقل الجداول يدويًا.

النسخة	الرابط	ملاحظات
التوثيق	https://docs.zelnum.com/openapi.yaml	مستقر، على هذا النطاق. وهو المرجع المعتمد لقرّاء هذا الموقع.
المنصة	https://app.zelnum.com/docs/openapi.yaml	المصدر الأعلى. ونسخة التوثيق مرآة مطابقة لها بايت ببايت.

الملفان مستند واحد. وتوجد المرآة ليكون العقد على المضيف الذي تقرأ منه الآن، في مسار تجده الأدوات.

ما يحتويه المستند

الجزء	العدد	المحتوى
Servers	1	https://api.zelnum.com/api/v1
Paths	10	نقاط النهاية التسع الموثّقة، إضافة إلى اسم الوقت الفعلي القديم
Tags	3	Common, Realtime, Bulk — التقسيم نفسه الذي تستخدمه قائمة التنقل
Schemas	9	أجسام الطلبات والاستجابات، بما في ذلك مغلّف الأخطاء
مخططات الأمان	2	X-API-Key وAuthorization: Bearer

التفاصيل على مستوى العمليات موجودة في المستند نفسه: الترويسات المطلوبة، وminItems/maxItems على المصفوفات، وقيم التعداد لـ series وmode وstatus وbilling_status، وعلامة deprecated: true على POST /v1/realtime/detect.

الاستيراد إلى أدوات API

Postman — Import → File → openapi.yaml. ينشئ Postman مجموعة مع متغير بيئة للرابط الأساسي؛ اضبط مفتاحك كترويسة X-API-Key على مستوى المجموعة لترثها كل الطلبات.

Insomnia — Create → Import From → File، ثم أضف X-API-Key كترويسة للمجموعة.

Bruno / HTTPie / curl generators — جميعها تستهلك OpenAPI 3.1 مباشرةً:

curl -fsSL https://docs.zelnum.com/openapi.yaml -o zelnum.yaml

توليد عميل مُنمّط

لا يوجد SDK رسمي — فالـ API مجرد JSON فوق HTTPS، والعميل المولَّد أنسب عادةً من عميل مكتوب يدويًا، لأنه يتبع أعراف لغتك.

# Pick your generator: python, typescript-fetch, php, go, java, csharp, ruby, …
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.zelnum.com/openapi.yaml \
  -g python \
  -o ./zelnum-client

يقرأ العملاء المولَّدون الرابط الأساسي ومخطط الأمان من المستند، فلا شيء توفّره وقت التشغيل سوى مفتاح API الخاص بك.

الوقت الفعلي يتطلب ترويسة لا يستطيع المولِّد اختراعها

Idempotency-Key ترويسة مطلوبة في نقاط نهاية الوقت الفعلي، وسيعرضها العميل المولَّد كمعامل دالة يجب ضبطه. ويجب أن تكون فريدة لكل إرسال — راجع عدم التكرار وإعادة المحاولة.

الحفاظ على أمانة المرآة

تتبع المرآة المصدر الأعلى، ولا تُحرَّر هنا أبدًا. ولأن التباعد بين عقد منشور وتوثيقه هو الخلل الذي وُجدت هذه الصفحة لمنعه، تُقارن النسخة بالمصدر بدلًا من الوثوق بها:

npm run openapi:check   # fetch upstream and fail if the bytes differ
npm run openapi:sync    # re-vendor, printing which operations changed

يحتاج openapi:check إلى اتصال بالشبكة، وهو ليس جزءًا من بناء الموقع عن قصد — فلا يجوز أن يفشل النشر لأن مضيف المنصة تعثّر لحظة. أما ما يفرضه البناء فهو الشق غير المتصل من الثابت: كل نقطة نهاية يصفها هذا التوثيق يجب أن تكون موجودة في المستند المضمَّن، فلا تستطيع صفحة توثيق عملية لا يملكها العقد.

التالي

• الإصدارات والإهمال — ماذا تعني لك علامة deprecated على نقطة النهاية القديمة
• تنسيق الاستجابة — المغلّف الذي تشترك فيه كل نقاط النهاية