ما هو
Wonder Fatoora MCP خادم بعيد لبروتوكول سياق النماذج (MCP)، المعيار المفتوح الذي تستخدمه المساعدات الذكية وأطر الوكلاء لاستدعاء الأدوات. يستطيع الوكيل المرتبط بمنشأة استخدام هذه الأدوات:
| الأداة | الصلاحية | ما تفعله |
|---|---|---|
get_company_profile، get_integration_status |
companies:read |
قراءة ملف المنشأة ومدى جاهزيتها للإصدار. |
search_customers، get_customer |
customers:read |
البحث عن العملاء. |
search_products، get_product |
products:read |
البحث عن المنتجات والخدمات مع أسعارها ونسب ضريبتها. |
list_invoices، get_invoice، get_invoice_status، list_invoice_notes، get_note، list_invoice_payments |
invoices:read |
قراءة الفواتير والإشعارات الدائنة والمدينة وحالتها لدى الهيئة والدفعات المسجّلة عليها. |
get_document_download_link |
invoices:download |
رابط PDF صالح لخمس دقائق، لا الملف نفسه. |
create_customer، update_customer |
customers:write |
إدارة العملاء. |
create_product، update_product |
products:write |
إدارة المنتجات والخدمات. |
create_invoice_draft، validate_invoice_draft، create_note_draft |
invoices:draft |
تجهيز المسودات والتحقق من إمكان إصدارها. التجهيز لا يصدر أبدًا. |
record_payment |
payments:write وinvoices:read |
تسجيل دفعة من العميل على فاتورة صادرة، بما لا يتجاوز المتبقي عليها. |
list_projects (companies:read)، get_project_summary (invoices:read)، set_invoice_project (invoices:draft) |
حسب كل أداة | قراءة المشاريع وأرقام كل مشروع من مبيعات وتكاليف وربح، وربط فاتورة بمشروع. المشروع وسم داخلي لا يغيّر شيئاً في الفاتورة ولا فيما يصل إلى الهيئة. |
issue_invoice، issue_note، create_credit_note، create_debit_note |
invoices:issue |
لا رجعة فيها. معطلة افتراضيًا، وكل استدعاء ينتظر موافقة شخص. |
تحتاج كل أداة أيضًا صلاحية الشخص الذي ربط التطبيق، كما في الواجهة البرمجية REST، وتجيب بالحقول نفسها. وتقبل أدوات الكتابة client_request_id: إعادة المحاولة بالمعرّف نفسه تعيد الإجابة الأولى بدل تنفيذ العمل مرتين.
الواجهة البرمجية أم MCP؟
| الواجهة البرمجية REST | MCP | |
|---|---|---|
| من يستدعيها | برنامجك أنت: متجر أو نظام حجوزات أو خادم منصة SaaS | مساعد ذكاء اصطناعي أو إطار وكلاء يتحدث بروتوكول Model Context Protocol |
| طريقة الدخول | مفتاح API لمنشأة واحدة، أو ربط OAuth | ربط OAuth وافق عليه مدير المنشأة، أو مفتاح API أُنشئ لوكلاء الذكاء الاصطناعي |
| ما يستطيعه | كل ما تسمح به صلاحياته، ومنه الإصدار بصلاحية invoices:issue |
قراءة البيانات وتجهيز المسودات؛ أدوات الإصدار تعمل فقط على ربط OAuth فعّلها فيه مدير المنشأة، ولا تعمل بمفتاح API أبدًا |
| إصدار الفاتورة | فوري إن كان المفتاح يحمل invoices:issue |
ينتظر موافقة شخص على ذلك المستند بعينه داخل وندرفاتورة |
| الأنسب لـ | الفوترة الآلية بكميات كبيرة | المساعدات التي تعين الشخص على تجهيز الفواتير وفحصها والبحث عنها |
كلاهما يصل إلى بيانات المنشأة نفسها بالصلاحيات نفسها، والفاتورة الصادرة بأي منهما تُرقَّم وتُوقَّع وتُرسل إلى الهيئة بالطريقة نفسها تمامًا. واستدعاء أداة MCP لا يُصدر بمفرده فاتورة ضريبية نهائية أبدًا.
الاتصال
- نقطة النهاية:
POST https://fatoora.tw.sa/mcpعبر Streamable HTTP بإجابات JSON. ويجيبGETوDELETEبـ405: لا يوجد بث أحداث ولا جلسة. - إصدارات البروتوكول:
2026-07-28(أرسلMCP-Protocol-Version، و_metaفيه الإصدار وقدرات العميل، وMcp-MethodوMcp-Name)، و2025-11-25و2025-06-18(ابدأ بـinitialize؛ لا يُصدر معرّف جلسة). - التفويض: OAuth 2.1 مع PKCE. سجّل عميلك من الإعدادات ← المطورون ← تطبيقاتي واطلب
resource=https://fatoora.tw.sa/mcp. بيانات الخادم الوصفية على/.well-known/oauth-protected-resource/mcp. دون رمز يجيب الخادم بـ401معWWW-Authenticateيشير إلى ذلك المستند، ونقص الصلاحية يجيب بـ403 insufficient_scope. - العملاء الذين يسجّلون أنفسهم (RFC 7591) مثل موصلات مساعدات الذكاء الاصطناعي: عند تفعيل التسجيل الذاتي تذكر بيانات خادم التفويض الوصفية
registration_endpoint(POST /oauth/register). التطبيق المسجّل ذاتيًا لا تقف خلفه منشأة: يربط المنشآت الحقيقية فقط، وبعدد محدود منها، وبعد أن يسمح له من يدير المنشأة في شاشة الموافقة التي توضح أن التطبيق سجّل نفسه. - الرمز الصادر للواجهة البرمجية REST مرفوض هنا، ورمز MCP مرفوض في الواجهة البرمجية REST. ولا يعمل مفتاح API إلا إذا أُنشئ مع السماح باستخدامه من وكلاء الذكاء الاصطناعي (MCP)، للعملاء الذين لا يرسلون إلا ترويسة ثابتة. والمفتاح المنتهي يجيب بـ
401معerror.data.codeبقيمةtoken_expiredوerror.data.renew_url. - يجب أن تأتي عملاء المتصفح من مصدر مسموح: يُرفض أي طلب يحمل
Originآخر.
كيف تعمل الموافقة
- يفعّل مدير المنشأة أداة إصدار لتطبيقك من الإعدادات ← المطورون ← التطبيقات المرتبطة. وحتى ذلك الحين تجيب الأداة بـ
tool_disabled. - يستدعيها الوكيل، فتتحقق وندرفاتورة من المسودة وتسجل موافقة معلقة مرتبطة بتلك المنشأة والربط والشخص والمستند كما هو محفوظ. لا يصدر شيء: الإجابة
approval_requiredمع رابط وconfirmation_id. والعميل بإصدار2026-07-28الذي يدعم الطلب عبر رابط يتلقى الرابط بتلك الطريقة. - يفتح الشخص الذي يعمل التطبيق باسمه الرابط، ويؤكد كلمة مروره، ويرى المستند كما تحفظه وندرفاتورة، فيوافق أو يرفض. وتظهر الطلبات المنتظرة أيضًا في الإعدادات ← المطورون ← الموافقات.
- يستدعي الوكيل الأداة نفسها بالمعاملات نفسها مع
confirmation_id، فتُنفذ مرة واحدة، خلال 15 دقيقة، وبشرط ألا يكون المستند قد تغير منذ الموافقة.
نموذج الأمان
- لا شيء يرسله الوكيل يُعد موافقة. لا توجد أداة موافقة ولا معامل يوافق؛ لا يوافق إلا شخص مسجل الدخول داخل وندرفاتورة.
- منشأة واحدة لكل ربط. المنشأة تأتي من الربط، لا من معاملات الأدوات أبدًا.
- سجلاتك بيانات. النصوص داخل الفواتير وسجلات العملاء تُعاد بيانات ولا تُعامل أبدًا كتعليمات.
- لا تمرير للرموز. رمز الوكيل لا تستخدمه إلا وندرفاتورة، ولا يُمرر إلى أي جهة أخرى.
- مسجّل ومحدود. يُسجّل كل استدعاء باسم الأداة دون معاملاتها، ويُحد معدله لكل ربط.
- نتائج بيئة الاختبار موسومة. في منشأة الاختبار تحمل كل نتيجة
SANDBOX؛ ولا شيء هناك فاتورة ضريبية.
وندرفاتورة منتج مستقل، لا يتبع هيئة الزكاة والضريبة والجمارك ولا أي مزود لخدمات الذكاء الاصطناعي.
صفحات ذات صلة
جاهز للبدء؟
الوصول إلى الواجهة البرمجية ضمن باقات: الأعمال والمؤسسات. أنشئ مفتاحًا من الإعدادات ← مفاتيح API وأرسل أول طلب خلال دقائق.