واجهة API v1
عقد 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 | الاسم والمعرف والنطاق الفرعي وتاريخ الإنشاء دون الإعدادات الخاصة أو بيانات البنك. |
GET /api/v1/catalog/products/{id} | catalog:read | منتج واحد مع الوصف والخيارات والمتغيرات. |
POST /api/v1/catalog/products | catalog:write | إنشاء منتج بالحقول الأساسية. |
PATCH /api/v1/catalog/products/{id} | catalog:write | تعديل الحقول الأساسية لمنتج. |
GET /api/v1/catalog/categories | categories:read | التصنيفات النشطة. |
GET /api/v1/orders/{id} | orders:read | ملخص طلب واحد. |
GET /api/v1/orders/{id}/items | orders:read_items | عناصر الطلب دون بيانات العميل. |
POST /api/v1/orders/{id}/tags | orders:write_tags | إضافة وسم داخلي يملكه التطبيق. |
DELETE /api/v1/orders/{id}/tags/{tag} | orders:write_tags | إزالة وسم أنشأه التطبيق. |
POST /api/v1/orders/{id}/fulfillments | orders:write_fulfillments | تسجيل شركة الشحن ورقم التتبع وشحن طلب مؤكد أو قيد التجهيز. |
GET /api/v1/customers/{id} | customers:read | بيانات تواصل عميل واحد. |
POST /api/v1/customers/{id}/tags | customers:write_tags | إضافة وسم لعميل. |
DELETE /api/v1/customers/{id}/tags/{tag} | customers:write_tags | إزالة وسم أضافه التطبيق. |
POST /api/v1/inventory/adjustments | inventory:write | تعديل كمية المخزون في موقع نشط. |
POST /api/v1/discounts | discounts:write | إنشاء كود خصم. |
PATCH /api/v1/discounts/{id} | discounts:write | تعديل كود أنشأه التطبيق. |
GET /api/v1/app-data | app_data:manage | عرض بيانات التطبيق الخاصة حسب السجل المالك. |
GET /api/v1/app-data/{key} | app_data:manage | قراءة قيمة خاصة واحدة. |
PUT /api/v1/app-data/{key} | app_data:manage | إنشاء قيمة خاصة أو استبدالها. |
DELETE /api/v1/app-data/{key} | app_data:manage | حذف قيمة خاصة. |
لا يوجد عقد API عام لتعديل الطلبات بشكل عام أو الدفع أو الاسترداد أو ملصقات الشحن أو الرسائل. يجب أن ينتمي كل معرف مذكور إلى متجر التثبيت؛ وسجلات المتاجر الأخرى تعيد 404.
الكتابة والحماية من التكرار
تتطلب كل عملية POST وPUT وPATCH وDELETE أعلاه ترويسة Idempotency-Key بطول 8 إلى 128 حرفًا من A-Z a-z 0-9 _ . : -. إعادة المحاولة بالمفتاح نفسه والمسار والهدف والجسم نفسه خلال 24 ساعة تعيد النتيجة المحفوظة دون كتابة جديدة. واستخدام المفتاح لطلب مختلف يعيد 409 idempotency_conflict. يجب أن يكون الجسم كائن application/json لا يتجاوز 32,768 بايت، والحقول غير المعروفة تعيد 400 invalid_request. تعيد قاعدة البيانات التحقق من الرمز والمنحة والعقد وبوابة الإصدار داخل معاملة الكتابة نفسها، وتُسجل كل كتابة ناجحة في سجل تدقيق السوق. وتصدر التغييرات أحداث Webhook الحالية للموارد مثل products.updated أو orders.fulfilled.
الترقيم
تقبل عمليتا قائمة المنتجات والطلبات 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 للمدخل غير الصالح (invalid_request وinvalid_json وinvalid_pagination)، و401 للرمز غير الصالح، و403 للقدرة غير المدعومة أو رفض إنشاء Webhook، و404 للسطح غير المتاح أو سجل خارج متجرك، و409 لـidempotency_conflict أو invalid_transition أو conflict، و413 للجسم الكبير، و415 لجسم كتابة ليس JSON، و422 لـvalidation_failed أو quota_exceeded، و429 لتجاوز المعدل، و500 لفشل الاستعلام أو التعديل، و503 لتعطل خدمة حد المعدل. قد تتضمن أخطاء الكتابة error.field باسم المدخل المرفوض. اعتمد على الرمز لا مطابقة النص. أعد محاولة الكتابة فقط بمفتاح Idempotency-Key نفسه وبانتظار متزايد محدود.
حدود المعدل
السياسة الفعلية هي 60 طلباً في نافذة ثابتة مدتها 60 ثانية لكل تثبيت ولكل مفتاح مسار. تعيد المصادقة الناجحة RateLimit-Limit وRateLimit-Remaining وRateLimit-Reset. وتعيد 429 أيضاً Retry-After. الحد ليس لكل رمز ولا لكل تطبيق عالمياً ولا لكل مستأجر عالمياً.
الإصدار والقيود
إصدار المسار هو v1. حوكمة الإهمال الرسمية وأدلة الترحيل PLANNED؛ راجع سجل التغييرات قبل الترقية. لا تشمل ملخصات الطلبات بيانات العملاء، وتتطلب عناصر الطلب orders:read_items. تحدد OpenAPI الحقول العامة وقد تكون أضيق من نماذج التجارة الداخلية.