# التكامل مع الذكاء الاصطناعي

> ادمج 2328.io في تطبيقك في دقائق باستخدام مساعدي الذكاء الاصطناعي مثل Claude وChatGPT وCursor وGitHub Copilot.

تم تصميم توثيق 2328.io ليكون **متوافقًا مع نماذج LLM**. يمكنك تسليم مرجع API بالكامل لأي مساعد ذكاء اصطناعي حديث وجعله ينشئ تكاملًا عاملًا بلغة من اختيارك — PHP، Node.js، Python، Go، Rust — في دقائق بدلًا من ساعات.

تشرح هذه الصفحة كيفية القيام بذلك بكفاءة.

## لماذا تستخدم الذكاء الاصطناعي للتكامل

- **تأهيل أسرع** — تجاوز الكود النمطي وانتقل مباشرة إلى منطق العمل
- **توقيع صحيح** — ينتج الذكاء الاصطناعي بشكل موثوق توقيع HMAC-SHA256 بأي لغة
- **معالجات webhook** — ينشئ التحقق من التوقيع ومعالجات idempotent جاهزة للاستخدام
- **محدّثة** — يُعاد إنشاء `llms-full.txt` لدينا عند كل تحديث للوثائق، لذا تحصل دائمًا على المخططات الحالية

## وثائق قابلة للقراءة آليًا

ننشر ثلاث نقاط نهاية تتبع معيار [llmstxt.org](https://llmstxt.org):

| نقطة النهاية | الغرض |
|----------|---------|
| [`/llms.txt`](https://doc.2328.io/llms.txt) | فهرس قصير لجميع الوثائق مع الروابط |
| [`/llms-full.txt`](https://doc.2328.io/llms-full.txt) | الوثائق الكاملة في ملف واحد — الصقها في محادثة الذكاء الاصطناعي لديك |
| [`/md/{locale}/{slug}`](https://doc.2328.io/md/en/payments) | أي صفحة كملف Markdown خام |

كل صفحة HTML تكشف أيضًا عن `<link rel="alternate" type="text/markdown">` يشير إلى نسختها بصيغة Markdown، حتى تكتشفها زواحف الذكاء الاصطناعي تلقائيًا.

## توثيق خادم MCP

يمكن للوكلاء الذكاء الاصطناعي الذين يدعمون [Model Context Protocol](https://modelcontextprotocol.io) الاتصال مباشرة بـ:

```
https://doc.2328.io/mcp
```

النقطة النهاية عامة، للقراءة فقط، ولا تتطلب مفتاح API للتاجر. وهي تخدم معرفات التوثيق فقط؛ لا يمكنها فحص الأرصدة أو إنشاء المدفوعات أو نقل الأموال.

تكوين MCP عن بُعد عام:

```json
{
  "mcpServers": {
    "2328-docs": {
      "url": "https://doc.2328.io/mcp"
    }
  }
}
```

صياغة التكوين الدقيقة تختلف حسب عميل MCP. استخدم HTTP قابل للبث وأشر بالعميل إلى عنوان URL أعلاه.

### أدوات MCP

| الأداة | متى يجب على الوكيل استخدامها |
|------|------------------------------|
| `list_docs` | اكتشاف جميع مواضيع التوثيق وURIs الموارد. |
| `search_docs` | ابحث عن إجابات على مستوى الأقسام مع مقتطفات مرتبة وروابط مباشرة للموارد. |
| `get_doc` | اقرأ النسخة الكاملة المحمولة من صفحة واحدة بصيغة Markdown. |
| `get_integration_guide` | قم ببناء خطة موجهة لصفحة الدفع المستضافة، H2H، الفواتير المشفرة الدقيقة، المحافظ الثابتة، التحويل التلقائي، التحويل اليدوي أو المدفوعات. |

تشمل جميع نتائج الأدوات JSON منسقة بالإضافة إلى النص المقروء من قبل الإنسان. تُرجع نتائج البحث عناصر `resource_link` حتى يتمكن الوكلاء من جلب الصفحات التي يحتاجونها فقط بدلاً من تحميل كامل المجموعة.

### موارد MCP

| المورد | الغرض |
|----------|---------|
| `docs://2328/index` | فهرس الخدمة والمستندات القابل للقراءة آلياً. |
| `docs://2328/en/full` | مرجع التكامل الكامل للغة الإنجليزية مع مقتطفات الشيفرة المشتركة الموسعة. |
| `docs://2328/{locale}/{slug}` | صفحة واحدة مترجمة محليًا؛ في حال فقد الترجمات يتم الرجوع إلى الإنجليزية. |

يدعم قالب الموارد إكمال اللغة المحلية والاختصار، مما يسمح للعملاء المتوافقين باكتشاف عناوين URI صالحة دون التخمين.

### موجهات MCP

- `integrate-2328` يوجّه الوكيل لقراءة الدليل الصحيح وإنتاج شيفرة التنفيذ، والاختبارات، والتكوين، وقائمة تحقق للبدء.
- `review-2328-integration` يطلب من الوكيل مراجعة الشيفرة الموجودة للتحقق من التوقيع، ونطاق المستأجر/المشروع، ومعالجة الأرقام العشرية، وإعادة التنفيذ، وترتيب الويب هوكس، ومهلة غير واضحة، والفجوات في التوفيق.

### توصية سير عمل الوكيل

1. استخدم `get_integration_guide` لنمط التكامل المحدد.
2. اقرأ كل صفحة مرتبطة تحتوي على موارد MCP أو `get_doc`.
3. استخدم `search_docs` لأسئلة محددة بالإطار أو الحالات الخاصة.
4. قم بتنفيذ اختبارات التوقيع وخطافات الويب قبل استدعاءات API.
5. راجع النتيجة مع `review-2328-integration`.
6. اختبر معاملات حقيقية صغيرة في بيئة مضبوطة؛ الوصول إلى وثائق MCP لا يثبت الاتصال بواجهة API الإنتاجية.

> **WARNING:** وثائق MCP هي مصدر معرفة التكامل، وليست محفظة MCP. لا تقم أبداً بلصق مفاتيح API، أو مفاتيح الدفع، أو أسرار webhook، أو بيانات العملاء الشخصية، أو أوامر الإنتاج في معاملات الأدوات أو المطالبات.

## بداية سريعة مع Claude أو ChatGPT

### الخطوة 1 — وفّر الوثائق

افتح محادثة جديدة والصق محتويات [`llms-full.txt`](https://doc.2328.io/llms-full.txt) كأول رسالة، أو فقط شارك الرابط إذا كان النموذج قادرًا على جلبه.

### الخطوة 2 — وصف بنية تطبيقك

أخبر المساعد ما الذي تقوم ببنائه:

```
أبني تطبيق Laravel 11. أحتاج إلى:
1. إنشاء دفعة لطلب (المبلغ بالدولار الأمريكي، يدفع المستخدم بـ USDT TRC20)
2. التعامل مع webhook وإيداع رصيد المستخدم
3. تخزين سجلات الدفع في جدول `payments`

استخدم 2328.io API أعلاه. اشمل توقيع HMAC، والتحقق من توقيع webhook، وidempotency.
```

### الخطوة 3 — راجع واختبر

سينتج المساعد متحكمًا، وفئة خدمة، ومعالج webhook. قبل الإطلاق:

- تحقق من أن `apiSign()` يرمّز المحتوى كـ Base64 **قبل** HMAC-SHA256
- تأكد من أن معالجات webhook تستدعي `hash_equals()` (وليس `===`) لمقارنة التوقيعات
- تأكد من أن المعالج idempotent — افحص `order_id` / `txid` قبل الإيداع
- اختبر بدفعة حقيقية صغيرة في بيئة dev أولًا

> **WARNING:** لا تطلق أبدًا كود دفع مولّد بالذكاء الاصطناعي دون مراجعة منطق التوقيع والتحقق من webhook. هذه هي الحدود الأمنية الحرجة.

## تكاملات IDE

### Cursor

أضف الوثائق كمصدر docs مخصص في إعدادات Cursor:

```
Settings → Features → Docs → Add new doc
URL: https://doc.2328.io
```

ثم في المحادثة، اسبق سؤالك بـ `@2328.io`:

```
@2328.io generate a webhook handler in Next.js App Router
with signature verification and idempotent credit logic
```

### GitHub Copilot

يمكن لـ Copilot Chat قراءة `llms-full.txt` مباشرة:

```
#fetch https://doc.2328.io/llms-full.txt

Using the 2328.io API docs above, implement a payout endpoint
in Express that withdraws USDT BEP20 to a user-supplied address.
```

### Windsurf / Continue / مساعدون آخرون

أي مساعد يدعم سياق URL أو إرفاق ملف يعمل بنفس الطريقة — أرفق `llms-full.txt` ووصف هدفك.

## Claude API (Agent SDK)

إذا كنت تبني وكيلك أو روبوت دردشتك الخاص الذي يحتاج إلى التفاعل مع 2328.io، احقن الوثائق مرة واحدة في system prompt:

```python
from anthropic import Anthropic
import urllib.request

docs = urllib.request.urlopen(
    "https://doc.2328.io/llms-full.txt"
).read().decode()

client = Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    system=f"""You are an integration assistant for 2328.io.
Use the API reference below to answer questions and generate code.

<docs>
{docs}
</docs>""",
    messages=[
        {"role": "user", "content": "Write a Python function that creates a USDT payment"}
    ],
)

print(response.content[0].text)
```

> **INFO:** ملف الوثائق الكامل ~15 KB — أقل بكثير من حد سياق أي نموذج حديث. يمكنك تخزينه مؤقتًا على جانبك وتحديثه مرة واحدة في اليوم.

## أمثلة من المطالبات التي تعمل بشكل جيد

انسخ هذه إلى Claude أو ChatGPT أو AI IDE الخاص بك بعد مشاركة `llms-full.txt`:

**تكامل خلفي كامل:**
```
Build a Node.js + Express service that exposes two routes:
- POST /checkout → creates a 2328.io payment and returns the payment URL
- POST /webhook/2328 → verifies the signature and marks the order as paid
Use TypeScript, Zod for validation, and a simple in-memory store.
```

**أداة سحب:**
```
Write a CLI in Go that takes a currency, network, amount, and address
and creates a payout via the 2328.io Payout API. Use a separate payout
API key from env. Poll the status endpoint until the payout is completed.
```

**محفظة ثابتة لإيداعات المستخدمين:**
```
I have a Django app where users deposit USDT TRC20 to top up their balance.
Each user should have a permanent deposit address. Implement this using
2328.io static wallets, including the webhook handler that credits their
balance when a deposit arrives.
```

## أفضل الممارسات للتكامل بمساعدة الذكاء الاصطناعي

- **ابدأ من `llms-full.txt`** — مصمم لسياق LLM، بدون كود نمطي
- **كن محددًا بشأن بنية تطبيقك** — الإطار، إصدار اللغة، ORM
- **اطلب اختبارات** — الذكاء الاصطناعي جيد في إنشاء اختبارات وحدة لمنطق التوقيع
- **راجع معالجة الأخطاء بعناية** — أحيانًا يتجاوز الذكاء الاصطناعي مسارات الفشل
- **راجع كود التوقيع يدويًا** — هذا الجزء الوحيد الذي *يجب* أن يكون صحيحًا تمامًا
- **حدّث دوريًا** — إذا تغيرت واجهة API لدينا، أعد جلب `llms-full.txt` وأعد المطالبة