مرجع الواجهات البرمجية
الواجهات البرمجية وWebhooks وMCP.

تبني بي في وكلاءك وتشغّلهم. وتتيح هذه الواجهات لأنظمتك وأدوات الذكاء الاصطناعي لديك العمل معهم:

• واجهات REST البرمجية: لبدء المهام، ومتابعة نتائجها، والتعامل مع الموافقات، وقراءة سجلات التدقيق.
• Webhooks: لتصلك إشعارات فور انتهاء مهمة أو حين يحتاج وكيل إلى قرار.
• MCP: لتتيح لمساعدي الذكاء الاصطناعي الذين يدعمون بروتوكول Model Context Protocol استخدام وكلاء بي في لديك كأدوات، ولتتيح لوكلائك استخدام خوادم MCP الخاصة بك.

يُهيّأ الوصول لكل مشروع على حدة: نفعّل نقاط النهاية وأحداث Webhooks وأدوات MCP التي يحتاجها مشروعك، ونرسل إليك التفاصيل مع بيانات الاعتماد. جديد على بي في؟ ابدأ من التوثيق.

تستخدم جميع الطلبات HTTPS وJSON. يأتي عنوانك الأساسي ومفتاح API مع مشروعك، وتستخدم الأمثلة $PV_API_URL و$PV_API_KEY. أرسل المفتاح كرمز Bearer. الطلبات التي لا تحمل مفتاحاً صالحاً تُعيد 401.

Authorization: Bearer $PV_API_KEY

تقتصر صلاحيات المفاتيح على مؤسستك والأذونات المتفق عليها لمشروعك. أبقِها خارج نظام إدارة الشيفرة المصدرية وخارج الشيفرة التي تعمل في المتصفح، ويمكنك أن تطلب منا تدوير أي مفتاح في أي وقت.

تُعيد الوكلاء الذين تشغّلهم بي في لمؤسستك مع حالتهم (active أو paused). يبني فريقنا الوكلاء ويهيّئهم، لذلك لا توجد نقاط نهاية لإنشائهم أو حذفهم. تواصل معنا لطلب وكيل جديد أو تعديل.

{
  "data": [
    {
      "id": "agt_123",
      "name": "invoice-processor",
      "description": "Reads supplier invoices and files them in the ERP.",
      "status": "active"
    }
  ],
  "next_cursor": null
}

تمر المهمة بالحالات queued وrunning وawaiting_approval، وتنتهي بإحدى الحالات succeeded أو failed أو cancelled. عند انتهائها يحمل الحقل output النتيجة. ولتجنّب الاستعلام المتكرر، استخدم Webhooks.

{
  "id": "tsk_456",
  "status": "succeeded",
  "output": "Filed 42 invoices. 3 need review.",
  "started_at": "2026-10-04T09:01:02Z",
  "finished_at": "2026-10-04T09:04:40Z"
}

توقف مهمة في قائمة الانتظار أو قيد التنفيذ أو بانتظار موافقة. تُعيد المهمة بالحالة cancelled.

الخطوات التي حدّدتها على أنها حساسة، مثل دفعة مالية أو رسالة إلى عميل، توقف المهمة مؤقتاً وتُنشئ طلب موافقة. يمكنك الموافقة عليه أو رفضه من هنا، أو من منصة بي في، أو من أدواتك الخاصة عبر حدث Webhook approval.requested.

كل إجراء يتخذه الوكيل: ماذا فعل، ومتى، وفي أي نظام.

زوّدنا بنقطة نهاية HTTPS واختر الأحداث التي تريدها. نرسل طلب POST بجسم JSON لكل حدث.

{
  "id": "evt_789",
  "type": "task.succeeded",
  "created_at": "2026-10-04T09:04:40Z",
  "data": {
    "task_id": "tsk_456",
    "agent_id": "agt_123",
    "output": "Filed 42 invoices. 3 need review.",
    "metadata": { "batch": "2026-10-04" }
  }
}

تحقّق من كل طلب. يحمل كل طلب الترويسة PV-Signature، وهي قيمة HMAC-SHA256 للجسم الخام محسوبة باستخدام سر Webhook الخاص بك. قارنها قبل الوثوق بالحمولة.

import crypto from "node:crypto";

function isFromPV(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

ردّ بأي رمز 2xx خلال 10 ثوانٍ. يُعاد إرسال الطلبات التي فشل تسليمها بفواصل زمنية متزايدة لمدة تصل إلى 24 ساعة. استخدم id الخاص بالحدث لتجاهل التكرارات.

بروتوكول Model Context Protocol (MCP) معيار مفتوح لربط تطبيقات الذكاء الاصطناعي بالأدوات والبيانات. وتدعمه بي في في الاتجاهين.

استخدم وكلاء بي في من مساعد الذكاء الاصطناعي لديك. أضف خادم بي في MCP إلى أي مساعد متوافق مع MCP يستخدمه فريقك، ليتمكن من بدء المهام ومتابعة نتائجها نيابةً عنك.

URL:            $PV_API_URL/mcp
Transport:      Streamable HTTP
Authorization:  Bearer $PV_API_KEY

دع وكلاءك يستخدمون خوادم MCP الخاصة بك. إذا كانت لدى أنظمتك خوادم MCP بالفعل، نربط وكلاءك بها، بصلاحية القراءة فقط ما لم توافق على أكثر من ذلك. وإن لم تكن لديها، يمكننا بناء خادم لها.

تقبل نقاط النهاية التي تُعيد قوائم المعاملين limit (من 1 إلى 100، والافتراضي 20) وcursor. مرّر قيمة next_cursor من الاستجابة لجلب الصفحة التالية، وتكون قيمتها null في الصفحة الأخيرة.

تستخدم الأخطاء رموز حالة HTTP القياسية وجسماً موحّد البنية:

{
  "error": {
    "code": "not_found",
    "message": "No task with id tsk_999."
  }
}