APIمرجع خادم RTC
عنوان URL الأساسي: https://api.rtc.champrep.com
تغطي هذه المرجع مسارات التكامل المدعومة بمفاتيحAPI مشاريع RTC. عمليات تسجيل الدخول إلى وحدة التحكم، وإعداد المؤسسة، وإدارة المفاتيح، وإدارة النظام الأساسي ليست مسارات تكامل باستخدام مفتاح الخادم. قم بإدارتها من خلال واجهة المستخدم المناسبة بدلاً من نسخ رموز جلسة المتصفح إلى البرامج النصية.
إرسال Authorization: Bearer YOUR_RTC_API_KEY وبالنسبة لنصوص JSON،
Content-Type: application/json. تستخدم الأمثلة عناصر نائبة، ولا تستخدم أبدًا بيانات اعتماد صالحة. تظل المفاتيح مقيدة بمشروعها ووصول الخطة الحالية.
قواعد الطلب والاستجابة
Section titled “قواعد الطلب والاستجابة”- المعرفات هي سلاسل UUID. استخدم المعرفات التي ترجعها RTC، وليس أسماء العرض.
- يتم اقتطاع الأسماء ولا يُسمح إلا بما بين 1 و80 حرفًا.
- يقتصر حجم نصوص JSON على 64 كيلوبايت وترفض الحقول غير المعروفة.
- تُرجع نقاط نهاية القوائم مصفوفات JSON، الأحدث أولاً.
?limit(1-200) يحدد حجم الصفحة؛ وعند وجود المزيد من العناصر، فإنX-Next-Cursorيحتوي رأس الاستجابة على المؤشر الذي سيتم إرجاعه كـ?cursor. - لا تعتمد على حقول الاستجابة غير الموثقة أو قم بإنشاء عناوين URL للوسائط/التخزين.
- لا توفر عمليات التغيير عقدًا عامًا لمفتاح الإيدمبوتنس. قم بمطابقة النتائج قبل إعادة المحاولة بعد انتهاء المهلة أو انقطاع الاتصال.
ملخص الطريقة
Section titled “ملخص الطريقة”| الطريقة والمسار | النطاق المطلوب | النتيجة |
|---|---|---|
GET /v1/projects | أي مفتاح مشروع صالح | مصفوفة مُفلترة حسب المشروع |
GET /v1/rooms | rooms:read | مصفوفة الغرف |
POST /v1/rooms | rooms:write | 201، غرفة تم إنشاؤها |
POST /v1/rooms/{roomId}/end | rooms:write | { "ended": true } |
POST /v1/rooms/{roomId}/tokens | tokens:write | مجموعة بيانات اعتماد المشاركين |
GET /v1/recordings | recordings:read | مصفوفة التسجيل |
POST /v1/recordings | recordings:write | 202، التسجيل في قائمة الانتظار |
POST /v1/recordings/{recordingId}/stop | recordings:write | { "stopping": true } |
POST /v1/recordings/{recordingId}/tracks/{trackId}/download | recordings:read | رابط التنزيل المؤقت |
POST /v1/recordings/{recordingId}/transcript | recordings:write | 202، يُطلب النص (نسخ) |
GET /v1/recordings/{recordingId}/transcript | recordings:read | النص في صيغة JSON، أو ملف يحتوي على ?format=vtt, srt أو txt |
GET /v1/transcripts | recordings:read | نصوصك وحالتها، بدون نص |
GET /v1/usage | أي مفتاح مشروع صالح | الاستخدام المكتمل والحدود المسموح بها |
GET /v1/webhooks/endpoints, GET /v1/webhooks/deliveries | webhooks:read | نقاط النهاية وسجل التسليم (webhooks) |
POST, PATCH /v1/webhooks/endpoints…، وإعادة التشغيل والاختبارات | webhooks:write | إدارة نقاط النهاية (webhooks) |
POST /v1/join | لا شيء (رمز انضمام) | مجموعة بيانات اعتماد المشارك (رموز الانضمام) |
GET /v1/error-codes | لا شيء | الـ كتالوج رموز الأخطاء |
تستخدم الردود الناجحة 200 ما لم يُذكر خلاف ذلك. كلا مساري القراءة اللتين لا يحتويان على نطاق مسمى لا يزالان يتطلبان مفتاح مشروع صالحًا لم تنته صلاحيته ووصولًا إلى الخدمة.
المشاريع والغرف
Section titled “المشاريع والغرف”GET /v1/projects تُرجع فقط المشروع المرتبط بالمفتاح. يتم إنشاء المشروع في وحدة التحكم.
بالنسبة لـ POST /v1/rooms، أرسل:
{ "projectId": "00000000-0000-4000-8000-000000000001", "name": "Customer conversation", "maxParticipants": 4}projectId و name مطلوبة. maxParticipants هو اختياري، والقيمة الافتراضية هي 8، ويجب أن يكون عددًا صحيحًا لا يقل عن 2 ضمن الحد المسموح به في خطتك. قم بتعيين قيمة أصغر صراحةً إذا كانت خطتك لا تسمح بالقيمة الافتراضية. تتضمن الاستجابة الغرفة الجديدة id, projectId, name, maxParticipants, status
(open)، و createdAt.
GET /v1/rooms تسرد غرف المشروع الخاصة بالمفتاح. قم بإنهاء الغرفة باستخدام
POST /v1/rooms/{roomId}/end، بدون نص. يؤدي إنهاء الغرفة إلى منع عمليات الانضمام الجديدة و قطع الاتصال بالجلسات النشطة. كما يطلب إيقاف مهام التسجيل النشطة. يؤدي تكرار العملية على غرفة تم إنهاؤها إلى إرجاع 404؛ فهي ليست استجابة نجاح متجانسة. لا توجد حاليًا أي طريقة لإعادة تسمية الغرفة أو إعادة فتحها أو حذفها.
إصدار بيانات اعتماد المشاركين
Section titled “إصدار بيانات اعتماد المشاركين”POST /v1/rooms/{roomId}/tokens يقبل كائن JSON اختياري:
{ "canPublish": false }canPublish القيمة الافتراضية هي true. اضبطه على false لعميل الاستقبال فقط. يجب أن تكون الغرفة مفتوحة وتابعة لمشروع المفتاح. تحتوي الاستجابة على:
| الحقل | المعنى |
|---|---|
token | رمز مشارك حساس وقصير الأمد |
participantId | المعرف المخصص لعملية الانضمام هذه |
expiresIn | مدة صلاحية بيانات اعتماد الانضمام بالثواني، حاليًا 300 |
url | عنوان URL للإشارة للعميل |
iceServers | تكوين ICE، بما في ذلك بيانات اعتماد الترحيل المؤقتة |
اطلب بيانات اعتماد جديدة لكل عملية انضمام وإعادة اتصال. لا تستنتج نجاح القبول من إصدار الرمز المميز: حيث يتم التحقق من حالة الغرفة وسعتها والتفويض أيضًا عند الانضمام. انظر تدفق العميل الكامل.
مهام التسجيل والتنزيلات
Section titled “مهام التسجيل والتنزيلات”ابدأ بـ POST /v1/recordings و { "roomId": "ROOM_UUID" }. الـ 202
تتضمن الاستجابة تسجيلاً id و status: "queued"؛ وهذا لا يعني وجود ملف قابل للتنزيل بالفعل. يؤدي وجود تسجيل نشط مكرر لنفس الغرفة إلى إرجاع 409.
GET /v1/recordings تُرجع المهام المُصفّاة حسب المشروع، بما في ذلك id,
roomId, status، و tracks. تتضمن بيانات تعريف المسار id, kind,
source, participantId، و bytes. استخدم معرّفات التتبع التي ترجعها RTC.
أوقف مهمة في قائمة الانتظار أو مهمة تسجيل باستخدام
POST /v1/recordings/{recordingId}/stop، بدون نص. استطلع القائمة أو استخدم
recording.ready webhook لتحديد اكتمال العملية. المهمة التي تكون بالفعل قيد المعالجة، أو جاهزة، أو فاشلة ليست هدفًا نشطًا للإيقاف وتُرجع 404.
بالنسبة لمسار جاهز، انشر إلى /download المسار. الرد هو
{ "url": "TEMPORARY_DOWNLOAD_URL", "expiresIn": 300 }. احصل على عنوان URL المُرجع دون تغيير لتنزيل بايتات المرفق. عنوان URL نفسه يصرح بالوصول حتى انتهاء الصلاحية؛ تعامل معه كبيانات اعتماد. إنه لا رابط عام دائم. انظر أمن التسجيل وتنسيقاته.
الاستخدام
Section titled “الاستخدام”GET /v1/usage تُرجع:
| الحقل | المعنى |
|---|---|
participantSeconds | مجموع مدد جلسات المشاركين المكتملة ضمن النطاق |
sessions | عدد الاتصالات المكتملة ضمن النطاق |
period | all-time لهذه عدادات الأنشطة |
billingStatus | تشير إلى الفوترة المدارة مركزيًّا |
quotas | قرارات الاستحقاق الحالية لميزات RTC في مساحة العمل |
اقسم ثواني المشاركين على 60 لعرض دقائق المشاركين. لا تمثل عدادات النشاط هذه فاتورةً أو عددًا مباشرًا للمشاركين. يقوم مفتاح المشروع بتصفية النشاط الخاص بمشروعه، بينما تنتمي المخصصات إلى مساحة العمل المالكة. قد يتم تحديث استخدام الفوترة بشكل غير متزامن؛ استخدم نظام الفوترة المركزي للحصول على معلومات الاشتراك والفواتير.
الأخطاء
Section titled “الأخطاء”تُرجع الأخطاء JSON error سلسلة نصية و code، والتي يتم إرسالها أيضًا في
X-Error-Code رأس الرسالة. أرسل RTC-Version: 2026-11-01 لغلاف الخطأ المنظم. انظر الأخطاء بالنسبة للأشكال وكتالوج الكود،
حدود المعدل لـ 429، و إصدارات لما قد يتغير في إطار /v1. لا تعتمد على نص الرسالة بالضبط.
| الحالة | التحقق أو الإجراء |
|---|---|
400 | الحقول المطلوبة، أو معرّفات UUID، أو الحقول غير المعروفة، أو نطاقات الإدخال |
401 | بيانات اعتماد مفقودة، أو غير صالحة، أو تم إلغاؤها، أو منتهية الصلاحية |
403 | نطاق المفتاح، أو الوصول إلى المشروع، أو استحقاق الخطة، أو الحصة المخصصة |
404 | المورد غير موجود، أو خارج النطاق، أو ليس في الحالة المطلوبة |
409 | عملية متعارضة، مثل تسجيل نشط |
413 | يتجاوز حجم نص الطلب الحد الأقصى المسموح به |
429 | تحديد معدل الاستخدام؛ تراجع وامتثل Retry-After عند توفيرها |
5xx | فشل مؤقت في الخدمة؛ أعد محاولة القراءة مع التراجع وقم بمطابقة عمليات الكتابة |
لا تقم أبدًا بفحص موارد عميل آخر للتمييز بين رفض الوصول و الغياب. اتبع إرشادات استكشاف الأخطاء وإصلاحها.