نظرة عامة على API

صُممت واجهة ZTXBAS العامة لتكون صغيرة عمدًا: عشرة مسارات عبر أربعة موارد، جميعها تحت /v1/*، بالإضافة إلى مسارين دون مصادقة لفحص الصحة واكتشاف المفاتيح.

مواصفات قابلة للقراءة الآلية

المواصفات المرجعية الرسمية في ملف openapi.yaml بالمستودع. وهي OpenAPI 3.1 ويمكن التحقق منها عبر Swagger Editor وStoplight وأدوات توليد الشيفرة المعروفة.

المسارات باختصار

الفعل	المسار	الغرض
POST	/v1/users	تسجيل مستخدم وإرسال بريد الإعداد
GET	/v1/users	عرض المستخدمين في المستأجر
DELETE	/v1/users	إلغاء تسجيل مستخدم، والبريد في جسم الطلب
POST	/v1/origins	تسجيل أصل
GET	/v1/origins	عرض الأصول المسجلة
DELETE	/v1/origins/{id}	حذف أصل
POST	/v1/auth/challenge	إنشاء تحدٍ وإرساله إلى الهاتف
GET	/v1/auth/status/{challenge_id}	الاستعلام عن نتيجة التحدي
GET	/.well-known/jwks.json	المفاتيح العامة للتحقق من JWT
GET	/health	فحص حياة الخدمة، دون مصادقة

كل ما يقع تحت /v1/* يتطلب توقيع HMAC-SHA256؛ انظر توقيع HMAC للاطلاع على الصيغة الموحّدة. وتتولى SDK ذلك نيابةً عنك.

المصادقة

أربعة رؤوس لكل طلب تحت /v1/*:

X-Application-ID: app_...
X-Timestamp: 1704067200
X-Nonce: 32-hex-chars
X-Signature: hex(HMAC-SHA256(secret, canonical))

الرؤوس المفقودة أو غير الصالحة تؤدي إلى 401 UNAUTHORIZED مع رمز error محدد يبين الفحص الذي فشل.

صيغة الأخطاء

تشترك جميع استجابات 4xx/5xx في بنية JSON نفسها:

{ "error": "UNREGISTERED_ORIGIN", "message": "origin not registered for this application" }

• error قابل للمعالجة آليًا ومستقر؛ استخدمه في منطق الإعادة أو التفرع.
• message نص موجّه للبشر وقد يتغير؛ لا تعتمد على تحليله برمجيًا.

رموز شائعة:

الرمز	السبب
MISSING_AUTH	غياب أحد رؤوس HMAC الأربعة
INVALID_SIGNATURE	فشل التحقق من HMAC
INVALID_TIMESTAMP	الطابع الزمني سالب أو ليس عددًا صحيحًا
TIMESTAMP_EXPIRED	الطابع الزمني خارج ±300 ثانية من ساعة الخادم
INVALID_APPLICATION	قيمة X-Application-ID غير معروفة
BODY_TOO_LARGE	جسم الطلب يتجاوز 8 KiB
DUPLICATE_EMAIL	محاولة تسجيل مستخدم موجود بالفعل
UNREGISTERED_ORIGIN	لم يُسجّل أصل التحدي أولًا عبر POST إلى /v1/origins
USER_NOT_FOUND	تحدٍ أو إلغاء تسجيل لمستخدم غير معروف
ENROLLMENT_FAILED	تعذر على الخادم إرسال رسالة التسجيل

حدود معدل الطلبات

لا يفرض ZTXBAS نفسه حاليًا حدود معدل الطلبات. استخدم وكيلًا عكسيًا (nginx أو Caddy أو Cloudflare) إذا احتجت حدودًا لكل مستأجر؛ يغطي دليل تقوية الأمان أساسًا موصى به.