للمطوّرين · واجهة REST واحدة

ابنِ على الواجهة البرمجية التي تعمل بها تطبيقات فكرة.

الاستوديو والمشغّل ولوحة الإدارة تقرأ وتكتب عبر واجهة REST واحدة، وخدمتك تستدعي نقاط النهاية نفسها للمؤسسات والمسارات والوحدات والتقدّم.

تحدّث إلينا عن الواجهة اقرأ البداية السريعة
zsh · fkra api
{ "statusCode": 200, "data": { "isRevoked": false, … } }
/api/v1200 OK
POST/public/user/login/credentialتسجيل الدخولPOST/shared/user/refreshتدوير الرموزGET/shared/user/profileالمستخدم الحاليGET/user/learning/pathsالمسارات المنشورةGET/public/certificate-verify/:codeالتحقق من شهادة
كل شاشات التطبيق، ونقاط النهاية نفسها

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

  • مفتاح واحد وسرّ واحديحمل كل طلب ترويسة x-api-key، وتضيف المسارات المحمية رمز Bearer.
  • غلاف واحدرمز الحالة والرسالة والبيانات الوصفية والبيانات في كل استجابة.
  • نطاق فرعي لكل مؤسسةلكل مؤسسة نطاق فرعي خاص بها، وتُقرأ الأدوار مع كل طلب.
  • العربية والإنجليزيةتعود الرسائل باللغة التي تطلبها.
ثلاثة طلبات

ثلاثة طلبات، من تسجيل الدخول إلى المحتوى

سجّل الدخول، واقرأ بيانات المستخدم الحالي، ثم اعرض مسارات التعلّم.

01سجّل الدخول
الطلبPOST/public/user/login/credentialx-api-keyx-captcha-token
accessTokenrefreshToken
صدر الرمزان
02اقرأ بيانات المستخدم الحالي
الطلبGET/shared/user/profilex-api-keyAuthorization
rolepermissions
عاد الدور والصلاحيات
03اعرض مسارات التعلّم
الطلبGET/user/learning/pathsx-api-keyAuthorization
enar
العناوين باللغة التي تطلبها
مرجع الواجهة

كل نقطة نهاية وترويسة ورمز خطأ في مكان واحد.

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

docsv1 المنتجسجل التحديثاتاحصل على مفتاح API
العنوان الأساسيhttps://<your-api-host>/api/v1المصادقةx-api-key · Bearerنوع المحتوىapplication/json

ملاحظةيعرض كل مقطع طلبًا والاستجابة التي يعيدها. وتعرض بيئات التشغيل غير الإنتاجية المرجع الكامل بصيغة OpenAPI على /docs.

بداية سريعة

#

أرسل البريد الإلكتروني وكلمة المرور، فتحصل على رمز وصول ورمز تحديث. ويتطلب الطلب أيضًا رمز CAPTCHA محلولًا. أما الحسابات التي فعّلت التحقق بخطوتين فتتلقى طلب تحقق بدل الرموز.

login.sh
curl -X POST "https://<your-api-host>/api/v1/public/user/login/credential" \  -H "Content-Type: application/json" \  -H "x-api-key: $FKRA_KEY:$FKRA_SECRET" \  -H "x-captcha-token: $CAPTCHA_TOKEN" \  -d '{ "email": "amina@acme.edu", "password": "…", "from": "website" }'
POST/api/v1/public/user/login/credential200 OK
معاملات متن الطلب
الحقلالنوعالوصف
emailمطلوبstringالبريد الإلكتروني للحساب.
passwordمطلوبstringكلمة مرور الحساب.
fromمطلوبenumwebsite أو mobile، بحسب مكان تسجيل الدخول.

المصادقة

#

تحمل الطلبات بعد تسجيل الدخول بيانات اعتماد اثنتين: مفتاح API يعرّف تطبيقك ويُرسل مع كل طلب، ورمز الوصول يعرّف المستخدم ويُرسل مع كل نقطة نهاية تتطلب تسجيل الدخول.

shell
curl "https://<your-api-host>/api/v1/shared/user/session/list" \  -H "x-api-key: $FKRA_KEY:$FKRA_SECRET" \  -H "Authorization: Bearer $ACCESS_TOKEN"
accessTokenرمز JWT موقّع بخوارزمية ES256. أرسله في ترويسة Authorization بصيغة Bearer، ويحدد expiresIn مدة صلاحيته بالثواني.refreshTokenرمز JWT موقّع بخوارزمية ES512، ولا تقبله إلا نقطة نهاية التحديث. كل تحديث يستبدل الرمزين معًا، وتحتفظ الجلسة بموعد انتهائها المحدد عند تسجيل الدخول.

تنبيهلا يظهر السرّ إلا مرة واحدة عند إنشاء المشرف للمفتاح. احفظه على خادمك، وأعد تعيين المفتاح من /admin/system/api-keys.

عرّف أنواع وحداتك

#

يسجّل المشرف نوع الوحدة بمخطّطَي JSON، أحدهما للإعدادات والآخر للمحتوى، ويبني الاستوديو نماذج التحرير منهما.

module-type.json
{  "key": "practice.branching_scenario",  "learnerAction": "Decide",  "configSchema": {    "properties": {      "branches": { "type": "array", "minItems": 2 },      "endings":  { "type": "array", "minItems": 2 },      "scoring":  { "enum": ["rubric", "points"] }    }  },  "bodySchema": {    "properties": { "persona": { "type": "string" } }  }}
كما يظهر في الاستوديو
branching_scenarioعُطل حرج في الثالثة فجرًا
personaon-call-engineerbranchesarrayendingsarrayscoringrubric
fkra/admin/content/module-typeمباشر

المؤسسات والأدوار والصلاحيات

#

كل مؤسسة مستأجر مستقل على نطاقها الفرعي. وتتحقق نقاط النهاية المحمية من دور المستخدم، ثم من صلاحية تتكوّن من موضوع وإجراء، ويُقرأ الاثنان من جديد مع كل طلب.

المستأجرacme-academy.fkra.ai019f6a2e-…
الصلاحية
learningModule · publishنشر الوحدات
apiKey · createإنشاء مفاتيح API وإعادة تعيينها
assessment · updateبدء التقييمات والإجابة عنها وتسليمها
يُخزَّن الأعضاء والمحتوى والنشاط في acme-academy تحت معرّف مؤسستها./admin/system/roles · مباشر

العربية والإنجليزية في صميم المنصة.

#

كل شاشة تصدر بالعربية والإنجليزية بتخطيط من اليمين إلى اليسار: المحتوى ولوحات المتابعة والشهادات.

أرسل x-custom-lang: ar فتصلك الرسالة بالعربية، ويُضبط metadata.language على القيمة نفسها. أما نقاط نهاية المحتوى التعليمي فتقرأ Accept-Language وتذكر اللغة التي قدّمت بها المحتوى، مع مؤشر عند الرجوع إلى لغة بديلة.

ENReading our codebasev4.2 · approved
01Absorb02Connect03Evaluate04Practice
Readiness
ARقراءة قاعدة الكود لديناالإصدار 4.2 · معتمد
01استيعاب02ربط03تقييم04ممارسة
الجاهزية

نقاط النهاية

#

ثماني نقاط نهاية للبدء، من تسجيل الدخول إلى التحقق من الشهادات، وهي نفسها التي تستدعيها تطبيقات فكرة. افتح أيًّا منها لترى ما تتطلبه وما تعيده.

يتطلبx-api-key · x-captcha-tokenيُعيدUserLoginResponseDto
{ "isTwoFactorEnable": false, "tokens": { "tokenType": "Bearer", "expiresIn": 3600, … } }
بقية نقاط النهاية، بمخطّطات طلباتها واستجاباتها، في مرجع OpenAPI على/docs

الاستجابات وترقيم الصفحات

#

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

المعاملمثالالنمط
page1offset
perPage20offset · cursor
cursormetadata.nextCursorcursor
searchaminaoffset · cursor
orderBycreatedAt:descoffset · cursor
البيانات الوصفية في صفحة بالمؤشر
"metadata": {  "language": "en",  "path": "/api/v1/shared/user/session/list",  "version": "1",  "type": "cursor",  "perPage": 20,  "hasNext": true,  "hasPrevious": false,  "nextCursor": "eyJ…",  "orderBy": [{ "createdAt": "desc" }],  "availableOrderBy": ["createdAt", "updatedAt"]}

الأخطاء والحدود

#

تصل الأخطاء في الغلاف نفسه. تبيّن حالة HTTP نوع الخطأ، ويبيّن statusCode في المتن رمز فكرة للسبب بدقة. وتضيف أخطاء التحقق مصفوفة errors فيها عنصر لكل حقل.

4015100 · 5102مفتاح API مفقود أو غير سليم أو منتهي الصلاحية، أو سرّه غير مطابق.
4015120 · 5041رمز الوصول مفقود أو منتهي الصلاحية، أو أُلغيت جلسته.
4035101لا يوجد مفتاح API نشط مطابق.
4035063 · 5180دور المستخدم أو صلاحياته لا تشمل نقطة النهاية هذه.
4036104لم يوافق المستخدم على شروط الخدمة وسياسة الخصوصية الحالية.
4225030لم يجتز متن الطلب أو معاملات الاستعلام التحقق.
429429طلبات كثيرة من هذا العميل. انتظر المدة المحددة في Retry-After.
5035000تعذّر التحقق من الرمز حاليًا. أعد إرسال الطلب.
خطأ تحقق
HTTP/1.1 422 Unprocessable Entity {  "statusCode": 5030,  "message": "There are validation errors.",  "metadata": { "language": "en", "version": "1", … },  "errors": [    {      "key": "isNotEmpty",      "property": "password",      "message": "password cannot be empty."    }  ]}

الحدود100 طلب كل 10 ثوانٍ، تُحسب لكل عنوان عميل لا لكل مفتاح. وبعد تجاوزها تردّ الواجهة بالحالة 429 مع ترويسة Retry-After بالثواني. وللتحقق من الشهادات حدّ مستقل قدره 60 طلبًا في الدقيقة.

سجل التدقيق

كل عملية كتابة تترك أثرًا.

تُسجَّل عمليات الدخول وتعديلات المحتوى وتغييرات الأدوار ومفاتيح API والشهادات الصادرة، مع المستخدم والإجراء وعنوان IP والجهاز. وتُسجَّل المحاولات الفاشلة أيضًا، ويستطيع المشرف تصدير أحداث الأدوار بصيغة CSV.

GET /api/v1/admin/activity-log/listمباشر
14:02:11learningModuleUpdatedpolicy-v4-2amina@acme.edu14:02:48userLoginCredentialwebsite · 10.4.2.18noor@acme.edu14:07:44adminApiKeyCreatepartner-syncamina@acme.edu
متضمَّن

بقية المنصة

كلها متاحة في كل مساحة عمل.

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

ما يسأل عنه المهندسون أولًا.

كيف أحصل على مفتاح API؟

ينشئ المشرف المفاتيح ويعيد تعيينها من لوحة الإدارة، ضمن «النظام» ثم «مفاتيح API». وإن لم تكن مؤسستك مهيّأة بعد فتحدّث إلينا أولًا ونرشدك خطوة بخطوة.

ماذا يحتاج كل طلب؟

المفتاح وسرّه في ترويسة x-api-key مفصولين بنقطتين. وتضيف المسارات المحمية رمز الوصول في ترويسة Bearer. أما الدخول والتسجيل والاستعادة فتحتاج أيضًا إلى x-captcha-token محلول.

كيف أتصفّح قائمة صفحةً صفحة؟

تقبل القوائم perPage وcursor وorderBy، وتحمل البيانات الوصفية في الاستجابة حالة الترقيم للطلب التالي.

ماذا يحدث عند بلوغ حدّ الطلبات؟

تردّ الواجهة بالرمز 429 وترويسة Retry-After بالثواني. وتردّ أخطاء التحقق بالرمز 422 ومصفوفة errors فيها إدخال لكل حقل.

كيف ترتبط المؤسسات بالواجهة؟

لكل مؤسسة نطاق فرعي خاص بها. ويُخزَّن الأعضاء والمحتوى والنشاط تحت معرّف المؤسسة، وتُقرأ الأدوار والصلاحيات من جديد مع كل طلب.

هل تستطيع الواجهة الرد بالعربية؟

نعم. أرسل x-custom-lang: ar فتعود الرسائل بالعربية. وتقرأ مسارات محتوى المتعلّم ترويسة Accept-Language وتذكر اللغة التي قدّمت بها.

اربط خدمتك بالواجهة.

أخبرنا بما تبنيه. سنرشدك في المفاتيح والأدوار ونطاق مؤسستك.

تحدّث إلينا عن الواجهةhello@fkra.ai

بالعربية والإنجليزية · نجهّز معك المفاتيح والأدوار