المطوّرون
المفاتيح والنطاقاتوالحدود
كيف تعمل المصادقة، وما تغطيه واجهة API، وكيف تُحدَّد معدلات الطلبات، وكيف تحصل على مفتاح لمتجرك.
المصادقة
رمز Bearer واحد لمتجر واحد
تُصدَر المفاتيح لكل متجر وتحمل نطاقات صريحة. يمكن لمفتاح أن يقرأ المنتجات دون أن يتمكن من إصدار المبالغ المستردة، وهذا هو الفرق بين ربط مصدر بيانات للمخزون وتسليم النشاط التجاري بأكمله.
- رموز Bearer في ترويسة Authorization
- نطاقات لكل مورد، مع فصل القراءة عن الكتابة
- مفاتيح يمكن إلغاؤها من لوحة التحكم في أي وقت
- كل استدعاء يُنسب إلى صاحبه في سجل تدقيق المتجر
POST /v1/orders/{id}/fulfilments
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"outletId": "out_3f9",
"lines": [{ "orderLineId": "ol_88", "quantity": 2 }],
"deliveryMethod": "RIDER"
}المرجع
ما يمكنك استدعاؤه
مجموعات الموارد المتاحة اليوم. ستصدر مخططات الطلب والاستجابة الكاملة مع المرجع العام.
| المورد | المسار | العمليات |
|---|---|---|
| المنتجات | /v1/products | عرض · إنشاء · تحديث · حذف |
| المتغيرات | /v1/products/{id}/variants | عرض · إنشاء · تحديث |
| المجموعات | /v1/collections | عرض · إنشاء · تحديث |
| المخزون | /v1/inventory/levels | عرض · تعديل · نقل |
| الطلبات | /v1/orders | عرض · إنشاء · تحديث · إلغاء |
| تجهيز الطلبات | /v1/orders/{id}/fulfilments | عرض · إنشاء |
| المرتجعات | /v1/returns | عرض · إنشاء · موافقة |
| العملاء | /v1/customers | عرض · إنشاء · تحديث |
| المدفوعات | /v1/payments | عرض · استرداد |
| الفواتير | /v1/invoices | عرض · إنشاء · إرسال |
| الفروع | /v1/outlets | list |
| Webhooks | /v1/webhooks | عرض · إنشاء · حذف |
الحدود والسلوك
ما تتوقعه من الاتصال
تحديد المعدل
حدود لكل مفتاح، مع إرجاع الرصيد المتبقي في كل استجابة. الطلب الذي يتجاوز الحد يُرجع الرمز 429 مع تلميح لإعادة المحاولة بدلًا من أن يفشل بصمت.
تقسيم الصفحات
نقاط القوائم مقسّمة إلى صفحات باستخدام المؤشر. تنقّل باستخدام المؤشر من الاستجابة السابقة بدلًا من جلب السجلات واحدًا تلو الآخر.
عدم التكرار (Idempotency)
تقبل طلبات الكتابة مفتاح عدم تكرار، فلا تؤدي إعادة المحاولة بعد انتهاء المهلة إلى إنشاء طلب ثانٍ أو استرداد ثانٍ.
الأخطاء
تُرجع حالات الفشل رمزًا ثابتًا قابلًا للقراءة آليًا إلى جانب الرسالة، كي يعتمد تكاملك على الرمز لا على الصياغة.
الإصدارات
يظهر رقم الإصدار في المسار. تصدر التغييرات غير المتوافقة في إصدار جديد، أما الإضافات فتُطبَّق على الإصدار الحالي ويُعلن عنها مسبقًا.
تسليم webhooks
تُوقَّع الحمولات وتُعاد محاولة إرسالها بفواصل متزايدة. عمليات التسليم واستجاباتها مرئية، فيمكن تشخيص أي نقطة اتصال تفشل.