# معلومات عامة

> المواصفات التقنية لمعالجة مدفوعات العملات المشفرة وتكامل عمليات السحب مع 2328.io.

مرحبًا بكم في توثيق واجهة برمجة تطبيقات 2328.io. يصف هذا المرجع كيفية دمج معالجة مدفوعات العملات المشفرة وعمليات السحب في تطبيقك.

## البدء

لبدء عملية الدمج:

1. أنشئ حساب تاجر ومشروعًا في [2328.io](https://2328.io)
2. احصل على **project UUID** و**API key** من إعدادات المشروع
3. أنشئ **Payout API key** منفصلًا إذا كنت تخطط لاستخدام عمليات السحب
4. اقرأ قسم [Authentication](/docs/authentication) للتعرف على كيفية توقيع الطلبات
5. قم بأول استدعاء [Create Payment](/docs/payments)

## عنوان URL الأساسي

تستخدم جميع طلبات API في بيئة الإنتاج عنوان URL الأساسي التالي:

```
https://api.2328.io/api
```

> **WARNING:** يجب إجراء جميع الطلبات عبر **HTTPS**. الطلبات التي لا تستخدم HTTPS يتم حظرها.

## ما يمكنك القيام به

من خلال واجهة 2328.io API يمكنك:

- **قبول مدفوعات العملات المشفرة** — إنشاء جلسات دفع وإعادة توجيه العملاء إلى صفحة دفع مستضافة أو Telegram MiniApp
- **سحب الأموال** — إرسال عمليات سحب برمجيًا من رصيد التاجر إلى أي عنوان بلوكتشين
- **التحقق من الأرصدة** — تحقق من أرصدة حسابات التاجر لكل عملة وما يعادلها بالدولار والمبالغ المحجوزة بسبب AML
- **استخدام المحافظ الثابتة** — إنشاء عناوين إيداع دائمة مرتبطة بمستخدم أو طلب
- **جلب أسعار الصرف** — الحصول على أسعار فورية لأزواج العملات الورقية والمشفرة
- **استقبال webhooks** — تلقي إشعار فوري عند تغير حالة الدفع
## حدود معدل الطلبات

تسمح واجهة API بحد أقصى **10 طلبات في الثانية لكل مشروع**. الطلبات التي تتجاوز هذا الحد تتلقى استجابة HTTP `429 Too Many Requests` — انتظر قليلًا ثم أعد المحاولة.

## اختر نمط التكامل الصحيح

| المتطلبات | النمط الموصى به | السبب |
|-------------|---------------------|-----|
| دع العميل يختار طريقة الدفع | الدفع المستضاف | قم بإنشاء دفع وإعادة التوجيه إلى `result.url`؛ يقدم 2328.io الاتجاهات المتاحة حالياً. |
| حافظ على العميل داخل صفحة الدفع الخاصة بك | فاتورة عنوان مباشر **H2H** | أرسل `to_currency` و `network` عند إنشاء الدفع؛ قم بعرض `address` و `payer_amount` و `qr` المعادة. |
| قم بتحصيل بالضبط `25 USDT` أو `0.001 BTC` | فاتورة بالعملة المشفرة | ضع العملة المشفرة في `currency` والمبلغ العشري الدقيق في `amount`. |
| قم بتزويد كل مستخدم بعنوان إيداع قابل لإعادة الاستخدام | محفظة ثابتة | العنوان دائم ويمكنه استقبال العديد من الإيداعات المستقلة. |
| قم بتوحيد الأصول المستلمة في عملة رصيد واحدة | تحويل تلقائي | قم بتكوين قواعد المشروع في لوحة التحكم واستخدم نتيجة `convert` عند اكتمال التحويل. |
| تحويل رصيد تاجر موجود | تحويل يدوي | قم بمعاينة باستخدام `/v1/convert/price`، ثم نفذ باستخدام `/v1/convert`. |
| إرسال الأموال إلى عنوان سلسلة الكتل | الدفع | استخدم مفتاح API الخاص بالدفع المنفصل، احسب أولاً، ثم وافر بين حالة الدفع. |

> **INFO:** خيار الدفع المستضاف و H2H هما شكلان من نفس واجهة برمجة التطبيقات للدفع. H2H لا ينشئ دفعة أضعف أو غير موقعة: لا يزال الخلفية تنشئ الفاتورة، 2328.io ما زالت تملك العنوان والحالة، وتبقى الويب هوكس الموقعة موثوقة للتسوية.

## ثوابت التكامل

تنطبق هذه القواعد على كل تكامل إنتاجي:

- **Backend only** — احتفظ بمفاتيح API خارج المتصفحات، التطبيقات المحمولة، السجلات، التحليلات، ولقطات الدعم.
- **Decimal strings** — أرسل وخزن الأموال كسلاسل نصية. لا تقم أبدًا بتقريب العملات المشفرة أو أسعار الصرف باستخدام الحسابات العشرية الثنائية العائمة.
- **Immutable idempotency keys** — أنشئ `order_id` قبل الطلب الأول واحتفظ بالطلب الكامل معها. يمكن لإعادة المحاولة بنفس `order_id` أن تُعيد الجسم الأصلي بدلاً من تطبيق الحقول المعدلة.
- **Webhook-first settlement** — التحويلات، واستطلاع العميل، وهاشات المعاملات المقدمة من المستخدمين، وTimeouts HTTP ليست دليلاً على الدفع.
- **Verify, deduplicate, then mutate** — تحقق من HMAC، واطلب سجل التكرار بشكل ذري، وقم بتحديث الطلب/الرصيد مرة واحدة، وارجع بسرعة HTTP 200.
- **Reconciliation** — استعلم بشكل دوري عن حالة الدفع، والمحفظة الثابتة، والحالة النهائية للصرف حتى لا يؤدي فقدان webhook إلى حدوث خلاف دائم.
- **Dynamic availability** — تحقق من أزواج العملة/الشبكة باستخدام `/v1/directions`؛ يمكن أن يكون للأصل المدعوم اتجاه إيداع أو سحب واحد معطلاً مؤقتًا.
- **Explicit status policy** — قرر كيفية تعامل منتجك مع الدفع الجزئي، والسداد الزائد، والانتهاء، وقفل مكافحة غسل الأموال، والتحويل الاحتياطي، ومهلات المهلة الغامضة في المصدر قبل الإطلاق.

## البيانات الموصى بالاحتفاظ بها

بالنسبة للمدفوعات، احفظ على الأقل `uuid`، `order_id`، ونص الطلب الأصلي، `amount`، `currency`، `payer_currency`، `payer_amount`، `network`، `address`، `expires_at`، أحدث `payment_status`، `txid`، `payment_amount`، `merchant_amount`، الكتلة الاختيارية `convert`، وحمولة الويب هووك الموثقة الخام.

بالنسبة لمحافظ التخزين الثابتة، احتفظ بالمحفظة `uuid`، العنوان، العملة، الشبكة، مرجع العميل/الحساب، الحالة، وعنوان URL للرد بشكل منفصل عن سجلات الإيداع. كل إيداع يحتاج إلى معاملته الخاصة `uuid`، `txid`، الحالة، المبلغ المستلم، مبلغ التاجر، ونتيجة التحويل.