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

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

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

نوعان من المفاتيح

تصادق بـ مفتاح API في ترويسة X-TrackerToken. وهناك نوعان:

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

الفروق:

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

تعمل 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"]
  }'

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

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

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 واختيار الحركة التالية الصحيحة دون كشط النصوص.

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

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.created" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

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

البحث بصيغة التصفية

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/search?query=type:feature%20state:started%20label:mvp" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

المرشّحات المتاحة:

المرشّح	المثال	الوصف
type:	type:feature	تصفية حسب نوع القصة
state:	state:started	تصفية حسب الحالة
label:	label:"my label"	تصفية حسب التسمية
owner:	owner:claire	تصفية حسب المالك
requester:	requester:tomas	تصفية حسب طالب القصة
has:	has:blocker	قصص لها عوائق
is:	is:unestimated	ميزات غير مُقدَّرة

يطابق النص الحر العنوان والوصف. ادمج المرشّحات بفصلها بمسافات — تُربَط بـ “و” (AND).

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

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

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

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

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

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

ملاحظة: تسرد openapi.json المُقدَّمة المساراتِ لكنها تشحن حاليًا أجسام طلبات فارغة — استخدم بنى الحقول في المواصفة للكتابات.

التحكّم عبر WebSocket

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

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

معظم المستخدمين لا يحتاجون هذا أبدًا؛ إنه موجود للحالات التي لا تكفي فيها 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.

صيغة الخطأ

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

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

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

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

تقبل نقاط نهاية السرد limit وcursor. المؤشّر غير شفّاف؛ مرّر next_cursor من الاستجابة السابقة. وتتضمّن ترويسات الاستجابة أيضًا X-Tracker-Pagination-Total لإجمالي الأعداد حيث يكون حسابه رخيصًا.

ما التالي

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