أدوات MCP

الشركات المصنعة

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

الشركة المصنعة مدخل في دليل مؤسستك للجهات التي تصنع ما تبيعه. يحمل بيانات التواصل والبلد وفترة سريان خطاب التفويض، ويرتبط بمنتجات الكتالوج، وتبنى عليه تحليلات الأسعار وخطابات التفويض. والدليل لمؤسستك كلها: ما يضيفه زميلك تراه أنت.

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

الأداة	ما تفعله
manufacturers_list	عرض الشركات المصنعة
manufacturers_get	عرض شركة مصنعة
manufacturers_export_csv	تصدير دليل الشركات المصنعة
manufacturers_create	إضافة شركة مصنعة
manufacturers_update	تعديل شركة مصنعة
manufacturers_delete	حذف شركة مصنعة
manufacturers_bulk_update	تعديل عدة شركات مصنعة
manufacturer_intel_get	عرض تحليلات توريد شركة
manufacturer_intel_generate	كتابة ملخص ذكي لشركة
manufacturer_letter_pdf	إنشاء خطاب تفويض

قراءة الدليل

البحث في الدليل وقراءة شركة واحدة وتصدير الدليل كله.

manufacturers_list

يعرض شركات دليل مؤسستك مرتبة أبجديا، لكل شركة عدد منتجات الكتالوج المرتبطة بها. ويبحث بكلمة عادية أو بصيغة منظمة بحقول الدليل في q.

للقراءة فقط · الصلاحية manufacturers.read · كل الأدوار · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`page`	`integer`	لا	رقم الصفحة، ويبدأ من 1.
`page_size`	`integer`	لا	عدد النتائج في الصفحة: 20 افتراضيا، وحده الأقصى 100.
`q`	`string`	لا	نص البحث. الكلمة العادية تبحث في الاسم وجهة الاتصال والبريد والبلد. وللدقة استخدم الحقول `name:` و`country:` (اسم البلد بالعربية أو الإنجليزية أو رمزه) و`contact:` و`email:` و`phone:` و`website:`، مع `AND` و`OR` والأقواس و`-` قبل الشرط لاستبعاده، مثل `country:germany -name:acme`. والكلمة العادية لا تبحث في الهاتف والموقع، فاستخدم حقليهما.

{
  "q": "country:germany -name:acme",
  "page": 1,
  "page_size": 20
}

مثال على المعاملات

ما يعيده: صفحة من الشركات، لكل شركة حقولها وproduct_count بعدد منتجاتها القائمة، مع total وpage وpage_size وtotal_pages.

بحث لا يستطيع المحلل قراءته يرد بـ400 مع سبب الخطأ.

manufacturers_get

يعرض شركة واحدة بكل حقولها وعدد منتجات الكتالوج المرتبطة بها.

للقراءة فقط · الصلاحية manufacturers.read · كل الأدوار · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الشركة، ويأتي من manufacturers_list.

ما يعيده: الشركة بحقولها، ومنها contact_person وcountry_code وauthorization_start_date وauthorization_end_date وagency_type، مع product_count.

يرد بـ404 إن لم توجد الشركة في دليل مؤسستك.

manufacturers_export_csv

يصدر دليل الشركات كاملا نص CSV، كل الصفوف لا صفحة واحدة، مع عدد منتجات كل شركة. ويقتصر على المالك والمدير.

للقراءة فقط · الصلاحية export · الأدوار: المالك، المدير · الخطة الاحترافية وخطة المؤسسات

لا معاملات.

ما يعيده: نص CSV بترميز UTF-8 مع علامة BOM، وأعمدته: ID وName وContact person وCountry وEmail وPhone وWebsite وAddress وNotes وAgency type وAuthorization start وAuthorization end وProducts وCreated at.

البلد يصدر برمزه من حرفين، والقيمة الناقصة خلية فارغة، وعمود Products بعدد المنتجات القائمة. ولا تصدر روابط المرفقات لأنها تنتهي بسرعة.
أسماء الأعمدة هي أسماء حقول استيراد الجداول، فيعود الملف إلى sheet_import بالهدف manufacturers. والاستيراد لا ينشئ إلا الشركات التي لا يوجد اسمها في الدليل.
نسخة Excel من التصدير نفسه متاحة لمن يستخدم واجهة REST. راجع واجهة البرمجة.

الإضافة والتعديل والحذف

أربع أدوات لتحرير الدليل، وكلها لأدوار المالك والمدير والمبيعات والمشتريات.

manufacturers_create

يضيف شركة إلى دليل مؤسستك، وله أن يربط بها منتجات موجودة في الكتالوج أو ينشئ منتجات جديدة تحتها في الاستدعاء نفسه. الاسم فريد، فاسم موجود يرد بتعارض.

يغير البيانات · الصلاحية manufacturers.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`name`	`string`	نعم	اسم الشركة، من حرف واحد إلى 200 حرف. الاسم فريد في المؤسسة: اسم موجود في الدليل يرد بـ409 مع `manufacturer_exists`.
`contact_person`	`string`	لا	اسم جهة الاتصال، حتى 200 حرف.
`email`	`string`	لا	البريد الإلكتروني للتواصل. يجب أن يكون عنوانا صحيحا، وحده 320 حرفا.
`phone`	`string`	لا	هاتف التواصل، حتى 50 حرفا.
`website`	`string`	لا	موقع الشركة، حتى 500 حرف.
`address`	`string`	لا	العنوان البريدي، حتى 500 حرف.
`country_code`	`string`	لا	رمز البلد من حرفين كبيرين (ISO 3166-1) مثل `SA` أو `DE`. والحرف الصغير يرفض.
`notes`	`string`	لا	ملاحظات داخلية حرة، حتى 2000 حرف.
`authorization_start_date`	`string`	لا	تاريخ بداية سريان خطاب تفويض الشركة بصيغة `YYYY-MM-DD`. أما الخطاب الموقع نفسه فيرفع مرفقا بفئة `authorization` عبر manufacturer_attachment_upload_url_create، ويرافق كل منتج مرتبط بالشركة في حزمة التقديم.
`authorization_end_date`	`string`	لا	تاريخ نهاية السريان بصيغة `YYYY-MM-DD`. يجب ألا يسبق تاريخ البداية حين يرسلان معا، وإلا رد الاستدعاء بـ400. وترك النهاية فارغة يعني تفويضا مفتوحا.
`agency_type`	`string`	لا	نوع الوكالة كما تذكره الشركة في بوابات الجهات، مثل `Distribution as authorized`، حتى 200 حرف. ويطبع في ملف معلومات مستند المنتج.
`product_ids`	`integer[]`	لا	معرفات منتجات موجودة في الكتالوج لتربط بالشركة، حتى 500. يجب أن تكون كلها منتجات قائمة في مؤسستك، وإلا رد الاستدعاء بـ400 مع `product_not_found` ولم ينشأ شيء.
`new_products`	`object[]`	لا	منتجات جديدة تنشأ وتربط بالشركة في الاستدعاء نفسه، حتى 500، بالحقول الأساسية أدناه فقط. وللشكل الكامل للمنتج (MDMA والتعبئة والتسليم) أنشئها بـproducts_bulk_create مع `manufacturer_names`.
`new_products[].product_name`	`string`	نعم	اسم المنتج، من حرف واحد إلى 200 حرف.
`new_products[].nupco_product_code`	`string`	لا	كود نوبكو للمنتج، حتى 100 حرف.
`new_products[].catalogue_number`	`string`	لا	رقم الكتالوج، حتى 100 حرف.
`new_products[].cost_price`	`number`	لا	سعر التكلفة بعملة `cost_currency`، من 0 إلى 9999999.99.
`new_products[].cost_currency`	`string`	لا	عملة سعر التكلفة: `USD` أو `SAR`. الافتراضي `USD`.
`new_products[].sale_price_sar`	`number`	لا	سعر البيع بالريال السعودي، من 0 إلى 9999999.99.
`new_products[].units_per_case`	`integer`	لا	عدد الوحدات في الكرتونة، عدد صحيح موجب حتى 1000000.
`new_products[].is_medical`	`boolean`	لا	`true` إن كان المنتج طبيا.

{
  "name": "Medline Europe GmbH",
  "contact_person": "Anna Keller",
  "email": "export@medline-europe.example",
  "country_code": "DE",
  "authorization_start_date": "2026-01-01",
  "authorization_end_date": "2027-12-31",
  "agency_type": "Distribution as authorized",
  "new_products": [
    {
      "product_name": "Syringe 5 ml with needle, sterile",
      "nupco_product_code": "4111610529900",
      "cost_price": 0.34,
      "cost_currency": "USD",
      "units_per_case": 1000
    }
  ]
}

مثال على المعاملات

ما يعيده: الشركة الجديدة بحقولها، مع product_count وlinked_count (المنتجات الموجودة التي جرى ربطها) وcreated_count (المنتجات الجديدة) وcreated_products وفيه index وid لكل منتج جديد بترتيب إرساله.

يتحقق الاستدعاء من المنتجات ومن حد خطتك قبل أن ينشئ الشركة. يرد بـ400 مع product_not_found لمعرف غير قائم، وبـ402 إن كانت المنتجات الجديدة ستتجاوز حد المنتجات في خطتك.
دور المبيعات لا يرى أسعار التكلفة، فتسقط الحقلان cost_price وcost_currency من المنتجات الجديدة بصمت، ويبقى sale_price_sar.

manufacturers_update

يعدل شركة في الدليل. لا يتغير إلا ما ترسله، وnull يمسح حقلا اختياريا. وللتعديل الجماعي لحقول التواصل استخدم manufacturers_bulk_update.

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الشركة، ويأتي من manufacturers_list.
`name`	`string`	لا	الاسم الجديد، من حرف واحد إلى 200 حرف. الاسم فريد في المؤسسة: اسم موجود في الدليل يرد بـ409 مع `manufacturer_exists`.
`contact_person`	`string`	لا	اسم جهة الاتصال، حتى 200 حرف. أرسل `null` لمسحه.
`email`	`string`	لا	البريد الإلكتروني للتواصل. يجب أن يكون عنوانا صحيحا، وحده 320 حرفا. أرسل `null` لمسحه.
`phone`	`string`	لا	هاتف التواصل، حتى 50 حرفا. أرسل `null` لمسحه.
`website`	`string`	لا	موقع الشركة، حتى 500 حرف. أرسل `null` لمسحه.
`address`	`string`	لا	العنوان البريدي، حتى 500 حرف. أرسل `null` لمسحه.
`country_code`	`string`	لا	رمز البلد من حرفين كبيرين (ISO 3166-1) مثل `SA` أو `DE`. والحرف الصغير يرفض. أرسل `null` لمسحه.
`notes`	`string`	لا	ملاحظات داخلية حرة، حتى 2000 حرف. أرسل `null` لمسحه.
`authorization_start_date`	`string`	لا	تاريخ بداية سريان خطاب تفويض الشركة بصيغة `YYYY-MM-DD`. أما الخطاب الموقع نفسه فيرفع مرفقا بفئة `authorization` عبر manufacturer_attachment_upload_url_create، ويرافق كل منتج مرتبط بالشركة في حزمة التقديم. أرسل `null` لمسحه.
`authorization_end_date`	`string`	لا	تاريخ نهاية السريان بصيغة `YYYY-MM-DD`. يجب ألا يسبق تاريخ البداية حين يرسلان معا، وإلا رد الاستدعاء بـ400. وترك النهاية فارغة يعني تفويضا مفتوحا. أرسل `null` لمسحه.
`agency_type`	`string`	لا	نوع الوكالة كما تذكره الشركة في بوابات الجهات، مثل `Distribution as authorized`، حتى 200 حرف. ويطبع في ملف معلومات مستند المنتج. أرسل `null` لمسحه.

{
  "id": 118,
  "phone": "+49 40 5550 1234",
  "authorization_end_date": "2028-12-31"
}

مثال على المعاملات

ما يعيده: الشركة بعد التعديل.

يرد بـ400 إن لم يحمل الطلب أي حقل، وبـ409 مع manufacturer_exists إن صار الاسم اسم شركة أخرى.
يرد بـ404 إن لم توجد الشركة في دليل مؤسستك.

manufacturers_delete

يحذف شركة من الدليل نهائيا. تزول روابطها بالمنتجات وتمحى ملفاتها المرفوعة، وتبقى المنتجات نفسها في الكتالوج. لا رجوع عنه، ولا مهملات للشركات.

يحذف بيانات أو يستبدلها · الصلاحية manufacturers.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الشركة، ويأتي من manufacturers_list.

ما يعيده: تأكيد الحذف success: true.

يرد بـ404 إن لم توجد الشركة في دليل مؤسستك.

manufacturers_bulk_update

يعدل حتى 200 شركة في معاملة واحدة: تنجح كلها أو لا ينجح شيء. كل صف يستبدل حقول التواصل الثمانية بالكامل، فاقرأ القيم الحالية أولا وأرسل كل حقل، وnull يمسح قيمة.

المعامل	النوع	مطلوب	الوصف
`updates`	`object[]`	نعم	صفوف الشركات المراد تعديلها، من 1 إلى 200.
`updates[].id`	`integer`	نعم	معرف الشركة.
`updates[].name`	`string`	نعم	اسم الشركة، من حرف واحد إلى 200 حرف.
`updates[].contact_person`	`string`	نعم	جهة الاتصال، حتى 200 حرف. أرسل `null` لمسحها.
`updates[].country_code`	`string`	نعم	رمز البلد من حرفين كبيرين مثل `SA`. أرسل `null` لمسحه.
`updates[].email`	`string`	نعم	البريد الإلكتروني، عنوان صحيح حتى 320 حرفا. أرسل `null` لمسحه.
`updates[].phone`	`string`	نعم	الهاتف، حتى 50 حرفا. أرسل `null` لمسحه.
`updates[].website`	`string`	نعم	الموقع، حتى 500 حرف. أرسل `null` لمسحه.
`updates[].address`	`string`	نعم	العنوان، حتى 500 حرف. أرسل `null` لمسحه.

{
  "updates": [
    {
      "id": 118,
      "name": "Medline Europe GmbH",
      "contact_person": "Anna Keller",
      "country_code": "DE",
      "email": "export@medline-europe.example",
      "phone": "+49 40 5550 1234",
      "website": "https://medline-europe.example",
      "address": null
    },
    {
      "id": 121,
      "name": "Hartmann Medical AG",
      "contact_person": null,
      "country_code": "DE",
      "email": null,
      "phone": null,
      "website": null,
      "address": null
    }
  ]
}

مثال على المعاملات

ما يعيده: عدد الشركات المعدلة في updated.

الملاحظات وتواريخ التفويض ونوع الوكالة ليست من حقول هذه الأداة ولا تمس أبدا. لتعديلها استخدم manufacturers_update.
معرف غير موجود في مؤسستك يرفض الدفعة كلها بـ400 مع manufacturer_not_found، واسم يطابق شركة أخرى يرفضها بـ409 مع manufacturer_exists. وفي الحالتين لا يتغير شيء.

تحليلات التوريد

تحليلات أسعار شركة مصنعة محسوبة من عروضها المسجلة في مؤسستك وحدها. ولأنها بيانات تكلفة فهي للخطة الاحترافية وخطة المؤسسات ولأدوار المالك والمدير والمشتريات والمشاهد.

manufacturer_intel_get

يعرض كيف تحركت أسعار شركة مصنعة، محسوبة من سطور الأسعار التي عرضتها على طلبات التسعير وأسعار التوريد المسجلة في مؤسستك: سلسلة أسعار كل منتج، ونسبة التغير بين أول عرض وآخره، والمنتجات التي عرضت بأسعار مختلفة. ويعيد ملخص الذكاء الاصطناعي المحفوظ إن وجد، ولا يكتب ملخصا جديدا: ذلك عمل manufacturer_intel_generate.

للقراءة فقط · الصلاحية manufacturers.read · الأدوار: المالك، المدير، المشتريات، المشاهد · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الشركة، ويأتي من manufacturers_list.

ما يعيده: facts: lineCount وresponseCount وproductCount وfirstQuoteAt وlastQuoteAt وmedianPctChange، وقائمة products (لكل منتج label وseries بأسعاره المؤرخة وfirstUsd وlastUsd وminUsd وmaxUsd وpctChange وtrend وspreadPctMaxOverMin)، وقائمتا topIncreases وtopSpreads. وai: الملخص المحفوظ (headline_en وheadline_ar وbody_en وbody_ar وmodel وgenerated_at) أو null. وai_stale.

كل الأسعار بالدولار. وpctChange يقارن آخر عرض بأول عرض، وقيمته null لمنتج له أقل من عرضين، ومعناها لا اتجاه لا صفر. وtrend هو flat ضمن 2% وإلا up أو down. وspreadPctMaxOverMin الفرق بين أعلى سعر وأقله نسبة إلى الأقل، وnull ما لم يوجد سعران مختلفان.
تحتسب فقط العروض المنسوبة إلى هذه الشركة في دليلك، لا العروض المسجلة باسم مورد حر. وشركة بلا عروض تعيد حقائق أصفارا.
ai_stale: true يعني أن بيانات العروض تغيرت منذ كتابة الملخص.
يرد بـ404 إن لم توجد الشركة في دليل مؤسستك.

manufacturer_intel_generate

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

يغير البيانات · الصلاحية manufacturers.write · الأدوار: المالك، المدير، المشتريات · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الشركة، ويأتي من manufacturers_list.

ما يعيده: ai بالملخص (headline_en وheadline_ar وbody_en وbody_ar وmodel وgenerated_at) مع ai_stale: false. وبدل ذلك: ai: null مع no_data: true (لا عروض مسعرة تروى) أو disabled: true (الميزة متوقفة)، أو الرمز 202 مع status: "generating" إن كان طلب آخر يكتبه الآن.

عند الرد بالرمز 202 اطلب manufacturer_intel_get بعد قليل لتقرأ الملخص.
بعد محاولة فاشلة يرد الاستدعاء بـ503 مع رسالة ولا يعيد المحاولة قبل مرور عشر دقائق.
يكتب الملخص من الأرقام المجمعة للأسعار وحدها، لا من بيانات التواصل ولا من الملاحظات.
يرد بـ404 إن لم توجد الشركة في دليل مؤسستك.

خطابات التفويض

خطاب تفويض جاهز للطباعة، تصدره الشركة المصنعة لصالح مؤسستك.

manufacturer_letter_pdf

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

للقراءة فقط · الصلاحية manufacturers.write · الأدوار: المالك، المدير، المبيعات، المشتريات · الخطة الاحترافية وخطة المؤسسات

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف الشركة، ويأتي من manufacturers_list.
`letter_type`	`string`	نعم	نوع الخطاب: `new_relation` (خطاب تفويض: يفوض مؤسستك موزعا دون ادعاء حصرية، ويشهد بأن الشركة ستورد كل البنود المسعرة) أو `change_agency` (إفادة بتغيير الوكالة: تحل مؤسستك محل وكيل سابق، ويلزمه `previous_agency_name`) أو `exclusive_distribution` (إعلان توزيع حصري: النوع الوحيد الذي يدعي الحصرية).
`territory`	`string`	لا	المنطقة التي يغطيها الخطاب، حتى 200 حرف. الافتراضي `Saudi Arabia`.
`recipient`	`string`	لا	الجهة التي يوجه إليها الخطاب، حتى 300 حرف. الافتراضي نوبكو (الشركة الوطنية للشراء الموحد).
`previous_agency_name`	`string`	لا	اسم الوكالة السابقة التي تستبدلها مؤسستك، حتى 300 حرف. مطلوب مع `change_agency`، وبدونه يرد الاستدعاء بـ400.
`tender_number`	`string`	لا	رقم المنافسة التي يصدر لها الخطاب، حتى 100 حرف. يطبع في رأس الخطاب، وفي `new_relation` يحصر التفويض بالبنود المسعرة تحت تلك المنافسة.
`notes`	`string`	لا	جملة إضافية تلحق بنص الخطاب، حتى 1000 حرف.

{
  "id": 118,
  "letter_type": "new_relation",
  "tender_number": "NPT0042/26"
}

مثال على المعاملات

ما يعيده: ملف PDF: filename وcontent_type وsize_bytes والمحتوى بترميز base64 في base64.

عنوان الشركة المصنعة لا يطبع في الخطاب: يترك له سطر فارغ يكتبه الموقع.
الأداة لا تغير شيئا، لكنها تحتاج الصلاحية manufacturers.write وأدوار التحرير نفسها، كالشاشة التي تنشئ الخطاب.
يرد بـ404 إن لم توجد الشركة في دليل مؤسستك.