العمليات الحالية الإحدى عشرة والمصادقة والترقيم والأخطاء وحد المعدل الثابت والقيود.

عقد API v1 العام

المسار الأساسي الحالي هو /api/v1. أرسل من خادمك رمز وصول مرتبطاً بالتثبيت ضمن Authorization: Bearer <ACCESS_TOKEN>. يجب أن تكون ميزة السوق مفعلة؛ وإلا فالسطح غير متاح.

العمليات الحالية

الطريقة والمسار	النطاق المطلوب	تغطية المورد الحالية
`GET /api/v1/catalog/products`	`catalog:read`	حقول قائمة المنتجات.
`GET /api/v1/orders`	`orders:read`	حقول ملخص الطلب.
`GET /api/v1/webhooks`	`webhooks:manage`	اشتراكات التثبيت.
`POST /api/v1/webhooks`	`webhooks:manage`	إنشاء اشتراك أو تدوير سره.
`DELETE /api/v1/webhooks/{id}`	`webhooks:manage`	تعطيل اشتراك واحد للتثبيت.
`GET /api/v1/customers`	`customers:read`	الاسم والهاتف والبريد وتاريخ الإنشاء دون العناوين أو الملاحظات.
`GET /api/v1/discounts`	`discounts:read`	القواعد النشطة حاليًا دون سجل استخدام العملاء.
`GET /api/v1/inventory/locations`	`inventory:read`	أسماء المواقع ونوعها وحالتها.
`GET /api/v1/inventory/levels`	`inventory:read`	معرفات المنتج والمتغير والموقع والكميات المتاحة والمحجوزة والإجمالية.
`GET /api/v1/inventory/movements`	`inventory:read`	معرفات الموارد وتغير الكمية وسببه وتاريخه دون الملاحظات أو هوية الموظف.
`GET /api/v1/store`	`store:read`	الاسم والمعرف والنطاق الفرعي وتاريخ الإنشاء دون الإعدادات الخاصة أو بيانات البنك.

لا يوجد عقد API عام حتى الآن لتعديل المنتجات والخصومات والطلبات أو الدفع أو الشحن أو الرسائل.

الترقيم

تقبل عمليتا قائمة المنتجات والطلبات limit من 1 إلى 100، والقيمة الافتراضية 25، كما تقبلان طابع ISO في before. تحتوي الاستجابة meta.limit وmeta.next_before. يعيد المؤشر غير الصالح كتاريخ حالة 400 ورمز invalid_before_cursor.

تعيد نقاط القراءة الست الجديدة data وmeta.next_cursor. أرسل before وbefore_id معًا كما عادا تمامًا، مع الحفاظ على دقة الطابع الزمني. يستخدم الترتيب تاريخ الإنشاء ثم المعرف تنازليًا، فلا تضيع السجلات المتساوية في التاريخ. المؤشر الفارغ يعني الصفحة الأخيرة. الحد الافتراضي 25 ويقبل عددًا صحيحًا من 1 إلى 100. المؤشر الناقص أو المعامل المكرر أو غير المعروف مثل tenant_id يعيد 400 invalid_pagination. تعيد قاعدة البيانات التحقق من الرمز والمنحة وبوابة الإصدار داخل معاملة القراءة نفسها؛ فلا يكفي تحقق سابق بعد سحب الإذن.

سلوك الأخطاء

تستخدم أخطاء API v1 الغلاف التالي:

{"error":{"code":"invalid_token"}}

تشمل الحالات المعروفة: 400 للمدخل غير الصالح، و401 للرمز غير الصالح، و403 لرفض إنشاء Webhook، و404 للسطح غير المتاح أو الاشتراك المفقود، و413 لجسم إنشاء كبير، و429 لتجاوز المعدل، و500 لفشل الاستعلام أو التعديل، و503 لتعطل خدمة حد المعدل. اعتمد على الرمز لا مطابقة النص. لا تعد إلا العملية idempotent وبانتظار متزايد محدود.

حدود المعدل

السياسة الفعلية هي 60 طلباً في نافذة ثابتة مدتها 60 ثانية لكل تثبيت ولكل مفتاح مسار. تعيد المصادقة الناجحة RateLimit-Limit وRateLimit-Remaining وRateLimit-Reset. وتعيد 429 أيضاً Retry-After. الحد ليس لكل رمز ولا لكل تطبيق عالمياً ولا لكل مستأجر عالمياً.

الإصدار والقيود

إصدار المسار هو v1. حوكمة الإهمال الرسمية وأدلة الترحيل PLANNED؛ راجع سجل التغييرات قبل الترقية. لا تشمل قراءة المنتجات موارد التصنيفات، ولا تشمل قراءة الطلبات عقداً عاماً لعناصر الطلب. تحدد OpenAPI الحقول العامة وقد تكون أضيق من نماذج التجارة الداخلية.