العنوان الأساسي وبيئة Sandbox والإصدارات وتنسيق البيانات والترقيم والمصادقة: ما تحتاج إلى معرفته قبل أول استدعاء لواجهة LinkHarbor REST API.

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

أي طريق يناسبك؟

تريد …	الطريق	المزيد
إدارة الصفحات والروابط والمحتوى من سكربت أو خادم	REST API بمفتاح API	هذا القسم
تلقّي إشعار عندما يحدث شيء (مثل نشر صفحة)	Webhooks	Webhooks
ربط المبيعات من متجرك بنقرة على رابط	Callbacks البيع	إرسال المبيعات والبيانات المخصصة
عرض بيانات حيّة من أدواتك الخاصة على صفحتك	تكامل Custom (API)	إرسال المبيعات والبيانات المخصصة
العمل في محادثة مع Claude أو ChatGPT	خادم MCP	استخدام LinkHarbor مع مساعدي الذكاء الاصطناعي

العنوان الأساسي والإصدارات

العنوان الأساسي (Base URL): https://dock.at-harbor.com، وكل نقاط نهاية المنتج تقع تحت /v1، مثل https://dock.at-harbor.com/v1/pages.
الإصدار: يوجد حاليًا الإصدار v1 فقط. ورقم الإصدار جزء من المسار.
البروتوكول: HTTPS فقط.
OpenAPI: الوصف المقروء آليًا (OpenAPI 3.1) موجود على https://dock.at-harbor.com/openapi.yaml. ويمكنك تحميله في Postman أو Insomnia أو في مولّد شيفرة.

الاختبار في بيئة Sandbox

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

الـ API: https://drydock.at-harbor.com، بالمسارات نفسها المذكورة أعلاه، مثل https://drydock.at-harbor.com/v1/pages.
لوحة التحكم: https://sandbox-deck.linkharbor.com، مثلًا لإنشاء مفاتيح API.
الصفحات: تظهر الصفحات المنشورة على https://<handle>.sandbox.linkharbor.com.
الحساب: حسابك الحقيقي في LinkHarbor لا يعمل هناك. أنشئ حساب Sandbox منفصلًا.

لا ترسل بيئة Sandbox رسائل بريد إلكتروني. إذا سجّلت عبر الـ API ‏(POST /v1/auth/register)، يعود رمز التحقق مباشرة في الاستجابة، في الحقل _dev_verification. وينطبق الأمر نفسه على إعادة تعيين كلمة المرور وتغيير البريد الإلكتروني. هذا الحقل موجود في Sandbox فقط، فلا تعتمد عليه في شيفرتك.

الإشعارات الفورية متوقفة
تمر المدفوعات عبر وضع الاختبار في Stripe، ولا تنتقل أموال حقيقية
حدود المعدل نحو ثلث القيم الحقيقية، والحسابات الجديدة محدودة بـ 5 في الساعة لكل عنوان IP
في اليوم 1 من كل شهر الساعة 3:00 UTC تُمسح بيئة Sandbox بالكامل، وتختفي بعدها كل الحسابات والبيانات
تحمل كل استجابة الترويسة X-Environment: sandbox

المصادقة باختصار

بصفتك مالكًا أو مسؤولًا، أنشئ في لوحة التحكم تحت «Callback وواجهة API» مفتاح API بالنطاقات التي تحتاج إليها (ابتداءً من Creator Pro)
استبدل معرّف المفتاح وسر المفتاح برمز وصول عبر POST /v1/token
أرسل الرمز مع كل طلب في الترويسة Authorization: Bearer …
احصل على رمز جديد بعد 15 دقيقة

كل التفاصيل في مفاتيح API ورموز الوصول، والصلاحيات في النطاقات (Scopes).

الطلبات والاستجابات

التنسيق: الطلبات والاستجابات بصيغة JSON بترميز UTF-8. ورفع الملفات يستخدم أيضًا multipart/form-data.
Content-Type: أرسل الترويسة Content-Type: application/json مع كل طلب له جسم. أي نوع آخر يُرفض بالخطأ 400 bad_request، بما في ذلك النوع الذي يضبطه curl تلقائيًا مع -d عند غياب هذه الترويسة.
الحقول غير المعروفة: الحقول التي لا تعرفها نقطة النهاية تؤدي إلى 422 validation_failed. وتذكر الاستجابة الحقول غير المعروفة.
JSON معطوب: يؤدي إلى 400 invalid_json.
الحجم: حسب نقطة النهاية، لا يتجاوز الجسم 64 KB أو 1 MB أو 2 MB، ورفع الملف 10 MB. وإذا كان أكبر، تستجيب الـ API بالخطأ 413 request_too_large. كل الحدود مذكورة في حدود المعدل.
القوائم: تأتي ككائن فيه الحقل items، مثل {"items":[…]}.
الإنشاء: يستجيب بـ HTTP 201 والمعرّف الجديد، مثل {"id":123}.
الإجراءات دون قيمة مُرجعة: تستجيب بـ {"ok":true}.
الأخطاء: لها دائمًا تنسيق ثابت مع رمز مقروء آليًا. انظر تنسيق أخطاء الـ API ورموز الأخطاء.

ترقيم الصفحات (Pagination)

لا يوجد نظام ترقيم موحّد. معظم القوائم صغيرة وتعود كاملة؛ ولعدد قليل فقط من نقاط النهاية معاملات:

نقطة النهاية	السلوك	المعاملات
GET /v1/pages, /v1/pages/{id}/links, /v1/pages/{id}/blocks, /v1/forms	قائمة كاملة	–
GET /v1/forms/{id}/submissions	الأحدث أولًا، مقسّمة بمؤشر: next_cursor من الاستجابة هو المؤشر (cursor) للصفحة التالية، وقيمته null في الصفحة الأخيرة	limit ‏1–500 (الافتراضي 100)، cursor
GET /v1/short-links	مقسّمة، مع total في الاستجابة	limit ‏1–100 (الافتراضي 50)، offset، sort، q
GET /v1/push/history	مقسّمة	limit حتى 100 (الافتراضي 50)، offset
نقاط نهاية الإحصائيات	حسب الفترة	period، from، to، granularity

لـ sort في الروابط المختصرة توجد القيم created_desc وcreated_asc وredirects_desc وredirects_asc؛ ويبحث q في الـ slug والعنوان والرابط الهدف (حتى 100 حرف، دون تمييز بين الأحرف الكبيرة والصغيرة). وفي الإحصائيات يقبل period القيم 24h و7d و30d و90d وthis_month وlast_month وlast_30d وcustom؛ أو تمرّر بدلًا من ذلك from وto. وقيمة granularity هي hour أو day.

معرّف الطلب واللغة

تحمل كل استجابة الترويسة X-Request-Id؛ أرفقها عند التواصل مع الدعم
إذا أرسلت ترويسة X-Request-Id بنفسك، تستخدمها الـ API
يأتي نص الخطأ في message بلغة حساب مالك مساحة العمل، وإلا فيتبع الترويسة Accept-Language؛ أما الرمز في error فيبقى دائمًا كما هو

الاستدعاء من المتصفح؟

تقنيًا تسمح الـ API بالاستدعاءات من المتصفح (CORS). لكن سر المفتاح لا مكان له أبدًا في شيفرة تعمل لدى الزائر، لا في موقع ويب ولا في تطبيق. استدعِ الـ API دائمًا من خادمك الخاص.

الخطط

الخطة	مفاتيح API	Webhooks	أسرار Callback
Creator Free	–	–	–
Creator Pro	حتى 5	حتى 5	حتى 5
Creator Agency	حتى 20	حتى 25	حتى 5
Enterprise	حتى 50 (قابل للتعديل)	حتى 100 (قابل للتعديل)	حتى 5

لا توجد حصة من استدعاءات الـ API لكل خطة. تسري فقط حدود المعدل في الدقيقة. أما حدود المحتوى في خطتك، مثل الصفحات أو الروابط أو الكتل لكل صفحة، فتسري عبر الـ API تمامًا كما في لوحة التحكم. انظر مقارنة الخطط.

أول استدعاء لك

الحصول على رمز وسرد الصفحات

# Exchange the key for a token
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# List pages (scope read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

مثال كامل يضيف رابطًا ويغيّر التصميم ثم ينشر تجده في خطوة بخطوة: تحديث صفحة عبر الـ API.

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

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

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

نظرة عامة على الـ API

#أي طريق يناسبك؟

#العنوان الأساسي والإصدارات

#الاختبار في بيئة Sandbox

#المصادقة باختصار

#الطلبات والاستجابات

#ترقيم الصفحات (Pagination)

#معرّف الطلب واللغة

#الاستدعاء من المتصفح؟

#الخطط

#أول استدعاء لك

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