مفاتيح API — tnea_ وtnsr_¶

تستخدم NumerologyAPI عائلتين من مفاتيح API. كلاهما متشابهان في الشكل، ويُولَّدان بنفس صيغة الأمان المكونة من 80 حرفًا، ويتم المصادقة بهما عبر نفس ترويسة X-API-Key — لكنهما يُحاسبان بشكل مختلف ومخصصان لمنتجات مختلفة.

1. صيغة المفتاح والأمان¶

يبلغ طول كل مفتاح 80 حرفًا بالضبط:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• البادئة المكونة من 4 أحرف تحدد نوع المفتاح؛ أما الأحرف الـ 75 المتبقية فتُولَّد من مصدر عشوائي آمن تشفيريًا.
• تُخزَّن المفاتيح على الخادم بعد تجزئتها SHA-256. يُعرض نص المفتاح مرة واحدة فقط، عند وقت الإنشاء.
• إذا تعرض المفتاح للكشف في أي وقت، قم بتدويره فورًا من لوحة التحكم.

2. مفاتيح المنصة (tnea_)¶

مفاتيح المنصة هي المفاتيح القياسية لدمج NumerologyAPI في منتجك الخاص — المواقع الإلكترونية، وتطبيقات الجوال، والخدمات من جانب الخادم.

المصادقة¶

أرسل المفتاح في كل طلب عبر ترويسة X-API-Key:

curl --request GET \
  --url "https://api.numerologyapi.com/api/v1/life_path?birth_year=1990&birth_month=5&birth_day=15" \
  --header "x-api-key: tnea_YOUR_API_KEY"

الاحتساب¶

تُخصم استدعاءات /api/v1 القابلة للفوترة من محفظة ائتمانات المؤسسة (ادفع حسب الاستخدام). يمكنك شحن المحفظة في أي وقت من لوحة التحكم.

قاعدة القناة: يجب على مفاتيح المنصة ألا ترسل ترويسة X-Numora-Client. إرسالها يُرجع خطأ 403 — فهذه الترويسة محجوزة لقناة التطبيق المكتبي.

3. مفاتيح Numora Studio (tnsr_)¶

تتحقق مفاتيح Numora Studio من هوية تطبيق Numora Studio المكتبي (macOS/Windows) الذي يستخدمه الممارسون لإنشاء تقارير العملاء. وهي شقيقة لمفاتيح المنصة بنفس الصيغة تمامًا، لكنها تُفوتر مقابل حصة خطة Numora Studio الخاصة بالمؤسسة بدلاً من ائتمانات المنصة.

التوفير¶

يتم إنشاء مفتاح tnsr_ بإحدى الطريقتين:

• عبر تدفق تسجيل الدخول في التطبيق المكتبي (صفحة موافقة المتصفح تقوم بتوفير مفتاح تلقائيًا)، أو
• يدويًا من صفحة مفاتيح API في لوحة التحكم (/api-keys).

توقيع القناة (إلزامي)¶

يجب أن يتضمن كل استدعاء يتم بمفتاح tnsr_ ترويسة قناة التطبيق المكتبي:

الإنفاذ من جانب الخادم:

• مفتاح tnsr_ بدون X-Numora-Client → 403.
• مفتاح tnea_ مع X-Numora-Client → 403.

الاحتساب¶

• تُخصم استدعاءات /api/v1 القابلة للفوترة من حصة خطة Numora Studio الخاصة بالمؤسسة (تجمع مشترك واحد عبر جميع مفاتيح tnsr_ الخاصة بالمؤسسة).
• يوجد مفتاح تبديل التراجع إلى الائتمانات لكل مفتاح tnsr_: عندما تنفد حصة الخطة، يمكن للمفتاح التراجع إلى ائتمانات منصة المؤسسة (معطّل افتراضيًا).
• إذا نفدت الحصة ولم يتم تفعيل التراجع، تُرجع الاستدعاءات خطأ 429.

قفل الأجهزة (اختياري)¶

يمكن قفل مفتاح tnsr_ على الأجهزة المسجلة. عند تفعيل القفل، يجب أن يحمل كل طلب X-Numora-Device-Id مسجلًا لدى المؤسسة؛ ويُرفض أي جهاز غير مسجل بخطأ 403.

نقاط النهاية الحصرية للتطبيق المكتبي¶

بعض نقاط النهاية محجوزة لقناة التطبيق المكتبي وتُرجع خطأ 403 لمفاتيح tnea_:

• POST /api/v1/numora/report-bundle — تقرير عميل كامل في استدعاء واحد
• POST /api/v1/numora/order — تدفق شراء الخطة/الحصة داخل التطبيق
• POST /api/v1/numora/devices/register — تسجيل تثبيت مكتبي
• GET /api/v1/numora/studio-status — أرصدة التطبيق المكتبي وعدادات الحصة

نصيحة: تحمل الاستجابات القابلة للفوترة أيضًا ترويستي X-Remaining-Credits وX-Remaining-Tokens لتتمكن من تتبع الأرصدة الحية دون استدعاءات إضافية.

4. إدارة المفاتيح (لوحة التحكم)¶

صفحة مفاتيح API في لوحة التحكم (/api-keys) هي مركز التحكم لكلا نوعي المفاتيح.

الأدوار: يمكن لأدوار admin وdeveloper إنشاء المفاتيح وإدارتها. لا يمكن لدور finance إنشاء مفاتيح API للإنتاج. العمليات المالية (شراء الخطط، والتعبئة) مقصورة على admin وfinance.

مفاتيح متعددة: يمكن للمؤسسات الاحتفاظ بالعديد من المفاتيح من كلا النوعين — على سبيل المثال مفتاح tnsr_ واحد لكل ممارس أو لكل تثبيت مكتبي. الحصص مشتركة على مستوى المؤسسة، لذا لا "تتنافس" المفاتيح أبدًا على رصيد خاص بها.

5. أفضل الممارسات¶

• عامل المفاتيح ككلمات مرور. لا تدمجها أبدًا في كود من جانب العميل، أو في مستودعات عامة، أو في السجلات.
• استخدم متغيرات البيئة أو مدير أسرار في الخادم الخلفي.
• قم بالتدوير فورًا إذا تم اختراق مفتاح أو غادر أحد أعضاء الفريق.
• استخدم مفتاح tnsr_ واحدًا لكل تثبيت مكتبي لتبسيط إدارة الأجهزة والإبطال.
• فعّل قفل الأجهزة للمؤسسات ذات المتطلبات الأمنية العالية.
• راقب الاستخدام في لوحة التحكم لرصد الارتفاعات غير المتوقعة مبكرًا.

6. الأسئلة الشائعة¶

هل يمكن لمفتاح tnsr_ استدعاء نقاط نهاية المنصة العادية؟ نعم. تعمل مفاتيح Numora Studio على مصادقة كامل سطح /api/v1؛ وتُفوتر تلك الاستدعاءات مقابل حصة خطة Numora Studio.

هل يمكن لمفتاح tnea_ استدعاء نقاط نهاية /numora/* الحصرية للتطبيق المكتبي؟ لا. تُرجع نقاط النهاية الحصرية للتطبيق المكتبي خطأ 403 لمفاتيح المنصة.

لماذا أحصل على خطأ 403 عند الاستدعاء بمفتاح tnsr_ الخاص بي؟ على الأرجح ترويسة X-Numora-Client مفقودة أو أن معرف التطبيق غير مطابق. تأكد من أن كل طلب يتضمن X-Numora-Client: numora-studio/<version>.

لماذا أحصل على خطأ 403 بمفتاح tnea_ الخاص بي؟ يجب ألا تحمل مفاتيح المنصة ترويسة X-Numora-Client — قم بإزالتها.

ماذا يحدث عندما تنفد حصتي؟ تُرجع الاستدعاءات القابلة للفوترة خطأ 429 ما لم يكن التراجع عن الائتمانات مفعلًا على مفتاح tnsr_ الخاص بك (أو قمت بشحن محفظة المنصة الخاصة بمفاتيح tnea_).

ذات صلة¶

• البدء
• التسعير
• حلول المؤسسات