واجهة CardV API للتجار

#الوثائق

#البيئات

بيئة Sandbox نسخة تجريبية منفصلة من CardV، تعمل بأموال تجريبية. المفاتيح والأرصدة والطلبات وأرقام المنتجات مختلفة في كل بيئة.

#البدء السريع

1. قدّم طلبًا لفتح حساب تاجر من البوابة، ثم أكّد بريدك الإلكتروني.

2. انتظر الموافقة. تراجع CardV بيانات شركتك، ثم تحصل على Merchant ID (رقم التاجر)، مثل M00000001.

3. افتح Sandbox. سجّل الدخول إلى البوابة واختر Sandbox من الشريط العلوي. ستجد في حسابك 1,000 USD من الأموال التجريبية.

4. أنشئ مفتاح API. في البوابة، اذهب إلى Integrations → API keys. أنشئ مفتاحًا، ثم اعرضه باستخدام الرمز الذي ترسله CardV إلى بريدك. احفظه في مخزن الأسرار لديك.

5. تحقق من رصيدك:

   ShellCopy

   export CARDV_BASE=https://sandbox.cardv.net
   export CARDV_MERCHANT_ID=M00000001     # yours
   export CARDV_API_KEY=cvb2b_...         # from your secret store
   AUTH=(-H "X-Merchant-Id: $CARDV_MERCHANT_ID" -H "X-Api-Key: $CARDV_API_KEY")
   
   curl -sS "$CARDV_BASE/api/v1/balance" "${AUTH[@]}"

6. ابحث عن منتج:

   ShellCopy

   curl -sS "$CARDV_BASE/api/v1/skus?search=steam&limit=20" "${AUTH[@]}"

   اختر منتجًا متاحًا ("availability": "available")، وسجّل رقمه sku_id.

7. اعرف السعر:

   ShellCopy

   curl -sS "$CARDV_BASE/api/v1/skus/S000001/quote?quantity=1" "${AUTH[@]}"

   سجّل قيمة merchant_price، فهي ما تدفعه عن الوحدة الواحدة.

8. أرسل الطلب. يجب توقيع هذا الطلب. استخدم أحد الأمثلة في المصادقة مع هذا المحتوى:

   JSONCopy

   {
     "external_order_id": "TEST-0001",
     "items": [
       {"sku_id": "S000001", "quantity": 1, "expected_unit_price": "9.2500"}
     ]
   }

   ستتلقى HTTP 201 ومعه رقم طلب CardV، مثل O-00001234.

9. استلم الأكواد. استدعِ GET/api/v1/orders/O-00001234 حتى تصبح الحالة succeeded. تجد الأكواد في items[].deliveries[].display_fields. ويمكنك أيضًا أن تتلقى إشعار Webhook عند اكتمال الطلب.

10. انتقل إلى التشغيل الفعلي (Live) بعد إكمال قائمة التحقق في Sandbox.

الأرقام والأسعار أعلاه مجرد أمثلة. استخدم القيم التي تظهر في قائمة منتجاتك.

#نظرة سريعة على الواجهة

تضم الواجهة سبع نقاط نهاية، وتبدأ كل المسارات بـ /api/v1.

أي نقطة نهاية أخرى تُرجع HTTP 403 عند استدعائها بمفتاح API:

{"detail": "This operation is only available in the Merchant Portal."}

شحن رصيد الهاتف المحمول غير متاح عبر API.

#الأرقام التعريفية

احفظ الأرقام التعريفية كنصوص، ولا تحاول تفكيكها. راجع القواعد العامة.

#ما يتم من بوابة التاجر

• شحن المحفظة، وتنبيه البريد عند انخفاض الرصيد
• سجل الطلبات والبحث فيها وتصديرها بصيغة CSV
• فواتير الطلبات
• حركات المحفظة ومطابقة الحسابات
• إعداد Webhook، وسجل الإرسال، وإعادة الإرسال
• مفاتيح API
• قائمة عناوين IP المسموح بها
• أعضاء الفريق وأدوارهم
• سجل التدقيق
• التحقق بخطوتين (2FA)
• التبديل بين Live وSandbox

#التوافق والدعم

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

راسل [email protected] وأرفق Merchant ID، والبيئة، وأرقام الطلبات، والوقت (UTC)، ورمز حالة HTTP. لا ترسل أبدًا مفاتيح API أو التواقيع أو أسرار Webhook أو أكواد البطاقات.