مرجع الـAPI

مقدّمة

واجهة PWF Auth مبنية على نمط REST. كل الطلبات والاستجابات بصيغة JSON عبر HTTPS. هناك ثلاث عائلات من النقاط:

• واجهة العميل (/api/auth/*، /api/update/*) — تُستدعى من تطبيقك المنشور باستخدام سرّ التطبيق.
• واجهة الأدمن (/api/admin/*) — إدارة المفاتيح والتطبيقات، بمصادقة رمز Bearer.
• واجهة العميل/الموزّع (/api/customer/*، /api/reseller/*) — بوّابات خدمة ذاتية.

كل المسارات أدناه نسبيّة إلى هذا العنوان الأساسي. كل نقطة تتطلّب HTTPS؛ وطلبات HTTP العادية يُعاد توجيهها.

تفضّل الآلات؟ السطح كامل موصوف في openapi.json ‏(OpenAPI 3.1) — استورده في Postman أو Insomnia أو مولّد الأكواد لديك.

تغييرات الواجهة والمنصة تُعلَن في سجل التغييرات — والتغييرات الكاسرة تُعلَّم هناك أولاً دائماً.

المصادقة

نقاط العميل — سرّ التطبيق

أرسل سرّ تطبيقك في ترويسة X-App-Secret. تجده في لوحة التحكّم ← تطبيقك. يحدّد السرّ التطبيقَ الذي ينتمي إليه الطلب.

curl https://pwfauth.com/api/auth/check-key.php \
  -H "X-App-Secret: 9f02532d9c60…  # 64-char hex, from your dashboard" \
  -H "Content-Type: application/json" \
  -d '{"license_key":"XXXXX-XXXXX-XXXXX-XXXXX"}'

نقاط الأدمن — رمز Bearer

صادِق عبر /api/admin/login.php للحصول على JWT، ثم أرسله بصيغة Authorization: Bearer <token> في كل استدعاء أدمن.

TOKEN=$(curl -s https://pwfauth.com/api/admin/login.php \
  -d '{"username":"admin","password":"…"}' | jq -r .token)

curl https://pwfauth.com/api/admin/keys.php \
  -H "Authorization: Bearer $TOKEN"

التغليف المشفّر

نقاط النهاية بمستوى الـ SDK تتبادل تغليف AES-256-CBC + HMAC-SHA256 بدل JSON العادي. صيغة النقل: {"p": base64(IV || ciphertext), "t": unix_timestamp, "s": hmac_sha256_hex(p + t)} — مفتاحا التشفير والتوقيع يُشتقّان كلاهما من سرّ تطبيقك، فلا حاجة لأي تبادل مفاتيح إضافي.

{
  "p": "aXYxNmJ5dGVzY2lwaGVydGV4dA…",   // base64( IV || AES-256-CBC ciphertext )
  "t": 1785671000,                       // unix timestamp (±300s accepted)
  "s": "b7fd09…"                        // hmac_sha256_hex( p + t, mac_key )
}

النقاط المعلَّمة سرّ التطبيق + تغليف مشفّر تتطلبه في الطلب وتردّ مشفّرة. أما check-key.php فيكتشف تلقائياً: أرسل JSON عادياً تستلم JSON عادياً (وهذا ما يجعل أمثلة curl في هذه الصفحة تعمل)؛ أرسل تغليفاً يأتيك الرد مشفّراً.

التغليفات الأقدم من ±300 ثانية تُرفض، فحافظ على دقة ساعة الجهاز. ولا تحتاج بناء هذا يدوياً: العملاء المفتوحون (VB.NET وC# وPython) يتضمنون تنفيذ CryptoEnvelope جاهزاً.

كيف يُبنى المظروف

الاتجاهان يستخدمان الوصفة نفسها. يُشتق مفتاحان من سر تطبيقك، فيحصل كل تطبيق على مفتاحي تشفير وتوقيع مستقلّين:

enc_key = SHA256("enc:" + app_secret)          # 32 bytes
mac_key = SHA256("mac:" + app_secret)          # 32 bytes

# client → server (and server → client — same recipe)
iv = random_bytes(16)
ct = AES-256-CBC(enc_key, iv, json_body)       # PKCS#7 padding
p  = base64(iv || ct)
t  = unix_time()                               # ±300 s accepted
s  = hex(HMAC-SHA256(p + str(t), mac_key))
send { "p": p, "t": t, "s": s }

# receiving: verify s FIRST (constant-time), check |now - t| ≤ 300,
# then base64-decode p, split off the 16-byte IV, decrypt the rest.

أي نقاط النهاية تتطلبه

كل بطاقة نقطة نهاية تحمل شارة مصادقة ملوّنة؛ وهذا الجدول يجمع المعلومة نفسها بنظرة واحدة:

الاستجابات والأخطاء

كل استجابة تحمل قيمة منطقية success. والأخطاء تضيف رسالة بشرية message ورمزًا ثابتًا قابلًا للقراءة آليًا error_code:

{
  "success": false,
  "message": "This license key has been banned.",
  "error_code": "BANNED"
}

أكواد حالة HTTP

حدود المعدل والاستخدام العادل

يحمي محدِّد طلبات عام لكل عنوان IP جميع نقاط النهاية — الإغراق يعيد 429 مع ترويسة Retry-After (وللمدراء الموثّقين سقف أعلى). وفوق ذلك حرّاس موجَّهون:

• دخول الأدمن محمي من التخمين — الإخفاقات المتكررة تقفل الحساب مؤقتاً.
• التجارب محدودة لكل جهاز (HWID) ولكل IP؛ تجاوزها يرجع TRIAL_LIMIT.
• إعادة توليد السر محدودة المعدل لكل تطبيق لمنع حلقات التدوير العرضية.
• أبقِ الheartbeats على الفاصل الذي يرجعه ردّ الدخول (30 ثانية افتراضاً) — الأسرع لا يضيف شيئاً.

بداية سريعة

أدنى تكامل: تحقّق من المفتاح عند تشغيل تطبيقك، ثم أرسل نبضًا للإبقاء على الجلسة حيّة.

# Validate a key from the terminal (plain JSON works here)
curl -X POST https://pwfauth.com/api/auth/check-key.php \
  -H "X-App-Secret: $APP_SECRET" \
  -d '{"license_key":"XXXXX-XXXXX-XXXXX-XXXXX"}'
# → { "success": true, "valid": true, "key": { "status": "active", … } }

التدفق نفسه عبر SDK رسمي

تسجيل الدخول ونبض القلب ومفتاح الإيقاف من جهة الخادم في أسطر قليلة — الـSDK يتكفّل بالمظروف المشفّر عنك:

// dotnet add package PWFAuth
using PWFAuth;

var client = new PwfClient(APP_SECRET);
client.SessionEnded += (s, e) =>              // ban / pause / expiry / revoke / offline
{
    Console.WriteLine($"{e.ErrorCode}: {e.Message}");
    Environment.Exit(0);
};

var login = await client.LoginAsync("XXXXX-XXXXX-XXXXX-XXXXX");
if (!login.Success) { Console.WriteLine(login.Message); return; }

client.StartHeartbeat();   // keeps the session alive AND enforces the kill switch

' dotnet add package PWFAuth
Dim client As New PwfClient(APP_SECRET)
AddHandler client.SessionEnded, Sub(s, e)     ' ban / pause / expiry / revoke / offline
                                    MessageBox.Show(e.Message)
                                    Application.Exit()
                                End Sub

Dim login = Await client.LoginAsync("XXXXX-XXXXX-XXXXX-XXXXX")
If login.Success Then client.StartHeartbeat()

# pip install pwfauth
import sys
from pwfauth import PwfClient

client = PwfClient(APP_SECRET)
client.on_session_ended = lambda code, msg: sys.exit(msg)   # kill switch

login = client.login("XXXXX-XXXXX-XXXXX-XXXXX")
if not login.success:
    sys.exit(login.message)

client.start_heartbeat()   # keeps the session alive AND enforces the kill switch

// npm install pwfauth
import { PwfClient } from 'pwfauth';

const client = new PwfClient(process.env.PWFAUTH_SECRET);
client.on('sessionEnded', ({ errorCode, message }) => {     // kill switch
    console.error(`${errorCode}: ${message}`);
    process.exit(1);
});

const login = await client.login('XXXXX-XXXXX-XXXXX-XXXXX');
if (!login.success) { console.error(login.message); process.exit(1); }

client.startHeartbeat();   // keeps the session alive AND enforces the kill switch

التراخيص والجلسات

{
  "success": true,
  "session_id": "8f2c…",
  "user": {
    "license_key": "XXXXX-XXXXX-XXXXX-XXXXX",
    "key_type": "days", "duration": 30,
    "expires_at": "2026-09-01T12:00:00Z",
    "days_remaining": 30, "status": "active"
  },
  "features": { "pro_tier": true },
  "heartbeat_interval": 30
}

{ "success": true, "message": "Heartbeat received" }

// the moment the key is banned / paused / expired / reset, the SAME call answers:
{ "success": false, "error_code": "BANNED",
  "message": "This license key has been banned." }   // session is dropped — log the user out

curl -X POST https://pwfauth.com/api/auth/check-key.php \
  -H "X-App-Secret: $APP_SECRET" \
  -d '{"license_key":"XXXXX-XXXXX-XXXXX-XXXXX"}'

var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-App-Secret", APP_SECRET);
var res = await http.PostAsync("https://pwfauth.com/api/auth/check-key.php",
    new StringContent("{\"license_key\":\"XXXXX-XXXXX-XXXXX-XXXXX\"}"));

import urllib.request, json
req = urllib.request.Request("https://pwfauth.com/api/auth/check-key.php",
    data=json.dumps({"license_key": "XXXXX-XXXXX-XXXXX-XXXXX"}).encode(),
    headers={"X-App-Secret": APP_SECRET})
print(json.load(urllib.request.urlopen(req)))

const res = await fetch('https://pwfauth.com/api/auth/check-key.php', {
  method: 'POST',
  headers: { 'X-App-Secret': process.env.APP_SECRET },
  body: JSON.stringify({ license_key: 'XXXXX-XXXXX-XXXXX-XXXXX' })
});
console.log(await res.json());

$ch = curl_init('https://pwfauth.com/api/auth/check-key.php');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-App-Secret: ' . $APP_SECRET],
    CURLOPT_POSTFIELDS => '{"license_key":"XXXXX-XXXXX-XXXXX-XXXXX"}']);
$res = json_decode(curl_exec($ch), true);

{
  "success": true, "valid": true,
  "key": {
    "status": "active", "key_type": "days", "duration": 30,
    "activated_at": "2026-08-02T12:00:00Z",
    "expires_at": "2026-09-01T12:00:00Z",
    "days_remaining": 30, "max_devices": 1
  }
}

التجارب المجانية

{
  "success": true, "message": "Trial activated! You have 3 days.",
  "trial_key": "TRIAL-1A2B3-C4D5E-F6A7B",
  "session_id": "8f2c…",
  "expires_at": "2026-08-23T12:00:00Z", "days_remaining": 3,
  "user": { "key_type": "days", "status": "active", … },
  "app":  { "name": "…", "version": "…" }
}

حسابات المستخدمين

تفضّل الدخول باسم مستخدم/كلمة مرور بدل المفاتيح الخام؟ يوفّر PWF Auth نموذج حسابات كامل مع تجزئة bcrypt وربط HWID.

محتوى التطبيق والتحكم عن بُعد

هذه النقاط تتيح لتطبيقك المنشور سحب محتوى تحرّره حيّاً من اللوحة — نصوص وشرائح وأسعار وسجلّ تغييرات — بدون إصدار تحديث.

تحديثات OTA

{
  "success": true, "update_available": true,
  "update": {
    "version": "1.4.0", "channel": "stable",
    "is_mandatory": false, "file_size": 5242880,
    "sha256": "…", "changelog": "…",
    "download_url": "api/update/download.php?v=1.4.0"
  }
}

Webhooks

حوِّل الأحداث إلى استدعاءات HTTP نحو خادمك: تفعيلات المفاتيح، الحظر، الانتهاء، الطلبات، التحديثات الجديدة وغيرها. جهِّز الوجهات لكل تطبيق (أو لكل التطبيقات) من اللوحة تحت Application → Webhooks، واختر الأحداث التي تهمك، وسيرسل PWF Auth جسم JSON موقَّعاً إلى رابطك بطلب POST. التسليم عبر طابور — توقَّعه خلال دقيقة أو دقيقتين من الحدث، لا في اللحظة نفسها.

حمولة التسليم

{
  "event": "key.activated",
  "timestamp": "2026-08-20T14:07:02Z",
  "data": {
    "app_id": "01af6643-…",
    "license_key": "XXXXX-XXXXX-XXXXX-XXXXX",
    "hwid": "A1B2C3…"
  }
}

ترويسات التسليم

التحقق من التوقيع

تحقَّق دائماً قبل الوثوق بأي تسليم: احسب MAC النسخة الثانية على timestamp + "." + raw body بسر نقطتك، وقارن بزمن ثابت، وارفض الطوابع القديمة (±5 دقائق تكفي). أجب بـ2xx بسرعة — الأعمال الثقيلة مكانها طابورك الخاص.

// X-Webhook-Signature-V2: t=<ts>,v1=<hex>
[$t, $v1] = explode(',', $_SERVER['HTTP_X_WEBHOOK_SIGNATURE_V2'] ?? ',');
$t = substr($t, 2);  $v1 = substr($v1, 3);
$raw = file_get_contents('php://input');

$ok = hash_equals(hash_hmac('sha256', $t . '.' . $raw, $secret), $v1)
   && abs(time() - (int)$t) < 300;
if (!$ok) { http_response_code(400); exit; }
http_response_code(200);   // answer fast — queue heavy work

// X-Webhook-Signature-V2: t=<ts>,v1=<hex>
const [t, v1] = req.headers['x-webhook-signature-v2']
    .split(',').map(kv => kv.split('=')[1]);
const mac = crypto.createHmac('sha256', secret)
    .update(`${t}.${rawBody}`).digest('hex');

const ok = crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1))
        && Math.abs(Date.now() / 1000 - Number(t)) < 300;
res.sendStatus(ok ? 200 : 400);   // answer fast — queue heavy work

# X-Webhook-Signature-V2: t=<ts>,v1=<hex>
import hmac, time
t, v1 = (kv.split("=", 1)[1]
         for kv in request.headers["X-Webhook-Signature-V2"].split(","))
mac = hmac.new(secret, f"{t}.{raw_body}".encode(), "sha256").hexdigest()

ok = hmac.compare_digest(mac, v1) and abs(time.time() - int(t)) < 300
return ("", 200) if ok else ("", 400)   # answer fast — queue heavy work

إعادة المحاولة وسياسة الفشل

• يُعَد التسليم ناجحاً عند أي رد 2xx/3xx خلال 5 ثوانٍ.
• الفشل يُعاد حتى 5 محاولات بفجوات متزايدة: 1د ← 5د ← 30د ← 2س ← 6س.
• X-Webhook-Id يُسَكّ مرة واحدة لكل حدث ويُعاد استخدامه في كل محاولة — منع التكرار يصبح فحص seen? واحداً.
• الوجهة التي تفشل 20 مرة متتالية تُوقَف تلقائياً؛ أعد تفعيلها من اللوحة (وزر حدث test موجود هناك).

الأحداث

اشترك بأحداث محددة أو اترك المرشِّح فارغاً لتستقبلها كلها. حقل event في الجسم يخبرك أيُّها وقع:

واجهة الأدمن

نقاط من جهة الخادم لإدارة التطبيقات والمفاتيح. كلها تتطلّب رمز Authorization: Bearer من نقطة الدخول أدناه.

لا تريد تخزين كلمة مرورك داخل سكربت؟ أنشئ توكن وصول شخصياً من اللوحة ← الملف الشخصي ← API Tokens واستخدمه كقيمة Bearer (pwf_…). لا تنتهي صلاحيته حتى تلغيه بنفسك، ويعمل مع كل نقاط /api/admin/*، وهو ممنوع تصميمياً من إدارة بيانات الاعتماد (كلمة المرور، البريد، 2FA، إنشاء توكنات جديدة).

curl -X POST https://pwfauth.com/api/admin/keys.php \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"app_id":"01af6643-cf3a-4280-b9ce-cb5fa8ae987c",
       "count":100,"key_type":"days","duration_value":30}'

تغطّي واجهة الأدمن أيضًا apps، sessions، updates، feature-flags، webhooks، analytics، audit، resellers، والمزيد — كلها تحت /api/admin/ بنفس مصادقة Bearer. سجّل الدخول إلى لوحة التحكّم لاستكشافها.

حِزَم SDK

تعمل واجهة REST من أي شيء يستطيع إرسال طلب HTTP. الحِزَم الرسمية منشورة على السجلّات العامة — PWFAuth على NuGet ‏(C#‎ / VB.NET)، وpwfauth على npm ‏(JavaScript / Node.js) وعلى PyPI ‏(Python) — إضافة إلى امتداد VS Code وأمثلة PHP من الدرجة الأولى. كل SDK يتكفّل عنك بالمظروف المشفّر ونبض القلب ومفتاح الإيقاف.

• عملاء أمثلة مفتوحو المصدر (VB.NET · C# · Python) — تدفقات دخول/heartbeat/تغليف كاملة جاهزة للنسخ
• البدء السريع داخل اللوحة — 5 خطوات موجَّهة تولّد مقتطفات تعمل بـ9 لغات ببياناتك الحقيقية
• مواصفة OpenAPI 3.1 ‏(openapi.json) — استيراد بنقرة واحدة في Postman / Insomnia، أو غذِّ بها مولّد الأكواد