الـ API

الـ API والتكامل

يتوفّر مرجع API تفاعلي عام بكامل نقاط النهاية والنطاقات وأمثلة cURL على صفحة مرجع الـ API — مناسب للمشاركة المباشرة.

URL الأساسي

https://getokta.io/api/apps

المصادقة

كل طلب يحمل Authorization: Bearer <installation_token>.

نقاط النهاية الجاهزة

Endpoint	Scope	الوصف
`GET /whoami`	(لا شيء)	معلومات الـ installation الحالي
`GET /entity`	(لا شيء)	أين أنا: نوع الجهة، هل هي حاوية، وأمّها
`GET /entity/children`	`entity.hierarchy.read`	الجهات التابعة (`?descendants=1` لكل المستويات) مع `installed` و`access`
`GET /entity/children/{id}`	`entity.hierarchy.read`	ملفّ جهة تابعة (الشعار مساراً، التواصل، الدولة، المرحلة، الأحجام)
`GET /entity/children/{id}/logo`	`entity.hierarchy.read`	شعار الجهة التابعة
`GET /entity/ancestors`	`entity.hierarchy.read`	الجهات فوقي، الأقرب أوّلاً
`GET /education/students`	`education.students.read`	قائمة الطلاب (paginated)
`GET /education/students/{id}`	`education.students.read`	طالب واحد
`POST /education/students`	`education.students.write`	إنشاء طالب
`PATCH /education/students/{id}`	`education.students.write`	تعديل طالب
`GET /education/subjects`	`education.subjects.read`	المواد
`GET /education/grades`	`education.grades.read`	الصفوف
`GET /education/sections`	`education.sections.read`	الشُعب
`GET /employees/directory`	`employees.directory.read`	الموظفين
`GET /reports/builder`	`reports.builder.read`	كتالوج التقارير
`POST /reports/builder/{key}/run`	`reports.builder.read`	تنفيذ تقرير
`GET /reports/templates`	`reports.builder.read`	قوالب المدرسة (الترويسات)
`POST /reports/templates/{id}/render`	`reports.builder.read`	طباعة محتواك على ترويسة (يعيد PDF)
`POST /reports/templates`	`reports.builder.write`	اقتراح قالب من تأليف تطبيقك (يصل مسودة)
`PATCH /reports/templates/{id}`	`reports.builder.write`	تعديل قالب ألّفه تطبيقك (يُسقط الاعتماد)
`DELETE /reports/templates/{id}`	`reports.builder.write`	حذف مسودة ألّفها تطبيقك

كل نقطة قراءة لبيانات الجهة (education/*، employees/directory، tool-keys/*، reports/*) تقبل ?entities=<ulid>,<ulid> أو ?entity=<ulid> لتقرأ الجهات التابعة من المجمّع — لشخص يحمل tenants.children.view_members، لا لتوكن التثبيت. التفاصيل في فصل «الشركات والمجمّعات: شجرة الجهة وبيانات مدارسها».

القائمة الكاملة دائماً في https://partners.getokta.io/docs/openapi.json (مواصفة OpenAPI 3.1 محدّثة آلياً). ويُمكنك استيراد Postman collection جاهزة.

Pagination

كل قائمة ترجع:

{
  "data": [ ... ],
  "total": 1242,
  "per_page": 20,
  "current_page": 1,
  "last_page": 63
}

استخدم ?page=2&per_page=50 (الحد الأقصى 100 لكل صفحة).

Idempotency

عمليات الكتابة تقبل header اختياري:

Idempotency-Key: <uuid>

نفس المفتاح خلال 24 ساعة يعيد نفس الإجابة المخزّنة، حتى لو تم استدعاؤه عشرات المرات. هذا يضمن أنه لو حصل timeout على جانبك، إعادة المحاولة لن تُنشئ سجلاً مكرراً.

عرض الدليل كاملاً في صفحة واحدة · ↧ Markdown خام