API v1

واجهة المطورين (API)

اقرأ وحدّث الطلبات والقوائم لمطعم واحد من نظام نقاط البيع أو الأكشاك أو أدوات التقارير، واستقبل خطافات ويب موقّعة فور حدوث أي تغيير. ينشئ مالك المطعم المفاتيح والخطافات من مساحة العمل.

العنوان الأساسي: https://www.dhawq.net/api/v1
الصيغة: JSON. المبالغ بأصغر وحدة للعملة، والأسماء بالعربية والإنجليزية، والأوقات بتوقيت UTC.
حد الطلبات: 120 طلبًا في الدقيقة لكل مفتاح

المصادقة

أرسل مفتاح API كرمز Bearer مع كل طلب. يتبع المفتاح مطعمًا واحدًا ولا يرى إلا بياناته. احفظه على خادمك فقط، ولا تضعه أبدًا في تطبيق أو صفحة ويب.

curl https://www.dhawq.net/api/v1/orders?status=received,preparing \
  -H "Authorization: Bearer <your key>" \
  -H "Accept: application/json"

الصلاحيات

orders:read

قراءة الطلبات

عرض الطلبات وأصنافها ومبالغها وحالتها.
orders:write

تحديث الطلبات

تحويل الطلب إلى قيد التحضير أو جاهز أو تم الاستلام، أو إلغاؤه.
menu:read

قراءة القائمة

الفروع والأصناف وأسعار الفروع والتوفر.
menu:write

تحديث التوفر

تفعيل الأصناف أو إيقافها في فرع.

نقاط الوصول

GET /orders orders:read

List orders

Newest first, 25 per page (up to 100). Follow next_cursor for the next page.

status: Comma-separated: pending_payment, scheduled, received, preparing, ready, picked_up, cancelled
branch: Branch code
since: ISO 8601 time; orders placed at or after it
per_page: 1–100
cursor: next_cursor from the previous page

GET /orders/{id} orders:read

Get one order

The order with its items, totals, branch and times.

POST /orders/{id}/status orders:write

Move an order along

preparing, ready, picked_up (only when paid) or cancelled (with a reason). Same rules as the staff screens; a refused move answers 409.

{
    "status": "ready",
    "reason": null
}

GET /branches menu:read

List branches

Codes, bilingual names and locations.

GET /branches/{code}/menu menu:read

Branch menu right now

Categories and products with the branch price, availability and the reason when unavailable.

PUT /branches/{code}/products/{id}/availability menu:write

Switch a product on or off

available, out_of_stock_today (back by itself at local midnight) or not_served.

{
    "status": "out_of_stock_today"
}

خطافات الويب

يستقبل كل خطاف طلب POST بمحتوى JSON يتضمن: id (ثابت عبر إعادة المحاولات، استخدمه لتجاهل التكرار)، وtype، وcreated_at، وrestaurant_id، وdata. أجِب بأي حالة 2xx خلال 10 ثوانٍ.

order.created
order.status_changed
payment.succeeded
payment.refunded

تحقّق من كل إرسال: يحمل الترويسة X-DTP-Signature الوقت وبصمة HMAC-SHA256 للنص "الوقت.المحتوى" باستخدام سر التوقيع الخاص بالخطاف. قارن بزمن ثابت وارفض أي إرسال أقدم من 5 دقائق.

// PHP: verify a delivery
[$t, $v1] = sscanf($_SERVER['HTTP_X_DTP_SIGNATURE'], 't=%d,v1=%s');
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
$valid = hash_equals($expected, $v1) && abs(time() - $t) <= 300;

// Node.js
const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

إذا لم يُجب نظامك بحالة 2xx نعيد المحاولة بعد دقيقة، ثم 5 دقائق، ثم 30 دقيقة، ثم ساعتين، ثم 6 ساعات، ثم 12 ساعة. ويُوقَف الخطاف الذي يفشل باستمرار لمدة 3 أيام ويُبلَّغ المالك.

الأخطاء والحدود

للأخطاء دائمًا الشكل نفسه، مع رمز ثابت يمكنك التصرف بناءً عليه.

{ "error": { "code": "insufficient_scope", "message": "This key does not have the \"orders:write\" scope." } }

401: المفتاح مفقود أو خاطئ أو ملغى.
403: لا يملك المفتاح الصلاحية التي تحتاجها نقطة الوصول.
404: غير موجود في هذا المطعم.
409: غير ممكن حاليًا (مثلًا لا يمكن تسليم طلب غير مدفوع).
422: مدخلات غير صحيحة، وتوضح الأخطاء الحقل المقصود.
429: طلبات كثيرة جدًا؛ انتظر عدد ثواني Retry-After.