DEV Community: Yusuf Khalidd

كيفية استخدام Hy3 Preview API مجانًا؟

Yusuf Khalidd — Thu, 23 Apr 2026 10:45:16 +0000

أطلقت Tencent الإصدار الأولي من Hy3 Preview كمصدر مفتوح في 22 أبريل 2026، وفي اليوم التالي أدرجه OpenRouter كنقطة نهاية مجانية بالكامل. لا حاجة لبطاقة ائتمان أو قياس توكنات أو فترة تجريبية. يمكنك استدعاء نموذج Mixture-of-Experts ذو 295 مليار معلمة، المستخدم في Yuanbao وCodeBuddy من Tencent، مباشرة من تعليماتك البرمجية اليوم وبدون تكلفة.

جرّب Apidog اليوم

يوضح هذا الدليل كيفية استخدام واجهة برمجة تطبيقات Hy3 Preview مجانًا عبر OpenRouter، ومساحة Hugging Face، ومستودع Hy3 الأصلي. كما يغطي أوضاع التفكير التي تميز Hy3 عن معظم النماذج المفتوحة لعام 2026، وكيفية اختبار واجهة البرمجة داخل Apidog دون كتابة سكربتات.

إذا كنت تريد أسرع طريق للحصول على ردك الأول، انتقل مباشرة إلى قسم "خطوة بخطوة: استدعِ Hy3 Preview مجانًا على OpenRouter".

باختصار

Hy3 Preview مجاني على OpenRouter عبر معرف النموذج tencent/hy3-preview:free (0 دولار للإدخال والإخراج).
نموذج Mixture-of-Experts: 295 مليار معلمة، 21 مليار نشطة لكل تمريرة، 192 خبيرًا مع توجيه top-8، ونافذة سياق 256 ألف توكن.
ثلاثة أوضاع تفكير:
- no_think للإجابات السريعة
- low للتفكير البسيط
- high لسلاسل التفكير العميق في مهام الوكيل والترميز.
معايير قوية: SWE-bench Verified 74.4، Terminal-Bench 2.0 54.4، GPQA Diamond 87.2، MMLU 87.42.
3 طرق مجانية للتشغيل:
1. OpenRouter (طبقة مجانية)
2. مساحة Hy3-preview في Hugging Face
3. الاستدلال المحلي باستخدام vLLM والأوزان المفتوحة.
تكامل Apidog: Hy3 يستخدم مخطط OpenAI Chat Completions، وبالتالي يمكن استخدام Apidog مباشرة مع نقطة نهاية OpenRouter.

ما هو Hy3 Preview؟

Hy3 Preview هو أول إصدار رئيسي من فريق Hunyuan الأساسي في Tencent بقيادة ياو شونيو (باحث سابق في OpenAI). يعتبر النموذج الأكثر تقدماً لدى Tencent حتى الآن وإجابة مباشرة على أبرز النماذج الصينية مفتوحة الأوزان من DeepSeek، Alibaba، وZhipu.

مواصفات النموذج من بطاقة النموذج الرسمية:

البنية: Mixture-of-Experts، 80 طبقة + طبقة MTP، 64 رأس انتباه مع انتباه مجمع.
المعلمات: 295 مليار إجمالاً، 21 مليار نشطة لكل تمريرة.
الخبراء: 192 خبير مع توجيه top-8 لكل توكن.
السياق: 256 ألف توكن (262,144 في OpenRouter).
الترميز: مفردات 120,832 إدخال بدقة BF16.
الترخيص: ترخيص Tencent Hy Community للاستخدام التجاري بشروط الترخيص.

نقطة القوة الأساسية: تدريب موجه للوكلاء مع بنية تحتية حديثة للتعلم المعزز واستخدام أدوات متعدد الأدوار، مما يضعه قريباً من أفضل النماذج المغلقة في مهام الكود وCLI حسب نتائج SWE-bench وTerminal-Bench.

ثلاث طرق مجانية لاستخدام Hy3 Preview

حدد المسار الأنسب حسب احتياجك:

المسار	ما هو	مجاني؟	مناسب لـ
OpenRouter `tencent/hy3-preview:free`	API متوافقة مع OpenAI	نعم	بناء الوكلاء، السكربتات، الخلفيات
مساحة Hugging Face	دردشة متصفح	نعم	مطالبات سريعة، تجارب أولية
أوزان ذاتية الاستضافة (vLLM/SGLang)	تشغيل الأوزان على GPU خاصتك	مجاني (تكلفة العتاد)	الخصوصية، الأحمال الكبيرة

معظم المطورين يختارون OpenRouter لسهولة الاستخدام وحدود المعدل السخية للطبقة المجانية.

خطوة بخطوة: استدعِ Hy3 Preview مجانًا على OpenRouter

للحصول على استجابة من tencent/hy3-preview:free بسرعة:

أنشئ حساب OpenRouter:

سجّل في openrouter.ai. لا حاجة لطريقة دفع للنماذج المجانية.
أنشئ مفتاح API:

من لوحة OpenRouter > "Keys" > أنشئ مفتاح جديد. خزنه في متغير بيئة:

   export OPENROUTER_API_KEY=sk-or-...

افتح صفحة النموذج: زر قائمة Hy3 Preview المجانية وتأكد أن الحالة "Free".

أرسل الطلب الأول: OpenRouter يدعم مخطط OpenAI Chat Completions. أي SDK لـ OpenAI يعمل. مثال عبر curl:

   curl https://openrouter.ai/api/v1/chat/completions \
     -H "Authorization: Bearer $OPENROUTER_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "tencent/hy3-preview:free",
       "messages": [
         {"role": "user", "content": "اشرح آلية توجيه MoE في إعداد top-8 من 192 في 3 جمل."}
       ],
       "temperature": 0.9,
       "top_p": 1.0
     }'

تشغيل وضع التفكير: Hy3 يقبل معلمة reasoning مع effort: low أو effort: high. مثال:

   {
     "model": "tencent/hy3-preview:free",
     "messages": [
       {"role": "user", "content": "خطط واكتب سكربت Bash يدوّر سجلات أقدم من 30 يوم إلى مجلد أرشيف بتاريخ."}
     ],
     "reasoning": {"effort": "high"}
   }

استمر بنفس الخيط: استخدم نفس الـ thread للحفاظ على السياق؛ نافذة 256K توكن تتيح لك العمل مع قواعد كود كاملة.

الجودة على الطبقة المجانية في OpenRouter مطابقة للمدفوعة على مزودين آخرين.

مجاني، مدفوع، ومستضاف ذاتيًا: المقارنة

القدرة	OpenRouter مجاني	OpenRouter مدفوع	مستضاف ذاتيًا (vLLM/SGLang)
تكلفة التوكن	0 دولار	حسب المزود	كهرباء + استهلاك GPU
أوضاع التفكير	جميعها	جميعها	جميعها
طول السياق	256K	256K	256K (حسب الذاكرة)
الأداء تحت الحمل	مجمع مشترك	مخصص	حسب العتاد
حدود المعدل	حسب OpenRouter	حسب المزود	لا يوجد
احتفاظ البيانات	سياسة OpenRouter	حسب المزود	على أجهزتك
رؤية توكن التفكير	نعم	نعم	نعم

الخيار المجاني مناسب للنماذج الأولية والمشاريع الجانبية. الخيار المدفوع أو المستضاف ذاتيًا مطلوب للأداء الحرج أو السعة الأعلى.

نصائح عملية لضبط Hy3

اضبط درجة الحرارة حسب المهمة: استخدم temperature=0.9, top_p=1.0 افتراضيًا. خفّض إلى 0.3 للإخراج المنظم.
ضع وضع التفكير على no_think للدردشة البسيطة: استخدم low أو high فقط للتخطيط، الأكواد متعددة الخطوات، أو المسائل الرياضية.
سمِّ الأدوات في مطالبة النظام: Hy3 درب على أدوات محددة، لذا وصف الأداة في system prompt يعطي نتائج أفضل.
ألصق الكود بدلاً من تلخيصه: استخدم نافذة 256K لصق ملفات كاملة واطلب التعديلات مباشرة.
عالج تعديلات الملفات دفعة واحدة: Hy3 يتعامل بشكل أفضل مع تعديلات متعددة بنفس الرسالة.
اطلب خطة أولاً في مهام الوكيل: نمط "خطط، ثم نفذ" يعطي نتائج أنظف من الطلبات المباشرة.

حدود يجب الانتباه لها قبل النشر

حدود المعدل ديناميكية: قد تواجه استجابات 429 في ساعات الذروة. نفذ آلية إعادة المحاولة مع تأخير متزايد.
توكنات التفكير تحسب كإخراج: مجانية في الطبقة المجانية، لكن تحسب في المدفوعة.
الترخيص ليس Apache 2.0: راجع شروط ترخيص Tencent Hy Community قبل دمج النموذج في منتج تجاري.
استدعاء الأدوات يتطلب المحلل الصحيح: في الاستضافة الذاتية، استخدم --tool-call-parser hy_v3 مع vLLM أو hunyuan مع SGLang.
الإنجليزية والصينية أولويتان: اللغات الأخرى مدعومة بجودة أقل.
متأخر قليلاً عن أفضل النماذج الأمريكية في بعض المعايير: الأفضلية في الوكلاء، مع بعض الفجوة في معايير التفكير المعقدة.

مسار المطور السريع: Hy3 Preview + Apidog

استخدام curl جيد للعرض السريع، لكن التكرار الفعلي أسرع عبر عميل API مرئي مثل Apidog.

افتح Apidog وأنشئ مشروع جديد.

استورد مواصفات OpenAI Chat Completions OpenAPI.
اضبط عنوان URL الأساسي:

استخدم https://openrouter.ai/api/v1 وعيّن متغير بيئة OPENROUTER_API_KEY.
أنشئ طلب جديد:

نفّذ /chat/completions مع النموذج tencent/hy3-preview:free.
انسخ الطلب للمقارنة:

جرب أوضاع التفكير الثلاثة (no_think, low, high) وقارن النتائج مباشرة في Apidog.
احفظ قوالب المطالبات:

استفد من نظام القوالب والمتغيرات لإعادة استخدام المطالبات وتهيئة أدواتك بسرعة.

إذا كنت قادمًا من Postman، يمكنك الانتقال بسرعة عبر دليل اختبار API بدون Postman في 2026. للعمل داخل VS Code، راجع شرح Apidog داخل VS Code.

بدائل مجانية عند بلوغ الحد الأقصى

إذا واجهت حدود الطبقة المجانية في OpenRouter، جرب التالي:

مساحة Hugging Face: استخدم مساحة Hy3-preview للدردشة السريعة في المتصفح.
نماذج صينية أخرى مفتوحة المصدر:
- Qwen 3.5 Omni من Alibaba: راجع إعلان Qwen 3.5 Omni ودليل الاستخدام.
- Zhipu GLM 5V Turbo: دليل GLM 5V Turbo API.

هذه النماذج لا تتطابق مع أرقام Hy3 في مهام SWE-bench/Terminal-Bench، لكنها جيدة للدردشة وحالات الاستخدام المتعددة. أنشئ مجموعة في Apidog وقارن النتائج فعليًا.

الاستضافة الذاتية لـ Hy3 Preview باستخدام vLLM

إذا كان لديك عتاد مناسب، اتبع الخطوات التالية لتشغيل النموذج محليًا:

vllm serve tencent/Hy3-preview \
  --tensor-parallel-size 8 \
  --speculative-config.method mtp \
  --speculative-config.num_speculative_tokens 1 \
  --tool-call-parser hy_v3 \
  --reasoning-parser hy_v3 \
  --enable-auto-tool-choice \
  --served-model-name hy3-preview

لـ SGLang استخدم --tool-call-parser hunyuan و--reasoning-parser hunyuan. بعد تشغيل الخادم على http://localhost:8000/v1، استخدم أي SDK متوافق مع OpenAI بتغيير الـ endpoint فقط.

النموذج الكامل يتطلب 8 وحدات معالجة رسومية فئة H100 بدقة BF16. ستظهر نسخ مكمّاة لاحقًا.

الأسئلة الشائعة

هل Hy3 Preview مجاني؟

نعم، عبر OpenRouter بنموذج tencent/hy3-preview:free، 0 دولار لكل مليون توكن إدخال/إخراج. توكنات التفكير مجانية في الطبقة المجانية أيضًا. تحقق من صفحة نموذج OpenRouter للحالة الفعلية.

كيف يقارن Hy3 Preview بـ DeepSeek V3 و Qwen 3؟

درجات SWE-bench Verified (74.4) وTerminal-Bench (54.4) تضعه في قمة النماذج الصينية. ميزة Hy3 في تدريب الوكيل واستخدام الأدوات المدرب بـ RL. للدردشة، Qwen 3 وDeepSeek V3 أيضًا منافسان.

ما هي أوضاع التفكير في Hy3؟

ثلاثة أوضاع:

no_think للإجابات المباشرة (افتراضي)
low
high بدل بينها عبر معلمة reasoning في OpenRouter أو chat_template_kwargs={"reasoning_effort": "high"} عند الاستدعاء المباشر.

هل يمكنني استخدام Hy3 Preview تجاريًا؟

نعم، بموجب ترخيص Tencent Hy Community مع الإسناد والالتزام بشروط الاستخدام. راجع مستودع GitHub للاطلاع على الترخيص الكامل.

ما هو طول السياق المدعوم في الطبقة المجانية؟

256 ألف توكن. قائمة OpenRouter تعرض 262,144 توكن مطابقة لبطاقة النموذج.

كيف أختبر Hy3 Preview دون كتابة كود؟

جرب مساحة Hy3-preview على Hugging Face، أو وجّه Apidog إلى نقطة نهاية OpenRouter. في Apidog، استورد مواصفات OpenAI OpenAPI وحدد: عنوان URL الأساسي، مفتاح API، واسم النموذج.

أفضل API لسوق التنبؤات لعام 2026

Yusuf Khalidd — Thu, 23 Apr 2026 09:59:08 +0000

تتيح أسواق التنبؤ للمطورين والمتداولين المراهنة على نتائج أحداث العالم الحقيقي مثل الانتخابات، قرارات البنوك المركزية، أو أسعار العملات الرقمية. منذ عام 2026، أصبحت هذه الأسواق مصدر بيانات أساسي للباحثين وبناة المنتجات المالية، حيث وصلت Polymarket وحدها إلى مليارات الدولارات من حجم التداول. إذا كنت تطور روبوتات تداول، لوحات تحكم بحثية، أدوات تحليل أو منتجات إعلامية، فأنت بحاجة لتوصيل تطبيقك بواجهة API موثوقة لسوق التنبؤ.

جرّب Apidog اليوم

التحدي الرئيسي هو التنوع الكبير بين هذه الأسواق: البنية التحتية، أساليب المصادقة، حدود المعدل، وتنسيقات البيانات تختلف بشكل كبير. بعض الواجهات تقدم دفاتر أوامر حية عبر WebSocket، وأخرى تعيد بيانات عقود عبر REST، والبعض مخصص للنماذج الأولية فقط. اختيار الواجهة الخاطئة سيكلفك وقتًا وجهدًا كبيرين.

في هذا الدليل، سنقارن أفضل واجهات API لأسواق التنبؤ لعام 2026، ونوضح ميزات كل واحدة، وكيفية اختبارها فعليًا باستخدام Apidog. ستحتاج إلى مراجعة الوثائق الرسمية لكل منصة مثل Polymarket، Kalshi، و Manifold Markets. إذا كنت تبني حلولًا قائمة على البلوكتشين، راجع أيضًا دليل أفضل API لمحفظة العملات المشفرة لتكامل Polymarket و Augur.

ملخص عملي

Polymarket: سيولة عميقة وتسوية على السلسلة عبر CLOB وGamma APIs؛ الأنسب للبيانات الضخمة والتداول المؤسسي.
Kalshi: بورصة أمريكية منظمة تدعم REST وWebSocket؛ تتطلب التحقق من الهوية (KYC) وتوفر بيئة منظمة.
Manifold Markets: واجهة REST سهلة بأموال افتراضية؛ الأفضل للنماذج الأولية والتعليم.
Augur v2: منصة لامركزية بالكامل على Ethereum مع إمكانية الوصول عبر subgraph؛ تخصصها الأمان واللامركزية.
PredictIt: تغذية بيانات عامة للقراءة فقط؛ مصدر بيانات سياسي بدون إمكانيات تداول آلية.
Metaculus: منصة بحثية لتجميع توقعات الخبراء عبر REST API؛ بدون تداول أو دفاتر أوامر.

ما الذي يجب تقييمه في API سوق التنبؤ؟

قبل اختيار API، تحقق من هذه العناصر:

تغطية السوق: هل تغطي السياسة، العملات، الاقتصاد، وغيرها؟ مثلًا Polymarket وKalshi يغطيان نطاقًا أوسع.
بيانات السيولة والحجم: ابحث عن نقاط نهاية تعرض حجم التداول، والفائدة المفتوحة.
تغذية الأسعار ودفاتر الأوامر في الوقت الفعلي: لتطبيقات التداول، يجب دعم WebSocket.
البيانات التاريخية: هل يمكنك الوصول إلى بيانات سابقة بسهولة للاختبار الخلفي؟
الحالة التنظيمية: هل تحتاج API منظمة (مثل Kalshi) أم تفضل اللامركزية (مثل Polymarket)؟
المصادقة: أنواع المصادقة (API Key, Wallet Signature, Token).
حدود المعدل وSDKs: هل يمكن تشغيل روبوتات نشطة دون حظر؟

جدول المقارنة

المزود	النوع	نمط API	مصادقة التداول	الأفضل لـ
Polymarket	لامركزي، على السلسلة (Polygon)	REST (CLOB, Gamma) + WebSocket	توقيع محفظة EIP-712	تداول العملات المشفرة عالي الحجم وبيانات الانتخابات
Kalshi	بورصة أمريكية منظمة من CFTC	REST + WebSocket	بريد إلكتروني/كلمة مرور + مفتاح API، KYC	عقود الأحداث المتوافقة مع الولايات المتحدة والمنتجات المنظمة
Manifold Markets	سوق اجتماعي بأموال وهمية	REST (JSON نظيف)	مفتاح API	النماذج الأولية، البحث، التدريس
Augur v2	لامركزي (Ethereum)	The Graph subgraph + عقود	توقيع المحفظة	أسواق لامركزية بالكامل، مقاومة للرقابة
PredictIt	سوق سياسي أمريكي منظم	تغذية JSON عامة (قراءة)	لا يوجد API تداول عام	بيانات تاريخية عن المشاعر السياسية الأمريكية
Metaculus	منصة بحث للتنبؤ	REST	مصادقة الرمز المميز	توقعات الخبراء المجمعة، مجموعات البيانات البحثية

أفضل مزودي API لأسواق التنبؤ: خطوات تطبيقية

Polymarket (CLOB و Gamma)

الميزات: أكبر منصة لامركزية، تعمل على Polygon، تدعم USDC.
كيفية الاستخدام:
1. استخدم Gamma API (الرابط) لقراءة الأسواق.
2. لبناء أوامر تداول، استخدم Polymarket SDK لإنشاء توقيعات EIP-712 من محفظتك (MetaMask/Privy).
3. استمع إلى بيانات WebSocket لتحديثات دفتر الأوامر.

مثال كود (قراءة سوق):

curl https://gamma-api.polymarket.com/markets

ملاحظات: للتداول تحتاج لمحفظة Polygon ممولة ودمج التوقيع البرمجي.
الأفضل لـ: التداول المؤسسي، الانتخابات، فرق الـ DeFi.

Kalshi

الميزات: منصة منظمة أمريكية، تغطي الاقتصاد، الطقس، السياسة.
كيفية الاستخدام:
1. أنشئ حساب Kalshi وفعّل KYC.
2. احصل على API key من حسابك.
3. استخدم REST API لقراءة الأسواق والأوامر:
```
curl -u "email:api_key" https://trading-api.kalshi.com/trade-api/v2/markets/
```

استخدم WebSocket للبث اللحظي.
- ملاحظات: مطلوب تخزين وتدوير رموز الدخول.
- الأفضل لـ: تطبيقات أمريكية، عقود الاقتصاد الكلي.

Manifold Markets

الميزات: أموال وهمية، REST API بسيط.
كيفية الاستخدام:
1. أنشئ حساب بسرعة (الوثائق).
2. استخدم API key للمصادقة مع نقاط النهاية الخاصة بالرهانات.
```
curl https://api.manifold.markets/v0/markets
```

للعمليات العامة (قراءة) لا حاجة لمفتاح.
- الأفضل لـ: النماذج الأولية، التعليم، البحث.

Augur v2

الميزات: لامركزية شديدة، مبنية على Ethereum.
كيفية الاستخدام:
1. استعلم عن الأسواق باستخدام The Graph subgraph.
```
{
  markets(first: 5) {
    id
    description
    volume
  }
}
```

للتداول، استخدم توقيع محفظة مع عقود Augur.
- ملاحظات: الرسوم على Ethereum، التوثيق أقل تفصيلًا.
- الأفضل لـ: التطبيقات المقاومة للرقابة، البحث الأكاديمي.

PredictIt

الميزات: مصدر بيانات سياسي أمريكي للقراءة فقط.
كيفية الاستخدام:
1. استخرج بيانات السوق من:
```
https://www.predictit.org/api/marketdata/all/
```

استخدم مكتبات scraping لتحليل البيانات.
- ملاحظات: لا توجد إمكانيات تداول API.
- الأفضل لـ: تحليل بيانات السياسة الأمريكية.

Metaculus

الميزات: توقعات خبراء، REST API.
كيفية الاستخدام:
1. استخرج الأسئلة والتوقعات عبر:
```
https://www.metaculus.com/api2/questions/
```

للمصادقة استخدم رمز Token في الهيدر.
- الأفضل لـ: لوحات تحكم البحث، تجميع التوقعات.

كيف تختار API مناسب؟

حدد جمهورك ومتطلبات التنظيم:
- مستخدمون أمريكيون وتداول حقيقي؟ استخدم Kalshi.
- جمهور العملات الرقمية؟ Polymarket.
- بحث داخلي أو تحليل بيانات؟ دمج Metaculus وPolymarket.
- تعليم أو بروتوتايب سريع؟ Manifold.
حدد نطاق الأصول:
- الانتخابات: Polymarket أو Kalshi.
- العملات الرقمية: Polymarket.
- مشروعات تعليمية: Manifold.
- بنية تحتية بلوكتشين: Augur أو Polymarket.
اختبر التكامل قبل البناء الكامل:
- استخدم Apidog أو أدوات مماثلة لتوحيد اختبارات المصادقة والبيانات عبر المنصات.

اختبار واجهات API لأسواق التنبؤ باستخدام Apidog

كل منصة تتطلب مصادقة مختلفة: Kalshi تحتاج تدوير رمز دخول، Polymarket توقيع محفظة EIP-712، Manifold مفتاح API، Metaculus رمز Token. إدارة هذه التكوينات يدويًا معقدة ويصعب تكرارها عبر أدوات متعددة مثل Postman وcurl.

مع Apidog يمكنك:

استيراد مواصفات OpenAPI لكل منصة بسهولة.
تخصيص ملفات تعريف المصادقة لكل بيئة.
تشغيل سيناريوهات اختبار متسلسلة (login → order → fetch market).
محاكاة استجابات API وتخزينها محليًا للاختبار الخلفي.
مقارنة بيانات الأسواق عبر الزمن للكشف عن تغييرات المخططات.

ابدأ بتنزيل Apidog (الرابط) واستورد مواصفات OpenAPI الخاصة بـ Polymarket أو Kalshi، وجرّب سيناريوهاتك مباشرة.

الأسئلة الشائعة

ما هو سوق التنبؤ الأعلى سيولة في 2026؟

Polymarket هو الأكبر، خاصة في انتخابات الرئاسة والأحداث الكبرى. Kalshi ينمو بسرعة في العقود المنظمة الأمريكية.

هل يمكن التداول في Polymarket من الولايات المتحدة؟

التداول محظور على عناوين IP الأمريكية. البيانات العامة متاحة للقراءة. للتداول الفعلي، استخدم Kalshi.

هل أحتاج لمحفظة عملات رقمية لتفعيل API Polymarket؟

نعم للتداول، حيث تتطلب توقيع EIP-712 من محفظة Polygon. للقراءة فقط، لا حاجة لمحفظة.

هل توجد API مجانية لتعلم أسواق التنبؤ؟

Manifold Markets مجانية تمامًا، وأيضًا Metaculus متاحة للقراءة.

ما الفرق العملي بين Kalshi وPolymarket للمطورين؟

Kalshi توفر REST + WebSocket مع مصادقة تقليدية وإشراف تنظيمي. Polymarket تعتمد على البلوكتشين والتوقيعات الرقمية ولا يسمح لمستخدمي الولايات المتحدة بالتداول.

كيف أتجنب حدود المعدل أثناء الاختبار الخلفي؟

استخدم التخزين المؤقت للبيانات، احترم استجابات 429 مع تراجع أسي، وادمج اشتراكات WebSocket حيثما أمكن. لمزيد من التفاصيل حول الأدوات الفعالة، راجع دليل اختبار API بدون Postman.

أفضل واجهة برمجة تطبيقات (API) لتحويل العملات الورقية إلى رقمية والعكس من فيات لعام 2026

Yusuf Khalidd — Thu, 23 Apr 2026 09:53:02 +0000

تُعد منصات الإيداع والسحب للعملات الورقية (fiat on-ramps and off-ramps) البنية التحتية الأساسية التي تربط الخدمات المصرفية التقليدية بالعملات المشفرة. إذا كنت تبني محفظة أو بنك رقمي أو تطبيق عملة مستقرة، من الضروري أن تدمج طريقة تُمكن المستخدم من تحويل أمواله من بطاقة فيزا أو تحويل مصرفي إلى USDC مثلاً، ثم إعادة السحب لاحقاً إلى الحساب البنكي بسهولة—بدون الحاجة لبناء بوابة دفع كاملة من الصفر.

جرّب Apidog اليوم

الحل العملي هو استخدام واجهات برمجة التطبيقات (APIs) الجاهزة للإيداع والسحب بالعملات الورقية. تكامل واحد سيغطي عنك إجراءات اعرف عميلك (KYC)، وقبول المدفوعات، والامتثال، والتسوية؛ بينما تركز أنت على تطوير منتجك. المفاضلة دائماً بين التغطية الجغرافية، وتنوع طرق الدفع، وحجم الرسوم، وتجربة المطور. للمقارنة، راجع Stripe Crypto Onramp وMoonPay Business.

في هذا الدليل ستجد مقارنة عملية بين 6 مزودين جاهزين للإنتاج لعام 2026، مع خطوات اختبارهم سريعاً باستخدام Apidog. إذا كنت تعمل مع بنية العملات المستقرة، اطلع أيضاً على دليل كيفية استخدام واجهة برمجة تطبيقات Circle.

خلاصة القول (TL;DR)

واجهة برمجة تطبيقات الإيداع تحول الأموال المصرفية إلى عملة مشفرة، والسحب يعيدها إلى حساب بنكي.
اختر مزودك بناءً على التغطية الجغرافية، وطرق الدفع (بطاقة، ACH، SEPA، UPI، Pix)، والرسوم، وهل تحتاج أداة جاهزة أم وصول كامل للـ API.
MoonPay وTransak يغطيان أكبر عدد من البلدان؛ Ramp Network تقدم تجربة مطور ممتازة في أوروبا والمملكة المتحدة.
Coinbase Onramp وStripe Crypto Onramp مناسبان إذا كان السوق الرئيسي هو الولايات المتحدة وتبحث عن علامة تجارية قوية.
Kado مميز في السحب منخفض التكلفة ودعم تدفقات العملات المستقرة.
اختبر دائماً الدورة الكاملة (إيداع وسحب) في بيئة اختبار قبل الإطلاق؛ رسوم واحتكاك KYC يظهران مبكراً في التجربة الحقيقية.

كيف تختار واجهة برمجة تطبيقات للإيداع والسحب بالعملات الورقية

التغطية الجغرافية والعملات: تحقق بدقة من العملات المدعومة والدول. بعض المزودين يعلنون تغطية عالمية لكن يقيّدون طرق الدفع في بلدان معينة.
طرق الدفع: إذا كان جمهورك في الهند أو البرازيل، تأكد من دعم UPI أو Pix. البطاقات متوفرة عالمياً لكن رسومها أعلى.
KYC: هل المزود يدير KYC بالكامل أم يحمّلها على منتجك؟ التكامل الأسرع مع مزودي KYC الشاملين.
وقت التسوية والرسوم: التسوية بالبطاقات أسرع (دقائق) لكن أغلى (3-5%). التحويلات البنكية أرخص وأبطأ.
مدمج أم مستضاف: الأداة الجاهزة أسرع في الدمج (30 دقيقة)، API كامل يمنحك تحكم لكن يتطلب ترخيصاً.
دعم العملات المستقرة والسحب: تأكد من دعم USDC/USDT على الشبكات الرئيسية، وافحص فعلياً توفر خدمة السحب في البلدان المستهدفة.

جدول المقارنة

المزود	التسعير	التغطية	تجربة المطور	الأفضل لـ
مون باي (MoonPay)	1% إلى 4.5% بطاقة، 1% ACH	أكثر من 160 دولة، أكثر من 30 عملة ورقية	أداة مدمجة + REST API، توثيق ممتاز	محافظ تحتاج تغطية عالمية للبطاقات
رامب نتورك (Ramp Network)	0.49% إلى 2.9%	أكثر من 150 دولة، قوية في الاتحاد الأوروبي/المملكة المتحدة	SDKs ممتازة، توثيق واضح	تطبيقات الاتحاد الأوروبي والمملكة المتحدة ذات احتكاك منخفض
ترانزاك (Transak)	0.99% إلى 5.5%	أكثر من 150 دولة، أكثر من 75 عملة ورقية	أداة مدمجة + API، سهلة الدمج	تغطية واسعة تشمل الهند (UPI)
كوين بيس أونرامب (Coinbase Onramp)	1% إلى 3.99%	الولايات المتحدة + 90 دولة	Pay SDK، مكونات React	تطبيقات تركز على الولايات المتحدة مع علامة تجارية موثوقة
كادو (Kado)	1.5% رسوم سحب ثابتة	أكثر من 170 دولة	API أولاً، متخصصة في العملات المستقرة	تطبيقات العملات المستقرة والسحب الرخيص
سترايب كريبتو أونرامب (Stripe Crypto Onramp)	1.5% + رسوم Stripe	الولايات المتحدة + تغطية دولية محدودة	تكامل محكم مع Stripe	تطبيقات قائمة على Stripe

استعراض عملي لأبرز مزودي منصات الإيداع والسحب بالعملات الورقية

مون باي (MoonPay)

أفضل خيار للحصول على تغطية عالمية بسرعة. يدعم أكثر من 160 دولة و30+ عملة ورقية، مع طرق دفع متنوعة (بطاقات، ACH، SEPA، Apple Pay، Google Pay، Pix). الأداة الجاهزة تغطي KYC وAML والاحتيال، بينما REST API مناسب إذا كان لديك تراخيص. رسوم متغيرة بين 1-4.5% حسب الطريقة والمنطقة. السحب متاح في معظم الأسواق الرئيسية.

للتكامل البرمجي: راجع كيفية استخدام واجهة MoonPay API.

أفضل استخدام: محافظ المستهلكين التي تحتاج تغطية عالمية من مزود واحد.

رامب نتورك (Ramp Network)

Ramp مثالية للمطورين في الاتحاد الأوروبي والمملكة المتحدة، مع SDKs سهلة، رسوم شفافة، وKYC سريع عبر SEPA. تركز على الخدمات المصرفية المفتوحة والرسوم المنخفضة (0.49% في أوروبا). الأداة الجاهزة تدمج في React أو vanilla JS خلال دقائق، ويوجد SDK للهاتف المحمول. السحب متاح في أوروبا وبريطانيا وبعض البلدان الأخرى.

للتكامل مع محافظ مثل MetaMask: راجع كيفية استخدام MetaMask API.

أفضل استخدام: تطبيقات أوروبا/المملكة المتحدة التي تحتاج أقل احتكاك على SEPA.

ترانزاك (Transak)

تغطية واسعة (150+ دولة، 75+ عملة)، مع دعم قوي للمدفوعات المحلية مثل UPI وPix. الأداة الجاهزة تدمج بسهولة في أي تطبيق ويب أو هاتف، ودعم API للعلامة البيضاء. الرسوم 0.99%-5.5% حسب الطريقة. KYC مدارة من البداية للنهاية.

أفضل استخدام: تطبيقات تستهدف الهند وجنوب شرق آسيا وأمريكا اللاتينية.

كوين بيس أونرامب (Coinbase Onramp) (Pay SDK)

يستخدم Pay SDK للسماح لمستخدمي Coinbase بتمويل محافظهم ببضع نقرات، خاصة الفئة الأمريكية. يدعم الإيداع بالبطاقات أو الطرق المحلية في أكثر من 90 دولة. حزمة SDK توفر مكونات React وتكامل مستضاف. خدمة السحب متاحة في عدد محدود من البلدان.

أفضل استخدام: تطبيقات تركز على الولايات المتحدة وتستفيد من علامة Coinbase وقاعدة مستخدميها.

كادو (Kado)

متخصص في العملات المستقرة (USDC، USDT) على Solana، Base، Polygon، Ethereum. رسوم السحب ثابتة 1.5% (الأقل غالباً)، وتغطية 170+ دولة. API مُصمم لتطبيقات العملات المستقرة، مع إمكانية تمويل وسحب من نفس الحساب البرمجي.

أفضل استخدام: تطبيقات العملات المستقرة، البنوك الرقمية، حلول الرواتب مع تركيز على السحب الرخيص.

سترايب كريبتو أونرامب (Stripe Crypto Onramp)

الخيار الأسرع إذا كنت تستخدم Stripe. يعيد استخدام حساب Stripe ولوحة التحكم، برسوم 1.5% + رسوم البطاقة. التغطية تركز على الولايات المتحدة، مع دعم دولي محدود. التكامل لا يتطلب سوى تضمين واحد، وStripe يدير KYC والتسوية. السحب محدود.

أفضل استخدام: تطبيقات قائمة على Stripe في الولايات المتحدة.

خطوات عملية لاختيار مزود الإيداع والسحب

حدد أهم 3 دول مستهدفة وطرق الدفع الشائعة فيها.
إذا كنت بحاجة لدعم UPI، Pix أو بطاقات أفريقية، اختر Transak أو MoonPay. الاتحاد الأوروبي يشير إلى Ramp. السوق الأمريكي إلى Coinbase أو Stripe. العملات المستقرة والسحب الرخيص إلى Kado.
قارن التسعير، ودعم السحب، ونوع التكامل (أداة جاهزة أو API كامل).
اختبر مزودين أو ثلاثة بالتوازي، واجمع بيانات حقيقية عن التحويل والرسوم قبل اتخاذ القرار النهائي.

اختبار عملي لواجهات الإيداع والسحب باستخدام Apidog

قبل اختيار المزود، قم بتشغيل الدورة الكاملة (إيداع وسحب) في بيئة اختبار (sandbox). استخدم Apidog لاستيراد OpenAPI من MoonPay وRamp وTransak وغيرهم، ثم نفّذ طلبات المصادقة في بيئة اختبارية.

خطوات عملية للاختبار:

أنشئ ثلاث بيئات في Apidog: sandbox، التحضير (staging)، الإنتاج (production).
خزّن مفتاح API لكل مزود كمتغير بيئة (environment variable) — لا تضع الأسرار في الكود.
أنشئ تسلسل طلبات: الحصول على عرض سعر، إنشاء معاملة، استطلاع الحالة، تأكيد webhook، تفعيل السحب.
تحقق من نجاح الدورة الكاملة على Apidog، ثم نقلها لاحقاً إلى backend الخاص بك.

نزّل Apidog الآن للبدء.

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

الأسئلة الشائعة

ما الفرق بين منصة الإيداع (on-ramp) ومنصة السحب (off-ramp)؟ الإيداع: تحويل العملة الورقية (بطاقة/تحويل مصرفي) إلى عملة مشفرة بمحفظة المستخدم. السحب: تحويل العملة المشفرة إلى عملة ورقية في حساب بنكي أو بطاقة.

هل أحتاج ترخيص تحويل أموال لاستخدام هذه APIs؟ عادةً لا. معظم المزودين يحملون التراخيص ويتكفلون بالامتثال. أنت شريك تقني فقط، لكن إذا كنت ترغب في تخصيص KYC أو الاحتفاظ بأموال العملاء، قد تحتاج ترخيصاً خاصاً.

أي مزود لديه أقل رسوم؟ في أوروبا، Ramp غالباً الأرخص للبطاقات (0.49%-2.9%). السحب الأرخص مع Kado (1.5% ثابتة). Stripe أرخص إذا كنت تستخدمه بالفعل. قارن الخيارات حسب احتياجك.

هل يمكن استخدام أكثر من مزود للإيداع في نفس الوقت؟ نعم. العديد من التطبيقات توجه المستخدم بناءً على البلد أو طريقة الدفع أو العملة. راجع شرح MoonPay API للتفاصيل.

كم يستغرق إجراء KYC؟ تدفق البطاقات مع تحميل المستندات عادةً 2-5 دقائق. KYC عبر الخدمات المصرفية المفتوحة (مثل Ramp) قد ينجز في أقل من 30 ثانية للمستخدمين المتكررين. المراجعة اليدوية للحالات عالية المخاطر تصل إلى 24-48 ساعة.

هل تدعم هذه المزودات العملات المستقرة؟ نعم، جميعهم يدعمون USDC وUSDT على الشبكات الرئيسية. Kado وStripe Crypto Onramp يركزان أساساً على العملات المستقرة؛ البقية يدعمونها كخيار إضافي.

كيفية استخدام واجهة برمجة تطبيقات MetaMask: ربط تطبيقك اللامركزي بمحافظ Ethereum

Yusuf Khalidd — Thu, 23 Apr 2026 07:34:47 +0000

ميتا ماسك هو الخيار الافتراضي للوصول إلى الإيثيريوم لملايين المستخدمين. إذا كنت تطور تطبيقًا لامركزيًا (dApp)، فإن واجهة برمجة تطبيقات ميتا ماسك (MetaMask API) هي الجسر بين واجهتك الأمامية ومفاتيح المستخدمين. واجهة برمجة تطبيقات ميتا ماسك تتكوّن من المزود window.ethereum (وفق معيار EIP-1193) وحزمة SDK الخاصة بميتا ماسك التي تتيح نفس الإمكانيات على الجوال وReact Native وNode.js. إذا أتقنت المزود، ستتمكن من تنفيذ أغلب تكاملات محافظ الويب بسهولة.

جرّب Apidog اليوم

هذا الدليل عملي: ستتعلم اكتشاف المزود، طلب الحسابات، قراءة السلسلة، التوقيع باستخدام personal_sign وEIP-712، إرسال المعاملات، إضافة/تبديل السلاسل، واستخدام SDK خارج إضافات المتصفح. سترى أين يمكن استخدام ethers.js v6 وviem كطبقات عليا، وأين يدخل Apidog لاختبار استدعاءات JSON-RPC بدون الحاجة لبناء واجهة مؤقتة.

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

ملخص سريع (TL;DR)

واجهة برمجة تطبيقات ميتا ماسك = مزود EIP-1193 في window.ethereum + SDK للجوال وNode.
ابدأ بـ eth_requestAccounts لطلب الاتصال، واستمع لحدثي accountsChanged وchainChanged.
وقّع الرسائل بـ personal_sign، والبيانات المنظمة بـ eth_signTypedData_v4 (EIP-712).
بدّل الشبكات بـ wallet_switchEthereumChain، وأضف شبكات جديدة بـ wallet_addEthereumChain.
استخدم مكتبات مثل ethers.js v6 أو viem أو wagmi كطبقات عليا.
اعتمد على Apidog لاختبار RPC، ومحاكاة المعاملات، وتصحيح التواقيع قبل الإطلاق.

ما هي واجهة برمجة تطبيقات ميتا ماسك (MetaMask API)؟

واجهة ميتا ماسك تتيح للتطبيقات التفاعل مع الإيثيريوم وسلاسل EVM عبر كائن المزود window.ethereum في المتصفح (مطابقة لمعيار EIP-1193). أي dApp يدعم هذا المعيار يعمل مع ميتا ماسك ومحافظ أخرى كتبادل مباشر.

خارج المتصفح، استخدم SDK ميتا ماسك للحصول على نفس السطح البرمجي في React Native، Node.js، Electron، وحتى السكريبتات الخلفية. SDK تدير الروابط العميقة (deep linking) وتفاعل رموز QR لتوقيع المعاملات من أجهزة مختلفة.

يدعم ميتا ماسك أيضًا Snaps لإضافة سلاسل وطرق RPC جديدة – خارج نطاق هذا الدليل، لكنها مهمة لمن يريد دعم سلاسل غير EVM أو تدفقات توقيع متقدمة.

المصادقة والإعداد

لا حاجة لمفاتيح API. المصادقة تتم بموافقة المستخدم على كل إجراء. تحتاج فقط لاكتشاف المزود والاستماع للتغييرات.

اكتشف المزود عبر @metamask/detect-provider أو مباشرة:

// اكتشاف المزود
import detectEthereumProvider from '@metamask/detect-provider';

const provider = await detectEthereumProvider({ mustBeMetaMask: true });

if (!provider) {
  alert('الرجاء تثبيت ميتا ماسك');
} else {
  console.log('تم اكتشاف ميتا ماسك');
}

اربط مستمعي الأحداث فورًا:

window.ethereum.on('accountsChanged', (accounts) => {
  if (accounts.length === 0) {
    console.log('تم قطع الاتصال');
  } else {
    console.log('الحساب النشط:', accounts[0]);
  }
});

window.ethereum.on('chainChanged', (chainId) => {
  // ينصح بإعادة تحميل الصفحة عند تغيير السلسلة
  window.location.reload();
});

في React، استخدم wagmi لتقوم تلقائيًا بكل ذلك.

نقاط النهاية الأساسية

كل الاستدعاءات عبر:

window.ethereum.request({ method, params })

فيما يلي أهم الاستدعاءات العملية:

طلب الحسابات وقراءة السلسلة

// طلب الاتصال
const accounts = await window.ethereum.request({
  method: 'eth_requestAccounts',
});
const account = accounts[0];

// قراءة chainId
const chainId = await window.ethereum.request({
  method: 'eth_chainId',
});

console.log(account, chainId); // مثال: '0x...' و '0x1'

للاستدعاءات للقراءة فقط، استخدم RPC عام مثل Infura أو Alchemy. راجع دليل Alchemy API.

توقيع رسالة بسيطة

const message = 'Sign in to Apidog at ' + new Date().toISOString();
const signature = await window.ethereum.request({
  method: 'personal_sign',
  params: [message, account],
});

توقيع بيانات منظمة (EIP-712)

const typedData = {
  domain: { name: 'Apidog Demo', version: '1', chainId: 1 },
  types: {
    EIP712Domain: [
      { name: 'name', type: 'string' },
      { name: 'version', type: 'string' },
      { name: 'chainId', type: 'uint256' },
    ],
    Login: [
      { name: 'wallet', type: 'address' },
      { name: 'nonce', type: 'uint256' },
    ],
  },
  primaryType: 'Login',
  message: { wallet: account, nonce: 42 },
};

const sig = await window.ethereum.request({
  method: 'eth_signTypedData_v4',
  params: [account, JSON.stringify(typedData)],
});

إرسال معاملة

const txHash = await window.ethereum.request({
  method: 'eth_sendTransaction',
  params: [{
    from: account,
    to: '0xRecipientAddressHere', // ضع عنوان المستلم هنا
    value: '0x38d7ea4c68000', // 0.001 ETH بالـ wei (hex)
  }],
});

تبديل/إضافة سلسلة

// التبديل إلى Polygon – chainId: 137 (0x89)
try {
  await window.ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0x89' }],
  });
} catch (err) {
  if (err.code === 4902) {
    // السلسلة غير مضافة بعد
    await window.ethereum.request({
      method: 'wallet_addEthereumChain',
      params: [{
        chainId: '0x89',
        chainName: 'Polygon',
        rpcUrls: ['https://polygon-rpc.com'],
        nativeCurrency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
      }],
    });
  }
}

استخدام SDK ميتا ماسك في React

import { MetaMaskProvider, useSDK } from '@metamask/sdk-react';

function Connect() {
  const { sdk, connected, account } = useSDK();
  return (
    <button onClick={() => sdk?.connect()}>
      {connected ? account : 'اتصل بميتا ماسك'}
    </button>
  );
}

export default function App() {
  return (
    <MetaMaskProvider sdkOptions={{ dappMetadata: { name: 'تطبيقي اللامركزي' } }}>
      <Connect />
    </MetaMaskProvider>
  );
}

لإنتاجية أعلى، غلّف المزود في ethers.js v6 أو viem لعقود مكتوبة (typed contracts) وتحليل ABI أفضل. إذا أردت تسجيل دخول بالبريد أو الشبكات الاجتماعية كخيار إضافي، راجع دليل Privy API.

الأخطاء الشائعة وحدود المعدل

أكثر رموز الخطأ شيوعًا:

4001: المستخدم رفض الطلب. لا تعاود المحاولة تلقائيًا.
4100: غير مصرح به. الحساب غير متصل.
4200: طريقة غير مدعومة. تحقق أن المحفظة ميتا ماسك.
4902: السلسلة غير مضافة. استخدم wallet_addEthereumChain.
-32002: طلب معلق فعليًا. قم بعمل debounce للأزرار.

المزود نفسه لا يفرض حدًا للمعدل، لكن مزودات RPC تفعل. للتعامل مع العملات الورقية والتحويلات، ستحتاج إلى واجهة API للتحويلات المالية.

تسعير واجهة برمجة تطبيقات ميتا ماسك

إضافة ميتا ماسك وSDK مجانيان بالكامل. لا توجد رسوم على المطورين. التكلفة الوحيدة تأتي من مزودات RPC مثل Alchemy أو Infura، وغالبًا ما تكون طبقتهم المجانية كافية للتطبيقات الصغيرة، بينما الإنتاج يتطلب اشتراكات شهرية.

اختبار واجهة برمجة تطبيقات ميتا ماسك باستخدام Apidog

تصحيح التواقيع في المتصفح معقد بسبب تداخل الإضافة، الصفحة، وأحيانًا الروابط العميقة للجوال. هنا يأتي دور Apidog كأداة اختبار للمطورين: اختبر نقاط نهاية JSON-RPC مباشرة، تحقق من eth_chainId وeth_getBalance، واحتفظ بكامل التدفق كمجموعة اختبار.

استورد مواصفات Ethereum JSON-RPC.
اضبط عنوان عقدتك كمتغير بيئة.
استفد من محاكاة الاستجابات لاختبار الواجهة الأمامية بدون عقد ذكي جاهز.
شغّل الاختبارات في CI وفشّل البناء في حال تغيّر الاستجابة.

لشرح أفضل حول اختبار واجهات التطبيقات بدون Postman، راجع دليلنا: اختبار API بدون Postman في 2026.

حمل Apidog للبدء.

الأسئلة الشائعة

هل تعمل MetaMask API على الجوال؟

نعم. استخدم SDK ميتا ماسك للتوصيل بالتطبيق الجوال بنفس واجهة المزود. للمقارنة مع SDKs أخرى، راجع ملخص أفضل APIs للمحافظ.

ما الفرق بين eth_sign وpersonal_sign وeth_signTypedData_v4?

eth_sign يوقع البايتات الخام (غير آمن). personal_sign يضيف بادئة للرسائل. eth_signTypedData_v4 يوقع بيانات EIP-712 المنظمة ويعرضها للمستخدم. استخدم الأخيرين، وتجنب eth_sign.

هل أحتاج لمفتاح API منفصل من ميتا ماسك؟

لا. المزود مجاني ولا يتطلب مفتاح. ستحتاج فقط مفتاحًا لمزود RPC مثل Infura أو Alchemy.

هل يمكنني استخدام ethers.js أو viem مع ميتا ماسك؟

نعم، كلاهما يدعم مزود window.ethereum مباشرة. استخدم BrowserProvider(window.ethereum) في ethers v6 أو createWalletClient({ transport: custom(window.ethereum) }) في viem.

ماذا لو كان لدى المستخدم عدة محافظ مثبتة؟

يدعم ميتا ماسك EIP-6963 لاكتشاف جميع المحافظ المثبتة. مكتبات مثل Wagmi وRainbowKit تدير ذلك تلقائيًا.

هل MetaMask Snaps جاهز للإنتاج؟

نعم، أصبح Snaps متاحًا للجميع في 2024. أبرز الاستخدامات: دعم سلاسل غير EVM، تنبيهات معاملات مخصصة، وتكامل محافظ الأجهزة.

كيفية استخدام MoonPay API: دمج بوابات الدفع من العملات الرقمية إلى العملات التقليدية والعكس

Yusuf Khalidd — Thu, 23 Apr 2026 07:33:34 +0000

كانت عمليات تحويل العملات الورقية إلى عملات مشفرة (Fiat-to-crypto on-ramps) تعني أسابيع من الأوراق القانونية والعلاقات المصرفية وموردي "اعرف عميلك" (KYC) المُجمعة بصعوبة. تختصر واجهة برمجة تطبيقات MoonPay هذه العملية في تكامل واحد: تقوم بإنشاء عنوان URL موقع، وتضع أداة واجهة المستخدم (widget) في تطبيقك، ويتولى MoonPay معالجة البطاقات، والتحويلات المصرفية، والتحقق من الهوية، والمدفوعات إلى محفظة المستخدم.

جرّب Apidog اليوم

يشرح هذا الدليل كيفية استخدام واجهة برمجة تطبيقات MoonPay من البداية إلى النهاية: إعداد حساب الشريك، واجهة المستخدم (widget) مقابل واجهة برمجة التطبيقات المباشرة، بناء عنوان URL الموقع، التحقق من Webhook، تدفق البيع، الدفع لـ NFT، وحدود الامتثال التي تحتاج إلى التخطيط لها. تم اختبار كل طلب أدناه مقابل بيئة الاختبار (sandbox) وتم توثيقه في بوابة مطوري MoonPay الرسمية. يمكنك تشغيل نفس الاستدعاءات داخل Apidog أثناء قيامك بالبناء.

إذا كنت لا تزال تقارن بين الموفرين، فابدأ بمراجعتنا لأفضل واجهات برمجة تطبيقات تحويل العملات الورقية إلى مشفرة والعكس لترى كيف يتناسب MoonPay مع Transak وRamp وStripe Crypto. يجب على المطورين الذين يقيمون البنية التحتية لحفظ الأصول أيضًا قراءة كيفية استخدام واجهة برمجة تطبيقات Circle للحصول على نظرة على جانب USDC من المكدس.

ملخص سريع

MoonPay بوابة مرخصة لتحويل العملات الورقية إلى مشفرة والعكس وتستخدمها المحافظ وأسواق NFT ومنصات التداول في أكثر من 160 دولة.
مساران للتكامل: SDK/واجهة المستخدم (widget) لـ Ramps (الأسرع، واجهة مستخدم يستضيفها MoonPay) أو REST API المباشرة (تحكم كامل، تبني واجهتك بنفسك).
يجب توقيع جميع عناوين URL الخاصة بالواجهة (widget) باستخدام HMAC-SHA256 بمفتاحك السري؛ عناوين URL غير الموقعة تُرفض في الإنتاج.
تعالج MoonPay عمليات KYC، ومعالجة البطاقات، والتحويلات البنكية من جانب الخادم؛ تصلك الحالة عبر Webhooks موقعة بنفس نمط HMAC.
التسعير: رسوم معالجة (3.5%-4.5% للبطاقات، أقل للتحويلات البنكية) + رسوم الشبكة، وتظهر بشفافية للمستخدم.
تدفق البيع (off-ramp) مشابه للشراء: عنوان URL موقع، يرسل المستخدم عملة مشفرة إلى عنوان إيداع، تسدد MoonPay العملات الورقية إلى الحساب البنكي للمستخدم.

ما هو MoonPay؟

MoonPay شركة مدفوعات مرخصة تتيح لمستخدميك شراء وبيع العملات المشفرة باستخدام البطاقات، التحويلات البنكية، Apple Pay، Google Pay، SEPA، والتحويلات المحلية. تعمل كشركة خدمات مالية في الولايات المتحدة، ولديها ترخيص EMI في الاتحاد الأوروبي، ومسجلة في المملكة المتحدة وكندا وأستراليا. عمليًا: لست بحاجة لأن تصبح محول أموال لقبول البطاقات وتسليم ETH لمحفظة المستخدم.

تدعم المنصة أكثر من 110 عملة مشفرة عبر 40+ شبكة (Ethereum، Solana، Bitcoin، Polygon، Base، Arbitrum) ودعم دفع NFT. MoonPay هي بوابة الشراء في MetaMask، Trust Wallet، وOpenSea.

المصادقة والإعداد

سجّل حساب شريك في moonpay.com/business. بعد الموافقة تحصل على مفاتيح بيئة اختبار (sandbox) ومفاتيح إنتاج (production): مفتاح عام (pk_test_...) ومفتاح سري (sk_test_...). المفتاح السري يوقع كل عنوان URL ويتحقق من Webhook.

export MOONPAY_API_KEY="pk_test_123..."
export MOONPAY_SECRET_KEY="sk_test_abc..."
export MOONPAY_BASE_URL="https://api.moonpay.com"

بيئة الاختبار (sandbox) لها نفس نقاط النهاية الخاصة بالإنتاج وتعيد معاملات اختبار يمكن تغيير حالتها من لوحة التحكم. استخدمها لتطوير المسار السعيد، ثم انتقل لمفاتيح الإنتاج بعد الموافقة النهائية من MoonPay.

نقاط النهاية الأساسية

MoonPay تقدم عدة مجموعات من نقاط النهاية: العملات، الأسعار، المعاملات، وWebhooks. راجع المرجع الكامل لـ REST API لكل مورد.

سرد العملات المدعومة

للحصول على قائمة العملات المدعومة مباشرة:

curl -X GET "https://api.moonpay.com/v3/currencies" \
  -H "Authorization: Api-Key $MOONPAY_API_KEY"

الرد يتضمن code، name، type (crypto أو fiat)، minBuyAmount، maxBuyAmount، وبيانات الشبكة للرموز على عدة سلاسل. قم بتصفية العملات حسب بلد المستخدم باستخدام عنوان IP أو الموقع.

الحصول على عرض سعر في الوقت الفعلي

للحصول على عرض سعر دقيق:

curl -X GET "https://api.moonpay.com/v3/currencies/eth/buy_quote?apiKey=$MOONPAY_API_KEY&baseCurrencyAmount=100&baseCurrencyCode=usd" \
  -H "Content-Type: application/json"

النتيجة تتضمن quoteCurrencyAmount، feeAmount، networkFeeAmount، وtotalAmount. خزن العرض مؤقتًا لفترة قصيرة لأن MoonPay يحترم السعر لـ 60 ثانية تقريبًا.

بناء عنوان URL موقع لواجهة شراء (Node)

لإنشاء buy widget موقع (Node.js):

import crypto from "node:crypto";

function buildMoonPayBuyUrl({ walletAddress, currencyCode, baseAmount, email }) {
  const params = new URLSearchParams({
    apiKey: process.env.MOONPAY_API_KEY,
    currencyCode,
    walletAddress,
    baseCurrencyCode: "usd",
    baseCurrencyAmount: String(baseAmount),
    email,
    redirectURL: "https://yourapp.com/moonpay/complete",
  });

  const originalUrl = `https://buy.moonpay.com?${params.toString()}`;

  const signature = crypto
    .createHmac("sha256", process.env.MOONPAY_SECRET_KEY)
    .update(new URL(originalUrl).search)
    .digest("base64");

  return `${originalUrl}&signature=${encodeURIComponent(signature)}`;
}

مرر هذا العنوان للمستخدم. التوقيع يربط المعلمات بحسابك ويمنع العبث. راجع دليل بدء التشغيل السريع لواجهة الشراء.

التحقق من توقيعات Webhook

تحقق من Webhook باستخدام HMAC-SHA256 قبل الوثوق بالبيانات:

import crypto from "node:crypto";

export function verifyMoonPayWebhook(rawBody, header, secret) {
  const [tPart, sPart] = header.split(",");
  const timestamp = tPart.split("=")[1];
  const signature = sPart.split("=")[1];

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex"),
  );
}

ارفض أي طلب أقدم من 5 دقائق. راجع مرجع Webhook لكل نوع حدث.

تدفق البيع (Off-ramp)

لتدفق البيع، أنشئ عنوان URL موقع يشير إلى sell.moonpay.com:

const sellParams = new URLSearchParams({
  apiKey: process.env.MOONPAY_API_KEY,
  baseCurrencyCode: "eth",
  baseCurrencyAmount: "0.5",
  quoteCurrencyCode: "usd",
  refundWalletAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbc",
});

const sellUrl = `https://sell.moonpay.com?${sellParams.toString()}`;
// وقّع بنفس طريقة عنوان الشراء

refundWalletAddress ضروري لإرجاع الأموال في حال فشل الصفقة أو إرسال أصل خاطئ.

دفع NFT

لدعم شراء NFT بالبطاقة، سجّل القائمة في MoonPay أو استخدم تكامل سوق مدعوم، ثم أنشئ عنوان URL موقع مع contractAddress، tokenId، و listingId. MoonPay يتكفل بالجانب الورقي والتحويل على السلسلة بعملية واحدة.

الأخطاء الشائعة وحدود المعدل

400 invalid_signature: إدخال HMAC لا يطابق ما يتوقعه الخادم. غالبًا بسبب اختلاف ترميز URL. وقّع السلسلة الدقيقة لطلبك.
403 geo_restricted: عنوان IP المستخدم في بلد محظور. تحقق من isAllowed في كائن العملة.
422 transaction_limit_exceeded: المستخدم تجاوز الحدود اليومية/الأسبوعية/الشهرية. عادةً بطاقات 2000$/يوم و 10000$/شهر حتى يكمل KYC المعزز.
429 rate_limited: حوالي 100 طلب/دقيقة لكل مفتاح API لنقاط النهاية العامة. استخدم التخزين المؤقت بكثافة.

اعتمد على Webhook لتحديث الحالة، وليس متصفح المستخدم فقط. حتى لو أغلق المستخدم الصفحة قبل إعادة التوجيه، تعتبر العملية مكتملة عندما يصلك transaction_updated بالحالة completed.

إذا كنت تدعم محافظ متعددة، راجع أدلتنا حول كيفية استخدام MetaMask API و أفضل واجهات برمجة تطبيقات المحافظ المشفرة. ولمتطلبات KYC، راجع أفضل واجهات برمجة تطبيقات KYC.

تسعير MoonPay

مشتريات البطاقات: 3.5%-4.5% من المبلغ الورقي، بحد أدنى 3.99$.
التحويل المصرفي (ACH، SEPA، الخدمات المصرفية المفتوحة): 1%-1.9%، أرخص لمبالغ كبيرة.
رسوم الشبكة: حسب السلسلة والازدحام، تمرر بالتكلفة.
تدفق البيع: هيكل مشابه مع رسوم دفع حسب الطريقة.

عمليات التكامل ذات الحجم الكبير تحصل عادةً على تسعير مخصص وجهة اتصال للامتثال.

اختبار MoonPay باستخدام Apidog

عناوين URL الموقعة وWebhooks أكثر نقاط MoonPay تعقيدًا، وتصحيحها أسرع في عميل API مناسب مثل Apidog. يمكنك استيراد مواصفات OpenAPI الخاصة بـ MoonPay، وتخزين مفاتيح بيئة الاختبار كمتغيرات، وتجربة دورة كاملة من "الحصول على سعر الشراء"، و"حالة المعاملة"، و"إعادة تشغيل Webhook" دون الحاجة لتغيير الكود الخلفي.

خطوات عملية: أنشئ بيئة Apidog لـ sandbox وأخرى لـ production، برمج إنشاء التوقيع كخطاف ما قبل الطلب باستخدام مقتطف Node أعلاه، واحفظ معرفات المعاملات النموذجية كمتغيرات. عند وصول Webhook في الإنتاج، انسخ النص الخام لخادم Apidog الوهمي وأعد تشغيله مقابل نقطة النهاية المحلية حتى ينجح التحقق. قم بتنزيل Apidog للحصول على كل هذه الأدوات في مكان واحد.

الأسئلة الشائعة

هل أحتاج إلى بائع KYC خاص بي بالإضافة إلى MoonPay؟ لا. MoonPay يدير التحقق من الهوية بالكامل من جانب الخادم؛ تطبيقك لا يرى وثيقة تعريف المستخدم. إذا رغبت في تسريع التحقق لأغراض أخرى، راجع مقارنة أفضل واجهات KYC.

هل يمكنني استخدام MoonPay دون عرض واجهتهم ذات العلامة التجارية؟ نعم عبر REST API المباشرة أو SDK بدون واجهة مستخدم، لكن يتطلب ذلك مراجعة امتثال إضافية. معظم الفرق تبدأ بالواجهة الجاهزة أولاً.

ما هي الدول التي يدعمها MoonPay؟ أكثر من 160 دولة للشراء وحوالي 50 للبيع، مع اختلاف العملات وطرق الدفع حسب المنطقة. تحقق من نقطة نهاية العملات لأي موقع مستخدم.

كم تستغرق المعاملة؟ مشتريات البطاقات تصل لمحفظة المستخدم خلال أقل من 5 دقائق. التحويلات البنكية من يوم إلى 3 أيام عمل. معاملات البيع تسدد بالعملات الورقية خلال 1-3 أيام بعد التأكيد على السلسلة.

ماذا يحدث إذا فشل تسليم Webhook؟ MoonPay يعيد المحاولة بتدرج أسي حتى 24 ساعة. أرجع استجابة 2xx فقط بعد حفظ الحدث، وتجنب التكرار بالتحقق من id.

هل بيئة الاختبار (sandbox) مكافئة للإنتاج؟ قريبة، لكن ليست متطابقة. القيود الجغرافية أخف، KYC يتم تجاوزه بوثائق اختبار، وتنتقل الحالات عبر لوحة التحكم. اختبر دائماً الإنتاج قبل الإطلاق النهائي.

كيفية استخدام واجهة برمجة تطبيقات Plaid: دليل المطور 2026

Yusuf Khalidd — Thu, 23 Apr 2026 07:33:00 +0000

تطبيقات التكنولوجيا المالية اليوم غالبًا ما تعتمد على مزودي الطرف الثالث مثل Plaid لربط الحسابات المصرفية وتحويل بيانات الاعتماد إلى JSON قابل للاستهلاك. Plaid يدعم ربط الحسابات، فحص الرصيد، سجل المعاملات، والتحقق من الهوية لآلاف التطبيقات (Venmo, Robinhood, Chime وغيرها).

جرّب Apidog اليوم

في هذا الدليل ستتعلم، كمطور، كيفية تنفيذ Plaid خطوة بخطوة: من استخراج المفاتيح، إلى تدفق توليد رموز الربط (Link token flow)، وأهم المنتجات التي يجب تفعيلها، وكيفية التعامل مع الأخطاء الأكثر شيوعًا في الإنتاج. ستجد أيضًا خطوات عملية لاختبار كل مرحلة باستخدام Apidog لتقليل التخمين في تكوين الطلبات. للمزيد من التفاصيل التقنية، راجع التوثيق الرسمي لـ Plaid أثناء التنفيذ.

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

TL;DR

Plaid يربط تطبيقك بأكثر من 12,000 بنك في أمريكا الشمالية وأوروبا.
تتوفر ثلاث بيئات: sandbox (مجانية بالكامل)، development (100 عنصر حي مجانًا)، production (دفع حسب الاستخدام).
تدفق الربط: إنشاء link_token (خادم)، تشغيل Plaid Link (عميل)، تبادل public_token بـ access_token (خادم)، استدعاء نقاط النهاية.
المنتجات الأساسية: Auth، Balance، Transactions، Identity، Investments، Liabilities، Income — فعّل ما تحتاجه لكل عنصر.
الأخطاء الأكثر شيوعًا: ITEM_LOGIN_REQUIRED و INVALID_CREDENTIALS. استخدم الـ webhooks لمتابعة الحالة.
حدود المعدل لكل عنصر ولكل عميل. اعتمد على webhooks بدل الاستقصاء المباشر.

ما هو Plaid؟

Plaid هو وسيط تقني بين تطبيقك والبنوك. عندما يدخل المستخدم بيانات البنك عبر Plaid Link، يقوم Plaid بجلب البيانات وتحويلها إلى JSON موحد، دون أن تتعامل أنت مباشرة مع بيانات الاعتماد.

أنت تتعامل مع عنصر (Item) لكل اتصال ببنك. تحصل على access_token يسمح لك بجلب بيانات الحسابات، الأرصدة، وهكذا. عنصر واحد قد يشمل عدة حسابات (جاري، توفير، بطاقة ائتمان).

Plaid يدعم حسابات الأفراد، البطاقات، القروض، الاستثمارات، والرواتب. لا ينفذ عمليات تحويل أموال – لعمليات ACH ستحتاج إلى ربط Plaid Auth مع مزود دفع خارجي. راجع مقالنا حول أفضل واجهات برمجة تطبيقات دفع ACH لمعرفة تفاصيل الربط.

المصادقة والإعداد

الخطوة 1: إنشاء حساب مطور Plaid

سجّل في plaid.com وفعل بريدك الإلكتروني.
ستجد ثلاث بيئات:
- Sandbox: بيانات وهمية، مجانية. استخدم user_good/pass_good.
- Development: اتصال حقيقي، حتى 100 عنصر مجاني.
- Production: غير محدود، فوترة حسب الاستخدام.

الخطوة 2: احصل على مفاتيحك

من لوحة التحكم: Team Settings > Keys.
ستحتاج:
- client_id: ثابت لكل البيئات.
- secret: يختلف حسب البيئة.
خزنها في متغيرات بيئة، لا ترفعها أبدًا إلى git.

الخطوة 3: تثبيت حزمة SDK

npm install plaid

الخطوة 4: تهيئة العميل

import { Configuration, PlaidApi, PlaidEnvironments } from 'plaid';

const config = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
      'PLAID-SECRET': process.env.PLAID_SECRET,
    },
  },
});

const client = new PlaidApi(config);

عند الترقية للبيئة التالية استبدل PlaidEnvironments.sandbox بـ development أو production.

نقاط النهاية الأساسية

تدفق رمز الربط (Link token)

إنشاء link_token (خادم):

const response = await client.linkTokenCreate({
  user: { client_user_id: 'user_123' },
  client_name: 'Your App',
  products: ['auth', 'transactions'],
  country_codes: ['US'],
  language: 'en',
});

const linkToken = response.data.link_token;

curl -X POST https://sandbox.plaid.com/link/token/create \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "secret": "YOUR_SANDBOX_SECRET",
    "user": { "client_user_id": "user_123" },
    "client_name": "Your App",
    "products": ["auth", "transactions"],
    "country_codes": ["US"],
    "language": "en"
  }'

فتح Plaid Link (عميل): أرسل link_token للواجهة الأمامية، مرره إلى SDK. بعد تسجيل المستخدم دخوله، ستحصل على public_token في onSuccess.
تبادل public_token (خادم):

const exchange = await client.itemPublicTokenExchange({
  public_token: publicToken,
});

const accessToken = exchange.data.access_token;
const itemId = exchange.data.item_id;

استخدام access_token لاستدعاء نقاط النهاية:

const accounts = await client.accountsGet({ access_token: accessToken });
const balance = await client.accountsBalanceGet({ access_token: accessToken });

نقاط نهاية المنتج التي يجب أن تعرفها

Auth: أرقام الحسابات والتوجيه لـ ACH (/auth/get).
Balance: أرصدة لحظية (/accounts/balance/get).
Transactions: حتى 24 شهر من بيانات المعاملات (/transactions/sync).
Identity: بيانات صاحب الحساب (اسم، بريد، هاتف، عنوان) (/identity/get). في حالات KYC، قارن مع خدمات KYC الأخرى.
Investments: مقتنيات ومعاملات الاستثمار (/investments/holdings/get).
Liabilities: قروض الطلاب، بطاقات الائتمان، الرهون (/liabilities/get).
Income: بيانات الرواتب (/credit/payroll_income/get).

اختبار واجهة برمجة تطبيقات Plaid باستخدام Apidog

خطوة الربط (Link) تحدث في المتصفح، لكن اختبار نقاط النهاية الخلفية بشكل موثوق يتطلب أدوات متخصصة. Apidog يسهّل عليك ذلك:

استورد مواصفات OpenAPI الخاصة بـ Plaid إلى Apidog، وستجد كل نقاط النهاية مُهيأة مسبقًا مع الأمثلة والرؤوس الصحيحة.
أنشئ مجموعة متغيرات بيئة (sandbox, production)، حدد client_id، secret، access_token.
استخدم التسلسل (chaining) لتشغيل linkTokenCreate → sandboxPublicTokenCreate → itemPublicTokenExchange → accountsGet بدون متصفح.
استعمل الخادم الوهمي في Apidog لتوفير استجابات جاهزة لـ /accounts/get قبل اكتمال تكاملك الخلفي.
راجع دليلنا حول اختبار API بدون Postman للترحيل، أو حمّل Apidog وابدأ فورًا.

الأخطاء الشائعة وحدود المعدل

تظهر أخطاء Plaid مع error_type، error_code، error_message. عالج الأخطاء التالية تحديدًا:

INVALID_CREDENTIALS: كلمة مرور خاطئة. أعد ربط الحساب عبر وضع التحديث.
ITEM_LOGIN_REQUIRED: جلسة المستخدم منتهية (تغيير كلمة مرور البنك أو مصادقة ثنائية). أعد تشغيل Plaid Link في وضع التحديث، وتابع الـ webhook.
RATE_LIMIT_EXCEEDED: تجاوزت الحد. استخدم retry مع jitter.
PRODUCT_NOT_READY: البيانات قيد التحميل. أعد المحاولة بعد webhook INITIAL_UPDATE.

Webhooks

أرسل عنوان الـ webhook عند إنشاء link_token وسيقوم Plaid بإرسال تحديثات POST.
أهم webhooks: SYNC_UPDATES_AVAILABLE (معاملات جديدة)، ITEM: LOGIN_REQUIRED (إعادة مصادقة)، ITEM: ERROR (فشل دائم).
تحقق دائمًا من توقيع JWT قبل أي إجراء.

حدود المعدل

كل نقطة نهاية لها حد معدل لكل عنصر ولكل عميل.
مثال: /accounts/balance/get = 5 استدعاءات/دقيقة/عنصر في الإنتاج.
القواعد العملية: اعتمد على webhooks، خزّن الأرصدة مؤقتًا، لا تستدعي Plaid مباشرة في مسارات المستخدم.

تسعير Plaid

Sandbox: مجاني وغير محدود.
Development: مجاني حتى 100 عنصر.
Production:
- Auth: حوالي 1.50$ لكل حساب مرة واحدة.
- Balance/Identity: تسعير لكل استدعاء.
- Transactions: اشتراك شهري لكل عنصر (~0.30$).
- Investments/Liabilities/Income: رسوم منفصلة لكل عنصر.

أسعار Plaid تفاوضية عند الأحجام الكبيرة. راجع صفحة المنتجات الرسمية للأرقام الأحدث.

الأسئلة الشائعة

مدة صلاحية access_token؟ غير محدودة حتى يتم الإلغاء من المستخدم أو البنك. خزّنه مشفرًا.
هل يمكن استخدام Plaid للتحقق من الهوية فقط؟ نعم، عبر Identity، لكن لغرض KYC راجع أيضًا مقارنة Stripe Identity.
هل Plaid يدعم دول خارج أمريكا؟ نعم: أمريكا، كندا، المملكة المتحدة، الاتحاد الأوروبي. تحقق من دعم كل منتج عند استدعاء /link/token/create.
ماذا لو غيّر المستخدم كلمة مرور البنك؟ يتحول العنصر إلى ITEM_LOGIN_REQUIRED وتستقبل webhook. شغّل Plaid Link في وضع التحديث.
هل يمكن اختبار تدفق Link بدون متصفح؟ نعم، استخدم /sandbox/public_token/create لاسترجاع public_token في اختبارات التكامل.
كيف أستخدم Plaid في بيئة تطوير محلية؟ ضع بيانات sandbox في .env، اربط التطبيق على PlaidEnvironments.sandbox، واستخدم tunneling (ngrok أو Cloudflare Tunnel) لاستقبال webhooks.

كيفية استخدام Grok Imagine API مجانًا: دليل خطوة بخطوة

Yusuf Khalidd — Thu, 23 Apr 2026 05:54:17 +0000

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

جرب Apidog اليوم

ما هي Grok Imagine API؟ القدرات الرئيسية

تحويل النص إلى فيديو (T2V): حول نصوصك إلى مقاطع فيديو قصيرة واقعية.
تحويل الصورة إلى فيديو (I2V): حرك صورة واحدة بإضاءة وعمق واقعي.
صوت متزامن: أضف صوتًا تلقائيًا متوافقًا مع الفيديو.
أوضاع إبداعية: اختر بين الوضع القياسي أو Spicy لمخرجات أكثر تعبيرًا.
توليد سريع وجودة عالية: نتائج فورية تصلح للنماذج الأولية أو العروض.

كيفية الوصول إلى Grok Imagine API مجانًا: مقارنة سريعة

المنصة	تفاصيل الوصول المجاني	الحصص والحدود	مفتاح API مطلوب	ميزات فريدة	الأفضل لـ
Kie.ai	أرصدة تجريبية مجانية عند التسجيل	قد تنتهي صلاحية الأرصدة؛ تتوفر ترقيات مدفوعة	لا (واجهة ويب)	تحويل النص إلى فيديو، تحويل الصورة إلى فيديو، مزامنة الصوت، وضع Spicy	الاستخدام بدون برمجة، النمذجة السريعة
Puter.js	لا تكلفة للمطورين؛ نموذج دفع المستخدم	غير محدود للمطورين؛ تكاليف الاستخدام تُحاسب للمستخدمين النهائيين	لا	تكامل JavaScript، لا يتطلب إعداد خادم، يدعم Grok 4.20	تطبيقات الويب، مشاريع JS، اختبار API السريع
fal.ai	أرصدة/عروض ترويجية مجانية لـ API من حين لآخر	محدودة بالعروض الترويجية/الأرصدة؛ خطط مدفوعة للتوسع	نعم	التكامل مع نماذج الذكاء الاصطناعي المتنوعة	التجريب مع عدة ذكاءات اصطناعية
xAI Playground	استخدام محدود مجاني (قد يتطلب التسجيل)	حصص صارمة؛ للعرض التجريبي/الاختبار فقط	ربما	ميزات رسمية ومحدثة	اختبار أحدث ميزات Grok

للاستخدام السريع وبدون برمجة: Kie.ai.
للتكامل البرمجي والتجربة غير المحدودة: Puter.js.
لتجربة API أو التعامل مع عدة نماذج: fal.ai.

الخيار 1: استخدام Grok Imagine API مجانًا عبر Kie.ai

الميزات الرئيسية في Kie.ai

تحويل النص أو الصورة إلى فيديو بسهولة تامة.
صوت متزامن يُولد تلقائيًا مع كل فيديو.
أوضاع Standard وSpicy لإبداع مختلف.
سير عمل سريع وواجهة ويب مباشرة.

خطوات عملية لاستخدام Grok Imagine API مجاناً على Kie.ai

انتقل إلى قسم Grok Imagine في Kie.ai.
أنشئ حسابًا مجانيًا (بريد إلكتروني أو وسائل التواصل).
اطلب أرصدة مجانية — تمنحك القدرة على توليد عدد محدود من المقاطع.
اختر نوع التوليد:
- تحويل النص إلى فيديو: أدخل مطالبتك (مثال: "مدينة مستقبلية عند الغروب").
- تحويل الصورة إلى فيديو: ارفع صورتك واضبط الإعدادات.
اختر الوضع الإبداعي (Standard أو Spicy).
اضغط على زر التوليد وانتظر النتيجة.
حمّل أو شارك الفيديو حسب حاجتك.

نصيحة: جرّب أكثر من وضع وغيّر صياغة المطالبات لتحسين النتائج. إذا نفدت الأرصدة، استخدم الإحالة أو جرب منصة أخرى.

الخيار 2: استخدام Grok Imagine API مجانًا عبر Puter.js

إذا كنت مطورًا وتريد دمج Grok Imagine API بدون تكاليف أو الحاجة لمفاتيح API، استخدم Puter.js.

مميزات Puter.js:

بدون مفاتيح API أو إعداد خوادم.
وصول غير محدود للمطورين.
دعم أحدث نماذج Grok (مثل 4.20).
مكتبة JS للعميل - مثالية لتطبيقات الويب.

خطوات عملية لدمج Grok Imagine API مع Puter.js

تثبيت Puter.js
- عبر npm:
```
 npm install @heyputer/puter.js
```

أو عبر CDN:

 <script src="https://js.puter.com/v2/"></script>

مثال استخدام أساسي (تحويل نص إلى فيديو أو محادثة):

   // مثال: توليد نص فيديو Grok ذكي
   puter.ai.chat(
       "اكتب نصًا قصيرًا لفيديو عن الكلاب التي تعمل بالذكاء الاصطناعي.",
       {model: 'x-ai/grok-4.20'}
   ).then(response => {
       puter.print(response.message.content);
   });

للتفاعلات المتقدمة أو Streaming: راجع توثيق Puter.js.
لا حاجة لمفتاح API أو فواتير: ابدأ فورًا.

نصيحة متقدمة: استخدم Apidog لمحاكاة (api-mocking) واختبار (api-testing) تكاملاتك قبل الإطلاق لضمان الوثوقية.

الخيار 3: استخدام Grok Imagine API مجانًا عبر fal.ai

يفضل بعض المطورين fal.ai لمرونته وتركيزه على API.

خطوات استخدام Grok Imagine API مجاناً على fal.ai

سجّل في fal.ai.
استرد الأرصدة المجانية (عروض ترويجية أو دعوات تجريبية).
حدد نموذج Grok Imagine API من المكتبة.
احصل على مفتاح API الخاص بك.
نفذ استدعاءات API عبر Python أو أي عميل HTTP.

مثال بايثون:

import requests
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {
    "prompt": "قط يرقص السالسا في زقاق مضاء بالنيون.",
    "mode": "video"
}
response = requests.post("https://fal.ai/api/grok-imagine", json=data, headers=headers)
print(response.json())

ملاحظة: الأرصدة المجانية محدودة. اختبر سيناريوهاتك باستخدام أدوات مثل Apidog لتوفير الأرصدة.

أمثلة عملية: مشاريع إبداعية باستخدام Grok Imagine المجاني

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

نصائح لاستكشاف الأخطاء وإصلاحها عند استخدام Grok Imagine API مجاناً

نفدت الأرصدة؟ جرب الإحالة أو التبديل بين المنصات (مثل التبديل من Kie.ai إلى Puter.js).
المخرجات ضعيفة الجودة؟ حسّن مطالبتك، وجرّب أوضاع مختلفة.
مشكلات فنية؟ امسح ذاكرة التخزين المؤقت للمتصفح أو تحقق من مطابقة بيانات الإدخال لمخطط API (استعن بـ Apidog للتحقق).
أخطاء تكامل؟ استخدم خادم Apidog الوهمي لمحاكاة استجابات Grok Imagine API دون استنزاف الأرصدة.

كيف يساعدك Apidog في تسريع العمل مع Grok Imagine API

أتمتة اختبارات Grok Imagine API: تحقق من نتائج المطالبات وحمولات البيانات تلقائيًا.
خادم وهمي: محاكاة استجابات Grok Imagine قبل استهلاك حصصك المجانية.
التحقق من المخطط: تأكد من أن الطلبات والاستجابات تتوافق مع مواصفات Grok Imagine.
اختبار الأداء: اختبر تطبيقك تحت أحمال مختلفة لضمان الاستقرار.

الحصص المجانية ثمينة—استخدم Apidog لاكتشاف المشكلات مبكرًا وتعظيم كفاءة سير عملك.

الخاتمة: أطلق العنان لإبداعك مع الوصول المجاني إلى Grok Imagine API

معرفة كيفية استغلال Grok Imagine API مجانًا تمنحك فرصًا تقنية وإبداعية واسعة. جرّب الطرق الثلاث: Kie.ai (بدون برمجة)، Puter.js (تكامل برمجي)، fal.ai (REST API)، وحدد الأنسب لسير عملك.

اختبر جميع المنصات وحدد ما يناسب احتياجك.
اعتمد على Apidog لتسريع اختبار وتكامل الـ APIs.
جرب، غيّر، وابتكر—Grok Imagine يمنحك إمكانيات غير محدودة.

هل أنت مستعد لتحويل أفكارك إلى واقع؟ ابدأ الآن وفعّل Grok Imagine API مجانًا!

أفضل واجهات برمجة تطبيقات (API) للصيرفة المفتوحة لعام 2026

Yusuf Khalidd — Thu, 23 Apr 2026 04:27:44 +0000

لقد تطورت الخدمات المصرفية المفتوحة من كونها مطلبًا تنظيميًا إلى عنصر أساسي في بنية التطبيقات المالية الحديثة. إذا كنت تطور بنكًا رقميًا (neobank)، منتج إقراض، أو برنامجًا لإدارة الأموال، فأنت بحاجة إلى ربط موثوق لآلاف البنوك عبر مناطق تنظيمية مختلفة. اختيار واجهة برمجة التطبيقات (API) المناسبة سيحدد تغطيتك البنكية، تجربة المصادقة للمستخدم (UX)، متطلبات الامتثال، وتكاليفك التقنية على المدى الطويل.

جرّب Apidog اليوم

في عام 2026، لم يعد المشهد مجرد "Plaid مقابل البقية". أوروبا تعتمد PSD2 والمدفوعات من حساب لحساب. المملكة المتحدة انتقلت إلى التمويل المفتوح. في الولايات المتحدة هناك مزيج من السحب المباشر (screen scraping)، وواجهات API، ومعايير FDX، مع دفع CFPB 1033 نحو قابلية التشغيل البيني. أستراليا لديها CDR. كل نظام يؤثر على ما يمكن أن يقدمه مزود الخدمة في كل منطقة.

هذا الدليل يقدم مقارنة عملية بين أهم مزودي واجهات برمجة تطبيقات الخدمات المصرفية المفتوحة ويركّز على المعايير الجوهرية، مع خطوات واضحة لاختبارهم باستخدام Apidog. إذا أردت التعمق في مزود معين، اطلع على دليل Plaid API لجانب الولايات المتحدة.

TL;DR (ملخص سريع)

الأفضل لتغطية أمريكا الشمالية: Plaid
الأفضل لتغطية PSD2 الأصلية في أوروبا: Tink (من Visa)
الأفضل لبدء الدفع في المملكة المتحدة وأوروبا: TrueLayer
الأفضل للتغطية الأوروبية الشاملة وبدون واجهة مستخدم: Yapily
الأفضل لتجميع بيانات المؤسسات الكبرى في الولايات المتحدة: Yodlee (Envestnet)
الأفضل لتحليل البيانات والرؤى في الولايات المتحدة: MX
لا يوجد مزود عالمي شامل – غالبًا ستحتاج لمزود أساسي وآخر احتياطي حسب المنطقة.

ما الذي تبحث عنه في أفضل واجهة برمجة تطبيقات للخدمات المصرفية المفتوحة

التغطية الجغرافية والمصرفية: تحقق من عدد البنوك المدعومة في سوقك المستهدف، وركز على أكبر البنوك التي يستخدمها عملاؤك.
اتساع المنتج: هل تحتاج بيانات حسابات فقط أم معاملات، رصيد، هوية، دخل، استثمارات، مدفوعات؟ تحقق من دعم كل منتج وأسعاره.
تدفق المصادقة: راجع كيف تتم مصادقة المستخدم (OAuth، إعادة توجيه، جلسات، إعادة اتصال)، وتأثيرها على تجربة المستخدم.
البصمة التنظيمية: هل المزود يحمل تراخيص (AISP/PISP) أم تحتاج لترخيصك؟ تحقق من الامتثال في منطقتك.
نموذج التسعير: لكل مستخدم، حساب، استدعاء API، أو دفعة. اسأل عن الأسعار حسب التزامك وحجمك.
تجربة المطور: جودة SDK، البيئة التجريبية (sandbox)، موثوقية الويب هوك، وسهولة بدء الربط.
وقت التشغيل والدعم: راقب صفحات الحالة، الاتفاقيات (SLA)، وجود قنوات دعم مباشرة.

جدول المقارنة

المزود	المنطقة الأساسية	بدء الدفع	منتجات البيانات	نموذج التسعير	الأفضل لـ
Plaid	الولايات المتحدة، كندا، المملكة المتحدة، الاتحاد الأوروبي	نعم (Plaid Transfer، PIS محدود)	المصادقة، المعاملات، الهوية، الدخل، الاستثمارات، الالتزامات	لكل حساب متصل + لكل منتج	التغطية في أمريكا الشمالية
Tink (Visa)	الاتحاد الأوروبي، المملكة المتحدة	نعم، أصلي لـ PSD2 PIS	معلومات الحساب، التصنيف، فحص الدخل، PIS	مخصص، للشركات	PSD2 شامل لأوروبا
TrueLayer	المملكة المتحدة، الاتحاد الأوروبي	نعم، أكبر حجم PIS	الحسابات، المعاملات، الأرصدة، المدفوعات	لكل دفعة + طبقة بيانات	مدفوعات من حساب إلى حساب في المملكة المتحدة
Yapily	المملكة المتحدة، الاتحاد الأوروبي	نعم، بدون واجهة مستخدم (headless)	الحسابات، المعاملات، الأرصدة، PIS	لكل استدعاء + اشتراك	الخدمات المالية البيضاء (white-label)، الشركات المالية المنظمة
Yodlee	الولايات المتحدة، عالمي	محدود	التجميع، المعاملات، التحقق، بيانات الثروة	للشركات، حسب حجم الاستخدام	المؤسسات المالية الأمريكية الكبيرة
MX	الولايات المتحدة	لا (بيانات فقط)	التجميع، التنظيف، التصنيف، الرؤى	اشتراك + لكل حساب	البنوك والاتحادات الائتمانية التي تحتاج إلى بيانات نظيفة

أفضل مزودي الخدمات المصرفية المفتوحة

Plaid

Plaid هو المعيار المرجعي في أمريكا الشمالية. يغطي أكثر من 12,000 مؤسسة مالية في الولايات المتحدة وكندا والمملكة المتحدة وأجزاء من أوروبا. يوفر منتجات المصادقة (ACH، تحقق الحساب)، المعاملات، الهوية، الدخل، الاستثمارات، والالتزامات. Plaid Transfer يدعم إنشاء مدفوعات ACH، مع توسع تدريجي في أوروبا لدعم PIS.
كيف تبدأ:

أنشئ حسابًا على plaid.com/docs.
استخدم بيئة الاختبار (sandbox) لتجربة ربط الحسابات وسحب بياناتها.
اعتمد على وثائق Plaid للبدء بسرعة – التوثيق واضح ومباشر.

أفضل استخدام: تطبيقات السوق الأمريكي التي تحتاج لربط سريع وواسع بالبنوك.

Tink (من Visa)

Tink منصة أوروبية استراتيجية لدى Visa، تدعم PSD2 بالكامل (AISP/PISP) وتغطي آلاف البنوك في الاتحاد الأوروبي والمملكة المتحدة. منتجاتها تشمل تجميع الحسابات، تصنيف المعاملات، التحقق من الدخل، وبدء الدفع.
خطوات عملية:

ابدأ من docs.tink.com لإنشاء بيئة تطوير.
استورد مواصفات OpenAPI إلى Apidog لاختبار نقاط النهاية.
اختبر تدفق المصادقة وتكامل PIS عبر بيئة الـ sandbox.

أفضل استخدام: الشركات المالية الأوروبية التي تحتاج منصة شاملة للبيانات والمدفوعات.

TrueLayer

TrueLayer متخصصة في المدفوعات من حساب لحساب في المملكة المتحدة وأوروبا، وتدير تدفقات تسجيل وإيداع لتطبيقات التداول والعملات المشفرة. توفر أيضًا بيانات الحسابات والمعاملات بجودة عالية.
كيف تبدأ:

راجع docs.truelayer.com للتهيئة والتكامل.
استخدم بيئة الاختبار لربط حسابات تجريبية وتنفيذ مدفوعات حقيقية.

أفضل استخدام: المنتجات التي تعتمد على مدفوعات بنكية سريعة في المملكة المتحدة وأوروبا.

Yapily

Yapily تقدم API بدون واجهة مستخدم (headless, white-label) ما يمنحك تحكمًا كاملاً في تجربة المصادقة. قوية في تغطية المملكة المتحدة وأوروبا، ومناسبة للمنصات المالية الكبيرة التي ترغب بتخصيص واجهة المستخدم بشكل كامل.
خطوات عملية:

اطلع على docs.yapily.com لقراءة التفاصيل التنظيمية والنقاط التقنية.
صمّم شاشات المصادقة الخاصة بك، واستخدم نقاط نهاية Yapily للربط البنكي وسحب البيانات.

أفضل استخدام: المنصات التي تحتاج API قابل للتخصيص والامتثال التنظيمي الأوروبي.

Yodlee (Envestnet)

Yodlee تدعم تجميع البيانات للبنوك الأمريكية الكبرى، مع تركيز قوي على الشركات والمؤسسات المالية الكبيرة. توفر بيانات ثروات واستثمارات عميقة وتغطية عالمية.
كيف تبدأ:

سجّل في developer.yodlee.com.
استخدم بيئة المطورين لبناء واختبار التكامل على بيانات تجريبية.

أفضل استخدام: البنوك والمؤسسات المالية الكبيرة داخل الولايات المتحدة.

MX

MX منصة أمريكية تركز على تجميع وتنظيف وتصنيف البيانات البنكية، مع منتجات تحليلية مثل اكتشاف المعاملات المتكررة وشعارات التجار.
خطوات البدء:

راجع mx.com للحصول على تفاصيل المنتجات.
ابدأ ببيئة Sandbox لاختبار جودة التصنيف وتنظيف البيانات.

أفضل استخدام: تطبيقات الميزانية والمحاسبة والبنوك التي تهتم بجودة البيانات.

كيف تختار

حدد منطقتك الأساسية أولاً. إذا كان 70% من مستخدميك في منطقة معينة، ابدأ بالمزود الأقوى هناك.
حدد المنتجات المطلوبة (بيانات، مدفوعات، هوية...الخ) وقارن الدعم لدى كل مزود.
وازن بين التسعير وسهولة التكامل وجودة التوثيق.
نفذ اختبار مكثف: سجّل في Sandbox لكل مزود، اربط نفس البنوك التجريبية، وراقب تدفق البيانات والمصادقة أسبوعياً.

اختبار واجهات برمجة تطبيقات الخدمات المصرفية المفتوحة باستخدام Apidog

اختبار تكاملات المصرفية المفتوحة يتطلب التعامل مع إعادة توجيه OAuth، تحديث الرموز، واستدعاءات Webhook. توفير الوقت يكون عبر أدوات مثل Apidog، حيث يمكنك:

استيراد مواصفات OpenAPI لكل مزود.
تخزين المفاتيح والمعرفات كمتغيرات بيئة.
إدارة تدفق OAuth واختبار سحب البيانات دون الحاجة لتطوير واجهة المستخدم في كل مرة.
مقارنة الاستجابات بين مزودين عبر نفس الحسابات البنكية.

مثال عملي:

# استيراد مواصفة OpenAPI لمزود Plaid أو Tink في Apidog
# إعداد بيئة Sandbox
# تنفيذ طلب OAuth وربط حساب تجريبي
# تنفيذ استدعاء لجلب المعاملات ومقارنة النتائج

إذا كنت تقارن أدوات الاختبار، راجع أيضًا دليل اختبار واجهات برمجة التطبيقات بدون Postman. لبدء تجربة Apidog، حمّل Apidog الآن.

الأسئلة الشائعة

هل الخدمات المصرفية المفتوحة هي نفسها PSD2؟
لا، PSD2 هو تنظيم أوروبي يلزم البنوك بفتح واجهات برمجة التطبيقات. الخدمات المصرفية المفتوحة أوسع وتشمل معايير أخرى (Open Banking UK، FDX في الولايات المتحدة، CDR في أستراليا).

هل أحتاج ترخيص AISP أو PISP؟
غالبًا لا في البداية؛ معظم المزودين يعملون كوكلاء بترخيصهم. عند التوسع أو رغبتك بتحكم كامل، قد تحتاج ترخيصك الخاص.

هل يمكنني الاعتماد على مزود واحد عالميًا؟
عمليًا لا. التطبيقات العابرة للحدود غالبًا تستخدم مزودًا أساسيًا وآخر احتياطيًا (مثال: Plaid مع Tink أو Yodlee مع Yapily).

المقارنة مع التحقق عبر البطاقات؟
للتحقق البنكي وإعداد ACH، غالبًا المصرفية المفتوحة أسرع وأرخص من الإيداع الجزئي. لمزيد من التحقق، راجع دليل Stripe Identity وأفضل واجهات برمجة تطبيقات KYC.

كيف يبدو التسعير؟
Plaid ينشر أسعارًا واضحة لكل منتج وحساب. باقي المزودين غالبًا يقدمون أسعارًا مخصصة. توقع 0.30$–2.00$ لكل حساب شهريًا للبيانات، و5–40 نقطة أساس لبدء الدفع.

كيف أختار بين Plaid وTink؟
اتبع توزيع مستخدميك. إذا في أمريكا الشمالية اختر Plaid، في أوروبا اختر Tink. إذا موزعين، اختبر كلاهما مكثفًا.

كيفية استخدام Circle API: مدفوعات USDC، محافظ رقمية، وتحويلات مالية

Yusuf Khalidd — Thu, 23 Apr 2026 04:27:33 +0000

تصدر Circle عملة USDC، ثاني أكبر عملة مستقرة من حيث القيمة السوقية، وتوفر مجموعة من واجهات برمجة التطبيقات (APIs) التي تتيح لك نقل الدولارات عبر السلسلة دون الحاجة إلى بناء بنية تحتية للحضانة أو الامتثال أو الخدمات المصرفية من الصفر. إذا كنت تريد تسوية دفعات الأسواق بسرعة، أو السماح للمستخدمين بالإيداع عبر البطاقة والسحب كـ USDC، أو نقل العملات المستقرة عبر ثماني سلاسل كتل بمكالمة واحدة، فإن واجهة برمجة تطبيقات Circle توفر لك المسار الأسرع للبدء. الوثائق الرسمية متوفرة على developers.circle.com، ومقدمة USDC على circle.com/en/usdc تستحق القراءة قبل البدء.

جرّب Apidog اليوم

في هذا الدليل ستجد خطوات عملية لتطوير تطبيقاتك عبر Circle: إنشاء الحساب، الفرق بين بيئة الاختبار والإنتاج، مصادقة Bearer Token، استخدام نقاط نهاية المدفوعات والمدفوعات الصادرة، إدارة محافظ Circle (Web3)، بروتوكول النقل عبر السلاسل (CCTP)، تشفير سر الكيان للمحافظ التي يتحكم فيها المطور، التكامل مع webhooks، التعامل مع الثباتية (idempotency)، والامتثال لـ KYB. ستجد أوامر curl وNode جاهزة للتنفيذ. للمهتمين بالمقارنة: راجع دليلنا حول أفضل واجهة برمجة تطبيقات (API) لربط العملات الورقية بالرقمية والعكس لمقارنة Circle بالبدائل.

💡ستحتاج إلى عميل API يتعامل مع REST وWeb3 بكفاءة أثناء النمذجة. Apidog يدعم مصادقة Bearer الخاصة بـ Circle، تبديل البيئات، إعادة اختبار الـ webhook ضمن مساحة عمل واحدة، بحيث يمكنك اختبار بيئة الاختبار والإنتاج جنبًا إلى جنب بدون إعادة كتابة الإعدادات.

ملخص سريع

واجهة برمجة تطبيقات Circle (Circle API) تنقسم إلى خدمات: Circle Payments (البطاقات، التحويلات البنكية، ACH)، Circle Mint (إصدار USDC للمؤسسات)، Circle Wallets / W3S (محافظ قابلة للبرمجة)، وCCTP (حرق-وسك USDC عبر السلاسل).
المصادقة تتم باستخدام Bearer Token. مفاتيح الاختبار تبدأ بـ TEST_API_KEY:، مفاتيح الإنتاج بـ LIVE_API_KEY:.
محافظ المطورين تتطلب نصًا مشفرًا (entity secret ciphertext) في كل عملية كتابة.
بروتوكول CCTP ينقل USDC عبر Ethereum، Arbitrum، Base، Optimism، Polygon PoS، Avalanche، Solana وغيرها، عبر عملية burn/mint موثوقة.
موافقة KYB مطلوبة للإنتاج؛ بيئة الاختبار متاحة لأي مطور.
استخدم مفتاح idempotency في كل طلب تغيير، وتحقق من توقيعات webhook عبر المفتاح العام من /notifications/publicKey/get.

ما هي واجهة برمجة تطبيقات Circle (Circle API)؟

Circle شركة مدفوعات منظمة تصدر USDC وتدير البنية التحتية اللازمة. واجهة Circle API تمنحك أربع خدمات أساسية:

Circle Payments API: تقبل البطاقات، ACH، SEPA، التحويلات البنكية، وتستقر كـ USDC في محفظة التاجر.
Circle Payouts API: ترسل تحويلات بنكية أو ACH من رصيد USDC لأي حساب مصرفي مضاف كمستفيد.
Circle Wallets (W3S): إنشاء محافظ حراسة أو محافظ يسيطر عليها المطور على سلاسل متعددة، مع إمكانيات توقيع المعاملات وإدارة الغاز.
CCTP: حرق USDC على السلسلة المصدر وسكه على وجهة أخرى بدون تغليف.

للمقارنة مع بنية Web3 العامة، راجع أفضل API لمحافظ العملات المشفرة ودليل كيفية استخدام Alchemy API.

المصادقة والإعداد

إنشاء حساب: ادخل console.circle.com وسجل حسابك.
البيئات: لديك بيئة اختبار (sandbox) مجانية وبيئة إنتاج (production) تتطلب KYB (مستندات تأسيس، معلومات المالك، حساب تمويل).
مفتاح API: من لوحة التحكم ← المطورين ← مفاتيح API. المفتاح يكون بصيغة:
- الاختبار: TEST_API_KEY:<id>:<secret>
- الإنتاج: LIVE_API_KEY:<id>:<secret>

تمرير المفتاح في الهيدر:

curl https://api-sandbox.circle.com/v1/ping \
  -H "Authorization: Bearer TEST_API_KEY:abc123:xyz789"

روابط API:
- Sandbox: https://api-sandbox.circle.com
- Production: https://api.circle.com
محافظ المطور (W3S): تحتاج إلى سر الكيان (entity secret) (سلسلة 32 بايت hex) تسجلها مرة واحدة في لوحة التحكم، وتستخدم كل مرة نصًا مشفرًا جديدًا (entitySecretCiphertext) مع المفتاح العام لـ Circle (تدوير تلقائي مع Node SDK).

تثبيت SDK:
```
npm install @circle-fin/developer-controlled-wallets
```

نقاط النهاية الأساسية

إنشاء مجموعة محافظ ومحفظة

إنشاء مجموعة محافظ (wallet set)، ثم إنشاء المحافظ داخل المجموعة.

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET,
});

const walletSet = await client.createWalletSet({ name: "payout-set-prod" });

const wallets = await client.createWallets({
  walletSetId: walletSet.data.walletSet.id,
  blockchains: ["ETH-SEPOLIA", "MATIC-AMOY"],
  count: 2,
});

console.log(wallets.data.wallets);

كل محفظة تعيد id وaddress وسلسلة الكتل. موّلها بـ USDC من صنبور الاختبار.

تحويل USDC من محفظة يتحكم فيها المطور

const transfer = await client.createTransaction({
  walletId: wallets.data.wallets[0].id,
  tokenId: "5797fbd6-3795-519d-84ca-ec4c5f80c3b1", // USDC on ETH-SEPOLIA
  destinationAddress: "0xRecipient...",
  amount: ["10.00"],
  fee: { type: "level", config: { feeLevel: "MEDIUM" } },
});

رد العملية يحتوي id لمتابعة حالة المعاملة عبر GET /v1/w3s/transactions/{id} أو عبر webhook.

قبول دفعة بطاقة وتسويتها كـ USDC

curl -X POST https://api-sandbox.circle.com/v1/payments \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "source": { "id": "card_4f1c...", "type": "card" },
    "amount": { "amount": "50.00", "currency": "USD" },
    "verification": "cvv",
    "description": "Order 1093",
    "encryptedData": "<PGP-encrypted card data>",
    "metadata": { "email": "buyer@example.com", "sessionId": "..." }
  }'

ملحوظة: بيانات البطاقة مشفرة بـ PGP باستخدام المفتاح العام لـ Circle (/v1/encryption/public). الرد يعيد id الدفعة، ويمكنك تتبع حالتها.

إرسال دفعة صادرة عبر تحويل بنكي أو ACH

curl -X POST https://api-sandbox.circle.com/v1/payouts \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destination": { "type": "wire", "id": "beneficiary_abc" },
    "amount": { "amount": "500.00", "currency": "USD" },
    "metadata": { "beneficiaryEmail": "vendor@example.com" }
  }'

نقل USDC عبر السلاسل باستخدام CCTP

CCTP بروتوكول عقود ذكية وليس REST endpoint. الخطوات العملية:

استدعي depositForBurn على عقد TokenMessenger في سلسلة المصدر.
راقب https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} حتى تصلك حالة complete وكائن attestation.
استدعي receiveMessage على عقد MessageTransmitter في السلسلة الوجهة مع بيانات الرسالة والتصديق.

ينتج USDC أصلي على السلسلة الوجهة بدون رموز مغلفة.

الـ Webhooks والثباتية (Idempotency)

Circle ترسل POST events (payments, payouts, transfers, chargebacks) إلى أي endpoint HTTPS تقوم بتسجيله عبر /v1/notifications/subscriptions.
كل webhook موقع بمفتاح ECDSA. احصل على المفتاح العام من /v1/notifications/publicKey/get وتحقق من رأس X-Circle-Signature.
كل endpoint قابل للتعديل يتطلب رأس Idempotency-Key (عادة UUID v4). إعادة محاولة نفس الطلب بنفس المفتاح تعيد نفس الرد بدون تكرار العملية.

الأخطاء الشائعة وحدود المعدل

401 Unauthorized: Bearer token ناقص أو خاطئ أو بيئة غير صحيحة.
400 Invalid entity secret ciphertext: النص المشفر أُعيد استخدامه أو تم تشفيره بمفتاح قديم.
429 Too Many Requests: حدود بيئة الاختبار تقريبًا 10 طلبات/ثانية/endpoint؛ في الإنتاج الحدود أعلى حسب الحجم.
Insufficient funds: المحفظة لا تملك USDC كافٍ أو فشلت البطاقة في فحص AVS/CVV.

للمزيد حول بنية البطاقات، راجع أفضل API لإصدار البطاقات.

تسعير واجهة برمجة تطبيقات Circle

بيئة الاختبار مجانية كليًا.
Circle Mint: سك/استرداد USDC للمؤسسات المؤهلة بدون رسوم.
Circle Payments: نسبة مئوية + رسوم ثابتة (عادة 2.9% + 30 سنت، تختلف حسب الحجم).
المدفوعات الصادرة (Wire/ACH): بضعة دولارات لكل معاملة.
W3S Wallets: التسعير لكل محفظة/معاملة (تواصل مع المبيعات).
CCTP: الخدمة مجانية، فقط تدفع رسوم الغاز للسلاسل.

اختبار واجهة برمجة تطبيقات Circle باستخدام Apidog

Circle API تشمل REST، webhooks موقعة، وعقود على السلسلة، لذلك أدوات مثل Postman لا تغطي كل السيناريوهات.
Apidog يستورد مواصفات OpenAPI مباشرة، ويدير رموز Bearer للبيئتين، ويمكنك كتابة نصوص اختبار تربط تدفقات البطاقات والمدفوعات والـ webhooks في تشغيل واحد.
حمل Apidog وحمّل مواصفات Circle من بوابة المطورين. استخدم الخادم الوهمي لمحاكاة webhooks ثم انتقل للإنتاج عند الجاهزية. لمساحات العمل المشتركة، سر الكيان يبقى آمنًا وتدير إصدارات المجموعة بجانب كودك.

الأسئلة الشائعة

هل أحتاج KYB لاختبار Circle API؟

لا، حسابات بيئة الاختبار متاحة لأي بريد إلكتروني. KYB فقط للإنتاج ونقل أموال حقيقية. بيئة الاختبار تقدم صنابير USDC لكل شبكة.

ما الفرق بين Circle Mint ومحافظ Circle؟

Circle Mint بوابة المؤسسات لتحويل الدولار إلى USDC والعكس. Circle Wallets/W3S بنية تحتية للمحافظ والمعاملات للمستخدم النهائي. معظم تطبيقات المستهلك تستخدم المحافظ؛ تطبيقات الخزانة تستخدم Mint. بديل التجزئة: راجع كيفية استخدام MoonPay API.

كيف يتجنب CCTP مخاطر الجسور؟

يتم حرق USDC الأصلي على السلسلة المصدر وسكه جديدًا على الوجهة بتصديق موقع من Circle، بدون مجمع سيولة يمكن استغلاله.

هل يمكن استخدام محافظ Circle بدون حفظ المفاتيح؟

نعم، المحافظ التي يتحكم فيها المستخدم في W3S تستخدم MPC والمصادقة بالـ PIN، والمستخدمون يوقعون عبر SDK. المحافظ التي يتحكم فيها المطور تعتمد على سر الكيان وتوقيع المعاملات في الخلفية.

هل تدعم Circle سلاسل Solana وغير EVM؟

نعم، W3S تدعم Solana وAptos وNEAR، والعديد من L2s. CCTP v2 يدعم Solana بالكامل منذ 2024.

كيف أدير سر الكيان بأمان؟

يمكن تدوير سر الكيان من لوحة التحكم؛ أنشئ سرًا جديدًا وسجله، واعمل بالنصين المشفرين الجديد والقديم فترة الانتقال. SDK يقرأ أي سر معرف في متغير البيئة، فيدعم النشر المتدحرج بسلاسة.

أفضل API لفحص غسيل الأموال لعام 2026

Yusuf Khalidd — Thu, 23 Apr 2026 04:24:57 +0000

لم تعد فحوصات مكافحة غسيل الأموال مجرد إجراء شكلي عند تسجيل المستخدمين. المنظمون في الولايات المتحدة، المملكة المتحدة، الاتحاد الأوروبي، وسنغافورة يطالبون الآن شركات التكنولوجيا المالية، بورصات العملات المشفرة، والأسواق الإلكترونية بفحص العملاء مقابل قوائم العقوبات، الأشخاص المعرضين سياسياً (PEPs)، والإعلام السلبي عند التسجيل وبشكل دوري. أي خطأ في رصد محفظة خاضعة للعقوبات أو أوليغاركي جديد قد يكلفك غرامات ضخمة تهدد عملك التقني.

جرّب Apidog اليوم

لاختيار أفضل واجهة برمجة تطبيقات (API) لفحص مكافحة غسيل الأموال (AML) لعام 2026، يجب الموازنة بين تغطية القوائم، تقليل الإيجابيات الكاذبة، دعم المراقبة المستمرة (webhook)، والحاجة لفحص العملات الورقية أو عناوين العملات المشفرة أو كلاهما. منصة Apidog تعطيك بيئة اختبار (sandbox) لكل مزود لتقييمه فعلياً قبل الالتزام، بينما توفر توصيات FATF 2024 إطاراً تنظيمياً يجب أن يلتزم به كل مزود.

هذا الدليل يقارن ستة مزودين يعتمد عليهم المطورون فعلياً. ستحصل على معايير الاختيار، جدول مقارنة عملي، وملفات تعريف تقنية لمزودي: ComplyAdvantage، Sumsub، Chainalysis، Refinitiv World-Check One، Elliptic، وOnfido AML. عادةً ما يكون فحص AML جزءاً من عملية التحقق من الهوية، لذا إذا لم تكن طبقة KYC لديك جاهزة، راجع ملخص أفضل واجهة برمجة تطبيقات (API) لمعرفة عميلك (KYC) أولاً.

خلاصة القول (TL;DR)

ComplyAdvantage هو الخيار الأمثل القائم على الـ API لشركات التكنولوجيا المالية التي تحتاج فحص عقوبات، PEP، وإعلام سلبي مع تنبيهات webhooks فورية.
Sumsub يجمع بين AML وKYC في SDK واحد، ما يقلل وقت التكامل للمشاريع الجديدة.
Chainalysis وElliptic رائدتا AML للعملات المشفرة؛ اختر Chainalysis للعمق، وElliptic للتحقيقات الأسرع.
Refinitiv World-Check One يملك أعمق قاعدة بيانات عقوبات وPEP، لكنه يتطلب دورة مبيعات مؤسسية.
Onfido AML خيار مثالي إذا كنت تستخدم Onfido بالفعل للتحقق من الهوية.
الأسعار تبدأ من 0.10 دولار لكل فحص وتصل لعقود سنوية بمئات الآلاف للمؤسسات.

ما الذي تبحث عنه في واجهة برمجة تطبيقات (API) لفحص مكافحة غسيل الأموال (AML)

لا يوجد مزود واحد يغطي كل سيناريو. طابق هذه المعايير مع احتياجاتك:

تغطية القوائم: الحد الأدنى يشمل قوائم OFAC، UN، EU، HMT وسجلات العقوبات الوطنية. اسأل عن عدد مصادر PEP ودورية التحديث.
جودة المطابقة والإيجابيات الكاذبة: اختر مزوداً بمعدل إيجابيات كاذبة منخفض (اطلب مقاييس دقة/استدعاء، اختبر ببياناتك عبر sandbox).
مراقبة مستمرة بتنبيهات Webhook: تحتاج فحص يومي وتنبيهات فورية عبر webhooks عند تحديث القوائم.
فحص الإعلام السلبي الذكي: ابحث عن معالجة لغوية وتصنيف حسب المخاطر، وليس مجرد تجميع أخبار.
فحص عناوين الكريبتو: إذا كنت تتعامل مع العملات المشفرة، تحتاج لفحص عناوين المحفظة والمعاملات وليس الأسماء فقط.
النهج التقني: مزود API-first يمنحك sandbox ومواصفات OpenAPI وجاهزية Postman فوراً. تجنب البائعين الذين يفرضون إجراءات يدوية أو تجريبية عبر CSV.
التسعير: الدفع لكل فحص مناسب حتى 50,000 فحص شهرياً. انتبه للرسوم الإضافية (إعلام سلبي، PEP، كريبتو).

جدول المقارنة

المزود	التسعير	التغطية	تجربة المطور	الأفضل لـ
ComplyAdvantage	مخصص، حوالي 0.15-1 دولار لكل فحص على نطاق واسع	عقوبات، PEP، إعلام سلبي، تحذيرات	واجهة API-first، sandbox سريع	شركات التكنولوجيا المالية والبنوك الرقمية
Sumsub	مجمع مع KYC، من حوالي 1.35 دولار لكل متقدم	عقوبات، PEP، إعلام سلبي	SDK وAPI، لوحة تحكم موحدة	KYC+AML في تدفق واحد
Chainalysis	مؤسسي، حسب العرض	عناوين العملات المشفرة، المعاملات، العقوبات	REST API قوي، توثيق شامل	بورصات الكريبتو، الأوصياء
Refinitiv World-Check One	مؤسسي، غالباً بستة أرقام سنوياً	أعمق DB للعقوبات وPEP	REST + دفعة، تركيز على وحدة التحكم	بنوك، مؤسسات كبرى
Elliptic	مؤسسي، حسب العرض	عناوين العملات المشفرة، تحليلات المحفظة	REST API مع SDKs قوية	فرق امتثال الكريبتو
Onfido AML	إضافة لخطة الهوية	عقوبات، PEP، إعلام سلبي	يمتد SDK Onfido	الفرق التي تستخدم Onfido

أفضل مزودي واجهات برمجة تطبيقات (API) لفحص مكافحة غسيل الأموال (AML)

ComplyAdvantage

ComplyAdvantage خيار تقني ممتاز للمطورين الراغبين في فحص AML عبر REST API. توفر قاعدة بيانات محدثة باستمرار تشمل أكثر من 150 قائمة عقوبات و1200 قائمة مراقبة وأكثر من 10,000 مصدر إعلام سلبي. يمكنك ضبط درجات المطابقة، استبعاد قوائم معينة، واستخدام بيانات إضافية مثل تاريخ الميلاد لتقليل الإيجابيات الكاذبة. الميزة الأساسية: تنبيهات webhooks فورية عند إضافة أي اسم لقائمة جديدة دون الحاجة لفحص كامل يومياً.

الأفضل لـ: شركات التكنولوجيا المالية، البنوك الرقمية، والدفع التي تحتاج API-first وتنبيهات Webhook.

Sumsub (وحدة مكافحة غسيل الأموال)

Sumsub AML توفر فحص العقوبات، PEP، والإعلام السلبي ضمن نفس منصة KYC وliveness. التكامل سهل إذا كنت تعتمد Sumsub في التحقق من الهوية، حيث أن AML يصبح مجرد خيار إضافي. المراقبة المستمرة متوفرة في الخطط الأعلى، ولوحة إدارة موحدة لنتائج AML وKYC تسهل عمل فرق الامتثال.

الأفضل لـ: الشركات الناشئة التي تريد KYC وAML في SDK واحد مع لوحة تحكم موحدة.

Chainalysis

Chainalysis تهيمن على فحص AML لعناوين الكريبتو. عبر منتج KYT (Know Your Transaction) يمكنك فحص عناوين المحفظة في الوقت الفعلي ضد قوائم العقوبات، أسواق الدارك نت، وجهات برامج الفدية. REST API يعيد درجة المخاطر وتفصيل التعرض (مباشر/غير مباشر). التكامل سهل والتوثيق شامل. الأسعار عبر فريق المبيعات (دورة 4-8 أسابيع عادةً).

الأفضل لـ: بورصات العملات المشفرة، الأوصياء، والبنوك التي تدخل عالم الأصول الرقمية.

Refinitiv World-Check One

Refinitiv World-Check One (جزء من LSEG) تملك أعمق قاعدة بيانات عقوبات وPEP. تُعتمد من أكبر البنوك حول العالم، وتوفر REST API للفحص الدفعي والمراقبة المستمرة، بالإضافة لوحدة تحكم مدمجة. لكنها تتطلب عادة عقوداً سنوية ضخمة وسير عمل مؤسسي ثقيل.

الأفضل لـ: البنوك، شركات التأمين، المؤسسات الكبرى ذات فرق الامتثال الضخمة.

Elliptic

Elliptic منافس Chainalysis في AML لعناوين الكريبتو، وتدعم أكثر من 20 سلسلة كتل. REST API مدعوم بـ SDKs (Python, Node, Go). منتج Navigator يسرّع التحقيقات، وواجهة المستخدم مناسبة للفرق التي تنفذ تحقيقات كثيرة في وقت قصير.

الأفضل لـ: فرق الامتثال للكريبتو التي تحتاج أدوات تحقيق قوية وتغطية API متقدمة.

Onfido AML

Onfido تشتهر بالتحقق من الهوية، وأضافت AML كامتداد. يمكنك تفعيل فحوصات العقوبات، PEP، والإعلام السلبي ضمن نفس تدفق الهوية عبر SDK واحد فقط. قاعدة بيانات AML ليست الأوسع، لكنها كافية إذا كنت تستخدم Onfido وتريد أتمتة فورية بدون تكاملات إضافية.

الأفضل لـ: فرق المنتجات التي تعتمد Onfido للتحقق من الهوية وتحتاج AML كخيار إضافي.

كيف تختار

حدد أولاً نطاق مخاطر عملك. إذا كان لديك تعاملات كريبتو، اختر Chainalysis أو Elliptic بناءً على سير عمل التحقيق وتغطية السلاسل. شركات التكنولوجيا المالية التي تتعامل بالعملات الورقية تجد ComplyAdvantage الأفضل تقنياً، بينما Refinitiv مناسب للبنوك الكبرى. إذا كنت ملتزماً ببائع KYC، استخدم وحدة AML لديهم (Sumsub أو Onfido) لتحقيق تكامل أسرع. اختبر جميع الخيارات عبر sandbox لمدة 30 يوماً ببيانات عينة وقارن معدل الإيجابيات الكاذبة، سرعة الاستجابة، وموثوقية webhook قبل التوقيع.

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

اختبار واجهات برمجة تطبيقات (APIs) فحص مكافحة غسيل الأموال (AML) باستخدام Apidog

كل مزود يوفر Sandbox، لكنك تحتاج أداة تقارنهم جميعاً على نفس بيانات الاختبار. Apidog يستورد مواصفات OpenAPI لكل مزود (ComplyAdvantage، Sumsub، Chainalysis، Refinitiv)، ويشغل نفس بيانات الفحص عبر الجميع، ويعرض الاستجابة والزمن بشكل موحد.

يمكنك أتمتة اختبارات الانحدار: أنشئ مجموعة ذهبية من كيانات خاضعة للعقوبات وشغّلها أسبوعياً على كل API لرصد أي تراجع في التغطية. حمّل Apidog وابدأ برفع مواصفات المزود. نفس سير العمل يناسب اختبار واجهات برمجة تطبيقات الامتثال الأخرى، كما هو موضح في اختبار API بدون Postman لعام 2026.

الأسئلة الشائعة

ما الفرق بين فحص العقوبات وفحص الإعلام السلبي؟ فحص العقوبات يطابق الأسماء مع القوائم الحكومية (OFAC، UN، EU). فحص الإعلام السلبي يبحث في الأخبار والمصادر الرقمية عن إشارات لمخاطر مالية أو جنائية. معظم المنظمين يطالبون بكليهما.

هل المراقبة المستمرة ضرورية أم يكفي الفحص عند التسجيل؟ المراقبة المستمرة ضرورية. قوائم العقوبات تتغير يومياً. يمكن أن يصبح عميل نظيف خاضعاً للعقوبات فجأة. الأفضل الاعتماد على تنبيهات webhook.

ما أرخص API لشركة تكنولوجيا مالية صغيرة؟ عادةً ComplyAdvantage أو Onfido AML بنظام الدفع لكل فحص أقل من 50,000 فحص شهرياً. إذا كنت تستخدم Sumsub في KYC بالفعل، قد يكون خيارهم فعالاً من حيث التكلفة. راجع مقارنة KYC API للأسعار المجمعة.

هل يمكن الجمع بين Chainalysis وComplyAdvantage؟ نعم، وهذا شائع في شركات التكنولوجيا المالية التي تتعامل مع الكريبتو. ComplyAdvantage يفحص أسماء العملات الورقية وPEP؛ Chainalysis يفحص عناوين المحافظ والمعاملات.

ما دقة هذه الواجهات البرمجية؟ جميع المزودين الستة يحققون دقة تنظيمية مقبولة بالعقوبات. معدل الإيجابيات الكاذبة يختلف (5-20%) حسب الإعداد والجغرافيا. دائماً اختبر بياناتك عبر Sandbox قبل التوقيع.

هل فحص AML للكريبتو مطلوب قانوناً؟ في معظم الولايات القضائية الكبرى نعم؛ EU MiCA، قاعدة سفر FinCEN الأمريكية، وPSA سنغافورة تطلب جميعها فحص عناوين المحافظ والمعاملات. Chainalysis وElliptic يغطيان هذه المتطلبات على نطاق واسع.

كيفية استخدام Privy API: محافظ مدمجة و Social Auth لـ Web3

Yusuf Khalidd — Thu, 23 Apr 2026 04:23:24 +0000

لا يزال إعداد المستخدمين لتطبيقات Web3 من أكبر العوائق أمام دخول المستخدمين الجدد. عبارات الاسترداد، وامتدادات المتصفح، ورسوم الغاز، كلها تعقد عملية التسجيل وتجعلها تستغرق وقتًا طويلًا. يقدم Privy API حلًا عمليًا عبر توفير محفظة مدمجة لكل مستخدم جديد، مع تجربة تسجيل دخول تقليدية (بريد إلكتروني، SMS، Google، Apple، أو محفظة MetaMask موجودة). بهذا تتيح للمستخدمين الانضمام بسرعة دون الحاجة لأي برامج إضافية. جرّب Apidog اليوم يدعم Privy المحافظ لتطبيقات كبرى مثل Blackbird وFriend.tech وOpenSea وغيرها، ويعمل مع Ethereum وSolana وجميع سلاسل EVM. في هذا الدليل ستجد خطوات عملية: إنشاء تطبيق Privy، ربطه بـ React SDK، التحقق من الرموز المميزة على الخادم، توقيع المعاملات بالمحافظ المدمجة، وإرسال Webhooks. إذا كنت ترغب بمقارنة أدوات مثل أدوات مطوري MetaMask، احتفظ بهذه الصفحة للرجوع السريع.

💡قبل تجربة الكود، اعتمد على Apidog لمراقبة وتحليل كل طلب HTTPS يصدره Privy SDK. ببساطة، وجه تطبيقك إلى وكيل محلي، راقب الحمولات الفعلية، وحل مشاكل المصادقة بسرعة بدلًا من تتبع السجلات يدويًا. ## خلاصة القول (TL;DR) - Privy يجمع بين محافظ مدمجة وتسجيل دخول عبر البريد أو الشبكات الاجتماعية أو المحافظ الخارجية في SDK واحد. - React SDK يوفر `PrivyProvider`, `useLogin`, `useWallets`, و`usePrivy` لإدارة المصادقة والتوقيع. - استخدم `@privy-io/server-auth` للتحقق من رموز الوصول على الخادم قبل الوثوق بهوية المستخدم. - دعم كامل لـ Ethereum وSolana وسلاسل EVM مع تصدير اختياري للمفاتيح وتوقيعات تفويض للعمليات الحساسة. - Webhooks للتزامن الفوري عند إنشاء المستخدم أو تسجيل دخوله أو تحديث المحفظة. - محرك السياسات يتيح MFA، قوائم السماح، وقواعد معاملات دون تعديل الكود الأساسي. ## ما هو Privy API؟ Privy عبارة عن منصة مصادقة ومحافظ، توفر لتطبيقك: - واجهة مستخدم تسجيل دخول قابلة للتخصيص، - محفظة مدمجة آمنة لكل مستخدم، - نقاط نهاية REST للتحقق من المستخدمين من جانب الخادم. المحفظة المدمجة تعيش في منطقة آمنة (secure enclave)، فلا Privy ولا خادمك يرى المفتاح الخاص. يمكن للمستخدم تصدير مفتاحه متى شاء. النموذج التسعيري يعتمد على عدد المحافظ النشطة شهريًا. الفئة المجانية حتى 1000 مستخدم نشط، Pro تبدأ من 149$/شهر، وفئة Enterprise لاحتياجات أكبر. ## المصادقة والإعداد 1. سجل في privy.io وأنشئ تطبيق جديد. 2. احصل على: - **App ID** (`clxxxxx...`) لاستخدامه في SDK العميل. - **App secret** لاستخدامه في SDK الخادم. 3. حدد طرق تسجيل الدخول المسموحة، اختر السلسلة الافتراضية، وأضف نطاقك إلى قائمة السماح. 4. ثبّت React SDK: ```bash npm install @privy-io/react-auth ``` 5. غلف تطبيقك بـ `PrivyProvider`: ```jsx import { PrivyProvider } from '@privy-io/react-auth'; export default function App({ Component, pageProps }) { return ( ); } ``` استخدم `createOnLogin` لإنشاء محفظة تلقائيًا عند أول تسجيل دخول، وتحكم في السلاسل المدعومة من نفس الإعدادات. ## نقاط النهاية الأساسية واستدعاءات SDK ### بدء تسجيل الدخول وقراءة المستخدم استخدم `usePrivy` و`useWallets` لإدارة جلسة المستخدم والمحافظ: ```jsx import { usePrivy, useWallets } from '@privy-io/react-auth'; function LoginButton() { const { ready, authenticated, login, logout, user } = usePrivy(); const { wallets } = useWallets(); if (!ready) return

; if (!authenticated) return تسجيل الدخول; const embedded = wallets.find((w) => w.walletClientType === 'privy'); return (

مرحبًا {user.email?.address ?? user.id}

  <p>المحفظة: {embedded?.address}</p>
  <button onClick={logout}>تسجيل الخروج</button>
</div>

);
}



`useWallets` يرجع جميع محافظ المستخدم، ويمكنك تمييز المحافظ المدمجة عبر `walletClientType`. هذا النمط مفيد لتطبيقات تعتمد على محافظ Privy كما في <a href="http://apidog.com/blog/best-crypto-wallet-api?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation">هذه المقارنة</a>.

### توقيع معاملة
لتوقيع معاملة Ethereum:


```jsx
const { wallets } = useWallets();
const wallet = wallets.find((w) => w.walletClientType === 'privy');

async function sendTx() {
  const provider = await wallet.getEthereumProvider();
  const hash = await provider.request({
    method: 'eth_sendTransaction',
    params: [{
      to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2',
      value: '0x38d7ea4c68000', // 0.001 ETH
    }],
  });
  console.log('tx hash', hash);
}

لـ Solana استخدم getSolanaProvider ومرر معاملة متسلسلة. إذا أردت محاكاة نمط Alchemy، اعتمد Privy للمفتاح وAlchemy لـ RPC كما هو موضح في هذا الدليل.

التحقق من الرموز المميزة على الخادم

ثبّت SDK الخادم:

npm install @privy-io/server-auth

تحقق من الرمز المميز JWT في كل طلب:

import { PrivyClient } from '@privy-io/server-auth';

const privy = new PrivyClient(
  process.env.PRIVY_APP_ID,
  process.env.PRIVY_APP_SECRET
);

export async function GET(req) {
  const auth = req.headers.get('authorization')?.replace('Bearer ', '');
  try {
    const claims = await privy.verifyAuthToken(auth);
    // claims.userId هو معرف المستخدم (DID)
    return Response.json({ userId: claims.userId });
  } catch (err) {
    return new Response('Unauthorized', { status: 401 });
  }
}

يمكنك أيضًا جلب بيانات المستخدم كاملة عبر privy.getUser(userId) للتحقق من الحسابات المرتبطة.

تصدير محفظة مدمجة

يسمح Privy بتصدير المفتاح الخاص بسهولة:

import { useExportWallet } from '@privy-io/react-auth';

const { exportWallet } = useExportWallet();
<button onClick={() => exportWallet()}>تصدير المفتاح الخاص</button>

سيعرض Privy نافذة آمنة، ولن يصل تطبيقك مباشرة للمفتاح.

توقيعات التفويض ومحرك السياسات

للعمليات الحساسة، استخدم توقيعات التفويض عبر إعداد السياسات من لوحة التحكم. يمكنك فرض MFA، قوائم السماح، أو موافقة من الخادم. راجع دليل التفويض في Privy للتفاصيل. مع MFA (TOTP، SMS، passkey)، تعزز حماية الحسابات بشكل كبير.

خطافات الويب (Webhooks)

لتزامن المستخدمين والمحافظ تلقائيًا:

curl -X POST https://yourapp.com/webhooks/privy \
  -H "Content-Type: application/json" \
  -H "svix-id: msg_..." \
  -H "svix-signature: v1,..." \
  -d '{
    "type": "user.created",
    "user": { "id": "did:privy:...", "email": { "address": "a@b.com" } }
  }'

تحقق من توقيع الرأس (svix-signature) باستخدام سر webhook قبل تحديث قاعدة البيانات.

الأخطاء الشائعة وحدود المعدل

invalid_token: انتهت صلاحية JWT. نادِ getAccessToken() من usePrivy قبل أي جلب جديد.
403 origin_not_allowed: نطاق التطبيق غير مضاف لقائمة السماح. أضف النطاق من لوحة التحكم.
wallet_not_ready: حاولت قراءة المحافظ قبل أن تصبح ready صحيحة. انتظر ready.
حدود المعدل: REST API يسمح بـ 100 طلب/ثانية في الخطة المجانية. استخدم التجميع أو التخزين المؤقت عند الحاجة.

استخدم Apidog لإعادة تشغيل webhook وفحصه محليًا حتى تنجح جميع المعالجات.

تسعير Privy

مجاني: حتى 1000 محفظة نشطة/شهر، تسجيل دخول أساسي، محافظ EVM + Solana.
Pro: 149$ شهريًا، حدود أعلى، جميع ميزات webhooks، تطبيق تجريبي.
Enterprise: اتفاقيات مستوى خدمة مخصصة، دعم وهندسة عند الطلب، سياسات مخصصة.

للمزيد راجع privy.io/pricing.

اختبار Privy API باستخدام Apidog

جميع استدعاءات Privy من الواجهة الخلفية هي REST عادي، ويمكن اختبارها مباشرة عبر Apidog:

أنشئ مجموعة Privy في Apidog.
ضع App ID وApp secret كمتغيرات بيئة.
اختبر نقاط النهاية مثل:
- GET /api/v1/users/{userId}
- POST /api/v1/users/{userId}/wallets

سجل حمولات webhook من لوحة التحكم، وأعد تشغيلها على بيئة التطوير لضبط المعالجة. أنشئ اختبارات تلقائية لتتحقق من صلاحية JWT ورجوع الأخطاء الصحيحة عند انتهاء الصلاحية.

نزّل Apidog مجانًا وتجاوز مشاكل cURL. إذا كنت انتقلت من Postman، اقرأ هذا الدليل لترى الفرق في سير العمل.

الأسئلة الشائعة

كيف يختلف Privy عن Web3Auth أو Magic؟

كلها تقدم محافظ مدمجة، لكن Privy يركز أكثر على المصادقة المختلطة ومحرك السياسات للمشاريع الكبيرة. Web3Auth يركز على MPC ومشاركة المفتاح، وMagic يقدم مصادقة أوسع عبر magic-link. اختر Privy إذا أردت تحكمًا دقيقًا وواجهة إعداد واضحة.

هل يدعم Privy شبكة Solana؟

نعم، المحافظ المدمجة تعمل على mainnet وdevnet. استخدم getSolanaProvider() لتوقيع المعاملات. يمكنك تفعيل كل من EVM وSolana بنفس التطبيق.

هل يمكن للمستخدمين ربط محافظهم الخاصة؟

نعم. MetaMask وCoinbase Wallet وWalletConnect وPhantom مدعومة تلقائيًا. تعتبر المحافظ الخارجية حسابات مرتبطة بنفس معرف المستخدم.

ماذا لو تعطل Privy؟

المستخدم يحتفظ بمحفظته إذا قام بتصدير المفتاح. فعّل دومًا خيار تصدير المحفظة ووضح للمستخدمين مسار الطوارئ. لمزيد من أنماط المخاطر راجع دليل مقارنة موفري الهوية.

هل يدعم Privy المصادقة متعددة العوامل (MFA)؟

نعم، يدعم TOTP وSMS وpasskeys، ويمكنك فرضها على إجراءات محددة عبر السياسات.

هل يجب تنفيذ الكود من جهة الخادم أم العميل؟

كلاهما: Client SDK لإدارة الجلسة والتوقيع، Server SDK للتحقق من الرموز وجلب بيانات المستخدم. لا ترسل App Secret أبدًا للعميل.

دليل المطور: استخدام Stripe Identity API للتحقق من الهوية

Yusuf Khalidd — Thu, 23 Apr 2026 04:22:16 +0000

إن التحقق من هوية المستخدم الحقيقية هو مهمة غالبًا ما تبدو بسيطة أثناء التصميم، لكنها تتحول لمشروع معقد عند التنفيذ العملي. يتطلب الأمر التقاط مستندات، تشغيل OCR، مطابقة وجه، التأكد من الحيوية، تحليل إشارات الاحتيال، وتغطية أنواع هويات متنوعة لكل دولة. تجمع واجهة Stripe Identity كل هذه العمليات في نقطة تكامل واحدة بحيث تستطيع بناء تدفق تحقق جاهز للإنتاج بسرعة وسهولة.

جرّب Apidog اليوم

هذا الدليل يوضح كل خطوة تقنية يحتاجها المطور لاعتماد Stripe Identity: من تفعيل الخدمة في لوحة التحكم، إنشاء VerificationSession، الاختيار بين تدفق إعادة التوجيه أو دمج Stripe.js، التعامل مع webhooks، وقراءة النتائج النهائية. ستجد أمثلة عملية باستخدام curl وNode، كيفية التعامل مع الأخطاء، وكيفية اختبار العملية بالكامل محليًا باستعمال Apidog. إذا كنت تبحث عن بدائل، اطلع على قائمتنا لأفضل واجهات KYC API قبل اتخاذ قرار.

يعتبر Stripe Identity الخيار الأمثل للفرق التي تستخدم Stripe للمدفوعات، لكنه يعمل كمنتج مستقل أيضًا. الوثائق الرسمية ممتازة لواجهة المنتج، لكن هذا الدليل التقني يركز على التفاصيل العملية: ماذا يحصل على الشبكة، الحقول المهمة، وأين تظهر المشاكل الشائعة.

باختصار عملي

Stripe Identity يتحقق من المستخدمين بواسطة مستند حكومي وصورة ذاتية، ابتداءً من 1.50 دولار لكل تحقق في الولايات المتحدة.
العنصر المركزي هو VerificationSession؛ أنشئه من السيرفر، ثم اعمل redirect أو دمج Stripe.js.
حدد الحقول المطلوبة عبر options.document.require_matching_selfie، require_id_number، وallowed_types.
تابع حالة التحقق من خلال webhooks: identity.verification_session.verified وidentity.verification_session.requires_input.
المخرجات المتحقق منها (كالاسم وتاريخ الميلاد) تظهر فقط إذا طلبتها صراحةً في verified_outputs عند إنشاء الجلسة.
يدعم Stripe Identity أكثر من 35 دولة مع مستندات محلية.

ما هي Stripe Identity API؟

Stripe Identity توفر نقطة نهاية واحدة (/v1/identity/verification_sessions) لإدارة عملية التحقق: التقاط المستندات، استخراج البيانات، مطابقة الوجه، وتسجيل إشارات الاحتيال. النتيجة هي سجل آمن وموثق يتضمن بيانات المستخدم وصور المستندات.

يعتمد Stripe على مفهوم الجلسة (Session) المشابه لعمليات Checkout وPayment Intents. أنشئ جلسة من السيرفر، واترك Stripe يدير واجهة الالتقاط. بمجرد الجاهزية، يتم إعلامك عبر webhook. إذا سبق وأنشأت تدفق Checkout، ستجد Identity مألوف جدًا.

المصادقة والإعداد السريع

قبل استدعاء API، فعّل Stripe Identity عبر لوحة التحكم: إعدادات > الهوية، وافق على الشروط، وأدخل بيانات عملك للامتثال لنظم KYC.

استخدم مفتاح Stripe السري المعتاد (يبدأ بـsk_test_ في الاختبار أو sk_live_ في الإنتاج).

ثبّت Stripe SDK في مشروع NodeJS:

npm install stripe

ثم فعّل العميل وحدد إصدار الـ API:

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});

الآن يمكنك استخدام stripe.identity.verificationSessions لكل العمليات.

نقاط النهاية الأساسية

إنشاء VerificationSession

كل محاولة تحقق للمستخدم تبدأ بإنشاء VerificationSession. هذا الكائن يحدد نوع المستندات، متطلبات الصورة الذاتية، والحقول المرجعية.

مثال باستخدام curl:

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "$STRIPE_SECRET_KEY:" \
  -d "type=document" \
  -d "options[document][require_matching_selfie]=true" \
  -d "options[document][require_id_number]=true" \
  -d "options[document][allowed_types][]=driving_license" \
  -d "options[document][allowed_types][]=passport" \
  -d "verified_outputs[]=first_name" \
  -d "verified_outputs[]=last_name" \
  -d "verified_outputs[]=dob" \
  -d "verified_outputs[]=address" \
  -d "verified_outputs[]=id_number" \
  -d "metadata[user_id]=usr_7f3k2"

أو عبر Node SDK:

const session = await stripe.identity.verificationSessions.create({
  type: "document",
  options: {
    document: {
      require_matching_selfie: true,
      require_id_number: true,
      allowed_types: ["driving_license", "passport", "id_card"],
    },
  },
  verified_outputs: [
    "first_name",
    "last_name",
    "dob",
    "address",
    "id_number",
  ],
  metadata: { user_id: "usr_7f3k2" },
});

// أرسل أحد هذه القيم للعميل:
// session.url              --> إعادة توجيه مستضافة
// session.client_secret    --> مكون Stripe.js مدمج

الحقول الهامة:

type: "document": يحدد نوع التحقق (مستندات). استخدم id_number فقط إذا كنت بحاجة لبحث SSN أمريكي دون مستند.
allowed_types: يحدد أنواع المستندات المقبولة (مثلاً رخصة قيادة أو جواز سفر).
verified_outputs: قائمة الحقول التي تريد استرجاعها. Stripe لن يعيد أي حقل لم تطلبه صراحةً.

التحقق المستضاف مقابل Stripe.js المدمج

لديك خياران:

إعادة توجيه مستضافة: أرسل المستخدم إلى session.url، حيث يدير Stripe كل خطوات التحقق ثم يرجع المستخدم إلى return_url الخاص بك. أسرع وأبسط.
التدفق المدمج (Embedded): استخدم @stripe/stripe-js ومرر session.client_secret إلى الواجهة الأمامية، ثم استدعِ stripe.verifyIdentity(clientSecret). هذا الخيار يعطيك تحكم أكبر في تجربة المستخدم.

اختر التدفق الأنسب اعتمادًا على مكانية التحقق ضمن رحلتك البرمجية.

التعامل مع Webhooks

لا تعتمد على إعادة توجيه العميل فقط لمعرفة نجاح التحقق. بدلاً من ذلك، اشترك في webhooks التالية من خلال لوحة التحكم > المطورون > Webhooks:

identity.verification_session.verified: عند نجاح التحقق.
identity.verification_session.requires_input: عند فشل التحقق (مثلاً مستند غير واضح).
identity.verification_session.processing: أثناء معالجة Stripe للطلب.
identity.verification_session.canceled: إذا تم إلغاء الجلسة.

app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers["stripe-signature"],
    process.env.STRIPE_WEBHOOK_SECRET
  );

  if (event.type === "identity.verification_session.verified") {
    const session = event.data.object;
    await markUserVerified(session.metadata.user_id, session.id);
  }

  if (event.type === "identity.verification_session.requires_input") {
    await notifyUserToRetry(event.data.object.metadata.user_id);
  }

  res.json({ received: true });
});

استرداد النتائج النهائية

الـ webhook يخبرك فقط عن نجاح التحقق، لكنه لا يتضمن بيانات المستخدم الحساسة. للحصول عليها، استدعِ verificationSessions.retrieve مع expand: ["verified_outputs"]:

const session = await stripe.identity.verificationSessions.retrieve(
  "vs_1N...",
  { expand: ["verified_outputs"] }
);

const { first_name, last_name, dob, address, id_number } = session.verified_outputs;

انتبه: id_number لن يعاد إلا مرة واحدة، لذا خزنه مباشرة وبطريقة آمنة. صور المستندات تبقى في لوحة تحكم Stripe فقط.

الأخطاء الشائعة وحدود الطلبات

أكثر الأخطاء شيوعًا:

verification_session.requires_input مع رموز كـ document_unverified_other أو selfie_face_mismatch.
حل: أعطِ للمستخدم خيار إعادة المحاولة. يمكنك إعادة استخدام الجلسة المفتوحة أو إلغاؤها وصنع واحدة جديدة.
حدود الطلبات: 100 طلب/ثانية (إنتاجي)، 25 طلب/ثانية (اختبار). إذا تجاوزت الحد، ستتلقى HTTP 429 مع Retry-After.
أخطاء إضافية: unsupported_document_type (نوع مستند غير مقبول)، country_not_supported (بلد غير مدعوم).

تسعير Stripe Identity

السعر يبدأ من 1.50 دولار لكل تحقق ناجح في الولايات المتحدة. تختلف الأسعار دوليًا (بين 1.50 و2.00 دولار لغالبية أوروبا). الجلسات التي لا تنجح (requires_input) ليست قابلة للفوترة. المؤسسات الكبيرة يمكنها التفاوض مع Stripe لأسعار أقل إذا تجاوزت 10,000 تحقق شهريًا.

اختبار Stripe Identity باستخدام Apidog

بدلاً من كتابة أوامر curl يدويًا، استخدم Apidog لاستيراد OpenAPI الخاص بـStripe، بحيث تظهر كل الحقول والخيارات بوضوح. يمكنك تنفيذ طلبات حقيقية على بيئة الاختبار وفحص الاستجابة بسهولة.

يتميز Apidog أيضًا باختبار الـ webhooks: يمكنك محاكاة أحداث مثل identity.verification_session.verified محليًا وإرسالها إلى خادم التطوير لديك لاختبار التدفق بدون الحاجة لإكمال تحقق حقيقي كل مرة. لمزيد من التفاصيل، راجع دليلنا حول اختبار API بدون Postman. قم بتنزيل Apidog لبيئة سطح المكتب.

الأسئلة الشائعة

ما الفرق بين Stripe Identity وKYC العادي في Stripe؟ نظام KYC ضمن Stripe يخص التحقق من أصحاب الأعمال لحسابات Connect وPayments. أما Stripe Identity فهو API مستقل للتحقق من المستخدمين النهائيين فقط، ولا تتشارك الأنظمة النتائج.

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

هل Stripe Identity مرتبط فقط بالمدفوعات؟ لا. يمكن استخدامه كطبقة KYC مستقلة بدون أي دمج مع مدفوعات Stripe، ويمكنك ربطه مع APIs أخرى مثل فحص AML لمزيد من التدقيق.

كيف يقارن Stripe Identity مع Plaid Identity Verification؟ يركز Stripe على مستند وصورة ذاتية، بينما Plaid يعتمد على بيانات الهوية من البنوك. راجع دليل Plaid API لدينا لمقارنة الأساليب.

هل فحص حيوية الصورة الذاتية مطلوب دائمًا؟ لا، يمكنك تعطيل options.document.require_matching_selfie إذا لم تحتج فحص صورة، لكن معظم فرق مكافحة الاحتيال تتركه مفعّلًا.

ما هي الدول المدعومة؟ أكثر من 35 دولة في أمريكا الشمالية، أوروبا، وأجزاء من آسيا والمحيط الهادئ، مع دعم مستندات محلية. راجع قائمة الدول المحدثة في وثائق Stripe.