كل ما تفعله لوحة التحكم، على REST.
API العامة تعكس لوحة التحكم: المحادثات والقنوات والعملاء والمنتجات والطلبات والأتمتة والتحليلات. المصادقة OAuth 2.0 مع رموز تحديث؛ ننشر مواصفة OpenAPI 3.1 وبدايات SDK لـ Node و Python و Go. كل نقطة كتابة محدودة السرعة لكل مساحة عمل، وكل نقطة قراءة قابلة للتخزين المؤقت مع ETag.
المصادقة
POST /v1/oauth/token مع client_id و client_secret و grant_type=client_credentials يرجع bearer قصير العمر (15 ديقة) إضافة إلى رمز تحديث. تدفقات التحديث مطابقة لـ RFC 6749 §6. كل نقاط الكتابة تتطلب مطالبة نطاق مساحة العمل؛ يمكن تحديد حسابات الخدمة بنطاق فرعي من قنوات المحادثات.
المحادثات والرسائل
GET /v1/conversations يعرض المحادثات النشطة بترقيم الصفحات بالمؤشر. POST /v1/conversations/{id}/messages يقبل payloads من نص وصورة وصوت ومستند وقالب ويرجع متزامناً معرّف الرسالة المُخزّنة. Webhooks: conversation.started، message.received، message.delivered، message.read.
الكتالوج والطلبات
GET /v1/catalog/products يعكس SKUs سلة وزد وشوبيفاي في فهرس بحث واحد — مفيد لطبقة أدوات الروبوت. POST /v1/orders توجّه مسودة طلب إلى منصة المتجر بدل محادث (نحن لا نفوتر). Webhooks: order.created، order.paid، order.fulfilled، order.cancelled.
حدود السرعة وإعادة المحاولة
المستوى الافتراضي: 60 طلب كتابة/ديقة/مساحة عمل، 600 طلب قراءة/ديقة/مساحة عمل. تتضمن ردود 429 رأس Retry-After بالثواني و X-RateLimit-Reset كحقبة. نوصي بالتراجع الأسي مع التذبذب؛ تُحترم مفاتيح idempotency في POST /v1/orders و POST /v1/conversations/{id}/messages.