واجهة REST البرمجية
تتيح واجهة REST API الخاصة بـ UserJot لشفرتك الوصول إلى بيانات مساحة العمل نفسها التي تستخدمها لوحة التحكم: بيانات مساحة العمل الوصفية، واللوحات، والطلبات (بما فيها عمليات الدمج والطلبات المشابهة والوسوم والاشتراكات والمرفقات)، والتعليقات، والتصويتات، وإدخالات سجل التغييرات، والأعضاء (بما في ذلك محو البيانات وفقًا للائحة GDPR)، والشركات، والمحادثات، والأصول، ومجموعات مركز المساعدة ومقالاته.
يتوفر المرجع التفاعلي الكامل، بما في ذلك كل المسارات والمخططات والأمثلة، على userjot.com/docs/api ومباشرةً على https://api.userjot.com/v1/docs. توجد وثيقة OpenAPI التي يستند إليها المرجع في https://api.userjot.com/v1/openapi.json (وتتوفر نسخة مطابقة لها أيضًا على https://userjot.com/docs/api/openapi.json) لتتمكن من إنشاء عملاء ذوي أنواع محددة بلغتك.
عنوان URL الأساسي والمصادقة
Base URL: https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKENتقبل UserJot نوعين من رموز Bearer على المسارات /v1/*:
رموز API: أنشئ رمزًا مميزًا من الإعدادات → MCP & API (للمسؤولين والمالكين فقط). تبدأ الرموز بالبادئة
uj_live_، وترتبط بمساحة عمل واحدة، ولا تنتهي صلاحيتها إلا عند إبطالها، ويمكن إعادة تسميتها. استخدم اضغط مطولًا للإبطال (اضغط باستمرار) لإبطال الرمز فورًا؛ وتبقى الرموز المُبطلة مدرجةً لأغراض سجل التدقيق.رموز الوصول عبر OAuth 2.0: تدعم PKCE (
S256)، والتسجيل الديناميكي للعملاء (/oauth/register), ومستندات بيانات تعريف معرّف العميل (CIMD)، وإبطال الرموز (/oauth/revoke), وبيانات الاكتشاف الوصفية علىhttps://api.userjot.com/.well-known/oauth-authorization-serverوhttps://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp. تظل رموز الوصول صالحة لمدة ساعة واحدة، مع رموز تحديث دوّارة صالحة لمدة 30 يومًا (النطاقانworkspaceوoffline_access)، ولا تظل صالحة إلا ما دام المستخدم الذي منح التفويض مالكًا أو مسؤولًا في مساحة العمل تلك.
أول طلب
curl https://api.userjot.com/v1/boards \
-H "Authorization: Bearer YOUR_USERJOT_API_TOKEN"حدود المعدل
تتشارك طلبات API وMCP ميزانية واحدة لحدود المعدل على مستوى مساحة العمل:
الخطة | في الدقيقة | في الساعة |
|---|---|---|
مجانية | 10 طلبات | 150 طلبًا |
Starter | 60 طلبًا | 1,500 طلب |
Professional | 120 طلبًا | 5,000 طلب |
تُطبَّق أيضًا حدود إضافية خاصة بكل عملية:
الأصول: تشترك عمليات استيراد الأصول والرفع متعدد الأجزاء وصور Markdown المستوردة تلقائيًا في حد منفصل لمساحة العمل يبلغ 20 طلبًا في الدقيقة و300 طلب في الساعة (بالإضافة إلى 20 طلبًا في الدقيقة و300 طلب في الساعة لإكمال الرفع).
المحادثات الصادرة (
POST /v1/conversations): متاحة في الخطط المدفوعة فقط، وبحد أقصى 5 يوميًا في Starter و15 يوميًا في Professional (وتُرجع409 plan_feature_unavailableفي خطة Free).
عند تجاوز الحد، تُرجع API استجابة HTTP 429 مع ترويسة Retry-After وerror.details.retry_after_seconds.
الترقيم الصفحي والأخطاء ومفاتيح منع التكرار
الترقيم الصفحي باستخدام المؤشر. تقبل نقاط النهاية الخاصة بالقوائم
cursorوlimit(بحد أقصى100؛ وتختلف القيم الافتراضية حسب نقطة النهاية، مثل10في القوائم الغنية مثل/v1/requestsو/v1/changelogs)، وتُرجعnext_cursorللانتقال إلى الصفحة التالية.بنية الأخطاء. تُرجع استجابات الأخطاء
{ "error": { "code", "message", "details" } }، وتتضمن ترويسة الاستجابةX-Request-Idفي كل استجابة. تشمل الرموز الشائعة422 validation_error(معdetails.issues), و409 plan_limit_reached, و409 plan_feature_unavailable, و409 request_merged, و410 member_erased(فيGET/PATCH /v1/members/{member_id}بعد محو البيانات وفقًا للائحة GDPR باستخدامDELETE /v1/members/{member_id}), و409 member_erased(في المسارات التي تشير إلى عضو ممحو البيانات), و409 help_slug_taken, و409 help_version_conflict.منع التكرار. أرسل ترويسة
Idempotency-Key(تُخزَّن لمدة 24 ساعة مع بصمة لمحتوى الطلب) لإعادة محاولة طلبات الإنشاء بأمان عبر ثمانية مسارات:/v1/requests, و/v1/changelogs, و/v1/conversations, و/v1/conversations/{conversation_id}/replies, و/v1/conversations/{conversation_id}/notes, و/v1/assets/import, و/v1/help/articles, و/v1/help/collections.
الأصول والصور
ارفع الصور (PNG أو JPEG أو GIF أو WebP، بحجم يصل إلى 10 MiB) بثلاث طرق:
الرفع متعدد الأجزاء: ترفع
POST /v1/assets(createAsset, عبر REST فقط) صورةً في طلبmultipart/form-dataواحد.الاستيراد من URL: تنزّل
POST /v1/assets/importصورة HTTPS متاحة للعامة إلى مساحة تخزين مساحة العمل.الرفع المسبق التوقيع من ثلاث خطوات:
POST /v1/assets/uploads(مع توفيرsize_bytesبدقة؛ وبحد أقصى 100 جلسة رفع مفتوحة لكل مساحة عمل) → أرسل بايتاتPUTإلى عنوان URL المسبق التوقيع الصالح لمدة 30 دقيقة →POST /v1/assets/uploads/{upload_id}/complete.
أشِر إلى الأصول المرفوعة في Markdown باستخدام asset:<id>. كما تُستورد تلقائيًا عناوين URL لصور HTTPS المتاحة للعامة والمضمّنة في Markdown المرسل إلى نقاط نهاية سجل التغييرات ومقالات مركز المساعدة (بحد أقصى 10 صور مضمنة لكل طلب سجل تغييرات و20 لكل طلب مقال في مركز المساعدة)، وتُحتسب ضمن حد الأصول لمساحة العمل.
خطافات الويب
خطافات الويب الصادرة للعملاء غير متاحة بعد. للحصول على تنبيهات فورية للفريق، استخدم Connect Slack أو Connect Discord، أو تحقّق من التغييرات دوريًا باستخدام REST API.
REST أم MCP
يُبنى خادم MCP على واجهة API هذه، ويتيح 98 من أصل 100 عملية REST كأدوات MCP (POST /v1/assets للرفع متعدد الأجزاء وDELETE /v1/members/{member_id} لمحو البيانات وفقًا للائحة GDPR متاحتان عبر REST فقط). استخدم واجهة REST API من الواجهة الخلفية أو الأتمتة أو شفرة التطبيق الخاصة بك عندما تريد التحكم الكامل في الطلبات والاستجابات. استخدم MCP عند الاتصال بعميل ذكاء اصطناعي يدعم بروتوكول Model Context Protocol.
التعامل مع الرموز المميزة
تعامل مع رمز API المميز كما تتعامل مع أي سر آخر:
لا تُضمّنه مباشرةً في ملفات الإعدادات التي تودعها في المستودع.
يُفضّل استخدام متغيرات البيئة أو مدير للأسرار.
استخدم رموزًا منفصلة للبيئات المختلفة أو لأعضاء الفريق متى أمكن.
أبطِل الرموز التي لم تعد بحاجة إليها من الإعدادات → MCP & API باستخدام اضغط مطولًا للإبطال.