تخطَّ إلى المحتوى
تسجيل الدخولاطلب حساب

مرجع REST API

الـREST API يخلّي نظام خارجي يقرأ ملاحظات مشروع ويُدخل ملاحظات جديدة برمجياً (للوحة داخلية عندك، أو سكربت ترحيل، أو أدوات العميل نفسه). السطح صغير وثابت: ستّ نقاط، مصادقة بمفتاح، وشكل استجابة موثّق لكل نقطة — وكائن ملاحظة واحد تتشاركه نقاط القائمة والإنشاء وتغيير الحالة.

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

https://api.umarker.com/api/v1

كل المسارات تحت نسبية لهذا الأساس.

كل طلب يحتاج مفتاح API. اسكّ واحد من اللوحة تحت مفاتيح API. يظهر مرّة وحدة وقت الإنشاء، وبعدها ما تشوف إلا بادئته. شوف مفاتيح الـAPI وحدود الطلبات للإنشاء والإدارة.

أرسل المفتاح إمّا كـbearer token أو في ترويسة X-Api-Key (الاثنين مقبولين):

Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

كل مفتاح يحمل واحد من نطاقين، والـAPI يفرضه مع كل طلب:

  • مفتاح على مستوى الحساب يوصل كل مشاريع الحساب.
  • مفتاح على مشروع يوصل مشروعه الواحد بس.

أي طلب لمشروع خارج نطاق المفتاح (أو في حساب ثاني أصلاً) يُرفض بـ403 وبلا أي تسريب بيانات. والمفتاح الناقص أو المشوّه أو المسحوب يُرفض بـ401.

حدّك اللي تشتغل عليه محسوب لكل مفتاح، مو لكل IP، عشان التكامل المزحوم يستهلك حصّته هو مو حصّة مشتركة: السقف الافتراضي 300 طلب بالدقيقة لكل مفتاح. وفوقه سقف لكل IP قدره 1200 طلب بالدقيقة — وهو حاجز ضد الإساءة، مو حدّك اللي تشتغل عليه — والمفاتيح اللي تنادي من نفس IP الخروج تتشارك هذا الرقم الخارجي. خمسة مفاتيح مزحومة خلف NAT مكتب واحد أو بوّابة سحابية وحدة يقدرون يوصلونه قبل لا أيّ واحد منهم يستهلك الـ300 حقّه. وفوق أيّ من الحدّين يُرفض الطلب بـ429 Too Many Requests ومعه ترويسة Retry-After تقول لك كم ثانية تنتظر:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

تراجع لين ترجع النافذة بدل ما تعيد المحاولة بشراسة.

قائمة المشاريع

GET /projects: المشاريع اللي يشوفها هذا المفتاح (id + name)، عشان الاكتشاف.

قائمة الملاحظات

GET /projects/{projectId}/feedback: اقرأ ملاحظات مشروع، الأحدث أوّلاً، بصفحات.

إنشاء ملاحظة

POST /projects/{projectId}/feedback: أدخِل ملاحظة جديدة لمشروع.

جلب تقرير

GET /feedback/{id}: تفاصيل كاملة لتقرير واحد، ومعها كتلة ماركداون جاهزة للّصق.

تغيير الحالة

PATCH /feedback/{id}: انقل حالة التقرير (مثلاً إلى resolved).

إضافة تعليق

POST /feedback/{id}/comments: اكتب ملاحظة على التقرير.

{projectId} هو معرّف المشروع الرقمي ولازم يكون داخل نطاق المفتاح، وإلا يرجع النداء 403. و{id} معرّف ملاحظة ولازم يكون في حساب المفتاح ونطاقه، وإلا يرجع 404. والاثنين لازم يكونون أعداداً صحيحة موجبة. وabc و1.9 تُرفض بنفس الطريقة اللي يُرفض فيها صفّ غير موجود، فالمعرّف المشوّه ما يصير جواب ثاني لأحد يجسّ السطح.

أول ثلاث نقاط (اكتشاف المشاريع والقائمة والإنشاء) موثّقة كاملة تحت. والثلاث الباقية (GET/PATCH/POST على /feedback/{id}) هي سطح القراءة والكتابة اللي بُني عليه خادم MCP، وملخّصة في نقاط الوكيل.

ترجع ملاحظات المشروع مرتّبة من الأحدث، بصفحات.

GET /api/v1/projects/{projectId}/feedback?per_page=25&page=1
Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
الباراميتر النوع الافتراضي ملاحظات
per_page عدد صحيح 25 عدد العناصر بالصفحة، مقصور بين 5 و100 من الطرفين.
page عدد صحيح 1 أي صفحة تبغى.
curl
curl "https://api.umarker.com/api/v1/projects/7/feedback?per_page=25&page=1" \
-H "Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

استجابة 200 تلفّ العناصر في data والترقيم في meta:

200 OK
{
"data": [
{
"id": 12,
"comment": "زرّ الدخول مو محاذي",
"rating": null,
"status": "new",
"priority": "high",
"source": "public",
"page_url": "https://site/checkout",
"submitter_email": "user@site.com",
"issue_url": null,
"created_at": "2026-06-30T10:00:00+00:00"
}
],
"meta": {
"current_page": 1,
"last_page": 3,
"per_page": 25,
"total": 61
}
}

مصفوفة data ترجع العناصر اللي داخل نطاق المفتاح بس. شوف كائن الملاحظة لكل الحقول.

تُدخل ملاحظة جديدة للمشروع. العنصر ينحفظ بـstatus: "new" وsource: "api".

POST /api/v1/projects/{projectId}/feedback
Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
الحقل النوع مطلوب القيود
comment نصّ نعم 5000 محرف كحدّ أقصى.
rating نصّ لا 50 محرف كحدّ أقصى.
page_url نصّ لا 2048 محرف كحدّ أقصى، ولازم يكون البروتوكول http أو https. والبروتوكول هو كل الفحص — المضيف والمسار ينحفظان كما أرسلتهما. أمّا javascript: وdata: وfile: فتُرفض بـ422 بدل ما تُسقط بصمت.
email نصّ لا بريد صالح، 255 محرف كحدّ أقصى. ينحفظ كبريد المُرسِل.
metadata كائن لا سياق حرّ مفتاح/قيمة. مسقوف بـ16 كيلوبايت JSON؛ واللي أكبر يُسقط.
custom_data كائن لا بيانات تطبيقك الحرّة. مسقوفة بـ16 كيلوبايت JSON؛ واللي أكبر يُرفض بـ422.
curl
curl -X POST "https://api.umarker.com/api/v1/projects/7/feedback" \
-H "Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"comment": "صفحة الدفع تطلع 500 على سفاري",
"page_url": "https://site/checkout",
"email": "user@site.com",
"metadata": { "browser": "Safari 17" },
"custom_data": { "plan": "pro" }
}'

استجابة 201 ترجع العنصر المُنشأ بنفس شكل نقطة القائمة، ومعه source: "api":

201 Created
{
"id": 84,
"comment": "صفحة الدفع تطلع 500 على سفاري",
"rating": null,
"status": "new",
"priority": null,
"source": "api",
"page_url": "https://site/checkout",
"submitter_email": "user@site.com",
"issue_url": null,
"created_at": "2026-07-01T09:15:00+00:00"
}

الملاحظة المُدخَلة تُطلق حدث new_feedback لكل وجهة يوجّه لها المشروع (سلاك، تيليجرام، تيمز، أو الـwebhook حقّك)، بالضبط مثل ما لو انرسلت من الودجت. شوف القنوات والتوجيه.

نقاط القائمة والإنشاء وتغيير الحالة كلها ترجع نفس الكائن الثابت:

الحقل النوع الوصف
id عدد صحيح معرّف الملاحظة.
comment نصّ نصّ التقرير.
rating نصّ | null تقييم اختياري كنصّ. سنيبت الموقع ما يرسله أبداً.
status نصّ حالة دورة الحياة: new أو in_progress أو waiting أو resolved أو archived.
priority نصّ وحدة من none أو low أو medium أو high أو urgent. وnone هي الافتراضي المخزَّن، وهي شكل «بلا أولوية»، فالفحص الصحيح للتقرير اللي له أولوية هو priority !== 'none' — أمّا priority !== null فيطابق كل تقرير موجود. (المكان الوحيد اللي يطلع فيه null هو استجابة 201 للإنشاء، لأنها ترجّع العنصر الجديد قبل ما يُقرأ الافتراضي المخزَّن.)
source نصّ من وين جت: public (سنيبت الموقع) أو extension (إضافة المتصفّح) أو api (هذا الـAPI) أو survey (إجابة استبيان انفتحت كتقرير). وما فيه قيمة اسمها widget.
page_url نصّ | null الرابط اللي انلقط منه التقرير.
submitter_email نصّ | null بريد المُبلِّغ، لو معروف.
issue_url نصّ | null رابط تذكرة المتتبّع المرتبطة، لو فيه وحدة.
created_at نصّ طابع زمني ISO 8601.

ثلاث نقاط إضافية تخلّي وكيل البرمجة يكتشف المشاريع، وبعد ما ينزل الإصلاح يقفل الحلقة على تقرير واحد. وهي السطح اللي يغلّفه خادم MCP. وكل اللي تحت توصله مباشرة بنفس المصادقة بالمفتاح.

GET /api/v1/projects ترجع المشاريع اللي يشوفها المفتاح (مفتاح الحساب يشوف كل مشاريع الحساب، ومفتاح المشروع يشوف مشروعه بس)، عشان الوكيل يحلّ معرّف المشروع قبل ما يسرد الملاحظات:

200 OK
{ "data": [ { "id": 7, "name": "الموقع" } ] }

GET /api/v1/feedback/{id} ترجع التفاصيل الكاملة لتقرير واحد: كلام المُبلِّغ زائد console_logs وfailed_requests وmetadata وcustom_data وlabels، والتذكرة المرتبطة issue لو موجودة. ومعها حقل markdown هو نفس الكتلة الجاهزة للّصق اللي ينتجها زرّ نسخ التقرير كنصّ باللوحة. والتقرير اللي برّا حساب المفتاح أو نطاقه يرجع 404.

وتحمل كمان capture_mode: "normal" أو "technical"، الوضع اللي كان عليه المشروع لمّا انرسل التقرير (وnull للتقرير اللي انرسل قبل ما توجد أوضاع الالتقاط). في تقرير الوضع العادي تكون console_logs وfailed_requests وbreadcrumbs وtechnical_capture كلها null؛ وفي تقرير الوضع التقني تحمل اللي انلتقط — breadcrumbs هي سلسلة آخر النقرات وتغييرات المسار، وtechnical_capture هو سجلّ الطلبات الكامل والاستثناءات والأداء والبيئة.

والاستجابة تحمل كمان element، وهو null ما لم يكن المشروع مشغّلاً تحديد العنصر — مفتاح عبر الـAPI فقط وما له تحكّم في اللوحة، ومستقلّ عن وضع الالتقاط.

PATCH /api/v1/feedback/{id} ينقل التقرير بين الحالات. أرسل حقل status واحد، ولازم يكون من new أو in_progress أو waiting أو resolved أو archived. الاستجابة هي كائن الملاحظة؛ وأي تغيير حقيقي يُطلق كمان حدثاً للوجهات اللي يوجّه لها المشروع: resolved لو الحالة الجديدة resolved، وstatus_change لأي نقلة ثانية. اشترك بالحدثين، وإلا المثال اللي تحت (وهو يحلّ التقرير) ما يوصل ولا وجهة.

curl
curl -X PATCH "https://api.umarker.com/api/v1/feedback/84" \
-H "Authorization: Bearer md_live_…" \
-H "Content-Type: application/json" \
-d '{ "status": "resolved" }'

POST /api/v1/feedback/{id}/comments يكتب ملاحظة على التقرير (ملخّص إصلاح، رابط PR). أرسل حقل body (لين 5000 محرف). والتعليق ينحفظ بلا أي شخص مربوط فيه: استجابة 201 ما فيها حقل مؤلّف أصلاً، وخيط اللوحة — وهو الشاشة الوحيدة اللي تعرض النسبة — يكتبه عبر الـAPI، عشان يفرّقه فريقك عن ردّ زميل. استجابة 201 ترجع التعليق المُنشأ:

201 Created
{ "id": 12, "body": "انحلّت في PR #128.", "created_at": "2026-07-01T09:15:00+00:00" }

ومثل أي تعليق يُكتب من اللوحة، يُطلق حدث comment، فيسمع فيه جرس الفريق وبريدهم، وسجلّ التدقيق يكتب أي مفتاح كتبه. لكن comment مو من السبعة اللي تقدر القناة تشترك فيها (new_feedback وassigned وmentioned وstatus_change وpriority وresolved وissue_linked)، فهو ما يوصل سلاك ولا تيليجرام ولا تيمز ولا webhook.

الـAPI يفشل مُغلقاً. كل خطأ يرجع جسم JSON فيه message (ومع التحقّق، كائن errors). ورسائل المصادقة والنطاق والباقة و«غير موجود» مكتوبة بالإنجليزية وتبقى إنجليزية مهما أرسلت — وهي اللي يتفرّع عليها التكامل. أمّا التحقّق (422) و503 الصيانة فمترجمة، فالطلب اللي يحمل X-Locale: ar يرجّعها بالعربي. فرّع على رمز الحالة وعلى مفاتيح الحقول داخل errors، لا على نصّ الرسالة أبداً.

الحالة المعنى متى
401 غير مصرّح المفتاح ناقص (API key required.) أو غير صالح/مسحوب (Invalid or revoked API key.).
403 ممنوع الباقة ما تشمل الوصول للـAPI؛ أو الحساب معلَّق؛ أو اللي سكّ المفتاح معلَّق أو مقعده متوقّف؛ أو المشروع موقوف بالباقة؛ أو المشروع المطلوب خارج النطاق أو في حساب ثاني.
404 غير موجود نداء /feedback/{id} سمّى تقريراً خارج حساب المفتاح أو نطاقه أو نافذة سجلّه (Not found.).
422 غير قابل للمعالجة حمولة الإدخال ما عدّت التحقّق: كائن errors بالجسم يسمّي كل حقل خاطئ.
429 طلبات كثيرة تجاوزت حدّ الطلبات. شوف Retry-After.
503 غير متاح uMarker في نافذة صيانة. أعد المحاولة بعد مدّة Retry-After.
403 Forbidden
{ "message": "Project not found or not in this key's scope." }
422 Unprocessable Content
{
"message": "The comment field is required.",
"errors": {
"comment": ["The comment field is required."]
}
}

دورة كاملة: اقرأ ثم أدخِل

Section titled “دورة كاملة: اقرأ ثم أدخِل”
  1. اسكّ مفتاحاً محصوراً بمشروع من اللوحة تحت مفاتيح API وانسخ السرّ md_live_… (يظهر مرّة).

  2. اسرد ملاحظات المشروع عشان تتأكّد إن المفتاح ونطاقه شغّالين:

    نافذة طرفيّة
    curl "https://api.umarker.com/api/v1/projects/7/feedback" \
    -H "Authorization: Bearer md_live_…"
  3. أنشئ ملاحظة:

    نافذة طرفيّة
    curl -X POST "https://api.umarker.com/api/v1/projects/7/feedback" \
    -H "Authorization: Bearer md_live_…" \
    -H "Content-Type: application/json" \
    -d '{ "comment": "مستوردة من صندوق الدعم" }'
  4. تأكّد إنها طلعت بأعلى القائمة (الأحدث أوّلاً) ومعها source: "api". وإذا كنت ضابط واحد، تأكّد إن الـwebhook حقّك استقبل حدث new_feedback.