1. تجهيز حساب التاجر
أكّد بريدك وانتظر موافقة الإدارة، ثم افتح واجهة البرمجة من لوحة التاجر وأنشئ مفتاح الربط. قد يُطلب تأكيد كلمة المرور عند إنشاء المفتاح أو تدويره. تأكد من رصيد المحفظة قبل شراء أي منتج.
احفظ المفتاح على خادمك فقط في إعدادات سرية. لا تضعه في JavaScript بالمتصفح أو تطبيق العميل، ولا في روابط URL أو مستودعات عامة. يمكنك ضبط عناوين IP المسموح بها من إعدادات المفتاح.
2. عنوان الخدمة والمصادقة
العنوان الأساسي للإصدار الأول: https://nexcodesa.com/api/v1. استخدم HTTPS وأرسل مفتاحك في Authorization بصيغة Bearer، مع Accept: application/json. استبدل YOUR_API_KEY بمفتاحك على الخادم.
ابدأ بفحص الاتصال ثم الرصيد. طلبات القراءة التالية لا تنشئ عملية شراء.
curl 'https://nexcodesa.com/api/v1/ping' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
curl 'https://nexcodesa.com/api/v1/balance' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'3. اختيار المنتج الصحيح
للقسائم استخدم GET /products وتفاصيل GET /products/{id}. احتفظ بمعرّف المنتج وأي variation_id مطلوب للمتغير. لا تفترض أن أرقام المنتجات ثابتة بين القسائم وشحن ID.
لشحن ID استخدم GET /topup-products ثم GET /topup-products/{id}. خذ id من استجابة المنتج وأرسله باسم system_product_id عند إنشاء الطلب، واقرأ الحقول الإضافية المطلوبة للعبة مثل المنطقة أو الخادم من تفاصيل المنتج. تحقق من السعر والتوافر قبل الشراء.
4. شراء قسيمة
أرسل POST /orders مع product_id وquantity، وvariation_id إذا كان المنتج يتطلب متغيرًا. الأرقام هنا أمثلة وليست منتجات مضمونة التوافر. هذا الطلب عملية شراء فعلية تخصم من رصيدك.
يمكن استخدام merchant_reference الذي ربطته مسبقًا بدل معرّف المنتج وفق الوثائق؛ لا تجمع طرق التعريف المتعارضة في الطلب نفسه.
POST /api/v1/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
Idempotency-Key: YOUR_UNIQUE_ORDER_KEY
{
"delivery_type": "voucher",
"product_id": 123,
"quantity": 1
}5. إنشاء طلب شحن بمعرّف اللاعب
أرسل delivery_type بقيمة top_up، ومعرّف system_product_id من قائمة شحن ID، وplayer_id كنص للحفاظ على الأصفار في بدايته. الكمية لهذا النوع هي 1. أرسل fields عند اشتراط المنتج حقولًا إضافية وبالبنية الموضحة في الوثائق.
يُسجل الطلب ويُخصم مبلغه عند قبوله، ثم تنفّذ الإدارة الشحن وتحدّث الحالة. لا تعتبر قبول طلب الإنشاء إشارة إلى اكتمال الشحن، ولا تنتظر كود قسيمة في استجابة طلب ID.
POST /api/v1/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
Idempotency-Key: YOUR_UNIQUE_TOPUP_KEY
{
"delivery_type": "top_up",
"system_product_id": 456,
"player_id": "213251326",
"quantity": 1
}6. منع التكرار ومتابعة الطلب
أنشئ Idempotency-Key فريدًا لكل عملية شراء واحفظه مع طلب عميلك. عند انقطاع الاتصال أعد الطلب بالمفتاح نفسه وبنفس البيانات؛ لا تنشئ مفتاحًا جديدًا قبل معرفة نتيجة العملية السابقة.
احفظ reference من الاستجابة، ثم استعلم باستخدام GET /orders/{reference}. الحالات الأساسية: pending قيد المعالجة، completed مكتمل، failed فشل. استخدم GET /orders لقراءة سجل طلبات مفتاحك. لا تسلّم منتجًا للعميل بناءً على HTTP 201 وحده.
7. الأخطاء والتشغيل الآمن
401 يشير إلى مشكلة المصادقة، و403 إلى صلاحية أو حساب أو IP غير مسموح. 422 يشير إلى بيانات تحتاج تصحيحًا. افحص error.code وerror.message وحقول الخطأ بدل الاعتماد على النص الظاهر فقط.
عند 429 خفّض معدل الاستعلام واحترم retry_after_seconds عند إرجاعه. عند خطأ اتصال أو 5xx لا تُكرر الشراء بمفتاح جديد؛ افحص الطلب أو أعد المحاولة بنفس مفتاح العملية وفق الوثائق.
اختبر أولًا عمليات القراءة، ثم عملية شراء صغيرة تعلم أنها حقيقية بعد التأكد من الرصيد والمنتج. لا يوجد في هذا الدليل وعد ببيئة تجريبية أو رصيد افتراضي.
المواصفات الكاملة والأمثلة
راجع حقول الاستجابة، أخطاء التحقق، المتغيرات وحدود الطلبات في الوثائق الفنية قبل تشغيل الربط.
فتح وثائق API