# وكلاء الذكاء الاصطناعي (/ar/integrate/ai-agents)

كل صفحة في الموقع متاحة كـ markdown، بالإضافة لملف كامل للموقع ومواصفة OpenAPI. وجّه مساعد الأكواد بتاعك للمصادر دي بدل ما يقرأ الـ HTML.

لو بتبني بمساعد أكواد، إداله مصادر الـ markdown بدل الصفحات المعروضة. كل صفحة توثيق بتقدّم markdown نضيف على رابط متوقّع، والموقع كله متاح كملف واحد. من غير قراءة HTML ولا scraping.

## هات صفحة واحدة كـ markdown [#هات-صفحة-واحدة-كـ-markdown]

كل صفحة فيها زرار **Copy Markdown** تحت عنوانها. بينسخ الصفحة كلها كـ markdown، جاهزة تتلزق في محادثة مع مساعدك. وقائمة **Open** اللي جنبه فيها رابط ملف الـ markdown الخام، وتقدر تفتح الصفحة كـ prompt في ChatGPT أو Claude.

الأدوات اللي بتجيب الصفحات بنفسها مش محتاجة الزراير. ضيف `.md` أو `.mdx` لآخر أي رابط توثيق:

```bash
curl https://docs.xpay.app/ar/integrate/idempotency.md
```

ده بيشتغل على كل صفحة في اللغتين. غيّر البادئة `ar` لـ `en` تجيب النسخة الإنجليزية. وإرسال `Accept: text/markdown` للرابط العادي بيرجّع نفس المحتوى، وكل صفحة شايلة وسم `<link rel="alternate" type="text/markdown">` في الـ head بتاعها، فالوكيل يقدر يكتشف رابط الـ markdown لوحده.

## هات الموقع كله [#هات-الموقع-كله]

تلات ملفات بيغطّوا سطح التوثيق كامل.

| الملف                                                   | بيحتوي على إيه                                                                                                                  |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| [`/llms.txt`](https://docs.xpay.app/llms.txt)           | فهرس بكل صفحة مع عنوانها ووصفها ورابطها. ابدأ من هنا.                                                                           |
| [`/llms-full.txt`](https://docs.xpay.app/llms-full.txt) | الأدلة ومرجع الـ SDK في ملف markdown واحد. مرجع الـ API مش متضمّن فيه: استخدم `/openapi.json` أو الـ `.md` بتاع صفحة واحدة لده. |
| [`/openapi.json`](https://docs.xpay.app/openapi.json)   | مواصفة الـ API القابلة للقراءة آليًا: كل endpoint وobject وحقل وenum.                                                           |

صفحات مرجع الـ API مولّدة من مواصفة OpenAPI، والـ markdown بتاعها شايل نفس المعاملات وأجسام الطلبات وحقول الردود اللي بتظهر في الصفحات المعروضة. الحقل اللي نوعه مورد رئيسي (Charge أو Refund أو Price) بيظهر كرابط لصفحة الـ object بتاعه، وأي شكل متداخل تاني بيتفرد في مكانه.

## تستخدم أنهي مصدر [#تستخدم-أنهي-مصدر]

اختار حسب حجم السياق اللي أداتك تقدر تشيله.

* **بتبني تكامل**: حمّل `/llms-full.txt` مرة واحدة وسيب المساعد يبحث فيه.
* **بترد على سؤال واحد**: هات الصفحة لوحدها بـ `.md`، واستخدم `/llms.txt` عشان تلاقي الرابط الصح.
* **بتولّد عميل أو بتتحقق من الطلبات**: استخدم `/openapi.json` على طول. هي نفس المواصفة اللي مرجع الـ API بيتعرض منها، فعمرها ما بتختلف عن الصفحات دي.

## وبعد كده [#وبعد-كده]

<Cards>
  <Card href="/integrate/object-model" title="نموذج الكائنات" icon="<Compass />" description="العلاقة بين Checkout Sessions وPayment Intents وCharges وRefunds." />

  <Card href="/api-reference" title="مرجع الـ API" icon="<Braces />" description="كل endpoint وobject، مولّد من مواصفة OpenAPI." />

  <Card href="/integrate/webhooks/event-reference" title="مرجع الأحداث" icon="<Webhook />" description="كل حدث webhook، وإمتى بيحصل، والكائن اللي بيشيله." />

  <Card href="/integrate/idempotency" title="عدم التكرار" icon="<FileText />" description="أعد محاولة طلبات الكتابة بأمان بـ Idempotency-Key." />
</Cards>