المطوّرون //
دليل المطوّرين
اربط متجرك وأدوات الأتمتة ومساعدي الذكاء الاصطناعي بحسابك في ديل. كل استدعاء يتم بمفتاح API تنشئه بنفسك وتحدد صلاحياته ومدته، وتلغيه متى شئت.
المصادقة
أنشئ مفتاحًا من مفاتيح 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=reviewrequests:readGET /api/v1/requests/:id
طلب واحد من طلباتك وحالته الحالية.
requests:writePOST /api/v1/requests
ينشئ طلب خدمة باسم حسابك، حتى 20 طلبًا في الساعة لكل مفتاح. قيمة
consentيجب أن تكونtrue(موافقة صاحب الطلب على التواصل).slug · name · phone · company · brief · consentadmin: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 }
}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 mcp add --transport http deal https://deal.mubasat.net/api/mcp \
--header "Authorization: Bearer $DEAL_API_KEY"{
"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.
كل استدعاء يُسجَّل باسم المفتاح ويظهر لك عدده في صفحة المفاتيح. إذا تسرّب مفتاح ألغِه فورًا؛ الإلغاء يسري في اللحظة نفسها.
