مرجع نقاط نهاية الخدمة

جميع المسارات الموجودة في هذه الصفحة مرتبطة بـ:

https://api.champrep.com

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

خريطة الخدمة

المنطقة	البادئة	النطاقات
الهوية والملف الشخصي	/v1/auth, /v1/users	users:read وسياق بيانات الاعتماد
البحث عبر الخدمات	/v1/search	نطاق القراءة لكل خدمة تم البحث عنها
Drive	/v1/drive	drive:read, drive:write, drive:delete
Chat	/v1/chat	chat:read, chat:write
Calendar	/v1/calendar	calendar:read, calendar:write
Contacts	/v1/contacts	contacts:read, contacts:write
Meet	/v1/meet	meet:read, meet:write
Notes	/v1/notes	notes:read, notes:write
Learn	/v1/learn, /v1/courses	courses:read, courses:write
CHAMPREP AI	/v1/ai	ai:chat
Mail	/v1/mail	mail:read, mail:write, mail:send
Work	/v1/work	work:read, work:write, work:delete
Org Chart	/v1/charts	charts:read, charts:write, charts:delete
Forms	/v1/forms	forms:read, forms:write
Invoice	/v1/invoice	invoice:read, invoice:write, invoice:send, invoice:delete
CHAMPREP QA	/v1/qa	qa:read, qa:write
CHAMPREP Business	/v1/business	business:read, business:manage
الفوترة	/v1/billing	billing:read, billing:manage
Webhooks	/v1/webhooks	webhooks:manage

GET, HEAD، و OPTIONS تتطلب عادةً نطاق القراءة. تتطلب طرق الإنشاء والتحديث والإجراءات نطاق الكتابة أو الإدارة. تتطلب طرق الحذف نطاق الحذف حيثما تحدده الخدمة. قد يتطلب المسار أذونات إضافية للدور أو المورد في الخدمة الوجهة.

حالة الهوية والبوابة

طريقة	المسار	الغرض
GET	/v1/version	إرجاع معلومات إصدار بوابة الوصول العامة.
GET	/v1/auth/whoami	إرجاع سياق المستخدم النشط والملف الشخصي وبيانات الاعتماد والخطة.
GET	/v1/auth/quota	إرجاع المفتاح الحالي ولقطة لحصة البوابة.
GET	/v1/users/me	إرجاع ملف تعريف المستخدم الحالي.
GET	/v1/users/me/notifications	سرد الإشعارات المرئية للمستخدم الحالي.

كما يستخدم التبادلCLI المدعوم بالمتصفح /v1/auth/cli/start, /v1/auth/cli/device، و /v1/auth/cli/poll. يتم تنفيذ هذه المسارات بواسطة التطبيق CLIالرسمي؛ ولا ينبغي للتطبيقات المخصصة محاكاة بروتوكول الموافقةCLI عندما يلبي مفتاحAPI ما احتياجاتها.

البحث عبر الخدمات

طريقة	المسار	النطاق	الغرض
GET	/v1/search	لكل خدمة، انظر أدناه	ابحث في كل خدمة يمكن لهذه البيانات التعريفية الوصول إليها، في استدعاء واحد.
GET	/v1/search/services	لا شيء	اذكر الخدمات التي يمكن لهذه البيانات التعريفية البحث فيها.

/v1/search يتفرع إلى الخدمات التي تدعم البحث ويدمج النتائج. المعلمات:

المعلمة	الافتراضي	الغرض
q	مطلوب	مصطلح البحث.
limit	5	الحد الأقصى للنتائج لكل خدمة، يصل إلى 20.
services	الكل	قائمة مفصولة بفواصل، على سبيل المثال mail,drive. يضيق نطاق الانتشار.
semantic	false	تعيين true لإعادة ترتيب النتائج باستخدام الذكاء الاصطناعي والحصول على إجابة موجزة. يستهلك رصيد الذكاء الاصطناعي الخاص بك.

البحث الذكي باستخدام الذكاء الاصطناعي

semantic=true تضيف «AI pass» إلى النتائج التي لديك بالفعل: فهي تقرأ سؤالك، وتعيد ترتيب النتائج المطابقة حسب مدى ملاءمتها للإجابة، وتضيف سببًا موجزًا لكل نتيجة، وتعرض فقرة واحدة answer.

يتم دفع تكلفة هذه الخدمة من رصيد الذكاء الاصطناعي الخاص بك — وهو نفس الرصيد الشهري الذي CHAMPREP AIيستخدمه المساعد. لا يتم تحصيل أي رسوم ما لم تطلب ذلك، و البحث باستخدام الكلمات المفتاحية لا يكلف أبدًا رصيد الذكاء الاصطناعي.

توضح كل استجابة ما حدث في semantic:

"semantic": { "requested": true, "applied": true, "answer": "..." }

عندما يتعذر تشغيل «AI pass»، يتم عرض نتائج الكلمات المفتاحية دون تغيير و semantic يشرح السبب:

reason	المعنى
AI_CREDITS_EXHAUSTED	لقد استنفدت رصيدك الشهري لخدمة الذكاء الاصطناعي.
PLAN_NO_AI	لا تشمل خطتك خدمة الذكاء الاصطناعي.
AI_UNAVAILABLE	تعذر الوصول إلى خدمة الذكاء الاصطناعي هذه المرة.

فشل «AI pass» لا يؤدي أبدًا إلى فشل عملية البحث. اتصل /v1/search/services أولاً لمعرفة ما إذا كان البحث الذكي قابلاً للاستخدام — فهو يعرض semantic.available بالإضافة إلى رصيدك المتبقي — وإخفاء خيار الذكاء الاصطناعي عندما لا يكون متاحًا.

لا يتم تضمين الخدمة إلا عندما تمتلك بيانات الاعتماد نطاق القراءة الخاص بها (mail:read, drive:read, notes:read, calendar:read, chat:read, work:read, invoice:read, contacts:read) و إذا كانت الخطة النشطة تسمح بذلك. يفشل كلا الاختبارين في حالة الإغلاق، لذا فإن الخدمة التي لا يمكنك استخدامها لا تساهم أبدًا في النتائج.

Chat يتم تشفير الرسائل أثناء تخزينها ولا يتم البحث فيها إلا داخل الغرف التي تنتمي إليها، عبر السجل الحديث بدلاً من الأرشيف الكامل.

curl -H "Authorization: Bearer $CHAMPREP_API_KEY" \
  "https://api.champrep.com/v1/search?q=roadmap&services=mail,notes&limit=3"

يتم تجميع النتائج حسب الخدمة وتوحيدها في شكل واحد، بحيث يعرض العميل كل خدمة بنفس الطريقة:

{
  "success": true,
  "data": {
    "query": "roadmap",
    "groups": [
      {
        "service": "notes",
        "label": "Notes",
        "results": [
          { "id": "6650...", "title": "Q3 roadmap", "subtitle": "Planning notes for...", "timestamp": "2026-08-02T10:14:00Z" }
        ]
      }
    ],
    "totalResults": 1,
    "searched": ["notes", "mail"],
    "skipped": [{ "service": "drive", "reason": "INSUFFICIENT_SCOPE" }],
    "cost": 2
  }
}

اقرأ skipped قبل اعتبار النتيجة الفارغة على أنها «لم يتم العثور على شيء». كل إدخال يشرح سبب استبعاد الخدمة — INSUFFICIENT_SCOPE, NOT_IN_PLAN، أو SERVICE_UNAVAILABLE عندما تكون الخلفية بطيئة جدًّا أو غير قابلة للوصول لفترة وجيزة. لا تؤدي خدمة واحدة غير متوفرة أبدًا إلى فشل الاستعلام بأكمله؛ حيث لا تزال بقية النتائج تُعرض.

تكلفة البحث

يصل البحث إلى خدمة واحدة لكل مجموعة نتائج، لذا يتم احتساب التكلفة على هذا النحو: وحدة حد معدل واحدة لكل خدمة تم البحث عنها فعليًا. الـ cost يخبرك الحقل الموجود في كل استجابة بالضبط بما تم احتسابه، و X-RateLimit-Remaining يعكس ذلك قبل أن تحصل على الرد.

الطلب	الخدمات التي تم البحث عنها	التكلفة
?q=roadmap في خطة تشمل الثماني خدمات جميعها	8	8
?q=roadmap&services=mail	1	1
?q=roadmap في خطة تضم فقط Notes	1	1

لن يتم تحصيل أي رسوم منك مقابل خدمة لا يمكنك استخدامها، لذا فإن تضييق نطاق البحث باستخدام services هي الطريقة الأرخص للحفاظ على استجابة البحث التفاعلي. احرص دائمًا على إزالة التداخل — لا ترسل أبدًا طلبًا لكل ضغطة مفتاح.

Drive

طريقة	المسار	النطاق	الغرض
GET	/v1/drive/files	drive:read	سرد الملفات أو البحث عنها. استخدم search الاستعلام عند الحاجة.
GET	/v1/drive/folders	drive:read	سرد محتويات المجلد الجذر.
GET	/v1/drive/folders/{folderId}	drive:read	إدراج محتويات مجلد.
GET	/v1/drive/starred	drive:read	سرد العناصر المُعلَّمة بنجمة.
GET	/v1/drive/recent	drive:read	سرد العناصر الحديثة.
GET	/v1/drive/shared	drive:read	سرد العناصر المشتركة.
GET	/v1/drive/quota	drive:read	إرجاع استخدام مساحة التخزين الحالية والمساحة المتاحة.
POST	/v1/drive/upload	drive:write	إنشاء وجهة تحميل.
POST	/v1/drive/files	drive:write	حفظ بيانات تعريف الملف بعد نجاح عملية التحميل.
POST	/v1/drive/download	drive:read	إنشاء وجهة تنزيل.
POST	/v1/drive/folders	drive:write	إنشاء مجلد.
POST	/v1/drive/rename	drive:write	نقل عنصر أو تغيير اسمه.
POST	/v1/drive/delete	drive:delete	حذف عنصر واحد أو أكثر.
DELETE	/v1/drive/files/{fileId}	drive:delete	حذف ملف عبر المسار القديم الخاص بالعنصر الفردي.

يُعد التحميل عملية متعددة الخطوات: طلب هدف تحميل، ونقل البايتات إلى ذلك الهدف، وحفظ البيانات الوصفية الناتجة. استخدم أوSDK CLI عندما لا تحتاج إلى تنفيذ تلك التسلسل بنفسك.

Chat

طريقة	المسار	النطاق	الغرض
GET	/v1/chat/rooms	chat:read	سرد الغرف المرئية للملف الشخصي النشط.
GET	/v1/chat/rooms/{roomId}	chat:read	قراءة غرفة واحدة.
POST	/v1/chat/rooms	chat:write	إنشاء غرفة.
GET	/v1/chat/rooms/{roomId}/messages	chat:read	سرد رسائل الغرفة.
POST	/v1/chat/rooms/{roomId}/messages	chat:write	إرسال رسالة إلى الغرفة.
GET	/v1/chat/messages/search	chat:read	البحث عن الرسائل.
GET	/v1/chat/unread	chat:read	إرجاع عدد الرسائل غير المقروءة.
GET	/v1/chat/favorites	chat:read	سرد الرسائل المفضلة.

Calendar

طريقة	المسار	النطاق	الغرض
GET	/v1/calendar/events	calendar:read	سرد الأحداث؛ يدعم startDate و endDate الاستعلامات.
GET	/v1/calendar/events/{eventId}	calendar:read	قراءة حدث واحد.
POST	/v1/calendar/events	calendar:write	إنشاء حدث.
PATCH	/v1/calendar/events/{eventId}	calendar:write	تحديث حدث.
DELETE	/v1/calendar/events/{eventId}	calendar:write	حذف حدث.
GET	/v1/calendar/upcoming	calendar:read	سرد الاجتماعات القادمة.
GET	/v1/calendar/invitations	calendar:read	سرد الدعوات المعلقة.

إرسال الطوابع الزمنية للأحداث بتنسيق ISO 8601 مع منطقة زمنية محددة. يستهلك إنشاء الأحداث وتحديثاتها الحصة المحددة للخطة النشطة و المؤسسة؛ ولا APIيحدد حدًا ثابتًا عامًا للخطة.

Contacts

طريقة	المسار	النطاق	الغرض
GET	/v1/contacts	contacts:read	عرض قائمة جهات الاتصال.
GET	/v1/contacts/search	contacts:read	البحث عن جهات الاتصال باستخدام q أو email.
GET	/v1/contacts/favorites	contacts:read	عرض قائمة المفضلة.
GET	/v1/contacts/labels	contacts:read	عرض قائمة بالتصنيفات.
GET	/v1/contacts/{contactId}	contacts:read	قراءة جهة اتصال واحدة.
POST	/v1/contacts	contacts:write	إضافة جهة اتصال.
PUT	/v1/contacts/{contactId}	contacts:write	تحديث بيانات التعريف الخاصة بجهات الاتصال.
DELETE	/v1/contacts/{contactId}	contacts:write	حذف جهة اتصال.

Meet

طريقة	المسار	النطاق	الغرض
GET	/v1/meet/rooms	meet:read	عرض قائمة بغرف الاجتماعات.
GET	/v1/meet/rooms/{roomId}	meet:read	قراءة غرفة واحدة.
POST	/v1/meet/rooms	meet:write	إنشاء غرفة.
GET	/v1/meet/sessions	meet:read	سرد جلسات الاجتماعات.
GET	/v1/meet/sessions/{sessionId}/participants	meet:read	عرض قائمة المشاركين في الجلسة.
GET	/v1/meet/recordings	meet:read	عرض قائمة بالتسجيلات المتاحة.
GET	/v1/meet/transcriptions	meet:read	عرض النصوص المكتوبة.
GET	/v1/meet/transcriptions/{sessionId}	meet:read	قراءة نص محضر الجلسة النهائية.
GET	/v1/meet/usage	meet:read	إرجاع استخدام الاجتماع الحالي.

يعتمد الوصول إلى التسجيلات والنصوص على ملكية الاجتماع، والموافقة، والاحتفاظ، والخطة، وسياسة المؤسسة.

Notes

طريقة	المسار	النطاق	الغرض
GET	/v1/notes	notes:read	عرض قائمة بالملاحظات.
GET	/v1/notes/shared	notes:read	عرض قائمة بالملاحظات التي تمت مشاركتها مع الملف الشخصي النشط.
GET	/v1/notes/{noteId}	notes:read	قراءة ملاحظة واحدة.
POST	/v1/notes	notes:write	إنشاء ملاحظة.
PATCH	/v1/notes/{noteId}	notes:write	تحديث ملاحظة.
DELETE	/v1/notes/{noteId}	notes:write	حذف ملاحظة.
POST	/v1/notes/{noteId}/share	notes:write	مشاركة ملاحظة باستخدام إعدادات الوصول المدعومة.

Learn والدورات التدريبية

/v1/learn و /v1/courses عرض مسارات الدورات التدريبية المختارة نفسها.

طريقة	المسار	النطاق	الغرض
GET	/v1/learn	courses:read	عرض قائمة بالدورات التدريبية المتاحة.
GET	/v1/learn/enrolled/my	courses:read	عرض قائمة بالتسجيلات الحالية للمستخدم النشط.
GET	/v1/learn/{courseId}	courses:read	قراءة دورة تدريبية واحدة.
GET	/v1/learn/{courseId}/sections	courses:read	عرض أقسام المقرر الدراسي.
POST	/v1/learn	courses:write	إنشاء دورة تدريبية عندما يسمح الدور بذلك.
PUT	/v1/learn/{courseId}	courses:write	تحديث دورة تدريبية عندما يسمح الدور بذلك.

استخدام /v1/courses البادئة بدلاً من ذلك عند صيانة تكامل يستخدم هذا الاسم المستعار بالفعل.

CHAMPREP AI

طريقة	المسار	النطاق	الغرض
POST	/v1/ai/chat	ai:chat	إرسال موجه أو حمولة محادثة مدعومة.
GET	/v1/ai/conversations	ai:chat	عرض قائمة بالمحادثات المحفوظة.
GET	/v1/ai/conversations/{conversationId}	ai:chat	قراءة محادثة واحدة.
DELETE	/v1/ai/conversations/{conversationId}	ai:chat	حذف محادثة.
GET	/v1/ai/usage	ai:chat	إرجاع الاستخدام الحالي للذكاء الاصطناعي.

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

Mail

طريقة	المسار	النطاق	الغرض
GET	/v1/mail/accounts	mail:read	سرد حسابات البريد المرتبطة.
GET	/v1/mail/emails	mail:read	سرد الرسائل.
GET	/v1/mail/emails/{emailId}	mail:read	قراءة رسالة واحدة.
GET	/v1/mail/threads	mail:read	سرد سلاسل المحادثات.
GET	/v1/mail/threads/{threadId}	mail:read	قراءة سلسلة محادثة واحدة.
POST	/v1/mail/send	mail:send	إرسال رسالة.
GET	/v1/mail/domains	mail:read	عرض قائمة بمجالات البريد المرئية.

Work

تعكس واجهة Work«البوابة» الإصدارات المدعومة الموجودة أسفلWorkAPI /v1/work. تحدد البوابة النطاق المطلوب من طريقة HTTP:

• تتطلب طرق القراءة work:read.
• تتطلب طرق الإنشاء والتحديث work:write.
• تتطلب طرق الحذف والإجراءات الجماعية المدمرة أو إجراءات إلغاء الاستيراد work:delete.

تشمل المسارات الشائعة ما يلي:

طريقة	المسار	الغرض
GET, POST	/v1/work/boards	سرد اللوحات أو إنشاؤها.
GET, PUT, DELETE	/v1/work/boards/{boardId}	قراءة لوحة أو تحديثها أو أرشفتها.
GET	/v1/work/boards/{boardId}/kanban	قراءة عرض «كانبان» للوحة.
GET	/v1/work/boards/{boardId}/export/csv	تصدير لوحة بتنسيق CSV.
GET	/v1/work/boards/{boardId}/export/json	تصدير لقطة منظمة للوحة.
GET, POST	/v1/work/tickets	البحث عن التذاكر أو إنشاؤها.
GET, PUT, DELETE	/v1/work/tickets/{ticketId}	قراءة تذكرة أو تحديثها أو أرشفتها.
GET	/v1/work/me/dashboard	إرجاع ملخص Workلوحة معلومات «العمل» النشطة.
GET	/v1/work/me/quota	إرجاع Workالاستخدام والحدود الحالية لـ .
GET, POST	/v1/work/import/jobs	سرد مهام الاستيراد المدعومة أو إدارتها.

لا تزال اللوحات، والتذاكر، والسباقات، وعمليات الأتمتة، وعمليات الاستيراد، وسجلات الوقت، والتعليقات، والمرفقات، وطرق العرض المحفوظة، وعضوية مساحة العمل تفرضWork أدوارها وأذونات الموارد الخاصة بها بعد فحص نطاق البوابة.

Org Chart

Org Chartتتوفر واجهة أسفل /v1/charts. تتطلب طرق القراءة charts:read، تتطلب طرق الإنشاء والتحديث charts:write، وطرق الحذف تتطلب charts:delete.

تشمل المسارات الشائعة ما يلي:

طريقة	المسار	الغرض
GET	/v1/charts/me/org-chart	اقرأ مخطط المستخدم النشط.
GET	/v1/charts/me/position	قراءة موضع المخطط النشط.
GET	/v1/charts/me/connections	قراءة اتصالات العلاقات.
GET	/v1/charts/me/suggestions	اقرأ اقتراحات العلاقات.
GET	/v1/charts/users/search	ابحث عن المستخدمين لعلاقات المخطط.
GET	/v1/charts/orgs/{orgId}/chart	قراءة مخطط هيكلي للمؤسسة.
PATCH	/v1/charts/orgs/{orgId}/config	تحديث تكوين المخطط.
POST	/v1/charts/orgs/{orgId}/chart/nodes	إنشاء عقدة مخطط.
PATCH, DELETE	/v1/charts/orgs/{orgId}/chart/nodes/{nodeId}	تحديث أو حذف عقدة.

واجهات الخدمة الموسعة

كما تعرض البوابة (Gateway) بادئات الخدمات ذات الإصدارات التالية:

البادئة	نطاق القراءة	نطاق الكتابة أو الإجراءات	نطاق الحذف
/v1/forms	forms:read	forms:write	—
/v1/invoice	invoice:read	invoice:write؛ تستخدم إجراءات الإرسال أو الإصدار invoice:send	invoice:delete
/v1/qa	qa:read	qa:write	—
/v1/business	business:read	business:manage	—
/v1/billing	billing:read	billing:manage	—

تحافظ هذه البادئات على لاحقة المورد المدعومة أسفل البوابة مع تركيز المصادقة، والوصول إلى الخدمة، والنطاقات، وحدود المعدل، وسياق التدقيق. يُفضل استخدام الخدمة الرسمية SDKأو مسار تظهره الخدمة صراحةً بدلاً من تخمين مسارات الموارد من حركة مرور المتصفح.

الفوترة هي واجهة مستوى التحكم. وتظل خاضعة لـ API Gatewayالوصول، وحدود المعدل، ونطاقات الفوترة حتى عندما تمنع بوابة خدمة الوجهة المستخدم من سداد الدفعة أو الترقية.

Webhooks

تستخدم إدارة Webhook /v1/webhooks و webhooks:manage. راجع الدليل المخصص لـ دليل webhook لتسجيل نقاط النهاية، والتحقق من التسليم الموقّع ، والحماية من إعادة التشغيل، وتناوب الأسرار.

الحفاظ على تحديث عمليات التكامل

• استخدم GET /v1/version للحصول على معلومات إصدار البوابة.
• تجاهل حقول الاستجابة الإضافية التي لا يفهمها عميلك.
• اقرأ رؤوس الحدود الحية بدلاً من الترميز الثابت لقيم الخطط.
• استخدم نطاق «أقل الامتيازات» المحدد.
• اتبع موقع الوثائق وملاحظات الإصدارSDK عند اعتماد مسار جديد .