REST API — أتمِت Telm من كودك الخاص

1ما يتيح لك الـ API فعله

يمنح REST API من Telm كودك الخاص المدى نفسه للوحة التحكم: مرّر أي نصّ عبر خطّ أنابيب مكافحة البريد المزعج، وابحث عن مستخدم Telegram قبل أن تدخله، واقرأ وغيّر إعدادات حماية مجموعة، وأدِر القواعد المخصّصة وقوائم السماح، واسحب سجل الإشراف والتحليلات، وسجّل webhooks للأحداث في الوقت الحقيقي.

يحوّل ذلك Telm من بوت يعيش داخل مجموعاتك إلى بنية تحتية يمكنك ربطها في أي مكان — نموذج تسجيل في موقع، أو بوت CRM، أو بوتات Telegram الخاصة بك، أو سكربت يضبط مئة مجموعة دفعةً واحدة.

• عنوان الأساس: api.telm.com/api/public/v1 — مسار مستقرّ ومُصدَّر (الـ v1 هو إصدار العقد).
• كل طلب واستجابة JSON عبر HTTPS.
• الوثائق التفاعلية ومواصفة OpenAPI 3.1 القابلة للقراءة آلياً على صفحة المطوّرين — حمّل المواصفة في Postman أو مولّد كود أو وكيل ذكاء اصطناعي لبناء تكامل في دقائق.
• تُعيد الاستدعاءات المُقاسة رؤوس X-Quota-Limit وX-Quota-Used وX-Quota-Reset على كل استجابة.

2كيف يتدفّق طلب عبر Telm

يعيش الـ API العام على بادئة مساره الخاصة، /api/public/، منفصلاً عن لوحة التحكم. يُصادَق كل استدعاء بمفتاح API بدل جلسة متصفّح، ويُفحَص مقابل خطتك وحصّتك، ويُشغَّل مقابل المحرّك الحيّ نفسه الذي يُشرِف على مجموعاتك، ويُعاد كـ JSON.

لأن الـ API يصل إلى المحرّك والبيانات نفسها للبوت، فأي شيء تراه أو تغيّره في لوحة التحكم يمكنك فعله أيضاً في الكود — وأي تغيير تجريه في الكود يظهر في لوحة التحكم فوراً.

• الطلبات عديمة الحالة: يحمل كل واحد مفتاحه الخاص ويقف بذاته.
• يتصرّف مفتاح نيابةً عن حسابك ولا يمكنه إلا مسّ المجموعات التي حسابك مشرف فيها.
• تصل نقطة نهاية فحص البريد المزعج إلى خطّ أنابيب القواعد الإنتاجي بالضبط، فيطابق حكم API ما سيفعله البوت في المجموعة.

3المصادقة بمفاتيح API

تُصادَق كل طلب بمفتاح API بصيغة tk_live_ متبوعاً بأحرف عشوائية — لا تسجيل دخول لوحة التحكم. تُنشئ المفاتيح في حسابك وترسل المفتاح في رأس Authorization كـ Bearer token، أو في رأس X-API-Key.

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

• أرسل المفتاح كـ Authorization: Bearer tk_live_your_key_here (يعمل رأس X-API-Key أيضاً).
• تحمل المفاتيح نطاق قراءة أو كتابة — قراءة لطلبات GET، وكتابة لأي شيء يغيّر البيانات. مفتاح للقراءة فقط لا يمكنه الإنشاء أو التحرير.
• يمكنك الاحتفاظ بحتى عشرة مفاتيح نشطة دفعةً واحدة، فتستطيع استخدام مفتاح منفصل لكل سكربت أو خدمة.
• مفتاح مفقود أو غير صالح يُعيد 401؛ ومفتاح دون النطاق المطلوب يُعيد 403 insufficient_scope.

4نقاط النهاية المتاحة

الـ API منظّم حول فحوص البريد المزعج والمستخدمين، وإدارة المجموعات، والخدمة الذاتية للحساب. نقطة نهاية فحص البريد المزعج الوحيدة مفتوحة لكل خطة؛ وبقية السطح جزء من Pro وBusiness.

• POST /spam/check — مرّر نصّاً واحداً عبر محرّك القواعد نفسه الذي يُشرِف على الحركة الحيّة (كل خطة). يمكن تفعيل فحص ذكاء اصطناعي اختياري على Pro وما فوق.
• POST /spam/check-batch — افحص حتى 20 نصّاً في استدعاء واحد، قواعد فقط (Pro+).
• POST /users/check — ابحث عن مستخدم Telegram: حالة CAS، وإشارات قرار البريد المزعج من Telm، والسمعة في مجموعاتك (Pro+).
• GET /groups وGET /groups/{id} — اسرد واقرأ مجموعاتك (Pro+).
• GET وPATCH /groups/{id}/settings — اقرأ وغيّر إعدادات حماية مجموعة (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — أدِر قواعد الإشراف المخصّصة (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — أدِر قائمة سماح المجموعة (Pro+).
• GET /groups/{id}/journal وGET /groups/{id}/analytics — اقرأ سجل الإشراف والتحليلات (Pro+).
• GET/POST/PATCH/DELETE /webhooks — أدِر webhooks الأحداث في الوقت الحقيقي (Pro+).
• GET /usage وGET /me — افحص حصّتك ومعلومات مفتاحك؛ هذه لا تستهلك حصّة أبداً (كل خطة).

5نقطة نهاية فحص البريد المزعج بالتفصيل

POST /spam/check قلب الـ API ونقطة النهاية الوحيدة التي يمكنك تجربتها على أي خطة. أرسل متن JSON بالنصّ المراد فحصه؛ تُعيد الاستجابة حكماً، ودرجة رقمية، وقيمة ثقة، وإجراءً موصى به يمكنك تطبيقه في منتجك الخاص.

يمكن أن يبلغ النصّ الواحد 10,000 حرف. على Pro وما فوق يمكنك اختيار فحص ذكاء اصطناعي للحالات الأصعب، مسحوب من بدل فحص ذكاء اصطناعي يومي منفصل. للحجم الكبير، تفحص نقطة النهاية الدُّفعية حتى 20 نصّاً في استدعاء واحد وتحتسب الحصّة لكل عنصر.

• استخدم الحكم والدرجة لتقرّر ما يفعله منتجك الخاص — حظر إرسال نموذج، أو تعليم عميل محتمل، أو إزالة رسالة تلقائياً في بوتك الخاص.
• نقطة النهاية الدُّفعية قواعد فقط؛ سُلّم الذكاء الاصطناعي متاح فقط على نقطة نهاية النصّ الواحد.
• متون الطلب محدودة (نحو 64 KB لفحص واحد، 256 KB لدُفعة)؛ المتون المفرطة الحجم تُعيد 413.

6الخطط وحدود المعدّل والحصص اليومية

الوصول مُقاس بطريقتين: حدّ معدّل لكل دقيقة (سقف اندفاع) وحصّة استدعاءات يومية يُعاد ضبطها منتصف ليل UTC. كلاهما يتناسب مع خطتك ويُحتسَب لكل حساب، مشترك عبر كل مفاتيحك. يمكنك تجربة نقطة نهاية فحص البريد المزعج الوحيدة على أي خطة، لكن تكاملاً حقيقياً يمسّ القواعد والإعدادات والفحوص الدُّفعية والـ webhooks يحتاج Pro أو أعلى.

• Free — 100 استدعاء/يوم، فحص البريد المزعج فقط.
• Basic — 1,000 استدعاء/يوم، فحص البريد المزعج فقط.
• Pro — 10,000 استدعاء/يوم، API كامل وwebhooks، إضافةً إلى بدل فحص ذكاء اصطناعي يومي.
• Business — 50,000 استدعاء/يوم، API كامل وwebhooks، بدل ذكاء اصطناعي أكبر.
• حدود المعدّل لكل دقيقة تتناسب أيضاً — الخطط الأعلى تحصل على سقف اندفاع أكبر بكثير.

7معالجة الأخطاء ورموز الحالة

يستخدم الـ API رموز حالة HTTP القياسية مع رمز خطأ قابل للقراءة آلياً في المتن. ابنِ عميلك ليقرأ هذه الرموز ويتراجع أو يطالب بترقية بدل إعادة المحاولة عمياء.

حين تتجاوز حصّتك اليومية، يُعيد استدعاء مُقاس 429 برمز daily_quota_exceeded، ورأس Retry-After، ومتن يسرد خطتك، والحدّ، وعدد المُستخدَم، ووقت إعادة الضبط، وتلميح ترقية. نقاط النهاية التي تحتاج خطة أعلى تُعيد 403 plan_required مع الخطة المطلوبة.

• 401 — مفتاح API مفقود أو غير صالح.
• 403 plan_required — تحتاج نقطة النهاية Pro أو أعلى.
• 403 insufficient_scope — ينقص المفتاح نطاق الكتابة لاستدعاء مُغيِّر.
• 429 daily_quota_exceeded أو rate_limit_exceeded — انتظر وقت إعادة الضبط أو رقِّ؛ احترم رأس Retry-After.
• اقرأ رؤوس الاستجابة X-Quota-* للبقاء متقدّماً على الحدّ.

8أفضل الممارسات لتكامل متين

بضع عادات تُبقي تكاملاً موثوقاً وآمناً وهو ينمو.

• خزّن المفاتيح في مدير أسرار، لا في كود من جانب العميل أو مستودع git؛ استخدم مفتاحاً منفصلاً لكل خدمة لتتمكّن من إلغاء واحد دون كسر الآخرين.
• راقب رؤوس X-Quota-Used وX-Quota-Limit (أو استطلِع GET /usage) وخفِّض وتيرة طلباتك قبل أن تبلغ الحدّ، لا بعده.
• عند 429، احترم Retry-After وتراجَع؛ عند 403 plan_required، أظهِر مطالبة ترقية بدل إعادة المحاولة.
• لردود فعل في الوقت الحقيقي، فضّل الـ webhooks على الاستطلاع — دع Telm يدفع الأحداث إليك.
• دوّر المفاتيح دورياً، وفوراً إن كان واحد قد تسرّب.

9سيناريوهات تكامل شائعة

يُستخدَم الـ API لأكثر بكثير من الإشراف على رسائل Telegram.

• التسجيل في موقع أو تطبيق: مرّر النصّ أو أسماء المستخدمين المُقدَّمة عبر POST /spam/check قبل قبول تسجيل أو تعليق.
• بوتات Telegram الخاصة بك: أعِد استخدام ذكاء Telm في بوت لا يديره Telm باستدعاء نقطة نهاية الفحص من معالجك.
• التهيئة الجماعية: اكتب سكربت القواعد وقوائم السماح والإعدادات نفسها عبر عشرات المجموعات بنقاط نهاية الإعدادات والقواعد.
• البيانات والتنبيه: سجّل webhooks لبثّ أحداث الإشراف إلى مستودع بيانات، أو لوحة تحكم، أو قناة تنبيه في الوقت الحقيقي.