مفاتيح API
استخدم مفتاح API شخصيًا لاستدعاء واجهة REST من نصوصك البرمجية.
إنشاء مفتاح وإلغاؤه
سجّل الدخول إلى NinjaBuy وافتح الحساب ← الإحالات ← مفاتيح API لإنشاء مفاتيح مُسمّاة وعرضها وإلغائها. يبدأ المفتاح الكامل بـ nb_ ولا يُعرض إلا مرة واحدة. استخدم نسخ المفتاح لحفظه في مكان آمن قبل إغلاق الرسالة.
لا تنتهي صلاحية المفتاح أبدًا إلا إذا اخترت له مدة عند إنشائه: 30 يومًا أو 90 يومًا أو سنة واحدة. ويسري الإلغاء أو انتهاء تلك المدة بدءًا من الطلب التالي، ويختفي المفتاح المنتهي من القائمة.
لا نخزّن سوى تجزئة SHA-256 للمفتاح.
استخدام مفتاح
مرّر مفتاحك إلى نصك البرمجي باسم NINJABUY_API_KEY وأرسله في الترويسة Authorization:
curl -sS https://www.ninjabuy.com/api/v1/links \
-H "Authorization: Bearer $NINJABUY_API_KEY" \
-H "Content-Type: application/json" \
--data '{"links":["https://weidian.com/item.html?itemID=7581746714"]}'تعمل الترويسة نفسها على كل مسارات REST التي تتطلب مصادقة: الروابط، والبحث، وعمليات الرفع والجداول، والمهام. أما مستند OpenAPI فلا يحتاج إلى مصادقة.
الصلاحيات والحدود
يحصل كل مفتاح على الصلاحيات الثلاث جميعها. ولا يوجد خيار لتحديد النطاق.
| الصلاحية | المسارات |
|---|---|
links:create | POST /api/v1/links, POST /api/v1/uploads, POST /api/v1/sheets |
jobs:read | GET /api/v1/jobs/{id} |
search:read | GET /api/v1/search |
تتشارك المفاتيح وطلبات REST عبر OAuth نافذتَي الإنشاء والبحث الخاصتين بالحساب. كما يتشارك إنشاء الروابط عبر MCP نافذة الإنشاء أيضًا. راجع حدود معدل الطلبات.
لا يمكن للمفتاح تسجيل الدخول أو فتح جلسة أو استدعاء MCP أو واجهات الحساب. استخدم OAuth لتطبيق يعمل نيابةً عن عملاء NinjaBuy آخرين أو لعميل MCP.
الإخفاقات
يُعيد المفتاح غير الصالح أو المنتهي أو المُلغى مشكلة 401 نفسها التي يُعيدها رمز OAuth غير الصالح. ويُعيد تعطّل تخزين المفاتيح 503 مع Retry-After. راجع الأخطاء.