ChefSync API v1

المصادقة

أنشئ مفتاحاً من لوحة التاجر ← التطبيقات والربط ← الربط البرمجي. يظهر المفتاح مرة واحدة فقط. أرسله في كل طلب:

curl https://mychefsync.com/api/v1/me \
  -H "Authorization: Bearer cs_xxxxxxxxxx.YOUR_SECRET" \
  -H "Content-Type: application/json"

• صلاحية read لطلبات GET، وصلاحية write لكل ما عداها.
• مفتاح مقيّد بفرع يرى طلبات ذلك الفرع فقط وينشئ طلباته فيه تلقائياً.
• كل الردود JSON بالشكل {"data": …}، والقوائم فيها meta للصفحات (?page=2&per_page=50).
• المبالغ بالريال السعودي، والتواريخ بصيغة ISO-8601.

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

الحساب والفروع

بيانات المطعم (الضريبة، رابط المتجر) والمفتاح المستخدم.

الفروع الفعّالة: مفتوح، مشغول، والخدمات.

المنيو والتوفر

التصنيفات والمنتجات بأسعار الفرع، والإضافات، والتوفر.

إيقاف أو تشغيل منتج من نظامك، في كل الفروع أو في فرع واحد، أو تحديث السعر:

{"is_active": false}
{"branch_id": 2, "available": false}
{"price": 45}

الطلبات

فلاتر: status=pending,accepted · source=web,app · branch · from / to (تاريخ) · updated_since (للمزامنة الدورية) · external_reference.

{
  "data": {
    "id": 1042, "number": "10042", "external_reference": "FDX-77812",
    "status": "accepted", "type": "pickup", "source": "foodics",
    "branch": {"id": 1, "name": "فرع العليا"},
    "customer": {"id": 55, "name": "أبو فهد", "phone": "0551234567"},
    "items": [{"product_id": 12, "name": "خروف كامل", "quantity": 1, "unit_price": 1450, "total": 1450, "addons": [], "notes": null}],
    "amounts": {"subtotal": 1450, "discount": 0, "delivery_fee": 0, "rental": 20, "deposit": 150, "tax": 191.74, "total": 1620, "currency": "SAR"},
    "payment": {"method": "cash", "status": "paid"},
    "created_at": "2026-10-11T12:30:00+03:00"
  }
}

إنشاء طلب

1) طلب مسعّر في نظامك (كاشير آخر) — الافتراضي

يظهر فوراً في شاشة المطبخ ويدخل في التقارير والأمانات والمخزون (إن طابق الصنف منتجاً عندنا بـ product_id أو external_id أو الاسم). إرسال نفس external_reference مرة ثانية يعيد نفس الطلب ولا يكرره.

{
  "source": "pos",
  "external_reference": "FDX-77812",
  "branch_id": 1,
  "type": "dine_in",
  "table": "7",
  "customer": {"name": "أبو فهد", "phone": "0551234567"},
  "items": [
    {"name": "خروف كامل", "quantity": 1, "unit_price": 1450, "addons": [{"name": "رز إضافي", "price": 25}], "notes": "بدون بصل"},
    {"product_id": 31, "quantity": 2, "unit_price": 12}
  ],
  "discount": 0, "total": 1499,
  "payment": {"method": "card", "paid": true},
  "status": "accepted"
}

source: api · pos · foodics · loyverse · printer. status: pending (يحتاج قبول) · accepted (للمطبخ مباشرة) · ready · completed (للتقارير فقط).

2) طلب بأسعار ChefSync

لتطبيق أو موقع خاص: نحسب السعر والعروض والضريبة ورسوم التوصيل من منيو المطعم.

{
  "pricing": "menu",
  "branch_id": 1, "type": "delivery",
  "customer": {"name": "سارة", "phone": "0559876543"},
  "items": [{"product_id": 12, "quantity": 1, "addons": [301, 305]}],
  "address": {"lat": 24.71, "lng": 46.67, "street": "طريق الملك فهد"},
  "payment": {"method": "cash"}
}

الحالات

{"status": "ready", "note": "جاهز للاستلام"}

التسلسل: pending → accepted → preparing → ready → on_the_way → delivered → completed، والإلغاء cancelled متاح قبل الاكتمال. الانتقال غير المسموح يعيد 422 مع قائمة allowed.

{"reason": "ألغاه العميل"}

العملاء

{"phone": "0551234567", "name": "أبو فهد", "email": "a@example.com"}

الأمانات (تأمين وإيجار الأواني)

{"name": "صينية خروف", "quantity": 1, "deposit_amount": 150, "customer_phone": "0551234567", "external_reference": "FDX-77812", "collected_via": "external"}

{"returned_quantity": 1, "deduction": 0, "method": "cash", "note": null}

التقارير

عدد الطلبات، المبيعات (بدون التأمين المسترد)، الضريبة، المتوسط، الملغي، المسترد، والتوزيع حسب المصدر.

Webhooks

أضف رابطك من لوحة التاجر واختر الأحداث. نرسل POST بصيغة JSON خلال ثوانٍ من الحدث، ونعيد المحاولة عند الفشل بعد 1 ثم 5 ثم 15 ثم 60 ثم 180 دقيقة. أي رد 2xx يعني الاستلام.

POST https://your-system.com/webhook
X-ChefSync-Event: order.created
X-ChefSync-Delivery: 7b0c…-uuid
X-ChefSync-Timestamp: 1760180000
X-ChefSync-Signature: 5f2a…hex

{"id": "7b0c…", "event": "order.created", "created_at": "…", "data": { …order… }}

استخدم X-ChefSync-Delivery لتجاهل التكرار: قد يصلك نفس الحدث مرتين عند إعادة المحاولة.

التحقق من التوقيع

التوقيع = hex( HMAC-SHA256( secret, timestamp + "." + rawBody ) ). ارفض الطلب إذا كان الوقت أقدم من 5 دقائق.

// PHP
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_CHEFSYNC_TIMESTAMP'];
$sig = hash_hmac('sha256', $ts.'.'.$raw, getenv('CHEFSYNC_WEBHOOK_SECRET'));
if (!hash_equals($sig, $_SERVER['HTTP_X_CHEFSYNC_SIGNATURE']) || abs(time() - (int) $ts) > 300) { http_response_code(401); exit; }

// Node.js (Express: app.use(express.raw({type: 'application/json'})))
const crypto = require('crypto');
const ts = req.get('X-ChefSync-Timestamp');
const sig = crypto.createHmac('sha256', process.env.CHEFSYNC_WEBHOOK_SECRET).update(ts + '.' + req.body).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(req.get('X-ChefSync-Signature')))) return res.sendStatus(401);

ربط نظام كاشير آخر

1. عنده API أو Webhooks: أرسل كل فاتورة إلى POST /orders (الطريقة 1) مع رقمها في external_reference، وألغِها بـ /orders/{id}/cancel.
2. فودكس ولويفرس: جاهزان من لوحة التاجر ← المنصات وأنظمة الكاشير، والصق رابط الـ Webhook في إعدادات النظام.
3. بدون API: «الطابعة الافتراضية» تلتقط تذكرة المطبخ من أي كاشير وتحوّلها لطلب.
4. للتقارير فقط: استورد ملف Excel من مركز البيانات.

شركات التوصيل (اللوجستيات)

للشركات التي توفر مناديب. عند كل طلب توصيل نرسل إلى رابط الشركة:

POST https://api.courier.com/your-endpoint
Authorization: Bearer {API key from the courier}
X-ChefSync-Signature: hex(HMAC-SHA256(secret, body))

{
  "event": "delivery.requested",
  "order_reference": "CS-1042", "order_number": "10042", "restaurant": "مطعم …",
  "pickup":  {"name": "فرع العليا", "phone": "…", "address": "…", "lat": 24.71, "lng": 46.67, "ready_at": "…"},
  "dropoff": {"name": "سارة", "phone": "0559876543", "address": "…", "lat": 24.75, "lng": 46.70},
  "items_count": 3, "order_value": 120, "cash_to_collect": 120,
  "callback_url": "https://…/webhooks/couriers/{token}"
}

الرد المتوقع (اختياري): {"reference": "SR-77", "tracking_url": "https://…", "fee": 15}. الإلغاء يصل بنفس الرابط: {"event": "delivery.cancelled", "reference": "SR-77"}.

وترسل الشركة كل تحديث إلى callback_url (موقّعاً بنفس الطريقة):

{"reference": "SR-77", "status": "picked_up", "driver": {"name": "علي", "phone": "0550000001"}, "tracking_url": "https://…", "fee": 15}

الحالات: assigned · picked_up · delivered · cancelled · failed (ونقبل المرادفات الشائعة مثل in_transit و completed). الاستلام يجعل الطلب «في الطريق» والتسليم يجعله «تم التوصيل» تلقائياً.

ChefSync API v1 · الدعم: من لوحة التاجر