Okta Partners

مرجع الـ API

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

مرحباً بك في مرجع واجهة برمجة تطبيقات منصّة أوكتا للشركاء. هذه الواجهة تمكّن تطبيقك — بعد الموافقة وتثبيته من قِبل المستأجر — من قراءة وكتابة بيانات أوكتا ضمن النطاقات التي مُنحت لك صراحةً.

واجهة الـ runtime تُستضاف على **okta-web** (التطبيق الأساسي للمنصّة)؛ كل طلب يصل إلى مسار `‎/apps`‎ تحت الرابط الأساسي. منصّة الشركاء (okta-partners) هي حيث تُسجّل تطبيقك، تختار النطاقات، وتدير الإصدارات والـ webhooks.

الواجهة REST فوق HTTPS، تتبادل JSON (UTF-8)، وتستخدم رموز HTTP القياسية. كل القراءات والكتابات معزولة لكل مستأجر (tenant) ومحمية بنطاق مُسمّى.

نداء أول

curl https://getokta.io/api/apps/whoami \
  -H "Authorization: Bearer $OKTA_PARTNER_TOKEN" \
  -H "Accept: application/json"

الرابط الأساسي

واجهة الـ runtime تُستضاف على okta-web تحت المسار التالي:

https://getokta.io/api/apps

بيئة الاختبار (Sandbox):

https://dev.getokta.io/api/apps

المصادقة

كل طلب يُصادَق عليه عبر **installation token** على هيئة Bearer. الرمز يُصدَر تلقائياً عند تثبيت المستأجر لتطبيقك، وهو مرتبط بثنائية (المستأجر، التطبيق) ويحمل النطاقات الممنوحة.

Authorization: Bearer <installation_token>
  • لا تُضمّن الرمز في كود الواجهة الأمامية ولا في مستودع عام — خزّنه كـ secret على الخادم (مثال: `OKTA_PARTNER_TOKEN`).
  • الرمز قابل للتدوير من لوحة الشريك؛ التطبيقات الخارجية تستلم الرمز الجديد عبر الجسر دون إعادة نشر.
  • الطلب بلا رمز أو برمز غير صالح يُردّ بـ `401 Unauthorized`. الرمز صالح لكن بلا النطاق المطلوب يُردّ بـ `403 Forbidden`.

تحقّق من الرمز

curl https://getokta.io/api/apps/whoami \
  -H "Authorization: Bearer $OKTA_PARTNER_TOKEN"
# → { "tenant_id": 42, "module": "your-app", "scopes": [ ... ] }

النطاقات (Scopes)

كل قطعة بيانات محمية بنطاق بالصيغة `..`. الشركاء يحصلون على فعلين فقط: `read` و `write`. الحذف لا يُمنح للشركاء أبداً. تختار النطاقات عند إنشاء التطبيق، ويوافق عليها المستأجر عند التثبيت.

النطاق الوصف
education.students.read قراءة الطلاب
education.students.write إنشاء/تعديل الطلاب
education.guardians.read قراءة أولياء الأمور
education.subjects.read قراءة المواد
education.grades.read قراءة الصفوف
education.sections.read قراءة الشُعب
education.academic_years.read قراءة الأعوام الدراسية
education.terms.read قراءة الفصول الدراسية
employees.directory.read قراءة دليل الموظفين
reports.builder.read كتالوج/تنفيذ التقارير، وسرد قوالب المدرسة والطباعة عليها
reports.builder.write اقتراح قالب من تأليف التطبيق (يصل مسودة)
notifications.providers.send إرسال إشعار عبر مزوّد
realtime.messages.write نشر رسالة فورية إلى أسطح تطبيقك (الاستماع بلا نطاق)

نقاط النهاية

جميع المسارات نسبية للرابط الأساسي أعلاه. تتطلب نقاط الكتابة (POST/PATCH) النطاق المقابل.

الهوية

GET /whoami بلا نطاق معلومات الـ installation الحالي (المستأجر، التطبيق، النطاقات).
GET https://getokta.io/api/apps/whoami

معلومات الـ installation الحالي (المستأجر، التطبيق، النطاقات).

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: بلا نطاق
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_a43d
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

الطلاب

GET /education/students education.students.read قائمة الطلاب (مُرقّمة).
GET https://getokta.io/api/apps/education/students

قائمة الطلاب (مُرقّمة).

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.students.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_b079
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الاستعلام

page integer

رقم الصفحة (يبدأ من 1).

per_page integer

عدد العناصر لكل صفحة (حد أقصى 100).

search string

بحث نصّي اختياري.

GET /education/students/{id} education.students.read طالب واحد.
GET https://getokta.io/api/apps/education/students/{id}

طالب واحد.

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.students.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_5905
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات المسار

id integer مطلوب

مُعرّف المورد في أوكتا.

POST /education/students education.students.write إنشاء طالب.
POST https://getokta.io/api/apps/education/students

إنشاء طالب.

  • حدّ المعدّل: MODERATE
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.students.write
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_0ec3
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الجسم

full_name string مطلوب

الاسم الكامل للطالب.

national_id string

رقم الهوية/الإقامة.

birth_date date

تاريخ الميلاد (YYYY-MM-DD).

gender enum

male أو female.

grade_id integer

مُعرّف الصف.

section_id integer

مُعرّف الشُعبة.

guardian_id integer

مُعرّف وليّ الأمر.

PATCH /education/students/{id} education.students.write تعديل طالب.
PATCH https://getokta.io/api/apps/education/students/{id}

تعديل طالب.

  • حدّ المعدّل: MODERATE
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.students.write
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_e45a
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات المسار

id integer مطلوب

مُعرّف المورد في أوكتا.

مُعطيات الجسم

full_name string

الاسم الكامل للطالب.

national_id string

رقم الهوية/الإقامة.

birth_date date

تاريخ الميلاد (YYYY-MM-DD).

gender enum

male أو female.

grade_id integer

مُعرّف الصف.

section_id integer

مُعرّف الشُعبة.

guardian_id integer

مُعرّف وليّ الأمر.

أولياء الأمور

GET /education/guardians education.guardians.read قائمة أولياء الأمور.
GET https://getokta.io/api/apps/education/guardians

قائمة أولياء الأمور.

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.guardians.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_aac5
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الاستعلام

page integer

رقم الصفحة (يبدأ من 1).

per_page integer

عدد العناصر لكل صفحة (حد أقصى 100).

search string

بحث نصّي اختياري.

GET /education/guardians/{id} education.guardians.read وليّ أمر واحد.
GET https://getokta.io/api/apps/education/guardians/{id}

وليّ أمر واحد.

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.guardians.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_4be0
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات المسار

id integer مطلوب

مُعرّف المورد في أوكتا.

POST /education/guardians education.guardians.write إنشاء وليّ أمر.
POST https://getokta.io/api/apps/education/guardians

إنشاء وليّ أمر.

  • حدّ المعدّل: MODERATE
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.guardians.write
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_8da4
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الجسم

full_name string مطلوب

الاسم الكامل لوليّ الأمر.

phone string مطلوب

رقم الجوال بصيغة E.164.

email string

البريد الإلكتروني.

relation enum

father | mother | other.

PATCH /education/guardians/{id} education.guardians.write تعديل وليّ أمر.
PATCH https://getokta.io/api/apps/education/guardians/{id}

تعديل وليّ أمر.

  • حدّ المعدّل: MODERATE
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.guardians.write
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_4ca6
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات المسار

id integer مطلوب

مُعرّف المورد في أوكتا.

مُعطيات الجسم

full_name string

الاسم الكامل لوليّ الأمر.

phone string

رقم الجوال بصيغة E.164.

email string

البريد الإلكتروني.

relation enum

father | mother | other.

المنهج الدراسي

GET /education/subjects education.subjects.read المواد.
GET https://getokta.io/api/apps/education/subjects

المواد.

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.subjects.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_bd8c
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الاستعلام

page integer

رقم الصفحة (يبدأ من 1).

per_page integer

عدد العناصر لكل صفحة (حد أقصى 100).

search string

بحث نصّي اختياري.

POST /education/subjects education.subjects.write إنشاء مادة (idempotent).
POST https://getokta.io/api/apps/education/subjects

إنشاء مادة (idempotent).

  • حدّ المعدّل: MODERATE
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.subjects.write
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_96e0
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الجسم

name string مطلوب

اسم المادة.

code string

رمز المادة.

GET /education/grades education.grades.read الصفوف.
GET https://getokta.io/api/apps/education/grades

الصفوف.

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.grades.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_7d9a
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الاستعلام

page integer

رقم الصفحة (يبدأ من 1).

per_page integer

عدد العناصر لكل صفحة (حد أقصى 100).

search string

بحث نصّي اختياري.

GET /education/sections education.sections.read الشُعب.
GET https://getokta.io/api/apps/education/sections

الشُعب.

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.sections.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_1d44
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الاستعلام

page integer

رقم الصفحة (يبدأ من 1).

per_page integer

عدد العناصر لكل صفحة (حد أقصى 100).

search string

بحث نصّي اختياري.

GET /education/academic-years education.academic_years.read الأعوام الدراسية.
GET https://getokta.io/api/apps/education/academic-years

الأعوام الدراسية.

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.academic_years.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_faa5
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الاستعلام

page integer

رقم الصفحة (يبدأ من 1).

per_page integer

عدد العناصر لكل صفحة (حد أقصى 100).

search string

بحث نصّي اختياري.

GET /education/terms education.terms.read الفصول الدراسية.
GET https://getokta.io/api/apps/education/terms

الفصول الدراسية.

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: education.terms.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_df6c
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الاستعلام

page integer

رقم الصفحة (يبدأ من 1).

per_page integer

عدد العناصر لكل صفحة (حد أقصى 100).

search string

بحث نصّي اختياري.

الموظفون

GET /employees/directory employees.directory.read دليل الموظفين.
GET https://getokta.io/api/apps/employees/directory

دليل الموظفين.

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: employees.directory.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_c6a4
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الاستعلام

page integer

رقم الصفحة (يبدأ من 1).

per_page integer

عدد العناصر لكل صفحة (حد أقصى 100).

search string

بحث نصّي اختياري.

GET /employees/directory/{id} employees.directory.read موظف واحد.
GET https://getokta.io/api/apps/employees/directory/{id}

موظف واحد.

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: employees.directory.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_5c8f
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات المسار

id integer مطلوب

مُعرّف المورد في أوكتا.

POST /employees/directory employees.directory.write إضافة موظف (idempotent).
POST https://getokta.io/api/apps/employees/directory

إضافة موظف (idempotent).

  • حدّ المعدّل: MODERATE
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: employees.directory.write
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_0fe2
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الجسم

full_name string مطلوب

الاسم الكامل للموظف.

job_title string

المسمى الوظيفي.

email string

البريد الإلكتروني.

التقارير

GET /reports/builder reports.builder.read كتالوج التقارير المتاحة.
GET https://getokta.io/api/apps/reports/builder

كتالوج التقارير المتاحة.

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: reports.builder.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_5f23
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.
POST /reports/builder/{key}/run reports.builder.read تنفيذ تقرير (idempotent).
POST https://getokta.io/api/apps/reports/builder/{key}/run

تنفيذ تقرير (idempotent).

  • حدّ المعدّل: HEAVY
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: reports.builder.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_8dd1
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات المسار

key string مطلوب

مفتاح التقرير من الكتالوج.

مُعطيات الجسم

parameters object

مُعطيات التقرير (تعتمد على نوعه).

GET /reports/templates reports.builder.read قوالب المدرسة المعتمدة (الترويسات).
GET https://getokta.io/api/apps/reports/templates

قوالب المدرسة المعتمدة (الترويسات).

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: reports.builder.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_865a
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.
POST /reports/templates/{id}/render reports.builder.read طباعة محتواك على ترويسة — يعيد PDF.
POST https://getokta.io/api/apps/reports/templates/{id}/render

طباعة محتواك على ترويسة — يعيد PDF.

  • حدّ المعدّل: HEAVY
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: reports.builder.read
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_2c93
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات المسار

id string مطلوب

مُعرّف القالب المبهم كما وصلك من السرد — ليس رقماً.

مُعطيات الجسم

blocks array مطلوب

جسم المستند — كتل: heading, text, table, info-row, divider, spacer, image. النوع المجهول يُرفَض ولا يُتخطّى.

variables object

قيم متغيّرات القالب بمفاتيحها. المفتاح غير المُعلَن يُسقَط، ومتغيّرات المنصّة لا تُكتب فوقها.

POST /reports/templates reports.builder.write اقتراح قالب (يصل مسودة، idempotent).
POST https://getokta.io/api/apps/reports/templates

اقتراح قالب (يصل مسودة، idempotent).

  • حدّ المعدّل: MODERATE
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: reports.builder.write
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_2d4e
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الجسم

name_ar string مطلوب

اسم القالب بالعربية.

name_en string

اسم القالب بالإنجليزية.

description string

وصف يراه من يختار القالب.

type enum

administrative | general.

orientation enum

portrait | landscape.

paper_size enum

a4 | a3 | letter.

header_enabled boolean

إظهار شريط الترويسة.

footer_enabled boolean

إظهار شريط التذييل.

header_right_content string

محتوى خانة الترويسة اليمنى — نصّ يقبل {{المتغيّرات}}.

header_center_content string

محتوى خانة الترويسة الوسطى.

header_left_content string

محتوى خانة الترويسة اليسرى.

footer_right_content string

محتوى خانة التذييل اليمنى.

footer_center_content string

محتوى خانة التذييل الوسطى.

footer_left_content string

محتوى خانة التذييل اليسرى.

watermark_text string

نص العلامة المائية.

watermark_opacity integer

شفافية العلامة المائية (0–100).

margin_top_mm integer

الهامش العلوي بالمليمتر (0–40).

margin_right_mm integer

الهامش الأيمن بالمليمتر (0–40).

margin_bottom_mm integer

الهامش السفلي بالمليمتر (0–40).

margin_left_mm integer

الهامش الأيسر بالمليمتر (0–40).

signatures_enabled boolean

طباعة كتلة الاعتماد أسفل المستند.

signatures_columns integer

عدد أعمدة كتلة الاعتماد (1–4).

signatures_title string

عنوان كتلة الاعتماد.

signatures array

الموقّعون: title_ar (مطلوب)، title_en، name، show_line. مصفوفة فارغة تحذفهم كلّهم؛ غياب المفتاح يتركهم كما هم.

variables array

حقول القالب: key (مطلوب)، label_ar (مطلوب)، label_en، type (text|date|number|currency)، required، default_value. مفتاح يظلّل متغيّراً جاهزاً يُسقَط بصمت.

PATCH /reports/templates/{id} reports.builder.write تعديل قالب ألّفه تطبيقك (يُسقط الاعتماد).
PATCH https://getokta.io/api/apps/reports/templates/{id}

تعديل قالب ألّفه تطبيقك (يُسقط الاعتماد).

  • حدّ المعدّل: MODERATE
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: reports.builder.write
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_1937
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات المسار

id string مطلوب

مُعرّف القالب المبهم كما وصلك من السرد — ليس رقماً.

مُعطيات الجسم

name_ar string

اسم القالب بالعربية.

name_en string

اسم القالب بالإنجليزية.

description string

وصف يراه من يختار القالب.

type enum

administrative | general.

orientation enum

portrait | landscape.

paper_size enum

a4 | a3 | letter.

header_enabled boolean

إظهار شريط الترويسة.

footer_enabled boolean

إظهار شريط التذييل.

header_right_content string

محتوى خانة الترويسة اليمنى — نصّ يقبل {{المتغيّرات}}.

header_center_content string

محتوى خانة الترويسة الوسطى.

header_left_content string

محتوى خانة الترويسة اليسرى.

footer_right_content string

محتوى خانة التذييل اليمنى.

footer_center_content string

محتوى خانة التذييل الوسطى.

footer_left_content string

محتوى خانة التذييل اليسرى.

watermark_text string

نص العلامة المائية.

watermark_opacity integer

شفافية العلامة المائية (0–100).

margin_top_mm integer

الهامش العلوي بالمليمتر (0–40).

margin_right_mm integer

الهامش الأيمن بالمليمتر (0–40).

margin_bottom_mm integer

الهامش السفلي بالمليمتر (0–40).

margin_left_mm integer

الهامش الأيسر بالمليمتر (0–40).

signatures_enabled boolean

طباعة كتلة الاعتماد أسفل المستند.

signatures_columns integer

عدد أعمدة كتلة الاعتماد (1–4).

signatures_title string

عنوان كتلة الاعتماد.

signatures array

الموقّعون: title_ar (مطلوب)، title_en، name، show_line. مصفوفة فارغة تحذفهم كلّهم؛ غياب المفتاح يتركهم كما هم.

variables array

حقول القالب: key (مطلوب)، label_ar (مطلوب)، label_en، type (text|date|number|currency)، required، default_value. مفتاح يظلّل متغيّراً جاهزاً يُسقَط بصمت.

DELETE /reports/templates/{id} reports.builder.write حذف مسودة ألّفها تطبيقك.
DELETE https://getokta.io/api/apps/reports/templates/{id}

حذف مسودة ألّفها تطبيقك.

  • حدّ المعدّل: MODERATE
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: reports.builder.write
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_43ce
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات المسار

id string مطلوب

مُعرّف القالب المبهم كما وصلك من السرد — ليس رقماً.

الإشعارات

GET /notifications/capabilities notifications.providers.send قدرات قناة الإشعار.
GET https://getokta.io/api/apps/notifications/capabilities

قدرات قناة الإشعار.

  • حدّ المعدّل: LIGHT
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: notifications.providers.send
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_f406
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.
POST /notifications/send notifications.providers.send إرسال رسالة (idempotent).
POST https://getokta.io/api/apps/notifications/send

إرسال رسالة (idempotent).

  • حدّ المعدّل: MODERATE
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: notifications.providers.send
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_3458
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الجسم

recipient string مطلوب

المُستلِم (رقم جوال أو مُعرّف مستخدم).

message string مطلوب

نص الرسالة.

channel string

قناة محدّدة (اختياري).

الرسائل الفورية

POST /realtime/publish realtime.messages.write دفع رسالة فورية إلى أسطح تطبيقك في هذه الجهة (ليست idempotent).
POST https://getokta.io/api/apps/realtime/publish

يدفع رسالة إلى قناة تطبيقك في هذه الجهة وحدها. الاستماع لا يحتاج نطاقاً — التثبيت هو الإذن، ولا يوجد `realtime.messages.read`.

  • حدّ المعدّل: MODERATE
    مدى استهلاك هذا الطلب لحصتك: LIGHT أخف من MODERATE ثم HEAVY.
  • النطاق المطلوب: realtime.messages.write
    النطاق (scope) الذي يجب أن يمنحه المستأجر لتطبيقك حتى يُسمح بهذا الطلب.
  • الرمز المرجعي: srv_c59d
    مُعرّف ثابت لهذا الـ endpoint — اذكره عند مراسلة الدعم لتسريع التتبّع.

مُعطيات الجسم

event string مطلوب

اسم الحدث بمفرداتك أنت — `^[a-z][a-z0-9_.:-]{0,63}$`. لا يصير اسم حدث البثّ أبداً: ذاك هو الثابت `app.message`، واسمك يسافر داخل الحمولة.

data object مطلوب

حمولة الرسالة، بحد أقصى 8192 بايت من JSON. ما يحتاج بيانات يقرؤها السطح من الـ API بنطاقه المعتاد.

القائمة الكاملة دائماً في مواصفة OpenAPI 3.1 المحدّثة آلياً: /docs/openapi.json · /docs/postman_collection.json

الترقيم (Pagination)

نقاط النهاية التي ترجع قوائم مُرقّمة. استخدم `?page=2&per_page=50` (الحد الأقصى 100 لكل صفحة).

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

Idempotency

عمليات الكتابة (POST/PATCH) تقبل header اختياري. نفس المفتاح خلال 24 ساعة يعيد نفس الإجابة المخزّنة — فإن انقطع الاتصال على جانبك، إعادة المحاولة لن تُنشئ سجلاً مكرّراً.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

الأخطاء

الأخطاء تُعاد بجسم JSON موحّد مع رمز HTTP المناسب.

{
  "message": "The given scope is not granted for this installation.",
  "error": "scope_not_granted",
  "scope": "education.students.write"
}
الرمز الاسم الوصف
400 Bad Request جسم الطلب غير صالح أو ناقص.
401 Unauthorized رمز مفقود أو غير صالح.
403 Forbidden الرمز صالح لكن بلا النطاق المطلوب.
404 Not Found المورد غير موجود ضمن نطاق المستأجر.
409 Conflict تعارض idempotency أو حالة غير متّسقة.
422 Unprocessable Entity فشل التحقق من الحقول.
429 Too Many Requests تجاوزت حدّ المعدّل.
5xx Server Error خطأ مؤقّت — أعد المحاولة مع backoff.

حدود المعدّل (Rate limits)

كل طلب يحمل ترويسات تُخبرك بالحدّ المتبقي. عند تجاوز الحدّ يُردّ `429` مع `Retry-After` (ثوانٍ). احترم backoff الأُسّي عند إعادة المحاولة.

Header الوصف
X-RateLimit-Limit الحدّ الأقصى للنافذة.
X-RateLimit-Remaining المتبقّي في النافذة الحالية.
Retry-After ثوانٍ حتى السماح بطلب جديد (مع 429).

Webhooks

التطبيقات الخارجية (External) تستقبل أحداث المنصّة عبر webhooks موقَّعة. كل webhook هو HTTP POST بجسم JSON موقَّع بـ HMAC-SHA256 على المظروف `.`.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "education.students.created",
  "tenant_id": 42,
  "created_at": "2026-04-26T10:30:15+03:00",
  "data": { "student": { "id": 123, "full_name": "..." } }
}
Header الوصف
X-Okta-Event اسم الحدث.
X-Okta-Delivery-Id UUID ثابت عبر إعادة المحاولات (للـ dedup).
X-Okta-Timestamp Unix timestamp وقت التوقيع.
X-Okta-Signature توقيع HMAC-SHA256 (hex).

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

$expected = hash_hmac(
    'sha256',
    $request->header('X-Okta-Timestamp').'.'.$request->getContent(),
    $YOUR_WEBHOOK_SECRET,
);

if (! hash_equals($expected, $request->header('X-Okta-Signature'))) {
    return response('invalid signature', 401);
}
  • افحص أن `X-Okta-Timestamp` ضمن آخر 5 دقائق، وخزّن `X-Okta-Delivery-Id` لمدة 15 دقيقة على الأقل لرفض إعادة الإرسال.
  • ردّك يجب أن يكون 2xx خلال 10 ثوانٍ. للمعالجة الطويلة اقبل بـ 202 فوراً وعالج خلفياً.
  • backoff إعادة المحاولة: 30s → 2m → 10m → 1h → 6h، ثم يُعتبر التسليم فاشلاً ويظهر في صفحة تسليمات Webhook في لوحة الشريك.

مصادر ومراجع

هذا المرجع ملخّص عملي. للتفاصيل الكاملة (أنواع التكامل، دورة حياة التطبيق، الـ manifest، policy scanner) راجع دليل المطوّر.