عنوان الأساس
https://api.currixa.net/v1
كل مسار يبدأ بـ /v1، وهو نسخة العقد لا نسخة المعرفة. الطلبات والردود بصيغة JSON.
ابنِ فوق بنية المناهج
واجهة واحدة للمعرفة الأكاديمية المهيكلة: مناهج رسمية، نسخ ثابتة، ومصدر موثّق لكل عنصر — عبر REST.
ملاحظة
الجهات ذاتية التسجيل تنشئ تطبيقاتها ومفاتيح الـ API في مساحة عملها؛ ومفتاح التجربة يقرأ المحتوى العام وحده. ويبقى المشغّل يُنشئ عملاء الخدمة للجهات التي يديرها. كل عميل يعمل ضمن حدّه وحدّ مستأجره.
حالة الخدمة والأعطال: status.currixa.net
ابدأ من هنا
خمس خطوات من الصفر إلى أول ردّ من الـ API.
أنشئ حسابك وجهتك
أنشئ حسابًا، ثم سمِّ جهتك واختر بلدها. الجهة هي مستأجرك: كل تطبيق ومفتاح وطلب تابع لها.
أنشئ تطبيقًا ومفتاحًا
افتح «المطوّرون» في مساحة العمل، وأنشئ تطبيقًا بنطاقات القراءة التي يحتاجها، ثم مفتاحًا. ابدأ بمفتاح تجربة: يقرأ المحتوى العام وحده، عشرة طلبات في الدقيقة. المفتاح يظهر مرة واحدة، فانسخه حينها.
ضع المفتاح في متغير بيئة
على خادمك، لا في الكود ولا في المتصفح. مفتاح للتطوير وآخر للإنتاج.
CURRIXA_API_KEY export CURRIXA_API_KEY="paste-your-key-here"أرسل أول طلب
يسرد أول خمسة نتاجات يقرؤها مفتاحك. الرد يحمل data و page.next_cursor.
GET /v1/framework-outcomes curl -s -H "Authorization: Bearer $CURRIXA_API_KEY" "https://api.currixa.net/v1/framework-outcomes?framework=CURRIXA-ARA-NATIVE-V1&limit=5"تابع
ثبّت النسخة التي تقرؤها، واتبع مصدر كل نتاج، واشترك في webhooks.
كل أمر في سطر واحد: الصقه، وبدّل القيمة النائبة، ثم شغّله.
الأساسيات
ما يحتاجه كل تكامل، بنظرة واحدة. لكل بند صفحته الكاملة.
الاستيثاق
Authorization: Bearer $CURRIXA_API_KEY
أرسل مفتاحك في ترويسة Authorization بصيغة Bearer، من خادمك وحده. يعمل المفتاح بنطاقات تطبيقه، داخل جهته.
المفاتيح
crx_test_…crx_live_…
مفتاح التجربة يبدأ بـ crx_test_ ويقرأ المحتوى العام وحده، ومفتاح الإنتاج يبدأ بـ crx_live_. المفتاح يظهر مرة واحدة. دوّره بمهلة حتى سبعة أيام أو ألغِه فورًا من مساحة العمل. تاريخ الانتهاء وقائمة عناوين IP المسموحة اختياريان. وإدارة المفاتيح تتطلب التحقق بخطوتين.
مرجع API
GET /v1/frameworksGET /v1/framework-outcomes
كل نقطة عاملة مع نطاقها، مأخوذة من عقد OpenAPI للواجهة. ملف OpenAPI نفسه غير منشور للتنزيل بعد.
النسخ
?version=YYYY.N?version=YYYY.N.P
مرّر version بصيغة YYYY.N أو YYYY.N.P في قراءات المعرفة، والرد يسمّي النسخة المحلولة دائمًا. المحتوى المنشور لا يتغيّر تحتك: التصحيح نسخة جديدة. والتغيير الكاسر للواجهة يصدر في /v2، لا داخل /v1.
الترقيم
?limit=100&cursor=…page.next_cursor
القوائم تأخذ limit وcursor. أغلب القوائم قيمتها الافتراضية 25، وترفض limit فوق 100. وقوائم المرجع (الدول، أنواع المناهج، مجالات المواد، الأنظمة التعليمية، المراحل الدراسية) و/v1/frameworks تصل إلى 200. أعد page.next_cursor في cursor حتى يصير null. لا أرقام صفحات.
إعادة الكتابة بأمان
Idempotency-Key
كل POST يغيّر الحالة يحمل Idempotency-Key من 8 إلى 128 حرفًا. القيمة نفسها مع الطلب نفسه تعيد الرد المخزّن دون تكرار الفعل؛ ومع طلب مختلف يكون الرد 409 CONFLICT.
حدود المعدّل
429Retry-After
حدود في الدقيقة لعميلك ولجهتك، وحصة شهرية حيث تنص الخطة. الردود تحمل RateLimit-Limit و-Remaining و-Reset. عند التجاوز 429 مع Retry-After: انتظر مدته كاملة، ثم أعد المحاولة مرة.
الأخطاء
request_idx-request-id
كل فشل ردّ Problem واحد: type و title (الرمز الثابت) و status و detail و instance و request_id. وكل رد يحمل x-request-id؛ اذكره حين تراسلنا.
Webhooks
Currixa-SignatureCurrixa-Event-Id
موقّعة بـ HMAC-SHA256 في Currixa-Signature، وتُسلَّم مرة على الأقل، فأزل التكرار بـ Currixa-Event-Id. وتُعاد خمس مرات. ثلاثة من أحداث العقد التسعة تُرسل اليوم.
SDKs
لا مكتبة رسمية منشورة بعد: استدعِ REST مباشرة، بأمثلة جاهزة في صفحة SDKs.
الخطط والاستهلاك
خطتك تحدد الطلبات في الدقيقة وفي الشهر، والتطبيقات والمفاتيح واشتراكات webhooks. تابع الاستهلاك وسجل الطلبات في «المطوّرون» بمساحة العمل.
الدعم والحالة
راسلنا من صفحة التواصل واذكر request_id. وأبلغ عن أي ثغرة عبر الإفصاح المسؤول.
الأمان والسياسات
كيف تعمل التوكنات والعزل والتدقيق، والشروط التي تحكم استخدامك.
كل التوثيق
المفاهيم
المنهج والنسخ والنتاجات والمصدر والرؤية وسياق المستأجر.
البداية السريعة
من العميل إلى أول نتاج مثبت النسخة في سبع خطوات.
مرجع API
النقاط العاملة فعلًا، النطاقات، الترقيم، والأخطاء.
الأخطاء
شكل Problem الموحّد وكل رموز العقد.
الحدود
بلا خطة: 60/دقيقة للعميل و600/دقيقة للمستأجر، وعلى خطة أرقامها، مع Retry-After.
Webhooks
كتالوج الأحداث التسعة، والثلاثة التي تُرسل اليوم، والتوقيع وإعادة المحاولة.
SDKs
لا حزمة رسمية بعد: REST مباشر بأمثلة جاهزة.
الأمان
التوكنات، MFA، العزل، التدقيق، وحدود الذكاء الاصطناعي.
السجل
كيف تتغيّر الواجهة والمعرفة دون مفاجآت.