دليل واجهة برمجة التطبيقات

واجهة برمجة تطبيقات East Agile Tracker مصمَّمة للوكلاء بقدر ما هي مصمَّمة للبشر. كل ما تستطيع فعله في الواجهة، تستطيع فعله عبر واجهة برمجة التطبيقات — وبعض الأشياء التي لا تكشفها الواجهة موجودة هنا أيضًا.

ينقلك هذا الدليل من الصفر إلى “كتابة سكربتات لقائمة أعمالك” في أقل من عشر دقائق. للمرجع الكامل لنقاط النهاية، انظر مواصفة واجهة برمجة التطبيقات.

ثلاثة أنواع من بيانات الاعتماد

تصادق بمفتاح في ترويسة X-TrackerToken. هناك نوعان من المفاتيح تُصدِرهما بنفسك، ونوع ثالث يحصل عليه عميل MCP نيابةً عنك:

• مفاتيح المستخدم (ea_user_…) — تتصرف بصفتك أنت. أنشئها في Account Settings ← API Keys. استخدمها للسكربتات الشخصية، وأدوات سطر الأوامر، والتكاملات.
• مفاتيح الوكلاء (ea_agent_…) — تتصرف بصفة وكيل له اسم في مشروع واحد. أنشئها في Project Settings ← Agents. استخدمها لوكلاء الذكاء الاصطناعي — Claude Code، أو Codex، أو وكيلك الخاص — الذين ينبغي أن يشاركوا في المشروع كزملاء فريق لهم أسماء.
• رموز MCP (ea_mcp_…) — رموز وصول OAuth 2.1 تُصدَر لعميل MCP ‏(Claude، أو بيئة تطوير متكاملة) بعد أن توافق عليه في صفحة الموافقة. تتصرف بصفتك أنت، ويمكنك إلغاؤها من Account Settings ← Connected apps.

الفروق بين النوعين اللذين تُصدِرهما بنفسك:

	مفتاح المستخدم	مفتاح الوكيل
النطاق	كل مشاريعك	مشروع محدد واحد
الهوية في سجل التدقيق	اسمك	اسم الوكيل
الدور	دورك في كل مشروع	يُحدَّد عند إنشاء المفتاح (viewer أو member أو manager — ولا يتجاوز أبدًا دور العضو الذي أصدره)
الإلغاء	ألغِ مفتاحًا؛ تحتفظ بالوصول عبر مفاتيح/جلسات أخرى	ألغِ مفتاحًا أو دوِّره؛ يفقد الوكيل الوصول فورًا
الأنسب لـ	الأتمتة الشخصية، والسكربتات	وكلاء الذكاء الاصطناعي الذين ينبغي تمييزهم عنك في السِّجِلّ

تعمل Authorization: Bearer … أيضًا إن فضّلت ذلك النمط من الترويسات.

مرحبًا، يا واجهة برمجة التطبيقات

احصل على مشاريعك:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN"

أو لمفتاح وكيل، اسرد المشروع المحصور به:

curl https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: ea_agent_xxxxx"

واجهة برمجة التطبيقات بصيغة JSON، أقرب إلى REST، ومُصدَّرة عند /api/v1/. البنى نفسها للبشر والوكلاء.

إنشاء مشروع

curl -X POST https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding redesign",
    "description": "Q3 redesign of new-user onboarding",
    "iteration_length_weeks": 1
  }'

تتضمّن الاستجابة project_id وأي قيم افتراضية طبّقها الخادم (مقياس التقدير، وحالة الإنجاز، إلخ).

إنشاء قصة

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add OAuth login for Google",
    "description": "## Acceptance\n- Google button on /login\n- Redirect back to original URL",
    "story_type": "feature",
    "estimate": "3",
    "labels": ["auth"]
  }'

estimate هو تسمية قيمة المقياس كسلسلة نصية — "3"، أو "13" على مقياس Fibonacci — لأنه يجب أن يطابق نقطة على مقياس المشروع. ويُرفَض الرقم بصيغة JSON.

تحريك قصة عبر دورة الحياة

تتحقّق نقطة نهاية الانتقال من الحركة المطلوبة وتُعيد الحالات التالية المسموح بها عند الخطأ:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/transitions \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "started" }'

الحقل هو to (لا to_state). إذا كانت الحركة غير قانونية — مثلًا حاولت القفز من unstarted مباشرةً إلى accepted — فالاستجابة هي 422 invalid_transition مع تفاصيل خطأ مهيكَلة:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`",
  "details": { "from": "unstarted", "to": "accepted", "allowed": ["started"] }
}

هذا أحد الأشياء الصغيرة التي تجعل واجهة برمجة التطبيقات ودودة للوكلاء: يستطيع الوكيل قراءة details.allowed واختيار الحركة التالية الصحيحة دون كشط النصوص.

rejected حالة نهائية بالنسبة إلى نقطة نهاية الانتقال. لإعادة قصة مرفوضة إلى العمل، استدعِ POST …/stories/{sid}/restart؛ أما POST …/stories/{sid}/reject فهي صيغة الفعل لرفض قصة مُسلَّمة.

التعليق على قصة

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/comments \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Investigation done. Picking this up." }'

يُنسَب التعليق إلى من يملك مفتاح API — وإذا كان مفتاح وكيل، فمؤلف التعليق هو الوكيل.

الكتابات المتكافئة (Idempotent)

تقبل كل نقطة نهاية كتابة ترويسة Idempotency-Key. أعِد المحاولة بالمفتاح نفسه والجسم نفسه، تحصل على الاستجابة نفسها. أعِد المحاولة بالمفتاح نفسه وجسم مختلف، تحصل على 409 idempotency_conflict:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Refactor auth middleware", "story_type": "chore" }'

هذا حاسم للوكلاء في حلقات إعادة المحاولة — تعطّل في منتصف الكتابة، أعِد المحاولة بالمفتاح نفسه، بلا قصص مكرّرة.

الانتقالات الجماعية

حرِّك قصصًا كثيرة دفعةً واحدة. تُحكَم كل قصة على نحوٍ مستقل؛ ولا تُفشِل حركةٌ واحدة غير قانونية البقية.

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/bulk_transition \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "story_ids": [101, 102, 103],
    "to": "delivered"
  }'

متابعة تدفق الأحداث

للوكلاء الذين يريدون التفاعل مع ما يفعله البشر، استطلِع نقطة نهاية الأحداث:

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/events?since=$LAST_CURSOR&types=story.created,story.transitioned,comment.added" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

الاستجابة تدفق أحداث مقسَّم صفحاتٍ بمؤشّر، يحوي الفاعل، والمورد، والتغيير. لكل حدث معرّف؛ مرّر آخر معرّف رأيته كـ since لاستئناف من حيث توقفت. بلا خطافات ويب (webhooks)، وبلا كشط، وبلا أحداث مفقودة. يحتاج التدفق إلى دور member — ويتلقّى المُشاهِد 403.

البحث

يُجري GET /projects/{id}/search?q=<query> بحثًا قويًا يجمع النص الكامل والبنية على قصص المشروع. لغة الاستعلام مصمَّمة على غرار مُحدِّدات بحث المشكلات في GitHub — فالصيغة التي تعرفها أنت (أو وكيل ذكاء اصطناعي) من GitHub تنتقل في معظمها كما هي.

curl -G "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search" \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  --data-urlencode 'q=payment crash type:bug,chore owner:@me created:>2026-05-01'

الاستجابة غلاف JSON، والقصص فيه مرتّبة حسب الصلة:

{ "results": [ /* canonical story objects */ ], "total": 42, "limit": 50, "offset": 0 }

total هو العدد الكامل للمطابقات، لا حجم الصفحة. قسّم الصفحات بـ limit (الافتراضي 50، والحد الأقصى 1000) وoffset؛ ورتّب بـ sort=relevance (الافتراضي)، أو created، أو created_asc، أو updated، أو state.

القواعد

• النص الحر يطابق عنوان القصة ومرجعها ووصفها (نص كامل، مع التجذيع والترتيب). أحِط العبارة الدقيقة بـ "quotes".
• المُحدِّدات بصيغة field:value. افصل البدائل بفواصل (OR داخل الحقل الواحد): type:bug,chore. وافصل المُحدِّدات بمسافات (AND فيما بينها).
• انفِ أي مصطلح أو مُحدِّد بسابقة -: -label:wontfix.
• المديات للتواريخ والنقاط: شاملة a..b، أو مفتوحة الطرف >x / <x.

المُحدِّدات

المُحدِّد	المثال	يطابق
type:	type:bug,chore	نوع (أنواع) القصة
state:	state:started,finished	حالة (حالات) سير العمل
label:	label:"my label"	تسمية
epic:	epic:"Checkout"	القصص في ملحمة
priority:	priority:p1	الأولوية
points:	points:3 · points:1..5 · points:>3	قيمة التقدير أو مداه
iteration:	iteration:42	معرّف التكرار
created: updated: started: completed: release:	created:2026-05-01..2026-06-01 · updated:>2026-06-01	تاريخ أو مدى (بدقة اليوم)؛ وrelease: هو تاريخ إصدار القصة
owner: requester: follower: reviewer: commenter: mention:	owner:claire · owner:@me	شخص بالاسم أو البريد الإلكتروني — الأعضاء والوكلاء، بما في ذلك mention:؛ و@me يعني أنت
has:blocker	has:blocker	له عائق مفتوح
is:	is:unestimated · is:icebox · is:backlog · is:blocked	راية

mywork: اسم بديل لـ owner: — فـ mywork:me هو owner:@me. أما المُحدِّد الأقدم scheduled: فقد أُحيل إلى التقاعد ويُتجاهَل بصمت؛ استخدم release:.

ينطبق الربط بالفاصلة (type:bug,chore) على مُحدِّدات الأوجه؛ أما مُحدِّدات الأشخاص (owner: requester: follower: reviewer: commenter: mention:) فتأخذ قيمة واحدة.

أمثلة

payment crash                              full text "payment" AND "crash"
"exact phrase"                             a phrase
type:bug,chore state:started               bugs or chores that are started
owner:@me -label:wontfix                   mine, excluding the wontfix label
points:3..8 created:2026-05-01..2026-06-01 estimated 3-8, created in May
follower:tomas has:blocker                 tomas follows it and it's blocked
is:backlog updated:>2026-06-01             backlog items touched since Jun 1

تقود سلسلة الاستعلام نفسها صندوق البحث في اللوحة (الذي يفتح عمود نتائج حيًّا) وواجهة برمجة التطبيقات هذه — قواعد واحدة للبشر والوكلاء على حدٍّ سواء. البحث في محتوى التعليقات والمهام والعوائق على خارطة الطريق؛ واليوم يغطّي النص الحر عنوان القصة ومرجعها ووصفها فقط.

استكشاف واجهة برمجة التطبيقات

مواصفة OpenAPI 3 الحيّة عند:

https://api.eastagiletracker.com/api/v1/openapi.json

وواجهة Swagger UI عند:

https://api.eastagiletracker.com/api/v1/docs/

/openapi.json و/docs غير مصادَق عليهما — يستطيع الوكيل قراءة العقد قبل أن يملك مفتاحًا. وحالما يملك مفتاحًا، تُعيد /api/v1/meta (التي تتطلّب مفتاحًا صالحًا) هويته ورسم انتقالات الحالات لكل نوع قصة؛ كما أن عمليات البحث في البيانات المرجعية (/story_types، و/story_states، و/effort_scales، و/priority_scales) غير مصادَق عليها. معًا تتيح للوكلاء الإجابة عن “ماذا أستطيع أن أفعل هنا؟” دون أخطاء 403 بالتجربة والخطأ.

يحمل openapi.json المُقدَّم مخططات أجسام الطلبات لنقاط نهاية الكتابة، بما في ذلك maxLength لكل حقل، كي يتحقّق العميل قبل أن يرسل. وتلخّص المواصفة البنى نفسها.

التحكّم عبر WebSocket

للأتمتة التفاعلية — قيادة جلسة متصفح مسجَّل الدخول من سكربت، أو التحكّم عن بُعد بالواجهة للدروس التعليمية — هناك قناة WebSocket:

const ws = new WebSocket('wss://eastagiletracker.com/ws/control?token=SESSION_JWT')
ws.send(JSON.stringify({ action: 'get_state', id: 'req-1' }))

الرمز token هو JWT جلسة المتصفح، لا مفتاح API — يُرفَض مفتاح ea_user_* أو ea_agent_* قبل الترقية. معظم المستخدمين لا يحتاجون هذا أبدًا؛ إنه موجود للحالات التي لا تكفي فيها REST.

الاستيراد من أداة تتبع أخرى

إن كنت تكتب سكربتًا لنقل جماعي:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -F "source=pivotal" \
  -F "file=@pivotal_export.csv"

مصادر الملفات المدعومة: pivotal، وjira، وasana، وgitlab، وshortcut، وtrello، وlinear، وplane، وplane_json، وeat (صيغة تصدير East Agile Tracker الخاصة — صيغة الرحلة كاملة). تعمل نقطة نهاية multipart تزامنيًا وتجيب بأعداد النتائج.

GitHub يستورد من واجهة برمجة التطبيقات بدلًا من ملف، عبر نقطة نهاية JSON — بلا file، بل بإحداثيات المستودع فقط:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import/json \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "source": "github",
        "owner": "octocat",
        "repo": "hello-world",
        "token": "ghp_…",
        "include_pull_requests": false,
        "include_milestones": false,
        "include_releases": false,
        "include_dependencies": false
      }'

نقطة نهاية JSON غير تزامنية: تجيب بـ 202 مع { "import_id", "status" } وتستطلع أنت GET /projects/{id}/imports/{import_id} إلى أن تبلغ المهمة done أو failed. لا يجري إلا استيراد واحد لكل مشروع في الوقت نفسه — والاستدعاء الثاني بينما يجري أحدها يُعيد 409 import_already_running. والحلقة كاملة، مع حقول تقدّم المهمة، في تعبئة مشروع من مستودع GitHub.

الرمز token اختياري في الطلب، لكن الجلب نفسه يستوثق دائمًا — فهو يجري على واجهة GraphQL من GitHub، ولا طبقة مجهولة فيها. أغفِل token فيضع الخادم مكانه رمز المنصّة: المستودعات العامة فقط، ومشترك بين كل المستدعين، ويُرفَض بالرمز import_github_shared_quota_low متى هبطت ميزانيته على GraphQL دون 500 نقطة. أما المستودع الخاص، أو نشر لم يُضبَط فيه رمز منصّة (import_github_no_token)، فيتطلّب رمزك أنت. وأيًّا كان الرمز العامل، فهو يُستخدَم فقط لنداءات GitHub الصاعدة ولا يُخزَّن ولا يُعاد صداه أبدًا. والتفصيل الكامل، بما فيه سقف REST غير المستوثق عند 60 طلبًا، في تعبئة مشروع من مستودع GitHub.

معاينة تشغيلٍ تجريبي. أضِف "dry_run": true (بصيغة JSON) أو -F "dry_run=true" (بصيغة multipart) إلى أي مصدر. يحلّل الاستيراد ويحسم ويزيل التكرار تمامًا كما في تشغيلٍ فعلي، ويُعيد أعداد النتائج نفسها (imported، وskipped، وerrors، وunmatched)، ثم يتراجع عن كل شيء — لا يُكتَب شيء. وعلى نقطة نهاية JSON تصل الأعداد على المهمة المُستطلَعة، سواء أكان التشغيل تجريبيًا أم لا.

الحدود. جسم الرفع مُقيَّد بـ 10 MiB، والاستيراد الواحد بـ 5٬000 قصة؛ وتجاوز أيٍّ منهما هو 400 بلا كتابة شيء. وإعادة استيراد ملف آمنة — الصفوف المُستورَدة مسبقًا (المُطابَقة بمعرّف المصدر) تُتخطّى لا تُكرَّر.

تصدير مشروع

يستطيع أي دور في المشروع سرد الصيغ؛ أما تنزيل إحداها فللمالكين فقط:

# The registered export formats: { id, name, content_type, drops, includes_archived }
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/formats \
  -H "X-TrackerToken: $TRACKER_TOKEN"

# Download one format (eat is the full-fidelity round-trip CSV)
curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/export/eat \
  -H "X-TrackerToken: $TRACKER_TOKEN" -o project-export.csv

معرّفات صيغ التبادل: eat، وjira، وpivotal، وshortcut، وtrello، وasana، وgitlab، وlinear، وplane، وplane_json، إضافةً إلى صيغتَي المستندات pdf وdocx. وكل مرفق قابل للتنزيل كملف zip واحد من GET /projects/{id}/export/attachments.

صيغة الخطأ

كل الأخطاء بصيغة JSON وتحوي على الأقل:

{
  "code": "invalid_transition",
  "error": "Cannot move story from `unstarted` to `accepted`"
}

تتضمّن كثير من استجابات الأخطاء أيضًا كائن details — details.fields (وهو مصفوفة بأسماء الحقول المخالِفة) على validation_failed، وdetails.allowed (إلى جانب from/to) على 422 invalid_transition. استخدمها. ويحمل 429 rate_limited ترويسة Retry-After ضمن غلاف JSON نفسه.

التقسيم إلى صفحات

تقبل نقاط نهاية السرد limit وcursor. المؤشّر غير شفّاف؛ مرّر next_cursor من الاستجابة السابقة. وسقف limit خاص بكل نقطة نهاية — 200 على القصص والتعليقات والمشاريع، و500 على الأحداث، و1000 على البحث وسجل التدقيق. والقائمة العادية (غير المعتمدة على المؤشّر) التي اضطُرّت إلى اقتطاع استجابتها تقول ذلك في الترويسات: X-Tracker-Pagination-Truncated، و-Limit، و-Offset، و-Next-Offset، التي تمرّرها رجوعًا كـ offset= للصفحة التالية. لا توجد ترويسة للعدد الإجمالي.

ما التالي

• مواصفة واجهة برمجة التطبيقات — كل نقطة نهاية، وكل فعل، وكل بنية.
• تعليمات التشغيل ← الوكلاء — من جهة الواجهة: إصدار مفاتيح الوكلاء، وتسمية الوكلاء، والإلغاء.
• المقدمة — المفاهيم خلف واجهة برمجة التطبيقات: القصص، والحالات، والتكرارات، والسرعة، والوكلاء.