مواصفات API v2.3

API المصادقة

من خلال واجهة استعلام GET موحدة، تسترد moonpacket بنشاط "قواعد المكافآت" و"سمات المستخدم" من خادمك. يتم التعامل مع جميع الأحكام المنطقية بواسطة moonpacket.

عرض المواصفات إرجاع ورقة العمل

منطق التفاعل

العملية بالكامل مقسمة إلى مرحلتين: 'مرحلة الإعداد' و'مرحلة وقت التشغيل'. ستقوم moonpacket بإرسال طلبات إلى واجهة برمجة التطبيقات الخاصة بك باستخدام طريقة GET:

← 左右滑動查看流程 →

الخطوة الأولى

المرحلة 1: تعريف القواعد (التكوين)

⚡ حدث التنشيط: عند ملء عنوان URL في 'إعدادات شروط المطالبة' وإرساله

GET GET

RET يعيد كائن تعريف القواعد مع المشغلين (gt, eq, lt...)

الخطوة الثانية

المرحلة 2: التحقق من المستخدم (وقت التشغيل)

⚡ حدث التنشيط: عند محاولة المستخدم المطالبة بـ Red Packet

GET ?user_id=...

RET يعيد القيمة الفعلية لخاصية ذلك المستخدم المحدد (قيمة بسيطة أو سلسلة نصية)

💡 المشغلون المدعومون: `eq` (يساوي، يدعم السلاسل/الأرقام)، `gt` (أكبر من)، `gte` (أكبر من أو يساوي)، `lt` (أقل من)، `lte` (أقل من أو يساوي). يجب أن تكون القيم لمشغلات غير `eq` أرقاماً.

سيناريوهات التطبيق

🎮

دمج GameFi

حدد القاعدة `level >= 10`. عندما يطالب المستخدم، يقوم moonpacket بالتحقق من سمات المستخدم، إذا كانت `level: 12` فإنه يتم الموافقة عليها.

🆔

مكافأة ربط الهوية

حدد القاعدة `kyc == true`. moonpacket يتحقق من حالة المستخدم، وإذا كانت النتيجة `kyc: true`، يتم توزيع المكافآت.

🚀

تصفية القوائم السوداء

حدد القاعدة `is_blacklist == false`. إذا أعاد API `is_blacklist: true`، يتم رفض المطالبة.

مثال التواصل (طلب GET)

Mode A 1. تعريف القواعد (الإعداد)

عند تقديم الإعدادات، ارجع JSON يحتوي على المشغلين.

محتوى الطلب

GET /check HTTP/1.1
Host: api.your-game.com
Content-Type: application/json
X-API-KEY: 1234567890
X-API-TIMESTAMP: 1698765432
X-API-NONCE: 987654
X-API-SIGNATURE: 5d41402abc4b2a76b9719d911017c592...

# No user_id = Get Rules

نتيجة الإرجاع (200 OK)

{
  "data": {
    "level": {
      "gt": 99
    },
    "status": {
      "eq": "active"
    },
    "is_blacklist": {
      "eq": false
    }
  }
}

Mode B 2. استعلام الحالة (وقت التنفيذ)

عند مطالبة المستخدم، ارجع القيم أو السلاسل النقية.

محتوى الطلب

GET /check?user_id=666666666 HTTP/1.1
Host: api.your-game.com
Content-Type: application/json
X-API-KEY: 1234567890
X-API-TIMESTAMP: 1698765432
X-API-NONCE: 123456
X-API-SIGNATURE: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6...

# With user_id = Get User Status

نتيجة الإرجاع (200 OK)

{
  "data": {
    "level": 100,
    "status": "active",
    "is_blacklist": false
  }
}

تعريف هيكل البيانات (TypeScript)

types.d.ts

// Step 1: Rules Definition
interface RulesResponse {
  data: {
    [key: string]: {
      eq?: string | number | boolean;
      gt?: number;
      gte?: number;
      lt?: number;
      lte?: number;
    };
  };
}

// Step 2: User Status
interface UserStatusResponse {
  data: {
    [key: string]: string | number | boolean;
  };
}

🔐 تحقق الأمان

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

الرؤوس اللازمة

➜ X-API-KEY

➜ X-API-TIMESTAMP

➜ X-API-NONCE

➜ X-API-SIGNATURE

خوارزمية التوقيع

التوقيع = HMAC_SHA256(secret, body + timestamp + nonce)

verify.ts

import crypto from "crypto";

// 1. Generate Signature
function generateSignature(
  apiSecret: string,
  body: object,
  timestamp: number,
  nonce?: string
) {
  const payload = JSON.stringify(body) + timestamp + (nonce || "");
  return crypto.createHmac("sha256", apiSecret).update(payload).digest("hex");
}

// Client Usage Example
const apiKey = "client123";
const apiSecret = "mysecretkey";
const body = { /* Query Params or Body */ }; 
const timestamp = Date.now();
const nonce = crypto.randomBytes(8).toString("hex");

const signature = generateSignature(apiSecret, body, timestamp, nonce);

console.log({ apiKey, timestamp, nonce, signature });

// 2. Verify Signature
function verifySignature(
  apiSecret: string,
  body: object,
  timestamp: number,
  nonce: string,
  signature: string
) {
  const expected = generateSignature(apiSecret, body, timestamp, nonce);
  return expected === signature;
}

// Verification Result
const isValid = verifySignature(apiSecret, body, timestamp, nonce, signature);
console.log("Is Valid:", isValid);

⚠️ ملاحظة

● مهلة: تأكد من أن واجهة برمجة التطبيقات يمكن أن ترجع النتائج خلال 3 ثوانٍ.
● التنسيق: يرجى الالتزام الصارم ببنية JSON، وإلا فسوف يؤدي إلى فشل التحليل.

رموز الحالة

رمز الحالة	الحالة	الوصف
200	حسنا	تم الطلب بنجاح
400	طلب غير صحيح	خطأ في معلمات الطلب (على سبيل المثال. صيغة غير صحيحة).
401	غير مصرح	رأس التفويض مفقود أو المفتاح غير صالح.
403	ممنوع	تقييد IP أو وصول غير مصرح به إلى المورد.
404	غير موجود	معرف المستخدم غير موجود (في سيناريوهات استعلام حالة المستخدم).
500	خطأ في الخادم	خطأ في الخادم الداخلي.

⚠️ تنويه لواجهة برمجة التطبيقات من الطرف الثالث

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