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

# إدارة رموز حساب منصة AceDataCloud (Account Token)

> Platform API guide - Ace Data Cloud

**رمز الحساب (Account Token، المعروف سابقًا باسم Platform Token)** هو "مفتاح على مستوى الحساب" للمطورين لإدارة موارد منصة AceDataCloud برمجيًا (طلبات الخدمات، بيانات اعتماد API، الطلبات، سجلات الاستدعاء، الرصيد، الملفات، إلخ). يشبه دوره رمز المستخدم بعد تسجيل الدخول من الواجهة الأمامية، ولا يملك وقت انتهاء افتراضيًا؛ يمكن للمستخدمين العاديين إدارة رموزهم فقط، بينما يمكن للمسؤولين المتميزين إدارة رموز حسابات أخرى وفقًا للصلاحيات.

يصل رمز الحساب إلى واجهات المنصة باستخدام الصلاحيات الحالية للحساب التابع له: تسري الصلاحيات الأساسية والصلاحيات الممنوحة مباشرةً وصلاحيات مجموعة المستخدمين التابع لها مجتمعةً؛ بعد الانضمام إلى مجموعة أو الإزالة منها، يُحكم وفقًا للصلاحيات الجديدة في الطلب التالي مباشرةً. لا يزال الوصول إلى موارد محددة مثل الطلبات والطلبات الشرائية يتطلب التحقق من الملكية. لا تنتهي صلاحية رموز الحساب افتراضيًا، لذا يُرجى استخدامها فقط في بيئات موثوقة وحفظها بعناية.

> ℹ️ تنتمي هذه الواجهة إلى **واجهة API لإدارة منصة AceDataCloud**، وبادئتها الموحدة هي `https://platform.acedata.cloud/api/v1/`. انظر فهرس الواجهات الكامل في [الحصول على قائمة وثائق منصة AceDataCloud](https://platform.acedata.cloud/documents/platform-document-list).

## رمز الحساب مقابل بيانات اعتماد API

هذان النوعان من المفاتيح هما الأكثر إرباكًا للمبتدئين، يُرجى التمييز بينهما أولًا:

| البعد | **رمز الحساب** (هذا المستند) | **بيانات اعتماد API (Credential)** |
| - | - | - |
| الاستخدام | استدعاء واجهات الإدارة من `https://platform.acedata.cloud/**` | استدعاء واجهات الأعمال من `https://api.acedata.cloud/**` (OpenAI، Midjourney، Suno، Veo، إلخ) |
| التنسيق | `platform-v1-` + 64 رقمًا سداسيًا عشريًا (76 حرفًا إجمالًا) | 32 رقمًا سداسيًا عشريًا |
| حساب واحد | عادةً 1–2 رمزًا | 1–N رمزًا لكل طلب خدمة |
| مدخل الإنشاء | [وحدة تحكم Account Token](https://platform.acedata.cloud/console/platform-tokens) | [إنشاء بيانات اعتماد API لمنصة AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) |
| شروط الإبطال | يُبطل فورًا بعد الحذف؛ يُبطل عند الانتهاء عندما لا تكون `expiration` فارغة | يمكن تعيين حد للحصة ووقت انتهاء وربط عنوان IP للمصدر |

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

***

## الإنشاء بنقرة واحدة في وحدة التحكم (موصى به)

1. سجّل الدخول إلى [https://platform.acedata.cloud](https://platform.acedata.cloud).
2. انتقل إلى الشريط الجانبي → «المطور» → «[Account Token](https://platform.acedata.cloud/console/platform-tokens)».
3. انقر زر «إنشاء» في أعلى اليسار، لتحصل فورًا على رمز `platform-v1-...`، **انقر زر النسخ واحفظه في مدير كلمات المرور**.

![وحدة تحكم Account Token](https://cdn.acedata.cloud/6g86oz.png)

> ⚠️ حاليًا، تُرجع استجابات الإنشاء والقائمة والتفاصيل جميعها النص الصريح للرمز. يُرجى التعامل مع الاستجابة بأكملها باعتبارها سرًا، ولا تكتبها في السجلات أو منصات التحليل أو التخزين الدائم للواجهة الأمامية؛ ويجب ألا يعتمد العميل أيضًا على استمرار إرجاع النص الصريح في القوائم على المدى الطويل.

***

## إنشاء رمز حساب باستخدام API

### نظرة عامة على الواجهة

| العنصر | المحتوى |
| - | - |
| الطريقة | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| المصادقة | ✅ أي رمز حساب موجود أو JWT لحالة تسجيل الدخول في المتصفح |
| Body | `application/json` (يمكن تمرير كائن فارغ `{}`) |

### توضيح المصادقة (مشكلة البيضة والدجاجة)

> كيف تحصل على الرمز الأول؟ الإجابة هي **عبر وحدة التحكم** — بعد تسجيل الدخول في المتصفح، تستخدم وحدة التحكم مصادقة JWT لاستدعاء `POST /platform-tokens/`، وتمنحك الرمز الأول.
> بعد ذلك، يمكنك استخدام أي رمز `platform-v1-...` موجود لإنشاء المزيد.

تنسيق رأس الطلب:

```http theme={null}
Authorization: Bearer ${PLATFORM_TOKEN}
Content-Type: application/json
```

### مثال الطلب

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/platform-tokens/' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{}'
```

### الاستجابة (HTTP 201)

```json theme={null}
{
  "id": "3264f1aa-cbe1-4e2c-a434-95adba4f8304",
  "token": "platform-v1-<REDACTED>",
  "expiration": null,
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "created_at": "2026-04-26T15:50:11.123456Z",
  "updated_at": "2026-04-26T15:50:11.123456Z",
  "used_at": null
}
```

### وصف الحقول

| الحقل | النوع | الوصف |
| - | - | - |
| `id` | UUID | المفتاح الأساسي للرمز، يُستخدم عند الحذف / الاستعلام عن التفاصيل |
| `token` | string | النص الصريح لرمز الحساب. التنسيق `platform-v1-` + 64 رقمًا سداسيًا عشريًا (76 حرفًا إجمالًا)، ويجب التعامل معه باعتباره سرًا |
| `expiration` | int \| null | وقت الانتهاء (طابع زمني بالثواني). تعني `null` أنه لم يتم تعيين وقت انتهاء |
| `user_id` | UUID | معرّف المستخدم التابع له. وهو أيضًا قيمة المعلمة `?user_id=` التي يجب تمريرها في جميع واجهات القوائم اللاحقة |
| `created_at` | datetime (ISO8601) | وقت الإنشاء |
| `updated_at` | datetime (ISO8601) | وقت التحديث |
| `used_at` | datetime \| null | آخر وقت استُخدم فيه للمصادقة. يكون `null` إذا لم يُستخدم من قبل، ويمكن استخدامه لاكتشاف "الرموز الخاملة" |

***

## الحصول على قائمة رموز الحساب

### نظرة عامة على الواجهة

| العنصر | المحتوى |
| - | - |
| الطريقة | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| المصادقة | ✅ يتطلب رمز حساب |

### معلمة الاستعلام الإلزامية

> ⚠️ **يجب تضمين `?user_id=<your_user_id>`**. السبب: تُجري واجهة القائمة تحققًا من الصلاحيات **لكل كائن** في نتائج الترقيم الصفحي، وعند عدم تضمين `user_id`، سيُرفض أول كائن لا ينتمي إليك وتُعاد `403 permission_denied`.

كيفية الحصول على `user_id`:

1. افتح [https://auth.acedata.cloud/user/profile](https://auth.acedata.cloud/user/profile) في المتصفح، حيث يظهر UUID الكامل في أعلى الصفحة.
2. أو أعد تعبئة حقل `user_id` مباشرةً من القيمة المرجعة بواسطة `POST /platform-tokens/`.

### معلمات الاستعلام

| المعلمة | مطلوب | النوع | الوصف |
| - | - | - | - |
| `user_id` | ✅ | UUID | معرّف المستخدم للحساب الحالي |
| `limit` | ❌ | int | عدد العناصر في الصفحة الواحدة، الافتراضي 10، والحد الأقصى 100 |
| `offset` | ❌ | int | الإزاحة |
| `ordering` | ❌ | string | حقل الترتيب، الافتراضي `-created_at` |

### مثال الطلب

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/platform-tokens/?user_id=89518d07-5560-4b05-92c1-667f3ddf6a4b&limit=5' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

### الاستجابة (HTTP 200)

```json theme={null}
{
  "count": 2,
  "items": [
    {
      "id": "51c575a2-801c-4211-bc47-711452a8c8c9",
      "token": "platform-v1-<REDACTED>",
      "expiration": null,
      "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
      "created_at": "2026-04-26T15:41:32.761705Z",
      "updated_at": "2026-04-26T15:41:32.761726Z",
      "used_at": null
    }
  ]
}
```

> تستخدم استجابة الترقيم لهذه الواجهة `count` + `items`. قد تستخدم واجهات المنصة الأخرى بنية مختلفة، لذا يُرجى الرجوع إلى الوثائق المقابلة والاستجابة الفعلية.

***

## الحصول على تفاصيل رمز الحساب

| البند | المحتوى |
| - | - |
| الطريقة | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**بدون شرطة مائلة في النهاية**） |
| المصادقة | ✅ يمكن فقط لمنشئ الرمز أو للمسؤول المتميز الوصول |

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/platform-tokens/51c575a2-801c-4211-bc47-711452a8c8c9' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

بنية الإرجاع مطابقة لعنصر القائمة، `HTTP 200`.

***

## حذف رمز الحساب

| البند | المحتوى |
| - | - |
| الطريقة | `DELETE` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**بدون شرطة مائلة في النهاية**） |
| المصادقة | ✅ يمكن فقط لمنشئ الرمز أو للمسؤول المتميز الحذف |

```shell theme={null}
curl -X DELETE 'https://platform.acedata.cloud/api/v1/platform-tokens/3264f1aa-cbe1-4e2c-a434-95adba4f8304' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

* عند النجاح يتم إرجاع `HTTP 204 No Content`، دون جسم استجابة.
* بعد الحذف يصبح الرمز **غير صالح فورًا**، وستتلقى جميع الخدمات التي تستخدمه حاليًا `401` مباشرةً.
* سيؤدي الاستعلام عن هذا `id` مرة أخرى إلى إرجاع `404`.

> ⚠️ الحذف غير قابل للعكس. إذا كنت تشك في تسرب الرمز، يمكنك **إنشاء رمز جديد أولاً، وتحويل جانب الأعمال إليه، ثم حذف الرمز القديم**.

***

## العمليات غير المدعومة

| العملية | HTTP | الوصف |
| - | - | - |
| تعديل `PATCH` | 405 | بعد إنشاء رمز الحساب، **لا يدعم تعديل أي حقل**. لاستخدامات مثل إعادة التسمية، احذفه ثم أعد إنشاؤه |
| استبدال `PUT` | 405 | كما سبق |

***

## مرجع سريع لرموز الخطأ

| HTTP | `code` | الأسباب الشائعة |
| - | - | - |
| 401 | `not_authenticated` | لم يتم إرسال ترويسة `Authorization`، أو تم حذف الرمز |
| 403 | `permission_denied` | لم يتم إرسال `?user_id=` مع واجهة القائمة، أو محاولة الوصول إلى تفاصيل رمز شخص آخر |
| 404 | `not_found` | `id` غير موجود أو تم حذفه |
| 405 | `method_not_allowed` | تم إرسال `PATCH`/`PUT` إلى واجهة التفاصيل |

تنسيق استجابة الخطأ موحد:

```json theme={null}
{
  "detail": "You do not have permission to perform this action.",
  "code": "permission_denied",
  "trace_id": "0a88956213edf6e62b71695ee2df0eff"
}
```

أثناء التحقيق، قدّم `trace_id` لخدمة العملاء أو ألصقه في تذكرة الدعم، لتحديد السجلات بسرعة.

***

## مثال كامل للكود

### Python

```python theme={null}
import os
import requests

BASE = "https://platform.acedata.cloud/api/v1"
PLATFORM_TOKEN = os.environ["PLATFORM_TOKEN"]
USER_ID = "89518d07-5560-4b05-92c1-667f3ddf6a4b"

headers = {
    "accept": "application/json",
    "authorization": f"Bearer {PLATFORM_TOKEN}",
    "content-type": "application/json",
}

# 1. إنشاء رمز جديد
created = requests.post(f"{BASE}/platform-tokens/", headers=headers, json={}).json()
print("رمز جديد: ", created["token"])
print("معرّف المستخدم: ", created["user_id"])

# 2. القائمة
listing = requests.get(
    f"{BASE}/platform-tokens/",
    headers=headers,
    params={"user_id": USER_ID, "limit": 50},
).json()
print(f"إجمالي {listing['count']} من الرموز")

# 3. الحذف (انتبه إلى عدم وجود شرطة مائلة في النهاية)
resp = requests.delete(f"{BASE}/platform-tokens/{created['id']}", headers=headers)
assert resp.status_code == 204, resp.text
```

### Node.js

```javascript theme={null}
const BASE = 'https://platform.acedata.cloud/api/v1'
const PLATFORM_TOKEN = process.env.PLATFORM_TOKEN
const USER_ID = '89518d07-5560-4b05-92c1-667f3ddf6a4b'

const headers = {
  accept: 'application/json',
  authorization: `Bearer ${PLATFORM_TOKEN}`,
  'content-type': 'application/json',
}

// إنشاء
const created = await fetch(`${BASE}/platform-tokens/`, {
  method: 'POST',
  headers,
  body: '{}',
}).then((r) => r.json())

// القائمة
const url = new URL(`${BASE}/platform-tokens/`)
url.searchParams.set('user_id', USER_ID)
const listing = await fetch(url, { headers }).then((r) => r.json())
console.log(`إجمالي ${listing.count} من الرموز`)

// الحذف (بدون شرطة مائلة في النهاية)
await fetch(`${BASE}/platform-tokens/${created.id}`, { method: 'DELETE', headers })
```

***

## الاستخدام في واجهات API الأخرى للمنصة

ضع `platform-v1-...` مباشرةً في ترويسة `Authorization: Bearer ...` لاستدعاء أي واجهة منصة تتطلب المصادقة:

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/applications/?user_id=89518d07-5560-4b05-92c1-667f3ddf6a4b' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

> يختلف **تمامًا** عن بيانات اعتماد API السداسية العشرية المكونة من 32 رقمًا المستخدمة في واجهات الأعمال `https://api.acedata.cloud/**` (مثل OpenAI وMidjourney وSuno وVeo وغيرها). لا تخلط بينهما — ستؤدي كتابة رمز الحساب في واجهة الأعمال إلى `401`، والعكس صحيح.

***

## الواجهات ذات الصلة

* [الحصول على قائمة طلبات خدمات منصة AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — استخدام رمز الحساب لمعرفة الخدمات التي تقدمت بطلبها
* [إنشاء بيانات اعتماد API لمنصة AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — استخدام رمز الحساب لإصدار بيانات اعتماد مكوّنة من 32 خانة لاستخدام API الخاص بالأعمال
* [الحصول على سجلات استدعاءات API لمنصة AceDataCloud](https://platform.acedata.cloud/documents/platform-usage-list) — لمراجعة الحسابات واستكشاف الأخطاء وإصلاحها
* [الحصول على قائمة طلبات منصة AceDataCloud](https://platform.acedata.cloud/documents/platform-order-list) — لمراجعة سجل إعادة الشحن


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.