انتقل إلى المحتوى
White page Kit
العربية

وثائق API

أنشئ مواقع whitepage من شيفرتك أو من أداة بلا شيفرة أو بمجرد أن تطلب من مساعد ذكاء اصطناعي، وتابع التقدم ونزّل الملفات. كل الطلبات JSON عبر HTTPS.

كيف يعمل

ثلاث خطوات مهما كانت طريقة الربط:

  1. أنشئ مفتاح API سجّل الدخول وافتح صفحة مفاتيح API في لوحة التحكم وأنشئ مفتاحاً. يعمل كأنه كلمة مرور لحسابك، فاحتفظ به سرياً.
  2. اطلب موقعاً أرسل عنواناً ولغة، وإن شئت الموضوع والجمهور والكلمات المفتاحية. يُحجز سعر التوليد من رصيدك ويبدأ بناء الموقع.
  3. استلم موقعك يكون جاهزاً عادةً خلال دقائق. استعلم عن حالته أو دعنا نستدعي رابطك عند الانتهاء، ثم عاينه وعدّله وحمّل الملفات.

اختر طريقة الربط

الأدوات بلا شيفرة: أي أداة تستطيع إرسال طلب HTTP (Zapier أو Make أو n8n أو سكربت جداول) تنفّذ الاستدعاءات نفسها. يبدأ POST /sites الموقع، ثم يخبرك GET /sites/{uuid} بمؤقّت أو callback_url بانتهائه. ضع مفتاح API في ترويسة Authorization.

مصطلحات أساسية

الموقع
موقع ويب واحد مُولَّد بكل صفحاته، ويُعرَّف بمعرّف uuid.
الحالة
pending أثناء البناء، وdone عند الجاهزية، وerror عند الفشل. يُسترد مبلغ الموقع الفاشل تلقائياً.
مفتاح API
نص سري يثبت أن الطلب صادر من حسابك. تنشئ المفاتيح وتلغيها من لوحة التحكم.
الرصيد
مبلغ مدفوع مسبقاً في حسابك. إنشاء موقع يحجز سعر التوليد منه.
الاستدعاء العكسي (Callback)
رابط خاص بك نستدعيه مرة واحدة عند انتهاء الموقع، فلا تحتاج إلى السؤال المتكرر.
مفتاح عدم التكرار (Idempotency)
وسم تضيفه إلى الطلب كي لا يؤدي إرساله مرتين إلى إنشاء موقعين أو خصم المبلغ مرتين.

استخدمه مع مساعدي الذكاء الاصطناعي

اربط مساعد ذكاء اصطناعي واطلب ببساطة: "أنشئ موقعاً لعيادة الأسنان الخاصة بي بالعربية." يستدعي المساعد واجهة API نفسها بحسابك. تبقى السيطرة بيدك: إنشاء موقع يستهلك رصيداً، والمساعدون الجيدون يسألونك قبل ذلك.

أمثلة على ما يمكنك قوله

  • كم رصيدي، وكم يكلّف الموقع الواحد؟
  • ما قوالب التصميم المناسبة لمخبز؟
  • أنشئ موقعاً من صفحة واحدة لنُزل ميناء هادئ اسمه Alder House بالإنجليزية.
  • هل موقعي جاهز؟ أرسل لي رابط المعاينة.

الربط عبر MCP (Claude وCursor وغيرهما)

MCP هو المعيار المفتوح الذي تستخدمه المساعدات لاستدعاء الأدوات الخارجية. وجّه مساعدك إلى عنوان MCP وأعطه مفتاح API كرمز Bearer.

Claude Code

bash

claude mcp add --transport http whitepagekit https://whitepagekit.com/api/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "whitepagekit": {
      "url": "https://whitepagekit.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:WPK_API_KEY}"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json

{
  "mcpServers": {
    "whitepagekit": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://whitepagekit.com/api/v1/mcp",
               "--header", "Authorization:${WPK_AUTH}"],
      "env": { "WPK_AUTH": "Bearer YOUR_API_KEY" }
    }
  }
}

JSON-RPC خام

curl

curl -X POST https://whitepagekit.com/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_account","arguments":{}}}'

يصل Claude Desktop إلى الخوادم البعيدة عبر جسر mcp-remote، ويحتاج إلى Node.js.

ChatGPT (GPT مخصص)

  1. في ChatGPT أنشئ GPT وافتح Configure ثم اختر Create new action.
  2. اختر Import from URL والصق https://whitepagekit.com/api/v1/openapi.json?profile=assistant. يضم هذا المخطط المختصر أدوات المساعد الست فقط.
  3. ضمن Authentication اختر API key واجعل Auth Type هو Bearer والصق مفتاح API.
  4. يطلب ChatGPT تأكيدك قبل إرسال الطلبات التي تغيّر شيئاً، فتبقى متحكماً بكل ما يستهلك الرصيد.

Schema URL

https://whitepagekit.com/api/v1/openapi.json?profile=assistant

OpenAI API (أداة MCP)

يستطيع Responses API استخدام عنوان MCP كأداة بعيدة. ويُبقي require_approval إنساناً في الحلقة.

Python

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="YOUR_MODEL",
    tools=[{
        "type": "mcp",
        "server_label": "whitepagekit",
        "server_url": "https://whitepagekit.com/api/v1/mcp",
        "headers": {"Authorization": "Bearer YOUR_API_KEY"},
        "require_approval": "always",
    }],
    input="What does one site cost, and which design kits suit a bakery?",
)
print(response.output_text)

حلقة الأدوات الخاصة بك (استدعاء الدوال)

إذا كنت تدير حلقة النموذج بنفسك فاجلب مخططات الأدوات الجاهزة ونفّذ كل استدعاء أداة على نقطة REST المقابلة. الصيغ: openai (Responses API) وopenai-chat وanthropic وmcp.

curl

curl "https://whitepagekit.com/api/v1/ai-tools?format=openai"   # or openai-chat, anthropic, mcp

الأدوات الست

الأدوات الست
الأداة ماذا تفعل استدعاء REST التكلفة
get_account تعرض رصيدك وسعر الموقع الواحد. GET /me مجانية
list_languages تسرد اللغات التي يمكن كتابة الموقع بها. GET /languages مجانية
list_themes تبحث في قوالب التصميم بحسب الموضوع أو الأسلوب. GET /themes مجانية
create_site تبدأ توليد موقع وتخصم سعر التوليد من رصيدك. POST /sites تستهلك الرصيد
get_site تعرض موقعاً واحداً: التقدم ورابطَي المعاينة والتحميل. GET /sites/{uuid} مجانية
list_sites تسرد مواقعك من الأحدث إلى الأقدم. GET /sites مجانية

أعطِ هذا التوثيق لأي ذكاء اصطناعي

هذه الصفحة متاحة أيضاً بصيغة Markdown بسيطة، مناسبة للصقها في محادثة أو إعطائها لمساعد برمجة:

Markdown

https://whitepagekit.com/api/v1/docs.md

نص يمكنك لصقه

Prompt

You can build websites with the White Page Kit API. Read https://whitepagekit.com/api/v1/docs.md first.
My API key is in the environment variable WPK_API_KEY.
Check my balance and the price, then create a site for my dental clinic in Izmir, in Turkish,
wait until it is ready and send me the preview link.

الأمان والتكلفة

  • أداة create_site وحدها تستهلك الرصيد. الأدوات الخمس الأخرى للقراءة فقط.
  • استخدم مفتاحاً منفصلاً للمساعدين. حدّد له تاريخ انتهاء وحداً للمعدل من لوحة التحكم، وألغِه متى شئت.
  • لا يستطيع المساعدون حذف المواقع أو تغيير الإعدادات أو لمس المدفوعات، فهذه المسارات غير معروضة كأدوات.
  • اضبط idempotency_key في create_site كي لا تؤدي إعادة المحاولة إلى خصم مرتين. تُسترد مبالغ عمليات التوليد الفاشلة.
  • يبقى تحرير الصفحات والصور المرجعية وتنزيل ZIP في REST API ولوحة التحكم.

بدء سريع

ثلاثة طلبات تنقلك من وصف مختصر إلى موقع قابل للتنزيل. استبدل YOUR_API_KEY بمفتاح من لوحة التحكم.

1. ابدأ الإنشاء

يتحقق POST /sites من وصفك ويحجز سعر الإنشاء من رصيدك ويرد فوراً.

curl

curl -X POST https://whitepagekit.com/api/v1/sites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-attempt-1" \
  -d '{"title":"Alder House","lang":"en","sector":"guesthouse","keywords":"quiet stay, harbour","structure":"onepage"}'

الرد 202 Accepted مع الموقع الجديد:

202 Accepted

{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "title": "Alder House",
    "lang": "en",
    "preview_url": null,
    "download_url": null
  }
}

2. استعلم عن الحالة

استعلم عن GET /sites/{uuid} كل 5 إلى 20 ثانية تقريباً حتى تصبح الحالة done أو error، أو استخدم callback URL بدلاً من الاستعلام.

curl

curl https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: YOUR_API_KEY"

3. نزّل الملفات

يُنزَّل الموقع المكتمل كملف ZIP. القيمة format هي multi أو onepage، وassets هي inline أو external.

curl

curl -o site.zip \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://whitepagekit.com/api/v1/sites/550e8400-e29b-41d4-a716-446655440000/download?format=multi&assets=inline"

التدفق نفسه بالشيفرة

PHP

<?php
$ch = curl_init('https://whitepagekit.com/api/v1/sites');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WPK_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: order-1042-attempt-1',
    ],
    CURLOPT_POSTFIELDS => json_encode(['title' => 'Alder House', 'lang' => 'en']),
]);
$site = json_decode(curl_exec($ch), true)['data'];
do {
    sleep(5);
    $ch = curl_init('https://whitepagekit.com/api/v1/sites/' . $site['uuid']);
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('WPK_API_KEY')]]);
    $site = json_decode(curl_exec($ch), true)['data'];
} while ($site['status'] === 'pending');

Node.js

const headers = {
  Authorization: `Bearer ${process.env.WPK_API_KEY}`,
  'Content-Type': 'application/json',
  'Idempotency-Key': 'order-1042-attempt-1',
};
let { data: site } = await (await fetch('https://whitepagekit.com/api/v1/sites', {
  method: 'POST', headers,
  body: JSON.stringify({ title: 'Alder House', lang: 'en' }),
})).json();
while (site.status === 'pending') {
  await new Promise((r) => setTimeout(r, 5000));
  ({ data: site } = await (await fetch(`https://whitepagekit.com/api/v1/sites/${site.uuid}`, { headers })).json());
}

Python

import os, time, requests

headers = {"Authorization": f"Bearer {os.environ['WPK_API_KEY']}",
           "Idempotency-Key": "order-1042-attempt-1"}
site = requests.post("https://whitepagekit.com/api/v1/sites", headers=headers,
                     json={"title": "Alder House", "lang": "en"}).json()["data"]
while site["status"] == "pending":
    time.sleep(5)
    site = requests.get(f"https://whitepagekit.com/api/v1/sites/{site['uuid']}", headers=headers).json()["data"]

المصادقة

أرسل مفتاح API مع كل طلب باستثناء مستند OpenAPI. احتفظ بالمفاتيح على خادمك ولا تضعها في شيفرة المتصفح أو الروابط.

  • الترويسة: Authorization: Bearer YOUR_API_KEY أو X-API-Key: YOUR_API_KEY.
  • أنشئ المفاتيح وألغِها وحدّد معدلها من لوحة التحكم. يمكن أن يكون للمفتاح تاريخ انتهاء وقائمة IP مسموحة.
  • ترى مواقعك فقط. الموقع التابع لحساب آخر يعيد 404 not_found.
  • أضف ?lang=xx أو Accept-Language لتعريب رسائل الأخطاء.

عدم التكرار (Idempotency)

أرسل Idempotency-Key (من 8 إلى 80 حرفاً: أحرف وأرقام و _ و -) مع POST /sites. تكرار المفتاح نفسه يعيد الموقع الأصلي ولا يخصم مرتين، لذا فإعادة المحاولة بعد انتهاء المهلة آمنة. استخدم مفتاحاً جديداً لإعادة محاولة إنشاء فاشل.

Webhook (استدعاءات)

مرّر callback_url إلى POST /sites (أو اضبط Webhook للحساب) لتستلم طلب JSON POST واحداً عند انتهاء المهمة (site.completed) أو فشلها (site.failed).

POST callback_url

{
  "event": "site.completed",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "done",
  "site_title": "Alder House",
  "lang": "en",
  "domain": null,
  "created_at": "2026-01-15T09:30:00+00:00",
  "preview_url": "https://whitepagekit.com/preview?uuid=550e8400-…"
}

عندما يكون للحساب سر Webhook يحمل كل طلب الترويسة X-Webhook-Signature: sha256=<hex>، وهي HMAC-SHA256 للجسم الخام. تحقق منها قبل تحليل JSON باستخدام مقارنة زمنها ثابت:

PHP

$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $webhookSecret);
if (!hash_equals($expected, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Node.js

import crypto from 'node:crypto';

const expected = 'sha256=' + crypto
  .createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
const received = req.get('x-webhook-signature') ?? '';
const ok = received.length === expected.length
  && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

تُجرَّب كل استدعاءات مرة واحدة بمهلة 10 ثوانٍ ولا تُعاد. اعتبرها إشعاراً وطابقها مع GET /sites/{uuid}. عالج التكرار بطريقة idempotent حسب uuid وevent. تُرفض أهداف الشبكات الخاصة.

الأخطاء

يستخدم كل رد غلافاً موحداً. تحمل الأخطاء رمزاً ثابتاً ورسالة معرّبة، وفي أخطاء التحقق الحقل الخاطئ.

JSON

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "...",
    "details": { "field": "title" }
  }
}
الأخطاء
HTTPرموز الأخطاء
400 validation_error, invalid_json, invalid_webhook_url
401 missing_api_key
402 insufficient_balance
403 api_disabled, invalid_api_key, forbidden
404 not_found, route_not_found
405 method_not_allowed
409 site_not_ready, conflict, edits_reset_required
413 payload_too_large
415 unsupported_media_type
429 rate_limited
500 internal_error, export_failed
502 generation_failed

الحدود

الحدود
الحد القيمة
الطلبات لكل مفتاح 60 في الدقيقة افتراضياً (قابل للضبط لكل مفتاح، 0 = بلا حد). المفاتيح غير الصالحة المتكررة من IP واحد تحصل على 429 مع Retry-After.
جسم الطلب 2 ميغابايت؛ وPOST /sites مع صور مرجعية حتى 162 ميغابايت؛ وحفظ المحرر حتى 4 ميغابايت.
الصور المرجعية حتى 12 صورة PNG أو JPEG أو WEBP (base64 أو data URL)، بحد أقصى 10 ميغابايت لكل صورة.
محتوى صفحة المحرر HTML حتى 500,000 حرف وCSS حتى 100,000. تُزال السكربتات ومعالجات الأحداث.
صور الموقع PNG أو JPEG أو WEBP أو GIF، 5 ميغابايت لكل صورة، حتى 200 لكل موقع.
عنوان الموقع عنوان الموقع من 1 إلى 200 حرف.

واجهة المحرر

كل ما يفعله محرر لوحة التحكم متاح لمواقعك المكتملة: محتوى الصفحة وخطة الصفحات والأقسام والنمط والعنوان/السمة/التخطيط/البنية والتتبع والصور. تعديل الصفحة يستبدلها؛ وDELETE يستعيد الصفحة المُنشأة.

curl

# Load, change and save a page
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://whitepagekit.com/api/v1/sites/UUID/editor?page=index"
curl -X PATCH https://whitepagekit.com/api/v1/sites/UUID/editor \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"index","html":"<main>…</main>","css":""}'
# Restore the generated page
curl -X DELETE -H "X-API-Key: YOUR_API_KEY" \
  "https://whitepagekit.com/api/v1/sites/UUID/editor?page=index"

يتطلب التعديل موقعاً مكتملاً (وإلا 409 site_not_ready). تغيير السمة أو التخطيط أو البنية فوق صفحات معدّلة يعيد 409 edits_reset_required ما لم تكن reset_edits تساوي true. التعديل مجاني.

مرجع نقاط النهاية

يُولَّد من مستند OpenAPI لذا يطابق الواجهة الحية دائماً. المسارات نسبية إلى عنوان القاعدة.

الحساب

  • GET /me

    Get the authenticated account

  • GET /transactions

    List account balance transactions

الفهرس

  • GET /languages

    List enabled supported languages

  • GET /themes

    List site themes

  • GET /layouts

    List enabled layouts

المواقع

  • GET /sites

    List the authenticated account's sites

  • POST /sites

    Start site generation

  • GET /sites/{uuid}

    Get site status and refresh generation state

  • DELETE /sites/{uuid}

    Delete a terminal site and its generated data — Pending, queued and running generation jobs cannot be deleted. Wait for done or error; active deletion returns 409 conflict without refunding or removing the job.

  • GET /sites/{uuid}/download

    Download a completed site archive

الذكاء الاصطناعي والأتمتة

  • GET /ai-tools

    Function-calling tool schemas — The same six tools the MCP endpoint offers, as JSON schemas for your own tool loop. format is openai (Responses API), openai-chat (Chat Completions), anthropic or mcp. Public; no response envelope.

  • GET /docs.md

    Documentation as Markdown — The developer guide, endpoint reference and AI integration guide as one Markdown file, written for language models and quick copy-paste. Public.

  • POST /mcp

    Model Context Protocol endpoint — MCP over Streamable HTTP (JSON-RPC 2.0, one JSON reply per POST). Methods: initialize, ping, tools/list, tools/call. Tools: get_account, list_languages, list_themes, create_site (paid), get_site, list_sites. Authenticate with the same API key; point an MCP client at this URL.

المحرر

  • GET /sites/{uuid}/editor

    Load a page for editing — Editor access for the site owner's API key; mirrors the dashboard editor. Only completed sites (409 site_not_ready otherwise).

  • PATCH /sites/{uuid}/editor

    Save a page's edited content — Replaces the page content and CSS. html must be non-empty (use DELETE to restore the generated page); scripts, event handlers and javascript: URLs are removed, HTML is limited to 500000 and CSS to 100000 characters, request body to 4 MB. Returns the saved page as GET does.

  • DELETE /sites/{uuid}/editor

    Restore a page's generated content — Discards the page's saved edits. Returns the regenerated page.

  • GET /sites/{uuid}/editor/canvas

    Get editing canvas data — Stylesheet, Tailwind theme, body class, direction, section blocks, icons and sample copy an external visual editor needs to render the page like the dashboard editor.

  • GET /sites/{uuid}/pages

    Get the page and section plan — Returns structure, pages with their sections and edited flag, one-page sections and the sections available to add. Same payload as the dashboard.

  • POST /sites/{uuid}/pages

    Save the page and section plan — Body: pages (list of {slug, title, nav, sections}; the first page is index) and, for onepage sites, onepage_sections. Sections of pages with saved edits are locked in the dashboard; edited pages that are removed lose their edits. At most 12 pages.

  • GET /sites/{uuid}/style

    Get style overrides — Returns stored overrides, effective colors, fonts, radius and density, and the allowed font, radius and density values.

  • POST /sites/{uuid}/style

    Save or reset style overrides — Send style ({colors, fonts: {heading, body}, radius, density}) or reset=true to return to the theme.

  • GET /sites/{uuid}/design

    Get site title, theme and layout — Returns site_title, title_suggestions, theme_variant, theme_mode, layout, structure and whether the site has saved edits.

  • POST /sites/{uuid}/design

    Change site title, theme, mode, layout or structure — theme_variant, theme_mode, layout and structure are required; site_title (1-200 characters), apply_blueprint and reset_edits are optional. Changing theme, layout or structure while pages have saved edits returns 409 edits_reset_required unless reset_edits is true; renaming alone keeps edits.

  • GET /sites/{uuid}/tracking

    Get tracking settings

  • POST /sites/{uuid}/tracking

    Save tracking settings — Body: tracking {ga4_measurement_id, google_ads_id, google_ads_conversion_label, meta_pixel_id, privacy_policy_url, terms_url}. Applied to exports; an empty object removes all tracking.

  • GET /sites/{uuid}/media

    List uploaded site images

  • POST /sites/{uuid}/media

    Upload or delete site images — multipart/form-data with one or more files in files[] (PNG, JPEG, WEBP or GIF, 5 MB each, at most 200 images per site), or JSON {"action": "delete", "name": <name>}. Returns the updated list for uploads. 409 conflict when the per-site image limit is reached.

المدفوعات الخارجية (مفاتيح المسؤول فقط)

  • GET /payment-sites

    List external payment sites owned by the admin API account — Admin role required; payment.manage permission alone is insufficient. Webhook secrets are never returned.

  • POST /payment-sites

    Register an external payment site (admin only)

  • PATCH /payment-sites/{id}

    Update an owned external payment site (admin only)

  • DELETE /payment-sites/{id}

    Delete an owned external payment site (admin only) — Deletion is allowed only when the site has no orders. Sites with orders must be disabled instead.

  • GET /payments

    List external orders owned by the admin API account

  • POST /payments

    Create external checkout or automatic subscription (admin only) — Server-to-server only. Separate from wallet top-ups: no White Page Kit balance, bonus or referral credit. Repeated idempotency key returns the original order; a different payload or reused external order ID conflicts. Provider uncertainty never starts a second checkout automatically.

  • GET /payments/{uuid}

    Read owned external payment status (admin only)

  • POST /payments/{uuid}/cancel

    Cancel an owned subscription or locally close a pending one-time order (admin only) — Subscriptions stop future renewals. Pending one-time cancellation is a local close, not a refund; an already-open provider checkout may still accept payment. A late authenticated real payment remains recorded and notified. No payment is marked paid by a browser return.

  • POST /payments/{uuid}/approve

    Approve funds received for an owned pending or locally cancelled bank transfer (admin only) — Manual confirmation of funds received, including a transfer arriving after local cancellation; never approves a Dodo or Enigmoss order and never credits White Page Kit balance.

تأتي الأوصاف من مستند OpenAPI وهي بالإنجليزية. مخططات الطلب والرد موجودة في ملف المخطط.

تكاملات جاهزة

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