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

التوثيق/للمطوّرين/مقدمة

واجهة فكرة البرمجية

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

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

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

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

1curl -X POST "https://<your-api-host>/api/v1/public/user/login/credential" \2  -H "Content-Type: application/json" \3  -H "x-api-key: $FKRA_KEY:$FKRA_SECRET" \4  -H "x-captcha-token: $CAPTCHA_TOKEN" \5  -d '{ "email": "amina@acme.edu", "password": "…", "from": "website" }'

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

curl "https://<your-api-host>/api/v1/shared/user/session/list" \  -H "x-api-key: $FKRA_KEY:$FKRA_SECRET" \  -H "Authorization: Bearer $ACCESS_TOKEN"

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

يسجّل المشرف نوع الوحدة بمخطّطَي 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" } }  }}

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

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

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

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

{ "isTwoFactorEnable": false, "tokens": { "tokenType": "Bearer", "expiresIn": 3600, … } }

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

"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 فيها عنصر لكل حقل.

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.

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

تصل رسالتك إلى المؤسسين مباشرة، دون مندوبي مبيعات أو نماذج تأهيل. hello@fkra.ai