واجهة البرمجة (API)

تكامل مع منصتنا باستخدام واجهة REST API. كل ما هو متاح في الواجهة متاح عبرها أيضا، وخادم MCP يتيح الشيء نفسه لوكلاء الذكاء الاصطناعي.

المصادقة

تتطلب جميع طلبات API رمز Bearer. أنشئ مفتاح API من الإعدادات > التكاملات.

curl -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  https://your-domain.com/api/v1/tenders

حدود الاستخدام

واجهة API وخادم MCP في الخطة الاحترافية وخطة المؤسسات. وتكون طلبات API محدودة حسب خطة الاشتراك: 1,000 في اليوم في الاحترافية، وبلا حد في المؤسسات. ولا تشمل خطة البداية الوصول إلى API، فيرفض كل مفتاح فيها بالرمز 403 plan_upgrade_required مع الميزة api_access. وفي الاحترافية لكل مستخدم مفتاح API واحد أو ربط MCP واحد، ويرفض الثاني بالرمز 403 plan_limit_reached مع الميزة api_keys_per_user حتى يلغى الأول. ولا يحتسب ربط المساعد على واتساب، ولا حد في خطة المؤسسات.

ترقيم الصفحات

ترجع جميع نقاط النهاية المرقمة استجابات بالهيكل التالي:

{
  "data": [...],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8
}

نقاط النهاية

GET /api/v1/tenders

قائمة المنافسات مع ترقيم الصفحات والترشيح. الصلاحية المطلوبة: tenders.read

GET /api/v1/tenders/:id

تفاصيل منافسة مع بنودها. الصلاحية المطلوبة: tenders.read

GET /api/v1/search

البحث في المنافسات بكلمة مفتاحية (بما في ذلك أسماء البنود). الصلاحية المطلوبة: search

GET /api/v1/bids

قائمة عطاءات مؤسستك. الصلاحية المطلوبة: bids.read

GET /api/v1/favorites

قائمة المنافسات المفضلة لمؤسستك. الصلاحية المطلوبة: favorites.read

الويب هوك

استقبل إشعارات فورية عند حدوث أحداث. كون الويب هوك من الإعدادات > التكاملات.

الأحداث المتاحة

• tender.matched: مناقصة جديدة تطابق تنبيهاتك أو منتجاتك
• bid.status_changed: تغيرت حالة العرض
• deadline.approaching: يقترب الموعد النهائي للمناقصة

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

يتم توقيع جميع حمولات الويب هوك بـ HMAC-SHA256. تحقق من رأس X-Webhook-Signature:

// Verify webhook signature
const crypto = require('crypto');
const signature = req.headers['x-webhook-signature'];
const expected = 'sha256=' + crypto
  .createHmac('sha256', webhookSecret)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature === expected) {
  // Valid webhook
}

خادم MCP

يتيح خادم MCP لوكلاء الذكاء الاصطناعي استخدام المنصة عبر واجهة REST API نفسها (v1)، بالأدوات ذاتها على مسارين: خادم بعيد تقدمه المنصة نفسها، وهو ما يتصل به Claude. وخادم محلي عبر stdio لتشغيل الأدوات إلى جانب نسخة من الشيفرة. لا يوجد تسجيل دخول منفصل: تتم المصادقة بمفتاح API. تلصقه في العميل بنفسك، أو ينشأ لك عند الموافقة في شاشة تسجيل الدخول عبر OAuth. المفتاح مرتبط بالمستخدم: يحمل دور العضو الذي أنشأه، فلا يستطيع تجاوز صلاحيات ذلك الشخص، ويتوقف عن العمل إذا غادر المؤسسة.

تجد كل أداة من أدوات الخادم مشروحة بمعاملاتها وما تعيده ومن يحق له استخدامها في مرجع أدوات MCP.

الخادم البعيد

العنوان هو https://procduck.com/api/mcp (Streamable HTTP). يقبل الترويسة Authorization: Bearer sk_live_…، ويعرض OAuth 2.1 للعملاء الذين يسجلون الدخول بأنفسهم — كتطبيقات Claude. خطوات الربط لكل عميل في ربط Claude.

تشغيل الخادم محليا (stdio)

١. أنشئ مفتاح API

اذهب إلى الإعدادات > التكاملات وأنشئ مفتاحا. امنح الصلاحيات التي يحتاجها الوكيل فقط (مثل tenders.read و search)، أو * للوصول الكامل. الصلاحيات والدور حدان مستقلان ويطبقان معا: مفتاح المستخدم بدور «مشاهد» للقراءة فقط مهما كانت صلاحياته. يظهر المفتاح sk_live_ مرة واحدة عند الإنشاء. انسخه حينها؛ إذ لا يخزن سوى تجزئته SHA-256. تتطلب أدوات إدارة مفاتيح API الصلاحية *.

٢. وجه عميل MCP إلى الخادم

يعمل الخادم المحلي عبر stdio من نسخة الشيفرة. عين PROCDUCK_API_KEY بالمفتاح الذي أنشأته و PROCDUCK_API_URL بعنوان نشرك (القيمة الافتراضية http://localhost:3000).

{
  "mcpServers": {
    "procduck": {
      "command": "npm",
      "args": ["run", "--silent", "mcp"],
      "cwd": "/path/to/procduck",
      "env": {
        "PROCDUCK_API_URL": "https://your-domain.com",
        "PROCDUCK_API_KEY": "sk_live_YOUR_API_KEY"
      }
    }
  }
}

٣. تحقق من المفتاح

قبل ربط الوكيل، تأكد من عمل المفتاح مباشرة مع واجهة REST API:

curl -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  https://your-domain.com/api/v1/tenders?page_size=1

ما الذي يسمح به المفتاح

يفحص كل طلب مقابل الدور الحالي لمنشئ المفتاح، لذا فإن خفض دور عضو أو إزالته يقلص مفاتيحه أو يبطلها فورا، دون الحاجة إلى إلغائها يدويا.

• المالك: كل شيء، بما في ذلك الفوترة.
• المشرف: جميع عمليات القراءة والكتابة؛ دون الفوترة.
• المبيعات: يعمل على العطاءات وعروض الأسعار وأوامر البيع والكتالوج؛ أسعار البيع فقط، مع حجب ردود الموردين وسجل التوريد وأوامر الشراء وأسعار التكلفة.
• المشتريات: يعمل على العطاءات وطلبات عروض الأسعار والتوريد وأوامر الشراء برؤية أسعار البيع والتكلفة معا؛ دون إدارة المنشأة.
• الفني: قراءة فقط لكتالوج المنتجات والمصنعين والمنافسات؛ مع حجب الأسعار وعروض الأسعار وطلبات عروض الأسعار والطلبات والخدمات اللوجستية.
• المشاهد: قراءة فقط. ترفض الكتابة أيا كانت الصلاحيات.
• المشاهد (بدون تسعير): قراءة فقط، مع حجب نقاط النهاية وحقول التسعير.

حل المشكلات

• 401: المفتاح مفقود أو غير صالح أو غير معروف. تأكد من تصدير PROCDUCK_API_KEY وأنه يبدأ بـ sk_live_.
• 402: استنفد الحد اليومي لاستدعاءات API في خطتك.
• 403: المفتاح معطل، أو غادر مالكه المؤسسة، أو أن دور المالك لا يسمح بهذا الإجراء. والرمز plan_upgrade_required مع api_access يعني أن الخطة (البداية) لا تشمل الوصول إلى API، والرمز plan_limit_reached مع api_keys_per_user يعني أن لدى مالك المفتاح في الخطة الاحترافية مفتاحا أو ربط MCP بالفعل، فلا ينشأ له مفتاح آخر ولا يعاد تفعيل مفتاح موقوف.
• 429: بلغت حد المعدل (١٠٠ طلب في الدقيقة لكل مفتاح). أعد المحاولة بعد قليل.