توثيق واجهة Cognita البرمجية (API)

للمطوّرين ومستخدمي Pro الراغبين في الدمج البرمجي مع حساباتهم وتراخيصهم ومزامنة بياناتهم.

الأساسيات

الرابط الأساسي (Base URL): https://cognita.dalilai.net

المصادقة: أرسِل رمز JWT في الترويسة Authorization: Bearer <token> (تحصل عليه من تسجيل الدخول). صلاحية الرمز 30 يوماً.

الصيغة: كل الطلبات والردود بصيغة JSON. الأخطاء ترجع { "error": "الرسالة" } مع رمز HTTP مناسب.

١) المصادقة

POST/api/auth/register

إنشاء حساب جديد.

curl -X POST https://cognita.dalilai.net/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"secret123"}'

→ { "token": "JWT...", "user": { "id":"...","email":"...","plan":"free" } }

POST/api/auth/login

تسجيل الدخول والحصول على الرمز.

curl -X POST https://cognita.dalilai.net/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"secret123"}'

→ { "token": "JWT...", "user": { ... } }

POST/api/auth/forgot

طلب رابط إعادة تعيين كلمة المرور بالبريد. {email} — يرجع {ok:true} دائماً (لا يكشف وجود الحساب).

POST/api/auth/reset

تعيين كلمة مرور جديدة. {email, token, password} (الرمز من رابط البريد، صالح ساعة).

٢) الحساب والصلاحية

GET/api/me

بيانات الحساب وصلاحيته (الخطة والميزات وتاريخ الانتهاء).

curl https://cognita.dalilai.net/api/me \
  -H "Authorization: Bearer JWT..."

→ {
  "user": { "email":"...", "plan":"pro", "expiresAt": 1790000000000 },
  "entitlement": {
    "plan": "pro",
    "features": { "aiOptimize":true, "agentRun":true, "autoSearchMulti":true, "cloudSync":true },
    "valid": true
  }
}

GET/api/license/validate

التحقّق السريع من حالة الترخيص (يُستخدم للتأكد من صلاحية Pro).

→ { "plan":"pro", "features": {...}, "expiresAt": 1790000000000, "valid": true }

POST/api/license/activate

تفعيل مفتاح ترخيص على الحساب.

-d '{"key":"COG-XXXX-XXXX-XXXX"}' → { "plan":"pro", ... }

٣) المزامنة السحابية Pro

متاحة لمستخدمي Pro فقط — ترجع 403 لغيرهم.

POST/api/sync/push

رفع مكتبة المستخدم (البرومبت/السلاسل/عمليات البحث).

-d '{"prompts":[...],"flows":[...],"searches":[...]}' → { "ok": true }

GET/api/sync/pull

جلب مكتبة المستخدم المخزّنة سحابياً.

→ { "prompts":[...], "flows":[...], "searches":[...] }

٤) وكيل النماذج المركزي Pro

يتيح لمشتركي Pro استدعاء نماذج الذكاء عبر مفاتيح الخادم المركزية — دون مفتاح خاص — ضمن حدّ شهري يحدّده المشرف. يجب أن يكون الحساب Pro وأن يُفعّل المشرف الوكيل، وإلا تُرجَع 403؛ وعند تجاوز الحدّ تُرجَع 429.

POST/api/model/proxy

الحقول: provider (openai/anthropic/gemini · اختياري، الافتراضي من إعداد الخادم)، system (اختياري)، user (نص الطلب)، temperature (اختياري).

curl -X POST https://cognita.dalilai.net/api/model/proxy \
  -H "Authorization: Bearer JWT..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","user":"لخّص النص التالي: ..."}'

→ { "text": "الناتج...", "usage": 12, "limit": 1000 }

usage عدد طلباتك هذا الشهر بعد هذا الطلب، وlimit الحدّ الشهري (0 = بلا حد). النموذج يحدّده الخادم لضبط التكلفة.

٥) الفوترة والدفع

POST/api/orders

إنشاء فاتورة اشتراك. {plan,cycle,coupon?} — يرجع الفاتورة وdiscountPercent إن وُجد كوبون.

POST/api/subscription/renew

إنشاء فاتورة تجديد. {cycle,coupon?}

POST/api/subscription/trial

بدء تجربة Pro المجانية (مرّة واحدة، إن فعّلها المشرف).

GET/api/invoices/mine

قائمة فواتير المستخدم.

POST/api/invoices/:id/reference

إرسال مرجع التحويل البنكي وإرفاق الإيصال. {reference, receipt?} (الإيصال صورة data URL ≤ 1.5MB).

POST/api/invoices/:id/paypal/create

بدء دفعة PayPal للفاتورة — يرجع {approveUrl} لتحويل العميل إليه. يُلتقط الدفع تلقائياً عند العودة.

٦) البيانات والخصوصية

GET/api/me/export

تنزيل نسخة JSON من بيانات الحساب والفواتير والمكتبة.

POST/api/me/delete

حذف الحساب وبياناته نهائياً. {password} للتأكيد.

رموز الأخطاء

الرمز	المعنى
400	طلب غير صالح (بيانات ناقصة)
401	غير مُصرّح (رمز مفقود/منتهٍ)
403	ممنوع (ميزة Pro أو صلاحية مشرف)
404	غير موجود
500	خطأ في الخادم