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

لا توفر AceDataCloud حاليًا نقطة نهاية مجمّعة `/api/v1/distribution/`. تتكون بيانات مكافآت الإحالة من أربع مجموعات من الواجهات: الحالة، والسجل، والمستوى، والاستبدال؛ يرجى استدعاؤها وفقًا للموارد المطلوبة، وتجنب الاعتماد على استجابة ملخصة غير موجودة.

## التحضير

1. أنشئ واحفظ Account Token في [لوحة تحكم Account Token](https://platform.acedata.cloud/console/platform-tokens).
2. استخدم `GET /api/v1/platform-tokens/me/` للحصول على UUID للحساب الحالي.

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
export USER_ID='你的账户 UUID'
```

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

| الطريقة | URL | الغرض |
| - | - | - |
| `GET` | `/api/v1/distribution-statuses/?user_id=${USER_ID}` | إجمالي مبلغ الإحالة والمكافآت والمستوى للحساب الحالي |
| `POST` | `/api/v1/distribution-statuses/initialize/` | التهيئة الأولى أو تحديث مستوى الحساب الحالي؛ سيؤدي إلى كتابة البيانات |
| `GET` | `/api/v1/distribution-histories/?user_id=${USER_ID}` | سجل مكافآت الإحالة |
| `GET` | `/api/v1/distribution-levels/` | قواعد المستويات والنسب |
| `GET` | `/api/v1/distribution-redemptions/preview/` | معاينة المكافآت القابلة للاستبدال حاليًا؛ `amount` اختياري |
| `GET` | `/api/v1/distribution-redemptions/` | سجلات الاستبدال المكتملة |
| `POST` | `/api/v1/distribution-redemptions/redeem/` | تأكيد الاستبدال؛ يتطلب `idempotency_key` وينشئ استبدالًا غير قابل للتراجع |

## أمثلة على طلبات القراءة فقط

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/distribution-statuses/' \
  --data-urlencode "user_id=${USER_ID}" \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

curl --get 'https://platform.acedata.cloud/api/v1/distribution-histories/' \
  --data-urlencode "user_id=${USER_ID}" \
  --data-urlencode 'limit=100' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

curl 'https://platform.acedata.cloud/api/v1/distribution-levels/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

curl 'https://platform.acedata.cloud/api/v1/distribution-redemptions/preview/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

شكل الاستجابة الذي تم التحقق منه في بيئة الإنتاج هو:

* status وhistory وlevel وredemption list: `{count, items}`؛
* redemption preview: كائن واحد، يتضمن حقولًا مثل `eligible` و`reason` و`reward_amount` و`credit_amount` و`credits_per_usd` و`currency` و`package` و`global_application`.

قد تتوسع عناصر الحالة والسجل وفقًا لضوابط مخاطر الإحالة والتعويضات وقواعد المكافآت؛ ينبغي للعميل قراءتها عند الحاجة، وألا يعتمد على حقول مجمّعة مثل `referral_url` و`recent_orders` و`withdrawable_balance` غير المُعادة من الواجهة في الوثائق القديمة.

> كل من التهيئة والاستبدال عمليتا كتابة. يجب أن تستدعي نصوص الإنتاج واجهات القراءة فقط أولًا للتحقق من الحالة، وأن تحفظ `idempotency_key` فريدًا لطلب الاستبدال؛ لا تعِد المحاولة تلقائيًا لاستبدال ذي نتيجة غير معروفة.

## الصفحات ذات الصلة

* [الحصول على قائمة الطلبات](https://platform.acedata.cloud/documents/platform-order-list)
* [إدارة رموز الحساب](https://platform.acedata.cloud/documents/platform-token)

## طلبات تسعير الزيادة للمواقع الفرعية

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

على سبيل المثال، إذا كان السعر الأساسي 100 والسعر بعد الزيادة 120، وكان مدير الموقع هو المُحيل الوحيد أيضًا وكانت النسبة 10%، فإن مكافأة هذا الطلب هي 10 + 20 = 30. وإذا لم يكن مدير الموقع والمُحيل الشخص نفسه، يحصل كل منهما على المكافأة المقابلة له.

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


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