> ## 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

> Platform API guide - Ace Data Cloud

يمثل «الطلب (Application)» علاقة اشتراك الحساب الحالي بخدمة معينة — يجب تقديم طلب أولًا، ثم يمكن إنشاء بيانات اعتماد API لهذا الطلب واستدعاء واجهات الأعمال. عند تقديم طلب لخدمة لأول مرة، سيحصل Application على قيمة `free_amount` المُهيأة حاليًا للخدمة؛ وقد تكون هذه القيمة 0.

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

## عملية التكامل الكاملة

عادةً ما يمر المستخدمون الجدد بهذه الخطوات الخمس من التسجيل حتى تشغيل أول واجهة أعمال:

1. **الحصول على رمز الحساب** → [إدارة رموز حساب منصة AceDataCloud](https://platform.acedata.cloud/documents/platform-token)
2. **اختيار خدمة** → [الحصول على قائمة خدمات منصة AceDataCloud](https://platform.acedata.cloud/documents/platform-service-list)
3. **إنشاء طلب** (هذه الوثيقة) → الحصول على الحصة الأولية وفقًا لإعدادات الخدمة
4. **إنشاء بيانات اعتماد API** → [إنشاء بيانات اعتماد API لمنصة AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create)
5. **استدعاء واجهة الأعمال** → استخدام Token ذي 32 بتًا الذي تم الحصول عليه لاستدعاء `https://api.acedata.cloud/<path>`

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

| البند | المحتوى |
| - | - |
| الطريقة | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/applications/` |
| المصادقة | ✅ يتطلب رمز الحساب |
| Content-Type | `application/json` |

## توضيح المصادقة (كيفية الحصول على رمز الحساب)

رأس الطلب:

```http theme={null}
Authorization: Bearer ${PLATFORM_TOKEN}
```

رمز الحساب (Account Token) هو «مفتاح على مستوى الحساب» يستخدمه المطور لإدارة موارد حسابه عبر API. طرق الحصول عليه:

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

> ⚠️ رمز الحساب حساس بقدر كلمة المرور، ويُمنع كتابته في كود الواجهة الأمامية أو المستودعات العامة. عند تسريبه، احذفه فورًا من لوحة التحكم وأنشئ واحدًا جديدًا.

## جسم الطلب

| المعامل | النوع | مطلوب | الوصف |
| - | - | - | - |
| `service_id` | UUID | ✅ | معرّف الخدمة المطلوب تقديم طلب لها. يمكن الحصول عليه من `items[].id` في [قائمة الخدمات](https://platform.acedata.cloud/documents/platform-service-list) |

## أمثلة الطلبات

### cURL

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/applications/' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{"service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452"}'
```

### Python

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

PLATFORM_TOKEN = os.environ["PLATFORM_TOKEN"]
SERVICE_ID = "38ecf158-36f2-42f2-8e7f-6786cdfc2452"

resp = requests.post(
    "https://platform.acedata.cloud/api/v1/applications/",
    headers={
        "accept": "application/json",
        "authorization": f"Bearer {PLATFORM_TOKEN}",
        "content-type": "application/json",
    },
    json={"service_id": SERVICE_ID},
    timeout=10,
)

if resp.status_code == 201:
    app = resp.json()
    print(f"申请成功！application_id={app['id']}")
    print(f"初始额度：{app['remaining_amount']} {app.get('service', {}).get('unit', '')}")
elif resp.status_code == 400 and resp.json().get("code") == "duplication":
    print("⚠️ 已经申请过此服务，请到 /applications/ 列表里找到现成的 application_id")
else:
    print(f"申请失败：HTTP {resp.status_code} - {resp.text}")
```

### Node.js

```javascript theme={null}
const PLATFORM_TOKEN = process.env.PLATFORM_TOKEN
const SERVICE_ID = '38ecf158-36f2-42f2-8e7f-6786cdfc2452'

const resp = await fetch('https://platform.acedata.cloud/api/v1/applications/', {
  method: 'POST',
  headers: {
    accept: 'application/json',
    authorization: `Bearer ${PLATFORM_TOKEN}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ service_id: SERVICE_ID }),
})

if (resp.status === 201) {
  const app = await resp.json()
  console.log('application_id =', app.id)
} else {
  console.error(await resp.text())
}
```

## أمثلة الاستجابات

### النجاح (HTTP 201)

```json theme={null}
{
  "id": "82f57141-2323-4453-8730-60f7d833a2da",
  "service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452",
  "remaining_amount": 1.0,
  "used_amount": 0.0,
  "paid": false,
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "disabled": false,
  "allow_consume_global": false,
  "scope": "Individual",
  "type": "Usage",
  "expired_at": null,
  "tags": null,
  "metadata": null,
  "client_ip": null,
  "client_fingerprint": null,
  "created_at": "2026-04-26T07:52:27.462400Z",
  "updated_at": "2026-04-26T07:52:27.462400Z"
}
```

يتطابق هيكل الحقول المُعادة مع [الحصول على تفاصيل طلب خدمة منصة AceDataCloud](https://platform.acedata.cloud/documents/platform-application-detail).

### تم تقديم طلب مسبقًا (HTTP 400)

```json theme={null}
{
  "detail": "Item already exists.",
  "code": "duplication",
  "trace_id": "1a87524f8cbba0b790b2951e2e43117e"
}
```

هذا قيد صارم في التصميم: **يمكن لكل مستخدم امتلاك Application واحد فقط لكل خدمة**. عند وجوده مسبقًا، ابحث عن الطلب الحالي عبر [الحصول على قائمة طلبات خدمات منصة AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list).

### الخدمة غير موجودة (HTTP 404)

```json theme={null}
{
  "detail": "Service not found.",
  "code": "not_found",
  "trace_id": "..."
}
```

### الخدمة تتطلب مراجعة (HTTP 403)

```json theme={null}
{
  "detail": "This service requires manual verification.",
  "code": "need_verify",
  "trace_id": "..."
}
```

إذا كانت قيمة `need_verify=true` للخدمة (يمكن رؤية هذا الحقل في قائمة الخدمات)، فيجب اتباع عملية التذكرة لطلب الإدراج في القائمة البيضاء.

## معالجة الأخطاء

| HTTP | الرمز | المعنى |
| - | - | - |
| 400 | `duplication` | تم طلب هذه الخدمة بالفعل بواسطة الحساب الحالي |
| 400 | `invalid` | `service_id` مفقود أو بتنسيق خاطئ |
| 401 | `not_authenticated` | رمز الحساب مفقود أو تم حذف الرمز |
| 403 | `need_verify` | تتطلب الخدمة مراجعة، يُرجى اتباع عملية التذاكر |
| 404 | `not_found` | الخدمة غير موجودة أو تم إيقافها |

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

```json theme={null}
{
  "detail": "...",
  "code": "...",
  "trace_id": "..."
}
```

## نصائح عملية

* **الإنشاء نفسه لا يخصم أي رسوم**: عند الإنشاء لأول مرة، يتم تعيين الحصة الأولية وفقًا لقيمة `free_amount` الحالية للخدمة؛ قد تكون هذه القيمة 0، ولا يضمن إنشاء Application من النوع نفسه مرة أخرى منحًا مجانيًا متكررًا.
* **ما إذا كان الدفع مطلوبًا يعتمد على حقل `paid`**: عند الطلب مباشرةً يكون `paid=false`، ويتحول إلى `true` بعد استدعاء [إنشاء طلب شحن رصيد لمنصة AceDataCloud](https://platform.acedata.cloud/documents/platform-order-create) وإتمام الدفع.
* **`disabled=true` يعني أنه تم تعطيله مؤقتًا**—مثلًا بسبب تفعيل التحكم بالمخاطر، أو المتأخرات، وما إلى ذلك. عند تعطيله، ستعيد واجهات الأعمال `403`.
* **لا تُنشئ الطلبات بتزامن غير محدود**: احصل أولًا على `service_id` المستهدف من قائمة الخدمات المرقمة بالصفحات، ثم قدّم الطلبات عنصرًا عنصرًا حسب احتياجات العمل؛ عند مواجهة `duplication`، أعد استخدام Application الموجود.

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

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


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