توثيق الـAPI

المصادقة

أرسل مفتاحك في ترويسة X-API-Key مع كل طلب. العنوان الأساسي:

https://sultankoo.xyz/api/v1

حالة حسابك GET /me.php

curl -H "X-API-Key: KEY" https://sultankoo.xyz/api/v1/me.php

{
  "success": true,
  "data": {
    "subscription": { "plan": "أساسية", "status": "active",
                      "ends_at": "2026-10-09 00:00:00", "days_left": 60 },
    "limits": { "rate_limit_hour": 1000, "used_this_hour": 4,
                "apps_cap": null, "files_hosting": false }
  }
}

استخدمها ليعرف نظامك متى يتوقّف عن الطلب بدل أن يصطدم بالحد.

التطبيقات GET /apps.php

المعامل	القيم	الوصف
platform	all · android · ios	الافتراضي all
page	1، 2، …	رقم الصفحة
per_page	1–500	الافتراضي 100
updated_since	YYYY-MM-DD HH:MM:SS	ما تغيّر بعد هذا الوقت فقط
category	اسم التصنيف	مثل: الالعاب
q	نص	بحث في الاسم

curl -H "X-API-Key: KEY" \
  "https://sultankoo.xyz/api/v1/apps.php?platform=android&per_page=50&page=1"

{
  "success": true,
  "data": {
    "page": 1, "per_page": 50, "total": 469, "returned": 50, "has_more": true,
    "server_time": "2026-08-10 21:15:00",
    "apps": [
      {
        "source_app_id": 512,
        "platform": "android",
        "app_name": "انستقرام الذهبي",
        "version": "11.20",
        "description": "…",
        "category": "التطبيقات",
        "icon_url": "https://sultankoo.xyz/uploads/android-icons/….png",
        "delivery_type": "file",
        "download_url": "https://sultankoo-apps.fra1.cdn.digitaloceanspaces.com/uploads/…apk",
        "file_size": "82.4 MB",
        "downloads": 0,
        "updated_at": "2026-08-10 16:51:17"
      }
    ]
  }
}

source_app_id ثابت لا يتغيّر — استخدمه مفتاحاً عندك للربط والتحديث.

التصنيفات GET /categories.php

curl -H "X-API-Key: KEY" https://sultankoo.xyz/api/v1/categories.php

{ "success": true, "data": {
  "android": [ { "id": 1, "name": "التطبيقات", "apps": 120 } ],
  "ios":     [ { "id": 1, "name": "تواصل اجتماعي", "apps": 1 } ] } }

المزامنة التفاضلية — الطريقة الموصى بها

لا تسحب الكتالوج كاملاً كل مرة. اسحبه مرة، ثم اسحب ما تغيّر فقط:

1) أول مرة:  GET /apps.php?per_page=500&page=1,2,3…
   واحفظ عندك server_time من الرد.

2) كل مرة بعدها:
   GET /apps.php?updated_since=<server_time المحفوظ>
   حدّث ما رجع، واحفظ server_time الجديد.

هذا يوفّر باقتك وباقتنا، ويسمح بالتحديث كل دقيقة بلا ضغط.

رموز الردود

الرمز	المعنى	ماذا تفعل
200	تمّ	—
401	المفتاح ناقص أو غير صحيح	تحقّق من الترويسة
402	الاشتراك منتهٍ	جدّد — يعود فوراً
403	المفتاح غير مفعّل أو مُبطَل	راجعنا
429	تجاوزت حدّ باقتك	انتظر حسب Retry-After أو رقِّ باقتك

كل خطأ يرجع برسالة عربية واضحة داخل error.message.

أمثلة جاهزة

PHP

$ch = curl_init("https://sultankoo.xyz/api/v1/apps.php?per_page=200");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: KEY"]]);
$data = json_decode(curl_exec($ch), true);
foreach ($data["data"]["apps"] as $app) {
    // احفظ $app["source_app_id"] عندك
}

Python

import requests
r = requests.get("https://sultankoo.xyz/api/v1/apps.php",
                 headers={"X-API-Key": "KEY"},
                 params={"per_page": 200, "platform": "android"})
for app in r.json()["data"]["apps"]:
    print(app["app_name"], app["version"])

JavaScript

const res = await fetch(
  "https://sultankoo.xyz/api/v1/apps.php?per_page=200",
  { headers: { "X-API-Key": "KEY" } });
const { data } = await res.json();
console.log(data.total, data.apps.length);