تكامل طلبات المطاعم

المواصفات الرسمية لربط نظام المنيو والمطبخ مع منصة صلة.

صلة تنشئ الطلبات تلقائياً من محادثات العملاء، وترسلها فوراً لنظام المنيو الخاص بك عبر الويب هوكس، مما يتيح لك قبولها أو رفضها أو تحديث حالاتها في الوقت الفعلي عبر الـ API.

إعداد التكامل السريع

  1. إنشاء مفتاح الوصول: أنشئ مفتاح API بصلاحيات orders:read و orders:write من لوحة إدارة صلة.
  2. تهيئة الويب هوك: أضف رابط الويب هوك الخاص بك (HTTPS) واشترك في الحدث order.created.
  3. التحقق الأمني: قم بتنفيذ خوارزمية التحقق من ترويسة X-Sela-Signature باستخدام مفتاح الويب هوك السري لمنع التلاعب وحماية الخادم الخاص بك.

1. استقبال الطلبات (Webhook)

ترسل صلة الويب هوك مع ترويسة X-Sela-Delivery كمفتاح لمنع تكرار الطلب (Idempotency Key) عند إعادة المحاولة.

json
{
  "event": "order.created",
  "data": {
    "id": "toolExecutions:...",
    "status": "pending",
    "orderSummary": "2 burgers, fries, delivery fee included",
    "customer": { "name": "Ali", "phone": "+964..." },
    "fulfillment": { "type": "delivery", "address": "Al Mansour" },
    "externalOrderId": null
  }
}

آلية التحقق من التوقيع الأمني

لحماية التكامل من الهجمات، ترفق صلة ترويسة X-Sela-Timestamp (الوقت بالملي ثانية) وترويسة X-Sela-Signature (توقيع HMAC-SHA256 بنظام سداسي عشر hex). يتم توليد التوقيع بدمج قيم التوقيع كالتالي: timestamp.body.

verify-webhook.js
const crypto = require("crypto");

function verifySelaWebhook(rawBody, signature, timestamp, secret) {
    // 5-minute tolerance window for replay attacks
    const fiveMinutes = 5 * 60 * 1000;
    if (Math.abs(Date.now() - Number(timestamp)) > fiveMinutes) {
        throw new Error("Replay attack suspected: timestamp window exceeded.");
    }

    // Concatenate timestamp and raw body using a dot
    const signedPayload = `${timestamp}.${rawBody}`;
    
    // Compute HMAC-SHA256 in hex format
    const computed = crypto
        .createHmac("sha256", secret)
        .update(signedPayload)
        .digest("hex");

    // Perform timing-safe comparison to prevent side-channel leaks
    return crypto.timingSafeEqual(
        Buffer.from(signature, "hex"),
        Buffer.from(computed, "hex")
    );
}

2. تحديث حالة الطلب (REST API)

أرسل قرارات المطعم (الموافقة أو الرفض أو التوصيل) لتحديث المحادثة تلقائياً وإغلاق سياق الطلب النشط للمساعد الذكي.

bash
curl "https://jovial-bison-730.convex.site/api/v1/orders/action" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "toolExecutions:...",
    "action": "approve",
    "external_order_id": "menu-123"
  }'
القيم والقرارات المدعومة:
  • approve: قبول الطلب وبدء التحضير. ترسل صلة رسالة تأكيد للعميل.
  • reject: رفض الطلب. ترسل صلة رسالة اعتذار وتنبيه للعميل.
  • mark_arrived: تأكيد وصول/تسليم الطلب بنجاح وإغلاق سياق المحادثة بشكل كامل.

3. الاستعلام عن الطلبات المعلقة (REST API)

استرجع الطلبات المعلقة مباشرة للاستعلام أو المزامنة اليدوية.

bash
curl "https://jovial-bison-730.convex.site/api/v1/orders?status=pending&limit=25" \
  -H "Authorization: Bearer sk_live_..."