المنتجات

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

لكل منتج سعر تكلفة واحد وسعر بيع واحد، ولكل منهما مستوى. يقول price_basis إن كان السعران للوحدة (unit) أو للعبوة (pack) أو للكرتون (case) أو لوحدة واحدة مما تحتويه الوحدة (content، كسعر الفحص الواحد). ومن هذا السعر الواحد يحسب التسعير من الكتالوج والتسعير بالهامش سعر كل بند بوحدة المنافسة: 150 ريالا للكرتون الذي فيه 1000 قفاز تصير 15 للعلبة التي فيها 100، و0.15 للقفاز. وإن لم يحدد المستوى استخدم السعر كما هو في كل بند، كما كان قبل هذه الحقول. فأرسل price_basis مع كل سعر، ولا تقسم السعر بنفسك.

قراءة الكتالوج

ثلاث أدوات للقراءة: قائمة بحث ترشح المنتجات، وبطاقة منتج واحد بتفاصيلها، وتصدير للكتالوج كاملا.

products_list

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

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

{
  "q": "manufacturer:acme -gauze",
  "include_manufacturers": true,
  "page_size": 50
}

ما يعيده: صفحة من المنتجات في data مع total وpage وpage_size وtotal_pages. يحمل كل منتج حقول سجله ومعها photo_urls، وهي روابط صوره.

• مع group_by تأتي groups بدل data. لكل مجموعة nupco_code (وقيمته null للمنتجات التي لا رمز لها) وproduct_count وoffset وproducts، ويحمل كل منتج فيها nupco_codes، أي كل رموزه. ويضاف إلى الرد total وهو عدد المنتجات المطابقة، وtotal_codes وproducts_without_code وtotal_rows. تعد الصفحات الصفوف لا المجموعات، فقد تكمل المجموعة في الصفحة التالية، وحينها يكون offset أكبر من صفر.
• روابط الصور مؤقتة، فاطلبها عند الحاجة ولا تحفظها.
• تحذف حقول الأسعار من النتائج بحسب دورك (انظر مقدمة الصفحة).

products_get

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

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

ما يعيده: سجل المنتج، ومعه photo_urls وattachments. لكل مرفق category (إحدى القيم sfda_cert وcatalog وother) وname وsize وuploaded_at وurl.

• ترد الأداة بخطأ 404 إن لم يوجد المنتج أو كان في المهملات. ولتجد منتجا في المهملات استخدم `products_trash_list`.
• روابط الصور والمرفقات مؤقتة، فاطلبها عند الحاجة ولا تحفظها.

products_similar

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

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

{
  "id": 42
}

ما يعيده: codes، وهي رموز المنتج نفسه والرئيسي أولها، وproducts مرتبة بعدد الرموز المشتركة. لكل منتج حقول سجله وshared_codes وnupco_codes وphoto_urls وmanufacturers.

• تقارن الرموز بعد حذف المسافات الزائدة وتوحيد كتابتها، فالرمز المكتوب كما يخرج من Excel يطابق أصله.
• تحذف حقول الأسعار من النتائج بحسب دورك (انظر مقدمة الصفحة).

catalog_files_list

يبحث في مكتبة مستندات مؤسستك في قائمة واحدة: صور المنتجات ومرفقاتها (شهادة الهيئة العامة للغذاء والدواء، الكتالوج، غير ذلك) ومرفقات الشركات المصنعة (الكتالوج، ترخيص SFDA AR، شهادة ISO، خطاب التفويض) ومستندات أوامر البيع (أمر شراء العميل). وهي صفحة مكتبة المستندات في التطبيق.

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

{
  "q": "syringe cert",
  "scope": "products",
  "page_size": 20
}

ما يعيده: صفحة من الملفات في data مع total وpage وpage_size وtotal_pages. لكل ملف owner_kind (product أو manufacturer أو sales_order) وowner_id وowner_name وnupco_code وcatalogue_number (وهو رقم أمر شراء العميل في أمر البيع) وcustomer_name وmanufacturer_names وcategory وname وsize وmime_type وuploaded_at وurl.

• لا تظهر ملفات الشركات المصنعة إلا إذا كان للمفتاح نطاق manufacturers.read أيضا، ولا تظهر مستندات أوامر البيع إلا إذا كان له نطاق orders.read وكان دور صاحبه يفتح مستندات أوامر البيع (كل الأدوار عدا الفني والمشتريات). وافتح صاحب الملف بـ `products_get` أو manufacturers_get أو `sales_orders_get`.
• الروابط مؤقتة وتنتهي بعد ساعة، فاطلبها عند الحاجة ولا تحفظها.

products_export_csv

يصدر كتالوج مؤسستك كاملا، كل الصفوف لا صفحة واحدة، نصا بصيغة CSV يقرؤه Claude في الرد نفسه. وهو للمالك والمدير فقط.

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

لا معاملات.

ما يعيده: نص CSV بترميز UTF-8 وعلامة BOM في أوله: صف للرؤوس ثم صف لكل منتج. وهو نص في الرد لا ملف.

• الرؤوس بالإنجليزية وتطابق ما يقرؤه `sheet_import`، فيمكنك تعديل الملف واستيراده من جديد.
• السعر غير المدخل يظهر خلية فارغة لا صفرا. وتفصل فاصلة منقوطة (;) بين الشركات المصنعة وبين الكلمات المفتاحية في الخلية الواحدة.
• لا تصدر روابط الصور لأنها مؤقتة.

products_import_template

ينزل قالب Excel لاستيراد المنتجات: ورقة Products بأعمدة الاستيراد الأساسية، وورقة تعليمات تشرح كل عمود ومثالا عليه وكل عمود آخر يقبله الاستيراد. سلمه لصاحب الكتالوج ليملأه.

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

{
  "locale": "ar"
}

ما يعيده: الملف بصيغة xlsx مرمزا بـbase64، مع اسمه ونوعه وحجمه.

• عناوين القالب هي عناوين الاستيراد نفسها، فالنسخة المملوءة التي تعطيها `sheet_import` بالهدف products تقرأ أعمدتها من عناوينها دون خطوة التعرف. ولا يضم القالب صف مثال، فالمثال المتروك في الورقة يستورد منتجا.
• أعمدة الأسعار التي لا يحق لدور صاحب المفتاح رؤيتها لا تظهر في القالب.

إضافة المنتجات وتعديلها

الإضافة والتعديل فرديان أو بالجملة. الأدوات الفردية تقبل كل حقول المنتج، والأدوات الجماعية تقبل مجموعة أصغر منها.

products_create

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

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

{
  "product_name": "Disposable syringe 5 ml, Luer lock",
  "nupco_product_code": "4111610529900",
  "catalogue_number": "SYR-5-LL",
  "keywords": [
    "syringe",
    "luer lock"
  ],
  "unit_of_measure": "Piece",
  "package_type": "Box",
  "package_size": 100,
  "units_per_case": 1000,
  "country_of_origin_code": "DE",
  "is_medical": true,
  "vat_percent": 0,
  "price_basis": "pack",
  "cost_price": 12,
  "cost_currency": "USD",
  "sale_price_sar": 55
}

ما يعيده: المنتج الذي أنشئ برد 201، بحقوله كاملة وid الجديد، وphoto_urls فارغة.

• عند بلوغ الحد يحمل رد 402 الحقول error: plan_limit_reached وlimit وcurrent.
• يتجاهل الخادم عند الكتابة الحقول التي لا يراها دورك، فلا تحفظ المبيعات حقلي cost_price وcost_currency.
• تعليم المنتج طبيا بهذه الأداة لا يغير vat_percent. اضبطها بنفسك: 0 للمنتجات الطبية المؤهلة للنسبة الصفرية.
• أرسل price_basis مع السعرين، ومعه عدد المستوى: price_basis: "case" مع units_per_case. والمستوى الذي ينقصه عدده يرفض بخطأ 400 (price_basis_level_missing) يسمي الحقل، وcontent_quantity بلا content_unit يرفض بخطأ 400 (content_incomplete).
• لاستيراد قائمة من ملف Excel أو CSV استخدم `sheet_import` بالهدف products.

products_update

يعدل حقول منتج، ولا يتغير إلا ما ترسله. أرسل null لمسح حقل يقبل الفراغ. ورمز نوبكو الجديد يضاف إلى روابط المنتج، وتبقى الروابط القديمة حتى تفكها بـ`product_nupco_unlink`.

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

{
  "id": 1207,
  "price_basis": "pack",
  "reprice": "convert",
  "package_size": 100
}

ما يعيده: المنتج بعد التعديل، مع photo_urls.

• ترد الأداة بخطأ 404 إن لم يوجد المنتج أو كان في المهملات.
• يرد الخادم بخطأ 400 (No fields to update) إن لم يحمل الطلب أي حقل يحق لدورك كتابته.
• إرسال nupco_product_code جديد يضيف رابطا ولا يزيل القديم، وإرسال null يمسح الحقل ويبقي الروابط كما هي.
• تعليم المنتج طبيا هنا لا يغير vat_percent: اضبطها بنفسك.
• تحديد price_basis في منتج لم يكن له مستوى لا يغير الأرقام: يقول فقط ما كانت تعنيه. والسعر الذي ترسله يؤخذ للمستوى كما يتركه الطلب نفسه. ولا يغير price_basis وreprice دور لا يرى سعر التكلفة (المبيعات)، فيتجاهلهما الخادم منه.
• ترفض الأداة بخطأ 400 دون أن تكتب شيئا، والرسالة تسمي الحقل والطريق الذي ينجح: price_basis_level_missing حين يخلو عدد المستوى المحدد (اضبط package_size أو units_per_case أو content_quantity في الطلب نفسه، أو اختر مستوى آخر)، وcontent_incomplete حين يرسل أحد content_quantity وcontent_unit دون الآخر، وreprice_required حين يتغير مستوى محدد أو يمسح وللمنتج سعر محفوظ لا ترسله (أرسل reprice أو السعرين الجديدين)، وconverted_price_out_of_range حين يتجاوز السعر بعد التحويل 9999999.99 (أرسل السعرين بنفسك أو reprice: "keep").

products_bulk_create

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

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

{
  "products": [
    {
      "product_name": "Disposable syringe 5 ml, Luer lock",
      "nupco_product_code": "4111610529900",
      "catalogue_number": "SYR-5-LL",
      "cost_price": 0.12,
      "cost_currency": "USD",
      "sale_price_sar": 0.55,
      "is_medical": true
    },
    {
      "product_name": "Surgical gloves, sterile, size 7.5",
      "catalogue_number": "GLV-S-75",
      "manufacturer_names": [
        "Acme Medical Supplies"
      ]
    }
  ],
  "manufacturer_id": 88
}

ما يعيده: رد 201 فيه created (لكل منتج index موضعه في قائمتك وid وproduct_name وnupco_product_code) وcreated_count، وmanufacturers_created وهي أسماء الشركات التي أضافتها الأداة إلى شركاتك. ويظهر manufacturer_links_failed: true فقط حين فشل الربط.

• تحفظ المنتجات أولا ثم تطبق روابط الشركات. فإن فشلت الروابط بقيت المنتجات وظهر manufacturer_links_failed. اربطها عندئذ بـ`product_manufacturer_bulk_link` ولا تكرر الاستدعاء، فتنشأ المنتجات مرتين.
• دفعة تتجاوز حد المنتجات في خطتك ترفض كلها بخطأ 402، وmanufacturer_id غير الموجود يرفض بخطأ 400 (manufacturer_not_found).
• يحمل الصف كل حقول نموذج المنتج. الكلمات المفتاحية وتصفية الجهة وحدهما تضبطان بعد ذلك بـ`products_update`.
• حقول التكلفة يتجاهلها الخادم لدور المبيعات.
• الصف الذي يحدد price_basis بلا عدده، أو يرسل نصف content_quantity وcontent_unit، يرفض الدفعة كلها بخطأ 400 قبل أي كتابة، ويسمي الحقل rows كل صف مرفوض بموضعه index والحقل والإصلاح.

products_bulk_update

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

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

{
  "updates": [
    {
      "id": 1207,
      "product_name": "Disposable syringe 5 ml, Luer lock",
      "catalogue_number": "SYR-5-LL",
      "nupco_product_code": "4111610529900",
      "cost_price": 0.12,
      "cost_currency": "USD",
      "sale_price_sar": 0.6,
      "units_per_case": 1000,
      "is_medical": true
    }
  ]
}

ما يعيده: عدد المنتجات المعدلة في updated.

• كل صف يستبدل الحقول التي يرسلها، وnull يمسح الحقل. ويبقى units_per_case وis_medical على قيمتيهما المخزنتين إن لم ترسلهما. ولتغيير حقل واحد دون غيره استخدم `products_update`.
• حقل لا يراه دورك يبقى على قيمته المخزنة مهما أرسلت، فتبقى تكلفة المنتج وعملتها كما هي حين تستدعي بدور المبيعات.
• المعرف المجهول أو الذي في المهملات يرفض الدفعة كلها بخطأ 400 (product_not_found).
• رمز نوبكو الجديد يضاف إلى روابط المنتج، وتبقى الروابط القديمة.
• الأسعار هنا بمستوى price_basis لكل منتج، ولا تغيره هذه الأداة (غيره بـ`products_update` مع reprice). والصف الذي يفرغ عددا يحتاجه مستوى محدد، كمسح units_per_case في منتج سعره للكرتون، يرفض الدفعة كلها بخطأ 400 (price_basis_level_missing) مع rows تسمي كل منتج.

المهملات

الحذف على خطوتين: نقل إلى المهملات ثم حذف نهائي. والمنتج الذي في المهملات يمكن استعادته ما دام لم يحذف نهائيا.

products_delete

ينقل منتجا إلى المهملات. يختفي من القوائم والروابط والتنبيهات وتتحرر خانته في خطتك، لكن لا شيء يمحى، و`products_restore` يعيده.

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

ما يعيده: { "success": true }.

• ترد الأداة بخطأ 404 إن لم يوجد المنتج أو كان في المهملات أصلا.

products_trash_list

يعرض المنتجات التي في المهملات، من الأحدث حذفا إلى الأقدم. استخدمه لتعرف معرف منتج تريد استعادته أو حذفه نهائيا.

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

ما يعيده: صفحة من المنتجات في data مع total وpage وpage_size وtotal_pages، بشكل `products_list` نفسه.

• حقول الأسعار تحذف حسب دورك كما في القائمة.

products_restore

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

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

ما يعيده: المنتج بعد الاستعادة، مع photo_urls.

• ترد الأداة بخطأ 404 إن لم يكن المنتج في المهملات.

products_purge

يحذف نهائيا منتجا واحدا من المهملات أو كل ما فيها، مع صوره وملفاته. ولا يمكن التراجع عن ذلك. والمنتج الذي اختير لبند في منافسة لا يحذف أبدا، لأن سجل المنافسة يحتاجه.

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

{
  "all": true
}

ما يعيده: success وremoved وهو عدد ما حذف، ومعهما blocked_ids إن بقي منتج لأن بنود منافسات تستخدمه. ويكون removed صفرا إن لم يطابق شيء في المهملات.

• ترد الأداة بخطأ 409 (referenced_by_tender_items مع blocked_ids) فقط حين تكون كل المنتجات المستهدفة محجوبة. أما إذا حجب بعضها فيحذف الباقي ويعود النجاح مع blocked_ids، فافحصه دائما.
• لتحرير منتج محجوب امسح اختياره من بنود المنافسات بـ`tender_item_product_selection_clear` ثم أعد المحاولة.
• المعرف الذي ليس في المهملات لا يسبب خطأ ولا يحذف شيئا. وطلب بلا id ولا all يرفض بخطأ 400.

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

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

product_manufacturer_link

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

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

ما يعيده: الرابط: id وproduct_id وmanufacturer_id وis_default وcreated_at.

• يرفض الخادم بخطأ 400 المنتج غير الموجود أو الذي في المهملات (product_not_found) والشركة غير الموجودة في مؤسستك (manufacturer_not_found).

product_manufacturer_unlink

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

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

ما يعيده: { "success": true }.

• فك ربط زوج غير مرتبط لا يسبب خطأ ولا يغير شيئا.

product_manufacturer_bulk_link

يربط حتى 500 منتج موجود بشركة مصنعة واحدة في استدعاء واحد. والأزواج المرتبطة أصلا تترك كما هي.

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

{
  "manufacturer_id": 88,
  "product_ids": [
    1207,
    1208,
    1215
  ]
}

ما يعيده: { "linked": n }، وهو عدد المنتجات المختلفة في الطلب، ويشمل ما كان مرتبطا منها قبل ذلك.

• معرف منتج غير موجود أو في المهملات يرفض الدفعة كلها بخطأ 400 (product_not_found)، والشركة غير الموجودة تعطي manufacturer_not_found.

product_manufacturer_set_default

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

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

{
  "product_id": 1207,
  "manufacturer_id": 88
}

ما يعيده: الرابط بعد التعديل: id وproduct_id وmanufacturer_id وis_default وcreated_at.

رموز نوبكو

رموز نوبكو هي ما يربط المنتج ببنود المنافسات. للمنتج رمز رئيسي في الحقل nupco_product_code، ويمكن أن يرتبط برموز أخرى.

product_nupco_link

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

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

ما يعيده: الرابط: id وproduct_id وnupco_code وis_default وcreated_at.

• حقل nupco_product_code يربط نفسه تلقائيا عند حفظ المنتج، فلا حاجة إلى ربط الرمز الرئيسي بهذه الأداة.
• يرفض الخادم بخطأ 400 (product_not_found) المنتج غير الموجود أو الذي في المهملات. ويجوز ربط الرمز نفسه بعدة منتجات.

product_nupco_unlink

يزيل رابطا واحدا بين منتج ورمز نوبكو. يزيل الرابط فقط: يبقى حقل nupco_product_code في المنتج كما هو، ويظل المنتج يطابق بهذا الرمز إن كان رمزه الرئيسي.

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

ما يعيده: { "success": true }.

• لإيقاف المطابقة بالرمز الرئيسي امسحه من الحقل بـ`products_update` (nupco_product_code: null) ثم فك رابطه هنا.
• الرمز يطابق حرفيا بعد قص الفراغات، وفك ربط زوج غير مرتبط لا يسبب خطأ.

سجل الأسعار وتنبيهات المنافسات

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

products_sourcing_history

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

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

ما يعيده: { "quotes": [...] }، وفي كل عنصر unitPriceUsd وunitPriceSar وquotedUnitPrice بعملة المورد currency وfxRate وvendorName وleadTimeDays وsubmittedAt وtenderLabel، وmatchBasis وقيمته product أو code وتبين كيف ارتبط السعر بالمنتج.

• تعود 50 نتيجة على الأكثر، ولا تعرض الأسطر التي بلا سعر.
• هذه أسعار تكلفة، فلا يصل إليها دور المبيعات. وترد الأداة بخطأ 404 إن لم يوجد المنتج أو كان في المهملات.

products_historical_prices

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

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

ما يعيده: { "prices": [...], "prices_hidden": null }، وفي كل صف unit_price وcurrency وuom وvendor_name وmanufacturer وcountry وcatalog_no وsource_tender_number وaward_date وawarded_to_us وprice_hidden، وprice_hidden_reason في الصف المخفي سعره حتى يدفع الاشتراك. وتكون prices_hidden بقيمة unpaid حين تخفى الأسعار لهذا السبب.

• الترتيب من أحدث فترة ترسية إلى أقدمها، والأرخص أولا داخل الفترة. وتعود 50 صفا على الأكثر.
• unit_price تكون null حين ذكر إعلان الترسية الفائز ولم ينشر السعر. وnull تعني غير منشور وليست صفرا، وتأتي هذه الصفوف بعد المسعرة.
• قبل أن تكتمل أول دفعة لاشتراك مؤسستك قد تأتي الصفوف بلا أسعار: الصف الذي أخفي سعره لهذا السبب يعود بـunit_price فارغ وprice_hidden بقيمة true وprice_hidden_reason بقيمة unpaid، وترتب الصفوف داخل الفترة بحسب المورد. فالسعر موجود لكنه مخفي، وليس سعرا غير منشور.
• والصف الذي يحمل price_hidden بقيمة true دون price_hidden_reason له سعر لا يظهر لمؤسستك، ويرتب مع الصفوف التي لا سعر لها. فالسعر موجود لكنه مخفي، وليس سعرا غير منشور.
• تحتسب كل قراءة من رصيد مؤسستك في الدقيقة لعمليات البحث في المنافسات وسجل الأسعار، وهو رصيد مشترك بين كل المفاتيح والموصلات والتطبيق. وحين ينتهي ترد الأداة بخطأ 429 rate_limited يذكر عدد الثواني قبل المحاولة التالية.
• منتج بلا رمز نوبكو يعود بقائمة فارغة، وترد الأداة بخطأ 404 إن لم يوجد المنتج.

products_alerts_list

يعرض المنافسات المفتوحة التي تطابق كتالوج مؤسستك، مجمعة بحسب المنافسة ومعها المنتجات التي طابقتها. لا توجد أداة تنشئ تنبيها لمنتج: يبدأ المنتج بالمطابقة حين يحمل استعلام بحث (search_query في products_update) أو يرتبط برمز نوبكو (product_nupco_link)، ثم تظهر مطابقاته هنا وفي الإشعارات.

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

لا معاملات.

ما يعيده: tenders: قائمة عناصرها { tender, products }، الأقرب موعدا أولا وبحد أقصى 200 منافسة، ولكل منتج في products الحقل product (id وproduct_name) وvia_item وقيمته true إن جاءت المطابقة من بند في المنافسة لا من نصها. وproducts_total عدد المنتجات في كتالوجك.

• يطابق المنتج المنافسات باستعلامه أو برموز نوبكو المرتبطة به، ولا يطابقها باسمه ولا بكلماته المفتاحية. ويضيق agency_filter المطابقات بنص من اسم الجهة.
• تحسب القائمة سلفا وتتجدد بعد كل جلب للمنافسات، وتعديل منتج يظهر أثره في الاستدعاء التالي.

خطاب الامتثال

خطاب واحد يولده النظام عند الطلب ولا يحفظه.

product_compliance_letter_pdf

ينشئ ملف PDF لخطاب الامتثال الذي يقوم مقام شهادة MDMA للمنتج في ملف تقديم منافسة، مطبوعا على ورقة مؤسستك وبختمها. لا يحفظ النظام شيئا: كل استدعاء يولد خطابا جديدا. وإن لم ترسل letter_type اختارت الأداة النوع: under_registration إن كانت حالة MDMA تحت التسجيل أو كان المنتج طبيا، وإلا non_medical_attestation.

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

{
  "id": 1207,
  "letter_type": "under_registration",
  "notes": "The MDMA application was filed in March 2026."
}

ما يعيده: ملف PDF بحقول filename وcontent_type وsize_bytes وbase64، كما في الملفات والمهام الخلفية.

• خطاب under_registration صفحتان، إنجليزية ثم عربية، تذكران رقم MDMA مرجعا للتسجيل إن وجد. وخطاب non_medical_attestation صفحة إنجليزية واحدة تقر بالتزام المنتج بالأنظمة خارج نظام الأجهزة الطبية.
• يطبع الخطاب اسم مؤسستك الإنجليزي وشعارها وختمها وبياناتها من إعدادات المؤسسة. وتشترط الأداة الصلاحية products.write ودورا يعدل المنتجات، مع أنها لا تغير شيئا.
• يعمل مع منتج في المهملات أيضا، وترد الأداة بخطأ 404 إن لم يوجد المنتج. وملف يتجاوز 4 ميغابايت لا يعاد في الرد.