مرجع الواجهة البرمجية

هذه الصفحة تجمع الأعراف التي تنطبق على كل عملية في واجهة المنصّة؛ صفحات الموارد التي تليها مولَّدة من مواصفة OpenAPI نفسها التي يعمل بها الخادم. اقرأها مرة واحدة ثم عد إليها عند أي رقم.

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

https://dukkan.one/platform-api/v1

تعمل الواجهة على المضيف الرئيسي فقط؛ نطاقات واجهات المتاجر الفرعية والنطاقات المخصّصة تعيد 404. كل الاستجابات application/json مع Cache-Control: no-store.

المصادقة#

Authorization: Bearer YOUR_ACCESS_TOKEN

رمز وصول تطبيق من التفويض، مربوط بمتجر واحد وتثبيت واحد. كل عملية تتطلب نطاقاً فعلياً محدداً في مرجع النطاقات؛ غيابه يعيد 403. الرمز الغائب أو المنتهي أو الملغى يعيد 401، وكذلك فقدان العضو المانح وصوله إلى المتجر.

Idempotency-Key#

كل عملية تُنشئ أو تغيّر بيانات المتجر (PATCH /orders/{id}/status، POST /orders/{id}/fulfillments، PATCH /orders/{id}/fulfillments/{fulfillmentId}، POST /orders/{id}/refunds، POST /inventory/movements) تتطلب الترويسة:

Idempotency-Key: booking-6f1d2c3b-1

• نص من 1 إلى 200 حرف، فريد لكل تثبيت. غيابه يعيد 400.
• إعادة الطلب بالمفتاح نفسه والحمولة نفسها تعيد الاستجابة الأصلية بحالتها مع الترويسة Idempotency-Replayed: true.
• المفتاح نفسه بحمولة مختلفة يعيد 409 برسالة Idempotency key was already used for a different request؛ والطلب الذي ما زال قيد التنفيذ يعيد 409 أيضاً.
• تُحفظ الاستجابات المسجّلة 24 ساعة.

PUT /webhooks وDELETE /webhooks مستقلّان بطبيعتهما ولا يتطلبان المفتاح.

التصفّح#

تعيد القوائم { "data": [...], "next_cursor": "..." }:

المؤشر مبنيّ على created_at الثابت، لذلك يبقى مستقراً أثناء التغييرات. للمزامنة التزايدية استخدم المرشّحات created_at_min وupdated_at_min (الطلبات) وupdated_at_min (المنتجات)، واحفظ آخر طابع زمني عالجته.

الحدود#

التجاوز يعيد 429 برمز rate_limited وترويسة Retry-After بالثواني. انتظرها ثم أعد المحاولة؛ لا تعد المحاولة قبلها.

الترويسات#

الإصدارات#

• v1 في المسار هو العقد: لا يُحذف حقل ولا يتغيّر نوعه ضمنه أبداً.
• التغييرات الإضافية (حقل جديد، موضوع جديد، قيمة تعداد جديدة) تُطلق كمراجعات مؤرّخة تظهر في X-Dukkan-Api-Version وتُسجَّل في سجل التغييرات.
• تحمل حمولات Webhooks المراجعة نفسها في ترويستها وapi_version: "v1" في الغلاف.
• تجاهل الحقول التي لا تعرفها، ولا تعتمد على ترتيب الحقول.

الأخطاء#

كل خطأ يحمل الغلاف نفسه:

{
  "error": {
    "code": "conflict",
    "message": "Order cannot be fulfilled in its current status",
    "request_id": "7d0c2b1a-5e4f-4a3b-8c9d-0e1f2a3b4c5d"
  }
}

message نص للبشر وقد يتغيّر؛ فرّع على code والحالة فقط. details كائن اختياري بتفاصيل التحقق.

سياسة البيانات الشخصية#

الواجهة خالية من بيانات العملاء افتراضياً. الحقلان customer وshipping_address يظهران في GET /orders/{id} فقط عندما يحمل التثبيت clients:read (المقيّد باتفاقية معالجة البيانات)، ولا يظهران في القوائم ولا في أي Webhook. كل استدعاء يُسجَّل في سجل نشاط التاجر بحالته وrequest_id. راجع مرجع النطاقات ومعالجة البيانات.

المال#

كل مبلغ كائن { amount_minor, currency, decimals }. اقرأ decimals من كل مبلغ؛ لا تستخدم جدول ISO. راجع المال بالوحدات الصغرى.