Specyfikacja API v2.3

API uwierzytelniania

Dzięki zunifikowanemu interfejsowi zapytań GET, moonpacket aktywnie pobiera 'reguły nagród' i 'atrybuty użytkownika' z Twojego serwera. Wszystkie logiczne oceny są obsługiwane przez moonpacket.

Zobacz specyfikację Zwróć Litepaper

Logika interakcji

Cały proces podzielony jest na dwie fazy: 'Faza Ustawień' i 'Faza Czasu Wykonania'. moonpacket wyśle żądania do twojego API za pomocą metody GET:

← 左右滑動查看流程 →

Krok Pierwszy

Faza 1: Zdefiniuj zasady (konfiguracja)

⚡ Zdarzenie wyzwalające: gdy URL jest wypełniony w 'Ustawieniach warunków roszczenia' i przesłany

GET GET

RET Zwraca obiekt definicji zasad z operatorami (gt, eq, lt...)

Krok Drugi

Faza 2: Weryfikacja użytkownika (Czas działania)

⚡ Zdarzenie wywołujące: gdy użytkownik próbuje odebrać Red Packet

GET ?user_id=...

RET Zwraca rzeczywistą wartość atrybutu tego konkretnego użytkownika (wartość prosta lub string)

💡 Obsługiwane operatory: `eq` (równa się, obsługuje ciągi/liczby), `gt` (większe niż), `gte` (większe niż lub równe), `lt` (mniejsze niż), `lte` (mniejsze niż lub równe). Wartości dla operatorów innych niż `eq` muszą być liczbami.

Scenariusze aplikacji

🎮

Integracja GameFi

Zdefiniuj zasadę `level >= 10`. Gdy użytkownik roszczy, moonpacket sprawdza atrybuty użytkownika, jeśli `level: 12`, to jest zatwierdzona.

🆔

Nagroda za powiązanie tożsamości

Zdefiniuj regułę `kyc == true`. moonpacket sprawdza status użytkownika, a jeśli zwraca `kyc: true`, to nagrody są przyznawane.

🚀

Filtrowanie czarnej listy

Zdefiniuj regułę `is_blacklist == false`. Jeśli API zwróci `is_blacklist: true`, roszczenie zostaje odrzucone.

Przykład komunikacji (żądanie GET)

Mode A 1. Zdefiniuj zasady (Ustawienia)

Podczas przesyłania ustawień zwróć JSON zawierający operatorów.

Zawartość żądania

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

Zwróć wynik (200 OK)

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

Mode B 2. Stan zapytania (czas działania)

Gdy użytkownik odbierze, zwróć czyste wartości lub ciągi.

Zawartość żądania

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

Zwróć wynik (200 OK)

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

Definicja struktury danych (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;
  };
}

🔐 Weryfikacja bezpieczeństwa

Aby zapewnić autentyczność żądań, moonpacket dołączy podpis w nagłówku. Możesz odwołać się do kodu po prawej stronie w celu walidacji:

Wymagane nagłówki

➜ X-API-KEY

➜ X-API-TIMESTAMP

➜ X-API-NONCE

➜ X-API-SIGNATURE

Algorytm podpisu

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

⚠️ Notatka

● Limit czasu: Upewnij się, że API może zwracać wyniki w ciągu 3 sekund.
● Format: Proszę ściśle przestrzegać struktury JSON, w przeciwnym razie może to prowadzić do błędów w analizie.

Kody statusu

Kod statusu	Status	Opis
200	OK	Żądanie zakończone sukcesem
400	Bad Request	Błąd parametru żądania (np. błąd formatu).
401	Unauthorized	Brak nagłówka autoryzacji lub klucz jest nieprawidłowy.
403	Forbidden	Ograniczenie IP lub nieautoryzowany dostęp do zasobu.
404	Not Found	ID użytkownika nie istnieje (w przypadkach zapytania o status użytkownika).
500	Server Error	Wewnętrzny błąd serwera.

⚠️ Zastrzeżenie dotyczące API stron trzecich

Metody integracji z platformami stron trzecich wymienione w tym dokumencie mają charakter jedynie informacyjny. Programiści powinni zapoznać się i stosować do najnowszej oficjalnej dokumentacji dewelopera danej platformy.