ديلDEAL FOR MARKETING

المطوّرون //

دليل المطوّرين

اربط متجرك وأدوات الأتمتة ومساعدي الذكاء الاصطناعي بحسابك في ديل. كل استدعاء يتم بمفتاح API تنشئه بنفسك وتحدد صلاحياته ومدته، وتلغيه متى شئت.

أنشئ مفتاحًاربط MCP

المصادقة

أنشئ مفتاحًا من مفاتيح API في حسابك. يظهر المفتاح كاملًا مرة واحدة فقط، ونحفظ منه بصمة مشفّرة لا غير. أرسله في ترويسة كل طلب:

الترويسة
Authorization: Bearer deal_live_…

عنوان الـ API: https://deal.mubasat.net/api/v1. الإجابات JSON دائمًا: { data, meta } عند النجاح، و{ error: { code, message, details } } عند الخطأ. لا تضع المفتاح في كود يصل للمتصفح.

الصلاحيات

امنح كل مفتاح أقل ما يحتاجه تكاملك. صلاحيات الفريق لا تظهر إلا لحسابات فريق ديل.

  • services:readقراءة الخدمات. يعرض قائمة خدمات ديل المتاحة للطلب. بيانات عامة لا تخص حسابك.
  • requests:readقراءة طلباتي. يقرأ طلباتك أنت فقط وحالة كل طلب. لا يرى طلبات أي عميل آخر.
  • requests:writeإنشاء طلبات. ينشئ طلبات خدمة جديدة باسم حسابك، ويصل كل طلب لفريق ديل كأنه من النموذج.
  • law:readقراءة بيانات مكتب المحامي. يقرأ عملاء مكتبك وقضاياه وجلساته ومهامه وتقاريره، بحدود دورك في المكتب. لمساعدات الذكاء الاصطناعي عبر MCP.
  • law:writeتعديل بيانات مكتب المحامي. يضيف ويعدّل العملاء والقضايا والجلسات والمهام والمواعيد باسمك وبحدود دورك (بدون حذف). تُسجَّل كل عملية في سجل المساعد.
  • admin:requests:readقراءة كل الطلبات. لفريق ديل: يقرأ طلبات كل العملاء مع بيانات التواصل.
  • admin:requests:writeتغيير حالة الطلبات. لفريق ديل: ينقل أي طلب بين المراحل (جديد، مراجعة، تنفيذ، تسليم).

مسارات REST

  • publicGET /api/v1/services

    قائمة خدمات ديل ومعرّف كل خدمة slug. عامة، لا تحتاج مفتاحًا.

  • requests:readGET /api/v1/requests

    طلباتك أنت فقط، الأحدث أولًا، مع ترقيم الصفحات وتصفية اختيارية بالحالة (حتى 100 في الصفحة).?limit=20&offset=0&status=review

  • requests:readGET /api/v1/requests/:id

    طلب واحد من طلباتك وحالته الحالية.

  • requests:writePOST /api/v1/requests

    ينشئ طلب خدمة باسم حسابك، حتى 20 طلبًا في الساعة لكل مفتاح. قيمة consent يجب أن تكون true (موافقة صاحب الطلب على التواصل).slug · name · phone · company · brief · consent

  • admin:requests:readGET /api/v1/admin/requests

    لفريق ديل: طلبات كل العملاء مع بيانات التواصل.

  • admin:requests:writePATCH /api/v1/admin/requests/:id

    لفريق ديل: يغيّر حالة الطلب إلى إحدى المراحل.{ "status": "new" | "review" | "production" | "delivered" }

قراءة طلباتك
curl https://deal.mubasat.net/api/v1/requests \
  -H "Authorization: Bearer $DEAL_API_KEY"
شكل الإجابة
{
  "data": [ { "id": 42, "service": { "slug": "crm", "title": "…" },
              "status": "review", "status_label": "…", "created_at": "…" } ],
  "meta": { "total": 1, "limit": 20, "offset": 0, "has_more": false, "next_offset": null }
}
إنشاء طلب (يحتاج requests:write)
curl https://deal.mubasat.net/api/v1/requests \
  -H "Authorization: Bearer $DEAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "crm",
    "name": "سارة العتيبي",
    "phone": "0551234567",
    "company": "متجر الورد",
    "brief": "نحتاج نظام CRM يربط طلبات المتجر بفريق المبيعات",
    "consent": true
  }'

خادم MCP

يعمل خادم MCP عبر Streamable HTTP على https://deal.mubasat.net/api/mcp بالمفتاح نفسه. يرى المساعد فقط الأدوات التي تسمح بها صلاحيات المفتاح:

  • services:readdeal_list_services
  • requests:readdeal_list_my_requests
  • requests:readdeal_get_request
  • requests:writedeal_create_request
  • admin:requests:readdeal_admin_list_requests
  • admin:requests:writedeal_admin_update_request_status
Claude Code
claude mcp add --transport http deal https://deal.mubasat.net/api/mcp \
  --header "Authorization: Bearer $DEAL_API_KEY"
عملاء يقبلون ملف إعداد (mcp.json)
{
  "mcpServers": {
    "deal": {
      "type": "http",
      "url": "https://deal.mubasat.net/api/mcp",
      "headers": { "Authorization": "Bearer deal_live_…" }
    }
  }
}

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

  • 401 unauthorizedالمفتاح ناقص أو غير صحيح أو ملغى أو منتهي.
  • 403 insufficient_scopeالمفتاح لا يملك الصلاحية المطلوبة لهذا المسار.
  • 404 not_foundالمسار غير موجود، أو الطلب ليس من طلبات حسابك.
  • 422 validation_errorحقل غير صالح؛ القائمة details تذكر كل حقل وسببه.
  • 429 rate_limitedتجاوزت الحد (60 استدعاء في الدقيقة لكل مفتاح). انتظر عدد الثواني في ترويسة Retry-After.

كل استدعاء يُسجَّل باسم المفتاح ويظهر لك عدده في صفحة المفاتيح. إذا تسرّب مفتاح ألغِه فورًا؛ الإلغاء يسري في اللحظة نفسها.

اطلب خدمتك