كل نقطة نهاية يمكنك استخدامها بمفتاح API، مرتّبة حسب المجال، مع طريقة HTTP والمسار والنطاق المطلوب وما تقوم به.

تسرد هذه النظرة العامة كل نقطة نهاية تعمل برمز من مفتاح API. كل المسارات تبدأ بـ https://dock.at-harbor.com. والحقول الدقيقة لكل نقطة نهاية موجودة في وصف OpenAPI على https://dock.at-harbor.com/openapi.yaml.

المصادقة ونقاط النهاية العامة

الطريقة والمسار	المصادقة	الغرض
POST /v1/token	لا شيء (معرّف المفتاح والسر في الجسم)	استبدال مفتاح API برمز وصول
GET /v1/plans	لا شيء	الخطط والأسعار
GET /v1/pages/available?handle=…	لا شيء	التحقق مما إذا كان المعرّف متاحًا

الصفحات

الطريقة والمسار	النطاق	الغرض
GET /v1/pages	read:pages	كل صفحات مساحة العمل مع المعرّف الرقمي (ID) والمعرّف (handle) والعنوان والحالة والإصدار المنشور والظهور والرابط
POST /v1/pages	write:pages	إنشاء صفحة؛ مطلوب: handle ‏(2–64 حرفًا: أحرف وأرقام وشرطة) وtemplate_key؛ واختياري: title وdomain_id وtheme_config
GET /v1/pages/{id}	read:pages	صفحة واحدة؛ وفيها أيضًا has_unpublished_changes (قيمته true إذا اختلفت المسودة عن الإصدار المنشور)
PATCH /v1/pages/{id}	write:pages	تغيير title أو handle أو discoverable (الإدراج في الدليل)
PATCH /v1/pages/{id}/visibility	write:pages	public أو private أو password (مع password بطول 4–72 حرفًا)؛ يسري فورًا
POST /v1/pages/{id}/publish	write:pages	نشر المسودة؛ وتحتوي الاستجابة على الإصدار الجديد
GET /v1/pages/{id}/versions	read:pages	الإصدارات المنشورة
GET /v1/pages/{id}/versions/{version}	read:pages	إصدار واحد
POST /v1/pages/{id}/versions/{version}/restore	write:pages	إعادة إصدار إلى المسودة؛ والقيمة current تتجاهل كل تغييرات المسودة
GET /v1/pages/{id}/seo	read:pages	نصوص SEO والمشاركة
PATCH /v1/pages/{id}/seo	write:pages	seo_title وseo_description وog_title وog_description وog_image_asset_id وcanonical_url وnoindex
POST /v1/pages/{id}/invite-link	write:pages	رابط دعوة لصفحة خاصة منشورة؛ days من 1–30، والافتراضي 7. وإلا 409 page_not_private أو page_not_published
POST /v1/pages/{id}/invite-link/revoke	write:pages	إلغاء رابط الدعوة
POST /v1/pages/{id}/uploads	write:assets	رفع ملف لصفحة

المسودة

الطريقة والمسار	النطاق	الغرض
GET /v1/pages/{id}/draft	read:pages	المسودة الحالية: template_key وconfig وtheme_config وcustom_css وseo وتعيينات الصور والروابط
PATCH /v1/pages/{id}/draft	write:pages	واحد على الأقل من: config (حتى 64 KB كـ JSON، وكل نص حتى 5,000 حرف)، وtheme_config، وcustom_css (حتى 50,000 حرف و65,535 بايت)، وseo، وtemplate_key، وtemplate_asset_bindings
GET /v1/pages/{id}/draft/validate	read:pages	التحقق مما إذا كان يمكن نشر المسودة

الكتل

الطريقة والمسار	النطاق	الغرض
GET /v1/pages/{id}/blocks	read:pages	كتل الصفحة
POST /v1/pages/{id}/blocks	write:pages	إنشاء كتلة؛ مطلوب: type وconfig
PATCH /v1/pages/{id}/blocks/{blockId}	write:pages	تعديل كتلة
DELETE /v1/pages/{id}/blocks/{blockId}	write:pages	حذف كتلة
POST /v1/pages/{id}/blocks/reorder	write:pages	تحديد الترتيب
GET /v1/blocks/schemas	read:pages	كل أنواع الكتل مع مخطط (schema) إعداداتها config

الأنواع التي يمكنك إنشاؤها: text وimage وembed وspacer وsocial_links وform وintegration وdonation وmodal وheading وnotice وcoupon وcontact وopening_hours وtour وfile وvcard وcountdown وgallery. أما كتلة الروابط فثابتة ولا تُنشأ عبر نقطة النهاية هذه. وترفض الـ API أنواع الكتل غير المشمولة في خطتك بالخطأ 403 block_type_requires_plan. ولا يتجاوز config الكتلة 128 KB كـ JSON، ولا يتجاوز كل نص فيه 10,000 حرف؛ وفي نافذة المعلومات يمكن أن يصل modal_body_html إلى 50,000 حرف وبحد أقصى 65,535 بايت.

الروابط

الطريقة والمسار	النطاق	الغرض
GET /v1/pages/{id}/links	read:links	روابط الصفحة
POST /v1/pages/{id}/links	write:links	إنشاء رابط؛ مطلوب: title ‏(1–200) وtarget_url_template ‏(8–2048)
GET /v1/pages/{id}/links/{linkId}	read:links	رابط واحد
PATCH /v1/pages/{id}/links/{linkId}	write:links	تعديل رابط
DELETE /v1/pages/{id}/links/{linkId}	write:links	حذف رابط
POST /v1/pages/{id}/links/reorder	write:links	تحديد الترتيب: {"order":[IDs]}

حقول اختيارية عند الإنشاء والتعديل: enabled، وgeo (قاعدة البلد مع mode بقيمة allowlist أو denylist، وcountries)، وdevice (أهداف منفصلة لكل جهاز)، وstarts_at وends_at (الجدولة)، وprotection_tier (الحماية من الروبوتات)، وage_restriction. الجدولة وقواعد البلد والجهاز متاحة ابتداءً من Creator Pro. وعند إعادة الترتيب يكفي إرسال معرّفات الروابط التي يجب أن تنتقل إلى الأمام، وتتبعها كل الروابط الأخرى بترتيبها السابق. وترفض الـ API المعرّفات التي لا تتبع الصفحة بالخطأ 422 validation_failed، وتسردها details.missing_link_ids.

الروابط المختصرة

الطريقة والمسار	النطاق	الغرض
GET /v1/short-links	read:short_links	الروابط المختصرة مع limit وoffset وsort والبحث q؛ وتحتوي الاستجابة على total
POST /v1/short-links	write:short_links	إنشاء؛ مطلوب: target_url ‏(http أو https، 8–2048)؛ واختياري: title (حتى 120) وcustom_slug ‏(3–32، أحرف صغيرة وأرقام وشرطات)
GET /v1/short-links/{id}	read:short_links	رابط مختصر واحد
PATCH /v1/short-links/{id}	write:short_links	تغيير target_url أو title
DELETE /v1/short-links/{id}	write:short_links	حذف رابط مختصر

إذا بلغت حد الروابط المختصرة في خطتك، تستجيب الـ API بالخطأ 402 plan_limit_reached.

الملفات

الطريقة والمسار	النطاق	الغرض
GET /v1/assets	read:assets	ملفات مساحة العمل
POST /v1/assets	write:assets	رفع ملف (multipart/form-data، الحقل file؛ واختياري: page_id وkind وtitle وalt_text)
DELETE /v1/assets/{assetId}	write:assets	حذف ملف

النماذج

الطريقة والمسار	النطاق	الغرض
GET /v1/forms	read:forms	النماذج
POST /v1/forms	write:forms	إنشاء نموذج؛ مطلوب: name وfields ‏(1–100 حقل)
GET /v1/forms/{id}	read:forms	نموذج واحد
PATCH /v1/forms/{id}	write:forms	تعديل نموذج
DELETE /v1/forms/{id}	write:forms	حذف نموذج
GET /v1/forms/{id}/summary	read:forms	الملخص
GET /v1/forms/{id}/submissions	read:forms	الإرسالات، الأحدث أولًا (limit ‏1–500، والافتراضي 100؛ والصفحات التالية عبر cursor = next_cursor)
GET /v1/forms/{id}/submissions/export	read:forms	كل الإرسالات كملف CSV، الأحدث أولًا، حتى حد التصدير في الخطة (ابتداءً من Creator Pro)؛ وتبيّن الترويسة X-Export-Truncated ما إذا كان الملف قد اقتُطع

الإحصائيات

الطريقة والمسار	النطاق	الغرض
GET /v1/stats/pages/{id}/summary	read:stats	المؤشرات الرئيسية لصفحة
GET /v1/stats/pages/{id}/timeseries	read:stats	السلسلة الزمنية لصفحة
GET /v1/stats/pages/{id}/compare	read:stats	المقارنة مع الفترة السابقة
GET /v1/stats/pages/{id}/links	read:stats	النقرات لكل رابط
GET /v1/stats/pages/{id}/widgets	read:stats	النقرات على الودجات
GET /v1/stats/pages/{id}/conversions/breakdown	read:stats	التحويلات لصفحة
GET /v1/stats/workspaces/me/summary	read:stats	المؤشرات الرئيسية لكل الصفحات
GET /v1/stats/workspaces/me/timeseries	read:stats	السلسلة الزمنية لكل الصفحات
GET /v1/stats/workspaces/me/compare	read:stats	المقارنة مع الفترة السابقة
GET /v1/stats/workspaces/me/top-pages	read:stats	أفضل الصفحات
GET /v1/stats/workspaces/me/conversions/breakdown	read:stats	التحويلات لمساحة العمل
GET /v1/stats/workspaces/me/donations	read:donations	مجاميع مدفوعات الداعمين

تختار الفترة كما هو موضّح في ترقيم الصفحات، بـ period أو بـ from وto. ومدى الرجوع إلى الوراء يعتمد على الخطة: 365 يومًا في Creator Pro وAgency، و730 يومًا في Enterprise. والفترات الأقدم تُقتطع حتى هذا الحد.

الإشعارات الفورية (قراءة فقط)

الطريقة والمسار	النطاق	الغرض
GET /v1/push/history	read:stats	سجل الإشعارات الفورية (limit، offset)
GET /v1/push/usage	read:stats	استهلاك الحد الأسبوعي

إرسال الإشعارات الفورية وإدارة قواعد الإشعارات الفورية ممكنان في لوحة التحكم فقط.

مساحة العمل والقوالب والنطاقات المخصصة

الطريقة والمسار	النطاق	الغرض
GET /v1/workspaces/me/entitlements	read:workspaces	ميزات الخطة وحدودها
GET /v1/workspaces/me/usage	read:workspaces	الاستهلاك الحالي
GET /v1/workspaces/me/usage/metering	read:workspaces	سجل الاستهلاك
GET /v1/workspaces/me/members	read:workspaces	قائمة الأعضاء
GET /v1/workspaces/me/settings	read:workspaces	إعدادات مساحة العمل
GET /v1/workspaces/me/callback-secrets	read:workspaces	أسرار Callback (دون السر بنص صريح)
GET /v1/workspaces/me/callback-secrets/{id}	read:workspaces	سر Callback واحد (دون السر بنص صريح)
GET /v1/templates	read:workspaces	كل القوالب
GET /v1/templates/available	read:workspaces	القوالب المدمجة وقوالب مساحة العمل النشطة مع قيم template_key الصالحة؛ ولقوالب مساحة العمل المفتاح ws:<key> والنوع workspace
GET /v1/templates/{key}	read:workspaces	قالب واحد
GET /v1/workspaces/me/templates	read:workspaces	قوالب مساحة العمل الخاصة بك
GET /v1/workspaces/me/templates/{id}	read:workspaces	قالب مساحة عمل واحد
POST, PATCH, DELETE /v1/workspaces/me/templates[/{id}]	write:templates	إنشاء قوالب مساحة العمل وتعديلها وحذفها؛ html حتى 60,000 بايت (وإلا 422 validation_failed مع details.reason بقيمة maxBytes)، وحتى 32 خانة في asset_slots
GET /v1/domains	read:workspaces	النطاقات المخصصة
GET /v1/domains/available	read:workspaces	النطاقات المتاحة للصفحات

غير متاح بمفاتيح API

الـ Webhooks والتكاملات وإرسال الإشعارات الفورية وإدارة النطاقات المخصصة والأعضاء والفوترة وحذف الصفحات متاحة في لوحة التحكم فقط. وأسرار Callback لا تُنشأ ولا تُدار إلا في لوحة التحكم؛ أما سردها وقراءتها (دون السر بنص صريح) فممكنان بالنطاق read:workspaces. القائمة الكاملة في النطاقات بالتفصيل. أما البيانات الواردة، أي المبيعات وبياناتك الحيّة الخاصة، فترسلها بأسرار منفصلة إلى نقاط النهاية الموضّحة في إرسال المبيعات والبيانات المخصصة.

لم تجد ما تبحث عنه؟

أخبرنا بما تحتاج إليه، وسيساعدك فريق الدعم لدينا شخصيًا.

تواصل مع الدعم

نقاط نهاية الـ API حسب المجال

#المصادقة ونقاط النهاية العامة

#الصفحات

#المسودة

#الكتل

#الروابط

#الروابط المختصرة

#الملفات

#النماذج

#الإحصائيات

#الإشعارات الفورية (قراءة فقط)

#مساحة العمل والقوالب والنطاقات المخصصة

#غير متاح بمفاتيح API

قد يفيدك أيضًا