طوّر على Eyivo عبر واجهة API منظمة واحدة.

1. نظرة عامة

تتيح Eyivo REST API التحكم برمجيًا في المواقع المنظمة. تستخدم HTTPS وJSON، وتحمل إصدارًا تحت /api/v1، وتطبق حدود الملكية والخطط والتحقق والتدقيق نفسها المطبقة في لوحة التحكم.

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

2. البدء السريع

1. 1
   أنشئ رمزًا.

   سجّل الدخول إلى التطبيق، وافتح رموز API، واختر أقل الصلاحيات اللازمة، ثم انسخ ey_ السري عند ظهوره.

2. 2
   اعرض مواقعك.

   تحقق من المصادقة واحصل على معرّف الموقع الرقمي الذي تستخدمه نقاط النهاية المتفرعة.

3. 3
   أرسل عمليات كتابة آمنة عند التكرار.

   أعطِ كل طلب POST وPATCH وDELETE مفتاحًا فريدًا من نوع Idempotency-Key.

curl --request GET \
  --url https://app.eyivo.com/api/v1/sites \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token'

تحتوي استجابة القائمة الناجحة على السجلات ضمن data:

{
  "data": [
    {
      "id": 42,
      "platform_subdomain_key": "7kr9mp2x",
      "template_key": "corporate-01",
      "status": "active",
      "native_locale": "en",
      "english_enabled": false,
      "content_version": 1,
      "search_visibility": "platform_noindex"
    }
  ]
}

3. المصادقة

يتطلب كل طلب إلى /api/v1 رمز حامل:

Authorization: Bearer <token>

مسار التفويض باستخدام PKCE

1. أنشئ code_verifier عشوائيًا عالي العشوائية، ثم احسب code_challenge المقابل بخوارزمية SHA-256.
2. وجّه المستخدم إلى /oauth/authorize مع response_type=code وclient_id العام وredirect_uri المسجّل بدقة وscope المطلوب مفصولًا بمسافات وstate وcode_challenge وcode_challenge_method=S256.
3. تحقق من state بعد إعادة التوجيه، ثم استبدل رمز التفويض المعاد لدى /oauth/token باستخدام code_verifier الأصلي.
4. احفظ رموز الوصول والتحديث بأمان. حدّثها قبل انتهاء صلاحيتها واستبدل بيانات الاعتماد الدوّارة بصورة ذرّية.

4. الصلاحيات

يحتاج كل طلب إلى الصلاحية المحددة أدناه. يجيز الرمز الشخصي الذي يحتوي على * جميع فحوص الصلاحيات، لكن ينبغي للتطبيقات طلب أقل مجموعة ممكنة.

يتطلب REST صلاحية نقطة النهاية وليس mcp:use. تستخدم الوسائط media:read أو media:write.

5. عمليات كتابة آمنة عند التكرار

أرسل Idempotency-Key مع تعديلات JSON لإعادة الطلب نفسه بأمان. يُستثنى رفع الوسائط بصيغة multipart وإصدار تذاكر الرفع؛ تحقق من نتيجة النقل قبل المحاولة مجددًا.

Idempotency-Key: site-42-page-create-01J7M6Y8RRF3ZE6WB4Z0Y9XJXC

تشمل مطابقة الطلب طريقة HTTP ومساره ومحتواه الخام كما أُرسل تمامًا. أعد استخدام JSON المتسلسل نفسه عند إعادة المحاولة.

6. الاستجابات وبنية الموارد

تُرجع عمليات المحتوى غلاف data. يوفر MCP كائن structuredContent ونسخة نصية من JSON؛ ويُرجع REST بيانات JSON. اقرأ مخططات المخرجات للمعرفات وجاهزية النشر وتقسيم النتائج. تابع معلومات الصفحات في المدونات والوسائط والإرسالات.

{ "data": { "id": 42, "status": "active" } }

{ "data": [{ "id": 42 }, { "id": 43 }] }

تختلف أشكال المجموعات. اتبع بيانات تقسيم النتائج لكل نقطة نهاية ولا تفترض أن كل نتيجة قائمة بسيطة أو غير مقسمة.

7. المواقع

إنشاء موقع

curl --request POST \
  --url https://app.eyivo.com/api/v1/sites \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: site-create-01J7M6Y8' \
  --data '{
    "display_name": "Northstar Studio",
    "template_key": "corporate-01",
    "native_locale": "en"
  }'

الاستجابة: 201 Created مع مورد الموقع. قد تظهر حالة غير نشطة أولًا أثناء اكتمال التخصيص. وتُرجع حدود المواقع والخطط 422.

حقول مورد الموقع: id وplatform_subdomain_key وtemplate_key وstatus وnative_locale وenglish_enabled وcontent_version وsearch_visibility وruntime الاختياري والطوابع الزمنية.

8. الصفحات

إنشاء صفحة

{
  "type": "page",
  "sort_order": 300,
  "locale": "en",
  "slug": "our-story",
  "title": "Our story",
  "body": "<p>How the company began.</p>",
  "meta_title": "Our story | Northstar Studio",
  "meta_description": "Learn about Northstar Studio."
}

استجابة الإنشاء: 201. استجابة التحديث: 200. استجابة الحذف: 204 دون محتوى.

احفظ مسودة وتحقق من جاهزيتها ثم انشر العنصر باللغة المطلوبة عندما يريد المستخدم إتاحته للزوار. لا تُنشر المسودات الأخرى.

9. عناصر الكتالوج

إنشاء عنصر كتالوج

{
  "sort_order": 100,
  "locale": "en",
  "slug": "strategy-advisory",
  "title": "Strategy advisory",
  "summary": "Focused advice for consequential decisions.",
  "body": "Talk to our senior advisory team."
}

احفظ مسودة وتحقق من جاهزيتها ثم انشر العنصر باللغة المطلوبة عندما يريد المستخدم إتاحته للزوار. لا تُنشر المسودات الأخرى.

هذه أمثلة حسب نوع المحتوى. اكتشف جميع مخططات الإدخال والإخراج والصلاحيات في tools/list أو OpenAPI. مسارات REST أدناه نسبية إلى /api/v1/sites/{site}.

القدرات وعقد تحرير المحتوى

اختر موقعًا ثم اقرأ قدراته: اللغات المفعلة وحقول القالب ومخططات المكونات ومواضع القوائم ولوحات الإضافات المثبتة. اقرأ مورد content-workflow قبل التعديل. يمكن للعملاء الذين لا يدعمون الموارد استخدام get-site-capabilities-tool. تابع nextCursor في tools/list حتى يكتمل الاكتشاف.

GET /api/v1/sites/{site}/capabilities
GET /api/v1/sites/{site}/pages/{page_id}/components/schema?locale=en

استخدم اللغة المطلوبة وقيمة version أو revision الحالية. حفظ المقال يستبدل المستند كاملًا ويلغي جدولته. تستخدم القوائم revision رقمية وتستخدم تعيينات المحتوى بصمة menu_revision منفصلة. احتفظ بعناصر المصفوفات المستبدلة. عند التعارض أعد القراءة وادمج التعديلات قبل المحاولة.

يبقى التنقل الرئيسي تلقائيًا. للقوائم الإضافية مسوداتها ونشرها المستقل. يحضّر حفظ المحتوى تعييناته للقوائم ويطبقها نشر العنصر دون نشر مسودات قوائم أخرى. نشر القائمة لا ينشر المحتوى المرتبط بها. يرفض source_hash ترجمات مبنية على نص مصدر قديم.

يقبل محتوى الصفحة وحقول richtext لغة HTML منقاة. استخدم list-page-links-tool لروابط ثابتة /__eyivo/pages/{id} تُحل بلغة الزائر بعد النشر. تستخدم المدونات document بتنسيق JSON منظم مع media_id من الموقع نفسه وأهداف صفحات أو مقالات، وليس body_html.

{
  "type": "doc",
  "content": [{
    "type": "paragraph",
    "content": [{ "type": "text", "text": "Our story" }]
  }]
}

رفع الصور والفيديوهات

يفتح upload-media-tool منتقي ملفات في عملاء MCP Apps مثل Claude. يمكن لـ ChatGPT توفير مرجع مرفق خاص به؛ مرفق محادثة Claude ليس مرجع ملف OpenAI. لا تختلق روابط تنزيل ولا ترسل ملفات base64 ضمن معاملات الأدوات.

يمكن لـ Codex وClaude Code استدعاء prepare-media-upload-tool ثم إرسال الملف بصيغة multipart إلى upload_url باستخدام upload_token لمرة واحدة خلال خمس دقائق. أبقِ الرمز سريًا. يمكن لعملاء REST استخدام رمز media:write الخاص بهم. لا يُرجع معرّف الوسائط إلا رفع مكتمل؛ إصدار تذكرة لا يرفع ملفًا.

POST /api/v1/sites/{site}/media
Authorization: Bearer <media:write token>
Content-Type: multipart/form-data; boundary=<generated by HTTP client>

file: <original file bytes>

10. النطاقات المخصصة

طلب نطاق

curl --request POST \
  --url https://app.eyivo.com/api/v1/sites/42/domains \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: domain-request-example-com' \
  --data '{"domain":"www.example.com"}'

يتضمن مورد النطاق المعلّق verification_token. أضف سجل DNS المطلوب لإثبات الملكية بالقيمة المعادة لنطاقك، وانتظر انتشار DNS، ثم استدعِ نقطة نهاية التفعيل. بعد التفعيل، استدعِ نقطة النهاية الخاصة بالاسم الأساسي إذا أردت أن يصبح اسم المضيف العام المعتمد.

حقول مورد النطاق: id وdomain وsite_id وis_primary وstatus وverification_token عند الاقتضاء والطوابع الزمنية. تُرجع حدود الخطة للنطاقات المخصصة وأخطاء التحقق من النطاق 422.

11. الأخطاء

استجابة التحقق

{
  "message": "The title field is required.",
  "errors": {
    "title": ["The title field is required."]
  }
}

استجابة فشل المصادقة أو التفويض

{
  "message": "Missing required scope [content:write]."
}

12. الحدود الحالية وقائمة فحص التكامل

تتيح REST v1 جزءًا محددًا من Eyivo عمدًا. غياب نقطة نهاية يعني حدًا للعقد، وليس إذنًا باستدعاء واجهات داخلية.

قبل التشغيل الفعلي

• استخدم HTTPS وتحقق من المضيف المتوقع app.eyivo.com.
• احتفظ برموز الحامل على الخادم واحذف ترويسات التفويض من السجلات.
• اطلب الصلاحيات اللازمة فقط، وفضّل الرموز الشخصية المقيدة بموقع عند الإمكان.
• استخدم مفتاحًا فريدًا لكل عملية كتابة منطقية، واحتفظ به عند إعادة المحاولة.
• تعامل مع 401 و403 و404 و422 بوصفها أخطاء لا تزول بإعادة المحاولة، ما لم يتغير الطلب أو بيانات الاعتماد.
• استخدم تراجعًا أسيًا مع تأخير عشوائي عند الإخفاقات المؤقتة، واحترم أي ترويسة Retry-After قد تُضاف مستقبلًا.
• تختلف أشكال المجموعات. اتبع بيانات تقسيم النتائج لكل نقطة نهاية ولا تفترض أن كل نتيجة قائمة بسيطة أو غير مقسمة.