تُصادَق كل طلبات Telm API بـمفتاح API يبدأ بـ tk_live_ — لا بتسجيل دخولك إلى لوحة التحكم أبدًا. أنشئ مفتاحًا في حسابك، وأرسله في ترويسة Authorization كرمز Bearer، فيتصرف نيابةً عن حسابك على المجموعات التي أنت مشرف فيها. إن تسرّب مفتاح، أبطِله في لوحة التحكم وأصدِر جديدًا.
1كيف تعمل مفاتيح API
لا يستخدم Telm REST API جلسة متصفحك. بل يحمل كل طلب مفتاح API — سلسلة سرية طويلة تبدأ بالبادئة tk_live_ متبوعةً بأحرف عشوائية. يعرّف المفتاح حسابك ويصرّح بالاستدعاء.
تولّد المفاتيح من حسابك ويمكنك الاحتفاظ بعدة منها في آنٍ واحد (مثلًا واحد لكل سكربت أو خدمة). يُعرَض السر الكامل مرة واحدة فقط، وقت الإنشاء؛ وبعدها تدرِج لوحة التحكم المفتاح ببادئته القصيرة (tk_live_ مع الأحرف الأولى) كي تتعرف عليه، ولا يُحتفَظ بالقيمة الكاملة بعد ذلك أبدًا.
- يبدو المفتاح كـ tk_live_ متبوعًا بسلسلة عشوائية طويلة.
- تُنشَأ المفاتيح وتُدار في لوحة التحكم.
- يُعرَض السر الكامل مرة واحدة فقط — انسخه فورًا وخزّنه في مكان آمن.
- عامِل المفتاح كأنه كلمة مرور: أي شخص يملكه يمكنه استدعاء API باسمك.
2إرسال المفتاح مع كل طلب
مرّر المفتاح في ترويسة Authorization باستخدام مخطط Bearer. قيمة الترويسة هي كلمة Bearer، ثم مسافة، ثم مفتاحك — مثلًا Authorization: Bearer tk_live_your_key_here.
للعملاء الذين لا يستطيعون ضبط ترويسة Authorization بسهولة، يقبل API أيضًا المفتاح في ترويسة X-API-Key. إن وُجِدت الاثنتان، تفوز ترويسة Authorization. الطلبات عبر أي شيء غير HTTPS غير مقبولة في الإنتاج.
- المفضّل: أرسل Authorization: Bearer tk_live_...
- البديل: أرسل المفتاح في ترويسة X-API-Key بدلًا من ذلك.
- عنوان القاعدة لكل استدعاء هو api.telm.com/api/public/v1.
- راجع قائمة الإندبوينت الكاملة والمخططات في صفحة المطورين.
3ما الذي يمكن لمفتاح الوصول إليه
يتصرف المفتاح حصريًا نيابةً عن حسابك. يمكنه فقط قراءة أو تغيير المجموعات التي يكون فيها حسابك مشرفًا — طلب يستهدف أي مجموعة أخرى يعيد 404، فلا يكشف API أبدًا حتى عن وجود مجموعة لا يمكنك إدارتها.
يعتمد الوصول أيضًا على خطة المجموعة المستهدَفة. إندبوينت فحص البريد المزعج مفتوح لكل خطة ضمن الحصة اليومية، بينما API الكامل (القواعد والإعدادات والقائمة البيضاء والسجل والتحليلات والفحوص الدُّفعية والويب-هوك) متاح على خطة Pro فأعلى على المجموعة المعنية.
- يمكن للمفتاح أن يمسّ فقط المجموعات التي أنت مشرف فيها.
- الطلبات إلى مجموعات لا تديرها تعيد 404، لا 403.
- الحصة اليومية مشتركة عبر كل مفاتيحك، تُحسَب لكل حساب.
4إبطال المفاتيح وتدويرها
إن انكشف مفتاح — أُودِع في مستودع، أو لُصِق في محادثة، أو تسرّب بأي طريقة أخرى — أبطِله فورًا من لوحة التحكم. يسري الإبطال على الفور: يتوقف المفتاح المُبطَل عن العمل خلال ثوانٍ، لا بعد تأخير.
ولأن الحصة اليومية مشتركة لكل حساب، لا يعيد إبطال مفتاح واحد ضبط عدّاد استخدامك. تدوير المفاتيح بانتظام نظافة جيدة: أنشئ المفتاح الجديد، وانشره إلى خدمتك، وأكّد أنه يعمل، ثم أبطِل القديم كي لا يكون هناك توقف.
- أبطِل مفتاحًا من لوحة التحكم؛ يتوقف عن العمل فورًا تقريبًا.
- أنشئ البديل أولًا، وانشره، ثم أبطِل المفتاح القديم لتدوير بلا توقف.
- إبطال مفتاح لا يعيد ضبط حصتك اليومية — تلك تُعاد عند منتصف الليل UTC.
5أخطاء المصادقة
مفتاح مفقود أو مشوّه أو مُبطَل يعيد 401 مع رمز خطأ مقروء آليًا ورسالة مقروءة بشريًا. إن بدأت طلباتك فجأة تفشل بـ 401، فتحقّق من أن المفتاح لم يُبطَل ومن أن ترويسة Authorization مكتوبة تمامًا كـ Bearer مع مسافة مع المفتاح.
مفتاح صالح يستهدف مجموعة لا تديرها يعيد 404. مفتاح صالح على خطة دون Pro يستدعي إندبوينت خاصًا بـ Pro يعيد 403 مع رمز plan_required وتلميح ترقية.
- 401 — المفتاح مفقود أو مشوّه أو مُبطَل.
- 404 — المجموعة المستهدَفة غير موجودة أو أنت لست مشرفها.
- 403 plan_required — يحتاج الإندبوينت إلى Pro فأعلى على تلك المجموعة.