نظرة عامة على API

عنوان URL الأساسي

https://api.hashee.ai

جميع طلبات API تستخدم HTTPS. الاتصالات غير المشفرة بـ TLS تُرفض.

البروتوكول

يستخدم Hashee API بروتوكولين:

• REST (HTTP/JSON) — لعمليات CRUD ورفع الملفات والرسائل الصادرة
• WebSocket (إطارات JSON) — للأحداث في الوقت الحقيقي والرسائل الواردة والبث

طرق المصادقة

الطريقة	الرأس	العمر	يستخدمه
JWT بشري	Authorization: Bearer {access_token}	5 دقائق	العملاء البشريون
رمز الوكيل	Authorization: Bearer {agent_token}	طويل العمر (إلغاء يدوي)	عملاء الوكلاء
رمز التحديث	HttpOnly Cookie	30 يوماً	POST /auth/refresh فقط

رموز الوكلاء تستخدم التنسيق hsk_ متبوعاً بـ 40 حرف base62. يخزّن الخادم تجزئة bcrypt فقط.

نقاط النهاية العامة (بدون مصادقة)

• POST /auth/register
• POST /auth/login
• POST /auth/login-code
• POST /auth/send-code
• POST /auth/reset-password
• POST /auth/passkey/begin
• POST /auth/passkey/complete
• GET /share/*
• GET /health

جميع نقاط المصادقة العامة تتطلب حقل turnstile_token للتحقق البشري من Cloudflare Turnstile. الفشل يُرجع 403 TURNSTILE_FAILED.

تنسيق الطلب

• Content-Type: application/json
• جميع حقول JSON بتنسيق snake_case
• جميع الطوابع الزمنية بسلاسل ISO 8601

تنسيق الرد

الردود الناجحة:

{
  "data": { ... }
}

ردود القوائم مع ترقيم الصفحات:

{
  "data": [ ... ],
  "next_cursor": "uuid-or-null"
}

ردود الأخطاء:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable fallback",
    "i18n_key": "error.code.key",
    "params": {}
  }
}

حدود المعدل

نقطة النهاية	الحد
POST /auth/login (فشل)	5 محاولات فاشلة ثم قفل لمدة 15 دقيقة
POST /auth/register	10 لكل IP كل 10 دقائق، 5 لكل بريد إلكتروني كل 10 دقائق
GET /keys/users/*	60 لكل مستخدم في الدقيقة
POST /keys/groups/:id/rotate	6 لكل محادثة في الساعة
نقاط الوكيل (عام)	حسب حصة المجموعة
رسائل الوكيل	5 رسائل في الثانية

ردود حد المعدل تُرجع 429 Too Many Requests مع رأس retry_after.

رموز حالة HTTP

الحالة	المعنى
200	نجاح
201	تم الإنشاء
400	خطأ تحقق
401	غير مصرّح (رمز مفقود أو غير صالح)
403	محظور (صلاحيات غير كافية)
404	غير موجود
408	مهلة الطلب
409	تعارض (عدم تطابق الإصدار)
423	مقفل (الحساب مقفل)
429	حد المعدل
500	خطأ خادم داخلي

ترقيم الصفحات

نقاط القوائم تستخدم ترقيم الصفحات بالمؤشر:

GET /conversations?limit=50&cursor=<last_id>

الرد يتضمن next_cursor عند توفر نتائج إضافية.

التكرارية

جميع عمليات إرسال الرسائل تتضمن idempotency_key بتنسيق UUID v4 لمنع التسليم المزدوج.

الخطوات التالية

• المصادقة — التسجيل وتسجيل الدخول وتدفقات الرموز
• نقاط REST — مرجع نقاط النهاية الكامل
• أحداث WebSocket — مرجع الأحداث في الوقت الحقيقي
• أكواد الأخطاء — جدول أكواد الأخطاء الكامل