مشخصات API نسخه ۲.۳

رابطه کاربری API

از طریق یک رابط جستجوی استاندارد GET، moonpacket به طور فعال 'قوانین پاداش' و 'خصوصیات کاربر' را از سرور شما بازیابی می‌کند. تمامی قضاوت‌های منطقی توسط moonpacket انجام می‌شود.

مشخصات را مشاهده کنید بازگشت به Litepaper

منطق تعامل

کل فرآیند به دو مرحله تقسیم می‌شود: 'مرحله راه‌اندازی' و 'مرحله اجرایی'. moonpacket درخواست‌ها را به API شما با استفاده از روش GET ارسال خواهد کرد:

← 左右滑動查看流程 →

مرحله اول

مرحله اول: تعریف قوانین (پیکربندی)

⚡ موقعیت تریگر: هنگام ورود URL در 'تنظیم شرایط دریافت' و ارسال آن

GET GET

RET برگشت شیء تعریف قوانین با عملگرها (gt, eq, lt...)

مرحله دوم

مرحله دو: تأیید کاربر (Runtime)

⚡ زمان triggering: وقتی کاربر سعی در دریافت Red Packet دارد

GET ?user_id=...

RET بازگشت به ویژگی‌های واقعی آن کاربر خاص (عدد خالص یا رشته)

💡 اپراتورهای پشتیبانی شده: `eq` (برابر، پشتیبانی از رشته/عدد)، `gt` (بزرگتر از)، `gte` (بزرگتر از یا برابر)، `lt` (کوچکتر از)، `lte` (کوچکتر از یا برابر). مقادیر برای اپراتورهای غیر `eq` باید عدد باشند.

سناریوهای کاربردی

🎮

ادغام GameFi

قانون `level >= 10` را تعریف کنید. وقتی کاربر ادعا می‌کند، moonpacket ویژگی‌های کاربر را بررسی می‌کند، اگر `level: 12` باشد، آنگاه تأیید می‌شود.

🆔

پاداش Bind Identity

قانون `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(محرمانه، بدنه + زمانسنج + نانس)

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);

⚠️ یادداشت

● زمان انقضا: اطمینان حاصل کنید که API می‌تواند نتایج را در ۳ ثانیه برگرداند.
● قالب: لطفاً به ساختار JSON به دقت پایبند باشید، در غیر این صورت منجر به خطای تجزیه خواهد شد.

کدهای وضعیت

کد وضعیت	وضعیت	توضیحات
200	OK	درخواست موفقیت آمیز
400	Bad Request	پارامتر درخواست نادرست (مانند فرمت نادرست).
401	Unauthorized	هدر مجوز از دست رفته یا کلید نامعتبر.
403	Forbidden	محدودیت IP یا عدم دسترسی به این منبع.
404	Not Found	شناسه کاربری وجود ندارد (مربوط به سناریوی بررسی وضعیت کاربر).
500	Server Error	خطای داخلی سرور.

⚠️ سلب مسئولیت API شخص ثالث

روش‌های یکپارچگی برای پلتفرم‌های شخص ثالث ذکر شده در این سند صرفاً برای مرجع می‌باشد. توسعه‌دهندگان باید به مدارک رسمی و آخرین مستندات توسعه‌دهنده پلتفرم مراجعه کرده و به آن‌ها پایبند باشند.