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

عناوين الأساس

الإنتاج هو https://api.heyservus.com (عنوان الأساس الافتراضي للحزمة)؛ والتطوير المحلي http://localhost:5080. كل الاستجابات JSON.

أربعة مخططات مصادقة، واحد لكل بادئة

يحمل الطلب تماماً بيانات الاعتماد التي تتوقّعها مجموعة مساره، وتُشتقّ هوية المستأجِر دائماً من بيانات الاعتماد، لا من جسم الطلب:

• /auth/** — مجهول (تسجيل / دخول).
• /portal/** — JWT البوابة (Authorization: Bearer <jwt>)؛ المستأجِر من ادعاء tenant في الـ JWT.
• /v1/** — مفتاح API لكل مستأجِر (X-Api-Key: <key> أو Authorization: Bearer <key>).
• /internal/** — رمز داخلي مشترك (للبوابة فقط؛ ليس API عاماً).

صلاحيات مفتاح API

تحمل مفاتيح API الصلاحيات كحقل بِتّي: Send=1 وRead=2 وContacts=4 وAdmin=8. امنح أقلّ ما يحتاجه المفتاح؛ والمفتاح الفاقد لصلاحية مسارٍ يحصل على 403. يُعرَض المفتاح الخام مرة واحدة عند الإنشاء — احفظه حينها؛ ولا يُحفَظ سوى التجزئة.

التعدادات أرقام ترتيبية

تُسلسِل الواجهة تعداداتها أرقاماً صحيحة على السلك (مثل channel: 1=واتساب، 2=Sms، 3=Email، 4=Telegram، 5=Push). ويُحوِّلها عميل @servus/sdk إلى اتحادات نصّية مريحة. الاستثناء الوحيد: channel في خطاف message.inbound هو اسم القناة نصّاً.

تنبيه: الأرقام الترتيبية لـ MessageStatus ليست بترتيب دورة الحياة (Sending هو 5، وReceived هو 6، أُلحِقا بعد الحالات الأصلية). قارِن بالقيمة المسمّاة — ولا تقارن الأرقام الترتيبية لاستنتاج التقدّم.

الأخطاء وفق RFC 7807

الأخطاء application/problem+json: { type, title, status, detail, traceId }. وطلب /v1 بمفتاح ناقص/غير صالح يفشل مغلقاً بـ 401 وترويسة WWW-Authenticate: ApiKey.