> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# واجهة برمجة تطبيقات الإدارة

> أدر رصيد المؤسسة ومفاتيح API واسترجع الاستخدام والفوترة على مستوى المفتاح باستخدام رمز إدارة.

## نظرة عامة

تتيح لك واجهة الإدارة استرجاع مجاميع رصيد المؤسسة وإدارة مفاتيح API الخاصة بالمؤسسة واسترجاع الاستخدام والفوترة لمفتاح محدد دون استخدام مفتاح استدلال عادي.

استخدم رمز إدارة من صفحة **Settings** في لوحة التحكم:

```bash theme={null}
Authorization: Bearer mt-your-management-token
```

<Warning>
  تختلف رموز الإدارة عن مفاتيح API الخاصة بالاستدلال. استخدم `mt-...` مع `/v1/management/*`، واستخدم `sk-...` مع واجهات الاستدلال مثل `/v1/responses`.
</Warning>

## الواجهات المتاحة

| Endpoint                                  | Method | الوصف                                                                          |
| ----------------------------------------- | ------ | ------------------------------------------------------------------------------ |
| `/v1/management/balance`                  | GET    | يجلب مجاميع الرصيد الحالية للمؤسسة                                             |
| `/v1/management/api-keys`                 | GET    | يعرض قائمة مفاتيح API الخاصة بالمستخدم في المؤسسة الحالية                      |
| `/v1/management/api-keys`                 | POST   | ينشئ مفتاح API جديدًا للمستخدم                                                 |
| `/v1/management/api-keys/{keyId}`         | PATCH  | يحدّث الاسم أو حد الاستخدام أو النماذج المسموح بها أو تاريخ الانتهاء أو الحالة |
| `/v1/management/api-keys/{keyId}/usage`   | GET    | يجلب تفاصيل الاستخدام المرقّمة على صفحات لمفتاح محدد                           |
| `/v1/management/api-keys/{keyId}/billing` | GET    | يجلب تفاصيل الفوترة المجمعة لمفتاح محدد                                        |

## عقد مرشحات الاستخدام

يدعم `GET /v1/management/api-keys/{keyId}/usage` معلمات الاستعلام التالية.

| المعامل         | النوع   | القيم الافتراضية / القيود                          | الوصف                                                                                              |
| --------------- | ------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `page`          | integer | الافتراضي `1`، الحد الأدنى `1`                     | رقم الصفحة بدءًا من 1                                                                              |
| `limit`         | integer | الافتراضي `50`، الحد الأدنى `1`، الحد الأقصى `100` | حجم الصفحة                                                                                         |
| `model`         | string  | أقصى طول `100`                                     | اسم النموذج المطلوب                                                                                |
| `modelVendor`   | string  | أقصى طول `100`                                     | مزود النموذج العام                                                                                 |
| `scene`         | enum    | -                                                  | `chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime` |
| `accessChannel` | enum    | -                                                  | `platform` أو `byok`                                                                               |
| `startDate`     | string  | -                                                  | حد سفلي شامل؛ يقبل RFC3339 مع منطقة زمنية أو `YYYY-MM-DD`                                          |
| `endDate`       | string  | -                                                  | حد علوي شامل؛ يقبل RFC3339 مع منطقة زمنية أو `YYYY-MM-DD`                                          |

إذا تم إرسال `startDate` و `endDate` معًا، فيجب أن يكون `startDate` أسبق من أو مساويًا لـ `endDate`.

## عقد جسم مفتاح API

### POST /v1/management/api-keys

| الحقل           | النوع          | القيم الافتراضية / القيود                      | الوصف                                                                                                                                |
| --------------- | -------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `name`          | string         | مطلوب، الافتراضي `Default Key`، الطول `1-50`   | اسم العرض؛ تتم إزالة المسافات من البداية والنهاية على الخادم                                                                         |
| `limitAmount`   | number \| null | الحد الأدنى `0`، الحد الأقصى للإدخال `1000000` | `null` أو الحذف = غير محدود، `0` = حصة صفرية. تُطبّع القيم الموجبة إلى حد مخزن لا يمكن أن يتجاوز ما يعادل `100000` دولارًا أمريكيًا. |
| `limitCurrency` | تعداد          | افتراضي `USD`                                  | USD فقط. إرسال `CNY` يُرجع `400 currency_retired`.                                                                                   |
| `models`        | string\[]      | الافتراضي `[]`                                 | قائمة اختيارية للنماذج المنطقية المسموح بها                                                                                          |
| `expiresAt`     | string \| null | تاريخ ووقت RFC3339                             | `null` يعني عدم وجود انتهاء                                                                                                          |

### PATCH /v1/management/api-keys/{keyId}

| الحقل           | النوع          | القيم الافتراضية / القيود                      | الوصف                                                                                                                       |
| --------------- | -------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `status`        | enum           | -                                              | `active`, `inactive`, `revoked`                                                                                             |
| `name`          | string         | الطول `1-50`                                   | اسم العرض بعد التحديث                                                                                                       |
| `limitAmount`   | number \| null | الحد الأدنى `0`، الحد الأقصى للإدخال `1000000` | `null` = غير محدود، `0` = حصة صفرية. تُطبّع القيم الموجبة إلى حد مخزن لا يمكن أن يتجاوز ما يعادل `100000` دولارًا أمريكيًا. |
| `limitCurrency` | تعداد          | افتراضي `USD`                                  | USD فقط. إرسال `CNY` يُرجع `400 currency_retired`.                                                                          |
| `models`        | string\[]      | -                                              | قائمة النماذج المنطقية المسموح بها بعد التحديث                                                                              |
| `expiresAt`     | string \| null | تاريخ ووقت RFC3339                             | `null` يزيل تاريخ الانتهاء                                                                                                  |

يجب أن يتضمن طلب PATCH حقلًا واحدًا على الأقل.

## عقد المبالغ المالية

## دلالات التقارير

* يشير `model` إلى النموذج المطلوب الذي طلبه المستدعي.
* يشير `modelVendor` إلى مزود النموذج العام، وليس المسار الفيزيائي المخفي.
* تمثل `scene` مشهد الطلب العام المشتق من الواجهة أو نوع المهمة.
* تعني `accessChannel=platform` أن الطلب تمت محاسبته عبر قناة منصة TokenLab.
* تعني `accessChannel=byok` أن الطلب استخدم مفتاح مزود upstream الخاص بك.

لا تكشف الاستجابات إلا حقول الفوترة والتقارير العامة. أما تفاصيل التوجيه الداخلي وبيانات المزود الفيزيائية فتبقى مخفية.

* قد تتضمن عناصر `/usage` الحقل `billing_transaction_id` بعد اكتمال تسوية الطلب الأساسي. استخدم `request_id` + `billing_transaction_id` للمطابقة على مستوى الطلب.

## ملاحظة حول ترقيم صفحات الفوترة

واجهة `/usage` تدعم ترقيم الصفحات. أما `/billing` فهي حاليًا واجهة تجميعية ولا تعيد بيانات ترقيم صفحات على نمط `page` / `limit`. وإذا كنت تحتاج إلى سجلات تفصيلية على مستوى الصفوف فاستعمل `/usage`.

## مثال سريع

ابدأ بالتحقق من رصيد المؤسسة باستخدام رمز الإدارة الحالي:

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
    -H "Authorization: Bearer mt-your-management-token"
  ```
</RequestExample>

ثم اعرض مفاتيح API المتاحة لرمز الإدارة نفسه:

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.tokenlab.sh/v1/management/api-keys" \
    -H "Authorization: Bearer mt-your-management-token"
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "key_abc123def456",
        "name": "Backend Worker",
        "key_prefix": "sk-abc123...",
        "status": "active",
        "limit_amount": 500.0,
        "limit_amount_decimal": "500",
        "used_amount": 148.25,
        "used_amount_decimal": "148.25",
        "models": ["gpt-4o-mini", "claude-3-7-sonnet"],
        "expires_at": "2026-04-30T00:00:00.000Z",
        "last_used_at": "2026-03-27T08:12:45.000Z",
        "created_at": "2026-03-01T10:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "totalPages": 1
    }
  }
  ```
</ResponseExample>

## الخطوات التالية

* [الحصول على رصيد المؤسسة](/ar/api-reference/management/get-balance)
* [عرض مفاتيح API](/ar/api-reference/management/list-api-keys)
* [إنشاء مفتاح API](/ar/api-reference/management/create-api-key)
* [تحديث مفتاح API](/ar/api-reference/management/update-api-key)
* [جلب استخدام مفتاح API](/ar/api-reference/management/get-api-key-usage)
* [جلب فوترة مفتاح API](/ar/api-reference/management/get-api-key-billing)