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

#الوثائق

#البيئات

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

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

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

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

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

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

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

   ShellCopy

   export CARDV_BASE=https://sandbox.cardv.net
   export CARDV_KEY_ID=ck_test_...            # shown in the Portal
   export CARDV_SIGNING_SECRET=cs_test_...    # from your secret store
   
   cardv_get() {  # every call is signed, see Authentication
     local ts nonce sig
     ts=$(date +%s); nonce=$(openssl rand -hex 16)
     sig=$(printf 'GET\n%s\n%s\n%s\n%s' "$1" "$ts" "$nonce" \
       e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 \
       | openssl dgst -sha256 -hmac "$CARDV_SIGNING_SECRET" -hex | sed 's/^.*= //')
     curl -sS "$CARDV_BASE$1" -H "X-Key-Id: $CARDV_KEY_ID" \
       -H "X-Timestamp: $ts" -H "X-Nonce: $nonce" -H "X-Signature: $sig"
   }
   
   cardv_get "/api/v1/balance"

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

   ShellCopy

   cardv_get "/api/v1/skus?search=steam&limit=20"

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

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

   ShellCopy

   cardv_get "/api/v1/skus/S000001/quote?quantity=1"

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

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

   JSONCopy

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

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

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

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

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

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

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

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

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

شحن رصيد الهاتف المحمول مشروح في شحن رصيد الهاتف المحمول.

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

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

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

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

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

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

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