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

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

المصادقة

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

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

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

تكون طلبات API محدودة حسب خطة الاشتراك. Pro: 1,000/يوم، Enterprise: غير محدود.

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

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

{
  "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. المفتاح مرتبط بالمستخدم: يحمل دور العضو الذي أنشأه، فلا يستطيع تجاوز صلاحيات ذلك الشخص، ويتوقف عن العمل إذا غادر المؤسسة.

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

العنوان هو 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 في خطتك، أو أن خطتك لا تشمل الوصول إلى API.
• 403: المفتاح معطّل، أو غادر مالكه المؤسسة، أو أن دور المالك لا يسمح بهذا الإجراء.
• 429: بلغت حد المعدل (١٠٠ طلب في الدقيقة لكل مفتاح). أعد المحاولة بعد قليل.