واجهة برمجة تطبيقات الإدارة في TokenLab تضيف ميزة الاستعلام عن رصيد مساحة العمل

إن السماح لخط إنتاج آلي بالتوقف بسبب نفاد الرصيد هو أمر يمكن تجنبه. تتيح ميزة الاستعلام عن الرصيد في TokenLab Management API لمهام سير العمل المؤتمتة الحصول على إجمالي رصيد قابل للاستعلام باستخدام رمز إدارة مميز بدلاً من مفتاح الاستدلال.

يغطي هذا الدليل اتفاقية نقطة النهاية GET /v1/management/balance، ومتطلبات المصادقة، والتعامل مع العملات، وكيفية التحقق من مخططات الاستجابة مباشرةً بالرجوع إلى الوثائق الرسمية.

أهم النقاط الرئيسية

• تُرجع نقطة نهاية الرصيد في Management API (GET /v1/management/balance) رصيد مساحة العمل الحالي، وإجمالي عمليات الشحن، والإنفاق التراكمي للاستخدام.
• تتطلب المصادقة رمز إدارة مميزاً (mt-...) يتم إنشاؤه في Dashboard → API → Management Tokens، مما يفصل الفحوصات التشغيلية عن مفاتيح استدلال النماذج (sk-...).
• تُرجع جميع القيم المالية بالدولار الأمريكي (USD). يجب استخدام السلاسل النصية العشرية المسترجعة (balance_decimal، total_recharge_decimal، total_used_decimal) في الحسابات الدقيقة.
• تقترن نقطة النهاية بتقارير على مستوى المفاتيح مثل /v1/management/api-keys/{keyId}/usage و/v1/management/api-keys/{keyId}/billing.

رموز الإدارة المميزة مقابل مفاتيح واجهة برمجة التطبيقات لاستدلال النماذج

تؤدي رموز الإدارة المميزة ومفاتيح استدلال النماذج أدواراً تشغيلية مختلفة في TokenLab:

• مفاتيح واجهة برمجة التطبيقات لاستدلال النماذج (sk-...): تُستخدم لاستدعاء نقاط نهاية الاستدلال مثل POST /v1/chat/completions، وPOST /v1/responses، وAnthropic Messages الأصلية على POST /v1/messages، وGemini على /v1beta/models/.... تنفّذ هذه المفاتيح طلبات التوليد ولكنها لا تكشف البيانات المالية على مستوى المؤسسة.
• رموز الإدارة المميزة (mt-...): تقتصر على مسارات /v1/management/*. وتسمح للأنظمة الخلفية بفحص أرصدة مساحات العمل، وسرد أو تعديل مفاتيح واجهة برمجة التطبيقات، ومراقبة الاستخدام دون منح حق الوصول لتوليد النماذج.

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

اتفاقية اتصال نقطة نهاية الرصيد

أرسل طلب GET إلى https://api.tokenlab.sh/v1/management/balance مع المصادقة باستخدام رمز الإدارة المميز الخاص بك في ترويسة Authorization:

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -H "Authorization: Bearer mt-your-management-token"

مخطط الاستجابة

يُرجع الطلب الناجح كود 200 OK مع كائن organization_balance:

{
  "object": "organization_balance",
  "organization_id": "org_123",
  "balance": 42.5,
  "balance_decimal": "42.50",
  "total_recharge": 100,
  "total_recharge_decimal": "100",
  "total_used": 57.5,
  "total_used_decimal": "57.50"
}

حقول الاستجابة

• object (string): دائماً ما يكون organization_balance.
• organization_id (string): المؤسسة المرتبطة برمز الإدارة المميز الحالي.
• balance (number): رصيد مساحة العمل الحالي بالدولار الأمريكي كرقم فاصلة عائمة لأغراض العرض.
• balance_decimal (string): رصيد مساحة العمل الحالي الدقيق بالدولار الأمريكي منسقاً كسلسلة نصية عشرية للتسوية المالية.
• total_recharge (number): إجمالي مبلغ الشحن الناجح لمساحة العمل بالدولار الأمريكي.
• total_recharge_decimal (string): إجمالي مبلغ الشحن الناجح الدقيق لمساحة العمل بالدولار الأمريكي منسقاً كسلسلة نصية عشرية.
• total_used (number): إجمالي إنفاق الاستخدام لمساحة العمل بالدولار الأمريكي.
• total_used_decimal (string): إجمالي إنفاق الاستخدام الدقيق لمساحة العمل بالدولار الأمريكي منسقاً كسلسلة نصية عشرية.

الحقول المالية هي حصراً بالدولار الأمريكي (USD). عند تحليل الرصيد برمجياً لإجراء فحوصات الحدود أو تسوية دفاتر الأستاذ، قم بتحليل balance_decimal باستخدام مكتبة عشرية ذات دقة عشوائية بدلاً من الأنواع الأساسية للأرقام ذات الفاصلة العائمة لمنع فقدان الدقة.

تنفيذ فحوصات الرصيد

تشمل أنماط التكامل الشائعة ما يلي:

1. ضوابط ما قبل الدُفعات: قبل إرسال أعباء العمل الكبيرة—مثل التوليد بكميات ضخمة على نماذج مثل gpt-5.5 أو glm-5.2—استعلم عن /v1/management/balance. إذا انخفض balance_decimal عن التكلفة التقديرية للدُفعة، فقم بإيقاف قائمة انتظار المهام مؤقتاً.
2. تنبيهات انخفاض الرصيد: على الرغم من أنه يمكن تكوين إشعارات البريد الإلكتروني المؤتمتة تحت Console → Settings، يمكن لعملية cron مجدولة للمراقبة استطلاع نقطة النهاية دورياً وإطلاق إشعارات داخلية عبر Slack، أو PagerDuty، أو خطافات الويب (webhooks).
3. تسوية الفواتير: ادمج الرصيد المباشر لمساحة العمل مع سجلات استخدام المفاتيح الفردية (/v1/management/api-keys/{keyId}/usage) لتسوية نفقات التوكنات مقابل بنود الفواتير المسواة.

للاطلاع على المواصفات الكاملة لنقطة النهاية وطرق إدارة المفاتيح، راجع مرجع واجهة برمجة التطبيقات للحصول على رصيد مساحة العمل ونظرة عامة على Management API.