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

# توضيح واجهة برمجة تطبيقات URL القصير

> Short link generation 集成指南 - XHuoAPI

ستقدم هذه الوثيقة توضيحًا لواجهة برمجة تطبيقات URL القصير، والتي يمكن أن تحول URL الطويل إلى URL قصير.

## عملية التقديم

لاستخدام واجهة برمجة التطبيقات، يجب أولاً الذهاب إلى [واجهة برمجة تطبيقات URL القصير](https://api.xhuoapi.ai/documents/a2303356-6672-4eb8-9778-75f55c998fe9) للتقدم للحصول على الخدمة المناسبة، بعد الدخول إلى الصفحة، انقر على زر "Acquire"، كما هو موضح في الصورة:

![](https://cdn.xhuoapi.ai/q6ytrc.png)

إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، بعد تسجيل الدخول والتسجيل، سيتم العودة تلقائيًا إلى الصفحة الحالية.

عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا.

## الاستخدام الأساسي

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

<p>
  <img src="https://cdn.xhuoapi.ai/4ascb2.png" width="500" className="m-auto" />
</p>

يمكنك أن ترى أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:

* `accept`: الشكل الذي ترغب في تلقي استجابة النتائج به، هنا يتم ملؤه بـ `application/json`، أي بتنسيق JSON.
* `authorization`: مفتاح استدعاء واجهة برمجة التطبيقات، بعد التقديم يمكنك اختيارها مباشرة من القائمة المنسدلة.

بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:

* `content`: محتوى URL الذي ترغب في تقصيره.

بعد الاختيار، يمكنك أن تلاحظ أن الجانب الأيمن قد أنشأ أيضًا الكود المقابل، كما هو موضح في الصورة:

<p>
  <img src="https://cdn.xhuoapi.ai/r3uakb.png" width="500" className="m-auto" />
</p>

انقر على زر "Try" لإجراء الاختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية:

```json theme={null}
{
  "success": true,
  "data": {
    "url": "https://surl.id/1uHCs01xa5"
  }
}
```

تتضمن النتيجة العائدة عدة حقول، كما هو موضح أدناه:

* `success`: حالة نجاح المهمة هنا.
* `data`: تحتوي على URL المحول هنا.

يمكنك أن ترى أن
URL الطويل الأصلي `https://api.xhuoapi.ai/documents/a2303356-6672-4eb8-9778-75f55c998fe9` قد تم تحويله بنجاح إلى URL القصير `https://surl.id/1uHCs01xa5`.

بالإضافة إلى ذلك، إذا كنت ترغب في إنشاء كود التكامل المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي:

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/shorturl' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "content": "https://api.xhuoapi.ai/documents/a2303356-6672-4eb8-9778-75f55c998fe9"
}'
```

كود التكامل بلغة Python كما يلي:

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/shorturl"

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

payload = {
    "content": "https://api.xhuoapi.ai/documents/a2303356-6672-4eb8-9778-75f55c998fe9"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

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

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات المناسبة. على سبيل المثال:

* `400 token_mismatched`: طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
* `400 api_not_implemented`: طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
* `401 invalid_token`: غير مصرح به، رمز تفويض غير صالح أو مفقود.
* `429 too_many_requests`: عدد كبير جدًا من الطلبات، لقد تجاوزت الحد الأقصى لمعدل الطلبات.
* `500 api_error`: خطأ داخلي في الخادم، حدث خطأ ما على الخادم.

### مثال على استجابة الخطأ

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## الخاتمة

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