الخطوات الأولى

في هذا الدليل تفتحون تذكرة باستخدام REST API v1، وتقرؤون حالتها، وتضيفون تعليقًا. تحتاجون إلى curl وإلى مفتاح API.

1. أنشئوا مفتاح API

ينشئ مسؤول المستأجر (tenant) لديكم المفتاح في exoCortex Core، من Integrations → API keys، بالنطاقات tickets:create وtickets:read وtickets:comment. لا يُعرض المفتاح إلا مرة واحدة: احفظوه في متغير بيئة، دون كتابته في الشيفرة.

export EXO_API_KEY='nhk.<keyid>.<secret>'

التفاصيل موجودة في مفاتيح API.

2. افتحوا تذكرة

curl -X POST "https://exocortex-api.ai-exo-cortex.com/api/v1/tickets" \
  -H "Authorization: Bearer $EXO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data '{
    "subject": "Payment gateway returns HTTP 502",
    "description": "Checkout fails for all EU customers since 09:12 UTC.",
    "priority": "High",
    "external_id": "INC-88231"
  }'

تتضمن الاستجابة مفتاح التذكرة والعنوان الذي تُقرأ منه حالتها:

{
  "ok": true,
  "ticket_key": "ACME-1042",
  "action": "created",
  "status_url": "/api/v1/tickets/ACME-1042"
}

لا حاجة إلى تحديد المستأجر: فهو مستأجر المفتاح. يحميكم Idempotency-Key من النسخ المكررة: إذا كرّرتم الطلب نفسه بمفتاح عدم التكرار نفسه، تتلقون التذكرة نفسها مع action: deduplicated. وباستخدام external_id تحتفظون بالمرجع إلى نظامكم.

3. اقرؤوا الحالة

curl "https://exocortex-api.ai-exo-cortex.com/api/v1/tickets/ACME-1042" \
  -H "Authorization: Bearer $EXO_API_KEY"

{
  "ok": true,
  "ticket": {
    "key": "ACME-1042",
    "summary": "Payment gateway returns HTTP 502",
    "status": "In Progress",
    "priority": "High",
    "assignee": "Jane Doe",
    "created": "2026-11-01T09:14:05.000Z",
    "updated": "2026-11-01T09:31:47.000Z"
  }
}

تستجيب تذكرة تابعة لمستأجر آخر بالرمز 404، تمامًا كتذكرة غير موجودة.

4. أضيفوا تعليقًا

curl -X POST "https://exocortex-api.ai-exo-cortex.com/api/v1/tickets/ACME-1042/comment" \
  -H "Authorization: Bearer $EXO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ "comment": "Rollback completed, monitoring for 30 minutes." }'

5. عالجوا الأخطاء والحدود

• لكل خطأ ok: false وcode ثابت، مثل invalid_api_key أو validation_error: ابنوا المنطق على code.
• مع 429 انتظروا عدد الثواني المحدد في Retry-After قبل إعادة المحاولة.
• مع خطأ 5xx أعيدوا المحاولة بالقيمة نفسها لـ Idempotency-Key.

القائمة الكاملة للرموز موجودة في مفاتيح API.

الخطوات التالية

• بدلًا من الاستعلام عن الحالة، استقبلوا الأحداث عبر webhook الصادرة.
• استخدموا SDK لتجنّب كتابة استدعاءات HTTP يدويًا.
• راجعوا مرجع التذاكر للاطلاع على جميع الحقول.