المطورون/المنظومة والموارد
CardV لـ Dujiao-Next
أضف CardV كمورّد داخل متجر Dujiao-Next الخاص بك. تستورد بطاقات الهدايا وشحن الألعاب من CardV كمنتجات خاصة بك وتحدّد أسعارك بنفسك. عندما يدفع المشتري، يشتري متجرك المنتج من CardV من رصيدك في CardV، ويظهر الكود في صفحة طلب المشتري تلقائيًا.
#ما تحتاج إليه
| Dujiao-Next | الإصدار v1.5.0 أو أحدث، مع ميزة الاتصال بالمورّد (قائمة Integration) |
| حساب CardV | حساب تاجر معتمد مع تفعيل الوصول إلى API |
| مفتاح API | مفتاح API موقّع من بوابة التاجر (معرّف المفتاح + سرّ التوقيع) |
| الرصيد | رصيد CardV مدفوع مسبقًا بالدولار الأمريكي (USD). يُدفع منه كل طلب يقدّمه متجرك |
أنت البائع أمام المشترين: تحدّد الأسعار، وتجيب عن أسئلتهم، وتتولّى عمليات الاسترداد.
#الخطوة 1: احصل على مفتاح API
استخدم مفتاح API الذي لديك بالفعل في بوابة التاجر ضمن API وWebhooks > مفاتيح API. لا تحتاج إلى مفتاح منفصل لـ Dujiao-Next.
- معرّف المفتاح يبدأ بـ
ck_live_. - سرّ التوقيع يبدأ بـ
cs_live_. يظهر مرة واحدة فقط عند إنشاء المفتاح. إذا لم يعد لديك، استخدم إعادة إنشاء السر على المفتاح. يبقى معرّف المفتاح كما هو، ويتوقف السرّ القديم عن العمل فورًا.
لا يمكن استخدام المفاتيح القديمة التي ليس لها معرّف مفتاح. أنشئ مفتاحًا جديدًا في البوابة بدلًا منها.
#الخطوة 2: أضف الاتصال
في لوحة تحكم Dujiao-Next، افتح Integration > Connection Management > New Connection واملأ النموذج:
| الحقل | ما تُدخله | السبب |
|---|---|---|
| Name | مثلًا CardV (USD) | لا يراه أحد غيرك. ذكر العملة يمنع الالتباس لاحقًا |
| Base URL | https://b2b.cardv.net/dujiao | أدرج /dujiao ولا شيء بعده، ومن دون شرطة مائلة في النهاية |
| API Key | معرّف المفتاح (ck_live_…) | |
| API Secret | سرّ التوقيع (cs_live_…) | عند تعديل الاتصال لاحقًا، اتركه فارغًا للإبقاء على السرّ المحفوظ |
| Protocol | dujiao-next | |
| Callback URL | اتركه فارغًا | لا يرسل CardV أي استدعاءات (callbacks). يتحقق متجرك من نتيجة كل طلب بنفسه (راجع آلية التسليم) |
| Max Retries / Retry Intervals | أبقِ القيم الافتراضية (3 / 30,60,120) | لا تنطبق إعادة المحاولة إلا على الأخطاء المؤقتة |
| Exchange Rate | رقم ثابت تكتبه بنفسك: سعر الصرف الفعلي اليوم من USD إلى عملة متجرك، مع رفعه قليلًا كهامش أمان. استخدم 1 إذا كان متجرك يبيع بالدولار الأمريكي | أسعار CardV دائمًا بالدولار الأمريكي. لا يجلب Dujiao-Next أسعار الصرف الحية، ولا يستطيع CardV ضبط هذه القيمة نيابةً عنك. القيمة الافتراضية 1، لذا فإن المتجر الذي يبيع بعملة أخرى سيعرض بطاقة بقيمة 10 USD بسعر 10 بعملته |
| Price Markup (%) | هامش ربحك، مثلًا 15 | القيمة الافتراضية 0، أي بلا ربح |
| Price Rounding | Round up (0.1) أو Round up (integer) | التقريب إلى الأعلى لا يجعل سعرك أقل من تكلفتك أبدًا |
| Auto-update price on sync | Yes | عندما يتغير سعر CardV، يُعاد حساب سعر البيع في المزامنة التالية |
يجتمع سعر الصرف ونسبة الزيادة على هذا النحو: سعر CardV × سعر الصرف × (1 + نسبة الزيادة)، ثم يُقرَّب الناتج. فمثلًا، بافتراض سعر صرف 7.2 (مثال فقط؛ أدخل السعر الحالي الذي تتحقق منه) ونسبة زيادة 15%، تُباع بطاقة بقيمة 5.78 USD بسعر 47.9.
عندما يتغير سعر الصرف، حدّثه في الاتصال وانقر Reapply Markup لتحديث أسعار المنتجات التي استوردتها سابقًا. افعل الشيء نفسه عند تغيير نسبة الزيادة.
#الخطوة 3: اختبر الاتصال
انقر Ping على الاتصال. ظهور Ping succeeded يعني أن مفتاحك يعمل، وتتغير حالة الاتصال إلى Active. إذا ظهر خطأ بدلًا من ذلك، فراجع حل المشكلات.
#الخطوة 4: استورد المنتجات
- افتح Integration > Product Mappings > Import from Upstream واختر اتصال CardV.
- تصفّح حسب الفئة، أو انتقل إلى Flat List لاختيار منتجات منفردة.
- اختر فئة محلية، أو فعّل Auto-create local categories. يحتاج المنتج إلى فئة قبل أن تتمكن من حفظه.
- استورد. يحتفظ كل منتج بعنوانه ووصفه وتعليمات الاستخدام وقيمه الاسمية (مثل
10 USD).
تكون المنتجات المستوردة غير معروضة للبيع. راجع كل منتج، ثم فعّل Active في محرر المنتج.
#الخطوة 5: اضبط منتجًا واحدًا لكل طلب
لكل منتج مستورد، افتح محرر المنتج واضبط Max purchase quantity على 1.
يسلّم CardV منتجًا واحدًا لكل طلب. إذا دفع المشتري ثمن كودين في طلب واحد، يرفض CardV عملية الشراء وعليك معالجة ذلك الطلب يدويًا. لا يستطيع Dujiao-Next استلام هذا الحد من CardV تلقائيًا، لذا اضبطه بنفسك.
وما دمت في المحرر، نوصي أيضًا بما يلي:
- عرض المخزون في واجهة المتجر: اختر Hide quantity. يشتري CardV من العلامة التجارية عند وصول الطلب، لذا فإن رقم المخزون الذي يعرضه متجرك يعني "متوفر" فقط.
- الصور: أضف صورك الخاصة إذا لم يكن للمنتج صورة.
#آلية التسليم
- يدفع المشتري في متجرك.
- يرسل متجرك عملية الشراء إلى CardV، ويخصم CardV المبلغ من رصيدك في CardV.
- يتحقق متجرك من الطلب لدى CardV. في اختباراتنا وصل الكود خلال دقيقة.
- يظهر الكود في صفحة طلب المشتري على شكل
CodeوPIN(إن كان للبطاقة رقم PIN) وExpires(إن كان للبطاقة تاريخ انتهاء). يكون دائمًا كودًا، وليس رابطًا أبدًا.
الشحن المباشر. تُشحن بعض المنتجات مباشرةً إلى حساب المشتري في اللعبة أو التطبيق. عند الدفع يُدخل المشتري البيانات التي يحتاجها المنتج، مثل معرّف اللاعب أو رقم الهاتف. عند اكتمال الشحن، تعرض صفحة طلب المشتري Top-up completed.
إذا لم يتمكن CardV من التسليم. يردّ CardV مبلغ الطلب إلى رصيدك في CardV، ويضع متجرك علامة "ملغى" على عملية الشراء. بعد ذلك تردّ المبلغ للمشتري أو تساعده من متجرك.
#ما هو غير متاح
لا تعرض قائمة الاستيراد إلا المنتجات التي يمكن لمتجرك بيعها عبر هذا الاتصال:
- القيم الاسمية الثابتة فقط. لا تظهر البطاقات التي يكتب فيها المشتري المبلغ بنفسه.
- غير مدرجة: شحن رصيد الهاتف المحمول، ومنتجات الدفع والمحافظ، والعملات المشفرة، وبطاقات الدفع المدفوعة مسبقًا.
- الأكواد فقط. لا تظهر المنتجات التي لا يمكن تسليمها إلا كرابط.
الأسعار التي تراها هي أسعار CardV الخاصة بك بالدولار الأمريكي.
#القائمة البيضاء لعناوين IP
إذا ضبطت قائمة بيضاء لعناوين IP في بوابة التاجر، فأضف عنوان IP العام للخادم الذي يشغّل متجر Dujiao-Next. وإلا فسيرفض CardV كل طلب يأتي منه. ينطبق المفتاح نفسه والقائمة البيضاء نفسها وحدود الطلبات نفسها على CardV API وعلى Dujiao-Next.
#حل المشكلات
تظهر هذه الرسائل في لوحة تحكم Dujiao-Next، بعد Ping، أو أثناء الاستيراد، أو على عملية شراء في Procurement Orders.
| الرسالة | السبب | ما يجب فعله |
|---|---|---|
status 401 (invalid_signature): signature verification failed | قيمة API Secret غير صحيحة، أو أعدت إنشاءها في البوابة | انسخ سرّ التوقيع الحالي إلى الاتصال |
status 403 (invalid_api_key): api key is invalid or disabled | قيمة API Key ليست معرّف مفتاح (ck_live_…)، أو المفتاح معطّل | استخدم معرّف مفتاح نشط |
status 403 (user_disabled): merchant API access is not enabled | لم يُعتمد حسابك للوصول إلى API بعد | أكمل مراجعة النشاط التجاري في البوابة |
status 403 (forbidden): source IP is not allowed for this merchant | القائمة البيضاء لعناوين IP لا تتضمن خادم متجرك | أضف عنوان IP العام للخادم في البوابة |
status 401 (timestamp_expired): timestamp expired | ساعة خادمك منحرفة بأكثر من 60 ثانية | فعّل المزامنة التلقائية للوقت (NTP) على الخادم |
status 404 متبوعة بصفحة ويب | قيمة Base URL غير صحيحة، وغالبًا ينقصها /dujiao | استخدم https://b2b.cardv.net/dujiao |
CardV wallet balance is insufficient | رصيدك في CardV لا يغطي عملية الشراء. يبقى طلب المشتري مدفوعًا | اشحن رصيدك في CardV، ثم انقر Retry على عملية الشراء في Procurement Orders |
quantity must be 1: CardV accepts one item per order | طلب المشتري أكثر من وحدة واحدة من منتج | اضبط Max purchase quantity على 1 (الخطوة 5)، ثم عالج الطلب يدويًا |
sku is invalid or not available | لم يعد المنتج متاحًا من CardV | شغّل مزامنة على الربط. المنتجات التي لم يعد CardV يقدّمها تُسحب من العرض |
status 429 (rate_limited) | طلبات كثيرة جدًا خلال دقيقة واحدة | يعيد متجرك المحاولة تلقائيًا. خفّض وتيرة المزامنة إذا تكرر ذلك |
#الأسئلة الشائعة
هل أحتاج إلى مفتاح API جديد لـ Dujiao-Next؟ لا. استخدم مفتاح API الموقّع الذي لديك بالفعل. إذا كنت تستخدم المفتاح أيضًا في تكاملك الخاص مع CardV API، فإن الاثنين يتشاركان حدود الطلبات نفسها.
لماذا أترك عنوان الاستدعاء (Callback URL) فارغًا؟ لا يرسل CardV استدعاءات إلى المتاجر. يتحقق متجر Dujiao-Next من كل طلب بنفسه حتى تصبح النتيجة نهائية.
ماذا يحدث عندما تتغير أسعار CardV؟ عند تفعيل Auto-update price on sync، يُعاد حساب أسعار البيع بسعر الصرف ونسبة الزيادة الخاصين بك في المزامنة التالية. وعند إيقافه، يواصل متجرك البيع بالسعر القديم.
أين أرى هذه الطلبات في CardV؟ في صفحة الطلبات في بوابة التاجر. يبدأ عمود معرّف طلبك بـ dujiao: متبوعًا برقم الطلب الفرعي في Dujiao-Next (مثلًا dujiao:DJ…-01). إذا أعددت Webhooks في CardV، فإنها تُرسَل أيضًا لهذه الطلبات.
هل يمكنني تغيير عناوين المنتجات وأوصافها وصورها؟ نعم. تُحدّث المزامنة الأسعار والتوفر. ولا تستبدل عناوينك أو صورك.
هل يمكنني بيع مبالغ مخصّصة؟ ليس عبر Dujiao-Next حاليًا. القيم الاسمية الثابتة فقط هي المتاحة.
#الدعم
راسل [email protected] مع ذكر Merchant ID ورقم طلب Dujiao-Next ورسالة الخطأ. يخضع استخدامك لـ CardV إلى شروط الخدمة.
هل لديك سؤال حول التكامل؟ راسلنا على [email protected] مع ذكر Merchant ID ومعرّف الطلب أو الاستدعاء.