Thông số kỹ thuật API v2.3

API xác thực

Thông qua giao diện truy vấn GET chuẩn hóa, moonpacket chủ động lấy 'quy tắc thưởng' và 'thuộc tính người dùng' từ máy chủ của bạn. Tất cả các phán đoán hợp lý đều được xử lý bởi moonpacket.

Xem Thông số kỹ thuật Trở về Litepaper

Logic Tương Tác

Toàn bộ quy trình được chia thành hai giai đoạn: 'Giai đoạn thiết lập' và 'Giai đoạn chạy'. moonpacket sẽ gửi yêu cầu đến API của bạn sử dụng phương thức GET:

← 左右滑動查看流程 →

Bước Một

Giai đoạn 1: Định nghĩa Quy tắc (Cấu hình)

⚡ Sự kiện kích hoạt: khi URL được điền vào 'Cài đặt Điều Kiện Yêu Cầu' và được gửi đi

GET GET

RET Trả về đối tượng định nghĩa quy tắc với các toán tử (gt, eq, lt...)

Bước Hai

Giai đoạn 2: Xác thực người dùng (Thời gian chạy)

⚡ Sự kiện kích hoạt: khi người dùng cố gắng nhận lì xì

GET ?user_id=...

RET Trả về giá trị thuộc tính thực tế của người dùng cụ thể đó (giá trị nguyên hoặc chuỗi)

💡 Nhà cung cấp được hỗ trợ: `eq` (bằng, hỗ trợ chuỗi/số), `gt` (lớn hơn), `gte` (lớn hơn hoặc bằng), `lt` (nhỏ hơn), `lte` (nhỏ hơn hoặc bằng). Giá trị cho các nhà cung cấp không phải `eq` phải là số.

Các Tình Huống Ứng Dụng

🎮

Tích hợp GameFi

Xác định quy tắc `level >= 10`. Khi người dùng yêu cầu, moonpacket kiểm tra thuộc tính của người dùng, nếu `level: 12` thì được phê duyệt.

🆔

Phần thưởng Gắn bó Danh tính

Định nghĩa quy tắc `kyc == true`. moonpacket kiểm tra trạng thái người dùng, và nếu nó trả về `kyc: true`, thì phần thưởng sẽ được phân phát.

🚀

Lọc Danh sách Đen

Định nghĩa quy tắc `is_blacklist == false`. Nếu API trả về `is_blacklist: true`, yêu cầu sẽ bị từ chối.

Ví dụ Giao tiếp (Yêu cầu GET)

Mode A 1. Định nghĩa quy tắc (Cài đặt)

Khi gửi cài đặt, hãy trả về JSON chứa các toán tử.

Nội dung yêu cầu

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

Trả Kết Quả (200 OK)

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

Mode B 2. Trạng thái truy vấn (Thời gian chạy)

Khi người dùng yêu cầu, trả về giá trị hoặc chuỗi nguyên bản.

Nội dung yêu cầu

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

Trả Kết Quả (200 OK)

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

Định nghĩa cấu trúc dữ liệu (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;
  };
}

🔐 Xác thực bảo mật

Để đảm bảo tính xác thực của các yêu cầu, moonpacket sẽ bao gồm một chữ ký trong tiêu đề. Bạn có thể tham khảo mã ở bên phải để xác thực:

Các tiêu đề cần thiết

➜ X-API-KEY

➜ X-API-TIMESTAMP

➜ X-API-NONCE

➜ X-API-SIGNATURE

Thuật toán Chữ ký

Chữ ký = HMAC_SHA256(bí mật, nội dung + dấu thời gian + số ngẫu nhiên)

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

⚠️ Ghi chú

● Thời gian chờ: Đảm bảo rằng API có thể trả về kết quả trong vòng 3 giây.
● Định dạng: Vui lòng tuân thủ nghiêm ngặt cấu trúc JSON, nếu không sẽ dẫn đến lỗi phân tích.

Mã Trạng Thái

Mã Trạng Thái	Trạng thái	Mô tả
200	OK	Yêu cầu thành công
400	Bad Request	Lỗi tham số yêu cầu (ví dụ: định dạng không chính xác).
401	Unauthorized	Thiếu Header ủy quyền hoặc khóa không hợp lệ.
403	Forbidden	Giới hạn IP hoặc truy cập không được phép vào tài nguyên.
404	Not Found	ID người dùng không tồn tại (đối với các kịch bản truy vấn trạng thái người dùng).
500	Server Error	Lỗi máy chủ nội bộ.

⚠️ Thông báo miễn trừ trách nhiệm API của bên thứ ba

Các phương pháp tích hợp cho các nền tảng bên thứ ba được đề cập trong tài liệu này chỉ mang tính chất tham khảo. Các nhà phát triển nên tham khảo và tuân thủ tài liệu chính thức mới nhất của nền tảng.