مرجع API

عنوان URL الأساسي

تُرسَل جميع طلبات API إلى هذا الجذر:

https://www.7275.com/api/v1

استخدام HTTPS إلزامي. تُرفض طلبات HTTP (ولا تتم إعادة توجيهها).

المصادقة

يحتاج كل طلب إلى رمز Bearer في ترويسة Authorization. أنشئ رمزًا من لوحة التحكم ← الإعدادات ← API Keys. تتوفر المفاتيح بنوعين live وtest، ولا يصل كل منهما إلا إلى بيئته.

curl https://www.7275.com/api/v1/accounts \
  -H "Authorization: Bearer dxk_live_...your-key..."

• صيغة مفتاح live: يبدأ بـ dxk_live_ ويتكوّن من 64 حرفًا
• صيغة مفتاح test: يبدأ بـ dxk_test_ ومقصور على حساب sandbox
• لا تستخدم المفاتيح أبدًا في كود الواجهة الأمامية — مرّر الطلبات عبر خادمك الخلفي
• إذا تسرّب مفتاح، ألغِه وأنشئ مفتاحًا جديدًا فورًا من لوحة التحكم

الاستخدام مباشرةً من Claude Desktop / Cursor (خادم MCP)

نوفّر خادم Model Context Protocol بلا أي اعتماديات، حتى تتمكن عملاء MCP مثل Claude Desktop وCursor من قراءة حالة AdWhiz لديك مباشرةً. لا حاجة لكتابة أي كود — انسخ كتلة الإعدادات، والصق مفتاح API، ثم أعد تشغيل العميل.

• خمس أدوات للقراءة فقط: عرض الحسابات الإعلانية، وعرض توصيات الذكاء الاصطناعي، ومعرفة وفورات هذا الشهر، وعرض النشاط الأخير، والتحقق من حصة API
• أدوات الكتابة (apply / pause) غير متاحة عمدًا حتى الآن — بانتظار خروج المحسِّن من shadow mode وتوفّر أدلة معايرة كافية لضبطها
• نص Node 18+ واحد. دون npm install. يعمل بلا مشكلات على الأجهزة غير المتصلة / المعزولة (airgapped)
• لا يغادر مفتاح API جهازك أبدًا. تذهب جميع الطلبات مباشرةً عبر HTTPS إلى www.7275.com

أضف ما يلي إلى ملف claude_desktop_config.json في Claude Desktop (macOS: ~/Library/Application Support/Claude/، Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "adwhiz": {
      "command": "node",
      "args": ["/path/to/mcp-server/src/index.mjs"],
      "env": {
        "ADWHIZ_API_KEY": "dxk_live_..."
      }
    }
  }
}

دليل التثبيت الكامل وإعدادات Cursor واستكشاف الأخطاء وإصلاحها على GitHub: github.com/dexun-inc/adwhiz/mcp-server.

نقاط النهاية

تتيح واجهة API في الإصدار v1 عدد 13 نقطة نهاية أساسية تغطي الهوية، وقراءة الحسابات، وإنشاء التوصيات (تطبيقها غير متاح بعد)، وسجلات التدقيق، وإدارة مفاتيح API، والاستعلام عن الحصة، وموجز سجل التغييرات.

مثال على طلب

أنشئ دفعة جديدة من توصيات التحسين للمنصات الثلاث:

curl -X POST https://www.7275.com/api/v1/recommendations/generate \
  -H "Authorization: Bearer dxk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "ga-548-203-7184",
    "platforms": ["google_ads", "meta_ads", "tiktok_ads"],
    "window": "7d"
  }'

مثال على الاستجابة:

{
  "summary": "Pausing 3 high-CPA keywords and reallocating budget...",
  "recommendations": [
    {
      "id": "rec_001",
      "type": "pause_keyword",
      "target": { "accountId": "ga-548-203-7184", "keywordText": "wool socks" },
      "title": "Pause broad-match 'wool socks'",
      "reason": "7-day CPA $45.82 vs target $8",
      "expectedImpact": "Save ~$412/week",
      "confidence": "high"
    }
  ]
}

الاستعلام التزايدي عن /changelog

نقطة النهاية /api/v1/changelog عامة (لا تتطلب مفتاح API) وتدعم أربع وسائل لتوفير عرض النطاق: ETag + If-None-Match، وLast-Modified + If-Modified-Since (curl -z)، والمعامل ?since=YYYY-MM-DD للجلب حسب التاريخ، والمعامل ?limit=N لتحديد الحجم. يمكن لحزم SDK ونصوص cron الجمع بينها للاستعلام المتكرر دون إعادة تنزيل JSON نفسه.

# 1. First call — store the ETag (or Last-Modified) you get back.
curl -i 'https://www.7275.com/api/v1/changelog?limit=10'

# 2. Subsequent calls — pass the stored ETag.
#    Server returns 304 with empty body if nothing has shipped.
curl -i 'https://www.7275.com/api/v1/changelog?limit=10' \
  -H 'If-None-Match: "abc123..."'

# 3. Or anchor on a date instead of an ETag.
#    Only entries whose `date >= since` come back; pair with ?limit
#    to cap the response size.
curl 'https://www.7275.com/api/v1/changelog?since=2026-01-01&limit=20'

# 4. curl -z for Last-Modified-style conditional GET (no ETag needed):
curl -z 'Mon, 20 May 2026 00:00:00 GMT' \
  'https://www.7275.com/api/v1/changelog'

حدود المعدّل

مقسّمة حسب خطة الاشتراك لتجنّب إرهاق حصص Google / Meta / TikTok لدى المصدر:

• Professional: 120 طلبًا في الدقيقة
• Business: 600 طلب في الدقيقة
• Enterprise: مخصّص (عادةً 3,000 طلب في الدقيقة)
• عند تجاوز الحد تُعاد 429 مع ترويسة retry-after — يُنصح باستخدام التراجع الأسّي (exponential backoff)

رموز الأخطاء

تُعيد جميع الأخطاء JSON يتضمن الحقول error.code وerror.message وerror.request_id: