أدوات MCP

العملاء

أدوات MCP لدليل العملاء وبياناتهم الضريبية وعناوينهم وربطهم بسجل مصنع.

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

تنبيه:الملف يملأ المستند ولا يزيد على ذلك. تحمل الفاتورة وأمر البيع وعرض السعر customer_id لربطها بملف، وتحتفظ كل منها بنسختها من بيانات المشتري كما كانت لحظة كتابتها. فتعديل العميل أو حذفه لا يغير مستندا كتب، والفاتورة الصادرة لا تتغير أبدا. راجع `invoices_create` و`sales_orders_create` و`quotations_create`.

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

الأداة	ما تفعله
customers_list	عرض العملاء
customers_get	عرض عميل
customers_create	إنشاء عميل
customers_update	تعديل عميل
customers_delete	حذف عميل
customers_link_vendor	ربط عميل بسجل مورد
customers_unlink_vendor	فك ربط عميل بسجل مورد

دليل العملاء

customers_list

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

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

المعامل	النوع	مطلوب	الوصف
`active`	`string`	لا	أي العملاء يعرض: `active` (الافتراضي) للنشطين، أو `inactive` لغير النشطين، أو `all` للجميع.
`vendor`	`string`	لا	`linked` للعملاء الذين لهم سجل مورد أيضا، أو `unlinked` لمن لا سجل لهم، أو `all` (الافتراضي).
`customer_type`	`string`	لا	`business` للمنشآت أو `individual` للأفراد.
`tax_treatment`	`string`	لا	يقصر النتائج على معاملة ضريبية واحدة: `vat_registered` أو `vat_not_registered` أو `gcc_vat_registered` أو `gcc_vat_not_registered` أو `non_gcc`. ومعنى كل قيمة في `customers_create`.
`manufacturer_id`	`integer`	لا	يعرض العميل المرتبط بسجل هذه الشركة المصنعة، إن وجد.
`q`	`string`	لا	كلمة أو جزء منها يطابق أي موضع في الاسم المعروض أو الاسم القانوني أو الرقم الضريبي أو رقم السجل التجاري أو البريد أو الهاتف. حتى 200 حرف.
`page`	`integer`	لا	رقم الصفحة، ويبدأ من 1.
`page_size`	`integer`	لا	عدد النتائج في الصفحة: 20 افتراضيا، وحده الأقصى 100.

{
  "q": "hospital",
  "tax_treatment": "vat_registered",
  "vendor": "linked"
}

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

ما يعيده: صفحة من العملاء في data مع total وpage وpage_size وtotal_pages. لكل عميل حقول الملف الرئيسية (الأسماء والنوع والمعاملة الضريبية والرقم الضريبي ورقم السجل التجاري والعنوان والعملة وis_active) وmanufacturers وفيه id وname لسجل المورد المرتبط أو null.

لا تحمل القائمة جهات الاتصال ولا الموقع ولا عنوان الشحن ولا الملاحظات. اقرأها من customers_get.

customers_get

يعيد عميلا واحدا كاملا: الملف وجهات اتصاله وسجل المورد المرتبط به إن وجد، وأحدث الفواتير وأوامر البيع وعروض الأسعار التي بدأت منه مع العدد الكلي لكل نوع.

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

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف العميل، ويأتي من `customers_list`.

ما يعيده: customer وهو الملف كاملا، وcontacts، وmanufacturer (id وname أو null)، وdocuments وفيه أحدث 10 من invoices وsales_orders وquotations، وcounts بمجموع كل نوع.

يرد الخادم بـ404 إذا لم يكن العميل في مؤسستك. وتحمل كل مستندات القائمة بيانات تعريفها كالرقم والحالة والتاريخ.

customers_create

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

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

المعامل	النوع	مطلوب	الوصف
`display_name`	`string`	نعم	الاسم الذي تعرضه القوائم وحقول الاختيار، من 1 إلى 200 حرف. وهو فريد في مؤسستك دون اعتبار لحالة الأحرف.
`customer_type`	`string`	لا	`business` (الافتراضي) للمنشأة، أو `individual` للفرد.
`company_name`	`string`	لا	الاسم القانوني الذي يطبع على المستندات إذا اختلف عن الاسم المعروض، حتى 200 حرف.
`email`	`string`	لا	البريد الإلكتروني للعميل.
`phone`	`string`	لا	هاتف العميل، حتى 50 حرفا.
`website`	`string`	لا	موقع العميل على الإنترنت، حتى 500 حرف.
`currency`	`string`	لا	رمز ISO 4217 لعملة العميل، من ثلاثة أحرف. الافتراضي `SAR`.
`tax_treatment`	`string`	لا	المعاملة الضريبية للعميل، وهي التي تحدد ما يطبع في خانة المشتري على الفاتورة: `vat_registered` (الافتراضي) عميل مسجل برقم ضريبي سعودي يلزم في `vat_number`؛ و`vat_not_registered` بلا رقم، وتطبع المستندات سجله التجاري أو معرفه الآخر بدلا منه؛ و`gcc_vat_registered` يحمل رقم دولة خليجية أخرى يحفظ في `vat_number` ويطبع معرفا من نوع GCC؛ أما `gcc_vat_not_registered` و`non_gcc` فيعاملان معاملة مشتر بلا رقم.
`vat_number`	`string`	لا	رقم التسجيل في ضريبة القيمة المضافة، حتى 20 حرفا. وللمشتري المسجل في السعودية هو 15 رقما يبدأ وينتهي بالرقم 3. وفي `gcc_vat_registered` يحمل رقم الدولة الأخرى.
`cr_number`	`string`	لا	رقم السجل التجاري، حتى 30 حرفا. وتعرف الفاتورة المشتري بلا رقم ضريبي به (بالنوع `CRN`) ما لم تحدد معرفا آخر أدناه.
`buyer_id_scheme`	`string`	لا	نوع معرف آخر لمشتر بلا رقم ضريبي، بتسمية هيئة الزكاة والضريبة والجمارك (ZATCA): `CRN` السجل التجاري، `MOM` رخصة وزارة الشؤون البلدية والقروية والإسكان، `MLS` رخصة وزارة الموارد البشرية والتنمية الاجتماعية، `700` الرقم الموحد 700، `SAG` رخصة وزارة الاستثمار، `NAT` الهوية الوطنية، `GCC` هوية مواطن خليجي، `IQA` الإقامة، `PAS` جواز السفر، `OTH` معرف آخر. ويرافقه `buyer_id_value`.
`buyer_id_value`	`string`	لا	قيمة المعرف، حتى 50 حرفا، وتستخدم مع `buyer_id_scheme`.
`street_name`	`string`	لا	العنوان الوطني: الشارع، حتى 200 حرف.
`building_number`	`string`	لا	العنوان الوطني: رقم المبنى من 4 أرقام.
`district`	`string`	لا	العنوان الوطني: الحي، حتى 100 حرف.
`city`	`string`	لا	العنوان الوطني: المدينة، حتى 100 حرف.
`postal_code`	`string`	لا	العنوان الوطني: الرمز البريدي من 5 أرقام.
`additional_number`	`string`	لا	العنوان الوطني: الرقم الإضافي، حتى 10 أحرف.
`country_code`	`string`	لا	رمز الدولة من حرفين وفق ISO 3166-1. الافتراضي `SA`.
`shipping_address`	`string`	لا	عنوان التسليم نصا حرا إذا اختلف عن العنوان الوطني، حتى 500 حرف.
`notes`	`string`	لا	ملاحظات حرة على العميل، حتى 2000 حرف.
`is_active`	`boolean`	لا	`false` تخفي الملف من حقول الاختيار ومن القائمة الافتراضية، ولا تؤثر في أي مستند. الافتراضي `true`.
`manufacturer_id`	`integer`	لا	معرف سجل المورد (الشركة المصنعة) للجهة نفسها، ويأتي من `manufacturers_list`. تربط الشركة المصنعة بعميل واحد فقط. وراجع `customers_link_vendor`.
`contacts`	`object[]`	لا	جهات الاتصال عند العميل، حتى 20.
`contacts[].name`	`string`	نعم	اسم الشخص، من 1 إلى 200 حرف.
`contacts[].email`	`string`	لا	البريد الإلكتروني للشخص.
`contacts[].phone`	`string`	لا	هاتف الشخص، حتى 50 حرفا.
`contacts[].mobile`	`string`	لا	جوال الشخص، حتى 50 حرفا.
`contacts[].designation`	`string`	لا	المسمى الوظيفي، حتى 100 حرف.
`contacts[].is_primary`	`boolean`	لا	يعلم جهة الاتصال الأساسية. إذا لم تعلم أي جهة فالأولى في القائمة هي الأساسية.

{
  "display_name": "Al Noor Hospital",
  "company_name": "Al Noor Medical Company",
  "tax_treatment": "vat_registered",
  "vat_number": "300123456700003",
  "cr_number": "1010123456",
  "street_name": "King Fahd Road",
  "building_number": "8228",
  "district": "Al Olaya",
  "city": "Riyadh",
  "postal_code": "12214",
  "additional_number": "2121",
  "email": "purchasing@alnoor.example.com",
  "contacts": [
    {
      "name": "Sara Alharbi",
      "designation": "Purchasing manager",
      "mobile": "0551234567",
      "is_primary": true
    }
  ]
}

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

ما يعيده: الملف الجديد في customer وجهات اتصاله في contacts.

يرد الخادم بـ400 vat_number_required إذا كان العميل مسجلا في الضريبة بلا رقم ضريبي، وبـ400 vat_number_invalid إذا لم يكن الرقم 15 رقما يبدأ وينتهي بالرقم 3.
ويرد بـ409 display_name_taken إذا كان عميل آخر يحمل الاسم، وبـ404 manufacturer_not_found إذا لم تكن الشركة المصنعة من مؤسستك، وبـ409 vendor_already_linked إذا كان عميل آخر مرتبطا بها.

customers_update

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

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف العميل، ويأتي من `customers_list`.
`display_name`	`string`	لا	اسم معروض جديد، من 1 إلى 200 حرف، وهو فريد في مؤسستك دون اعتبار لحالة الأحرف.
`customer_type`	`string`	لا	`business` (الافتراضي) للمنشأة، أو `individual` للفرد.
`company_name`	`string`	لا	الاسم القانوني الذي يطبع على المستندات إذا اختلف عن الاسم المعروض، حتى 200 حرف. أرسل `null` لمسح القيمة.
`email`	`string`	لا	البريد الإلكتروني للعميل. أرسل `null` لمسح القيمة.
`phone`	`string`	لا	هاتف العميل، حتى 50 حرفا. أرسل `null` لمسح القيمة.
`website`	`string`	لا	موقع العميل على الإنترنت، حتى 500 حرف. أرسل `null` لمسح القيمة.
`currency`	`string`	لا	رمز ISO 4217 لعملة العميل، من ثلاثة أحرف. الافتراضي `SAR`.
`tax_treatment`	`string`	لا	المعاملة الضريبية للعميل، وهي التي تحدد ما يطبع في خانة المشتري على الفاتورة: `vat_registered` (الافتراضي) عميل مسجل برقم ضريبي سعودي يلزم في `vat_number`؛ و`vat_not_registered` بلا رقم، وتطبع المستندات سجله التجاري أو معرفه الآخر بدلا منه؛ و`gcc_vat_registered` يحمل رقم دولة خليجية أخرى يحفظ في `vat_number` ويطبع معرفا من نوع GCC؛ أما `gcc_vat_not_registered` و`non_gcc` فيعاملان معاملة مشتر بلا رقم.
`vat_number`	`string`	لا	رقم التسجيل في ضريبة القيمة المضافة، حتى 20 حرفا. وللمشتري المسجل في السعودية هو 15 رقما يبدأ وينتهي بالرقم 3. وفي `gcc_vat_registered` يحمل رقم الدولة الأخرى. أرسل `null` لمسح القيمة.
`cr_number`	`string`	لا	رقم السجل التجاري، حتى 30 حرفا. وتعرف الفاتورة المشتري بلا رقم ضريبي به (بالنوع `CRN`) ما لم تحدد معرفا آخر أدناه. أرسل `null` لمسح القيمة.
`buyer_id_scheme`	`string`	لا	نوع معرف آخر لمشتر بلا رقم ضريبي، بتسمية هيئة الزكاة والضريبة والجمارك (ZATCA): `CRN` السجل التجاري، `MOM` رخصة وزارة الشؤون البلدية والقروية والإسكان، `MLS` رخصة وزارة الموارد البشرية والتنمية الاجتماعية، `700` الرقم الموحد 700، `SAG` رخصة وزارة الاستثمار، `NAT` الهوية الوطنية، `GCC` هوية مواطن خليجي، `IQA` الإقامة، `PAS` جواز السفر، `OTH` معرف آخر. ويرافقه `buyer_id_value`. أرسل `null` لمسح القيمة.
`buyer_id_value`	`string`	لا	قيمة المعرف، حتى 50 حرفا، وتستخدم مع `buyer_id_scheme`. أرسل `null` لمسح القيمة.
`street_name`	`string`	لا	العنوان الوطني: الشارع، حتى 200 حرف. أرسل `null` لمسح القيمة.
`building_number`	`string`	لا	العنوان الوطني: رقم المبنى من 4 أرقام. أرسل `null` لمسح القيمة.
`district`	`string`	لا	العنوان الوطني: الحي، حتى 100 حرف. أرسل `null` لمسح القيمة.
`city`	`string`	لا	العنوان الوطني: المدينة، حتى 100 حرف. أرسل `null` لمسح القيمة.
`postal_code`	`string`	لا	العنوان الوطني: الرمز البريدي من 5 أرقام. أرسل `null` لمسح القيمة.
`additional_number`	`string`	لا	العنوان الوطني: الرقم الإضافي، حتى 10 أحرف. أرسل `null` لمسح القيمة.
`country_code`	`string`	لا	رمز الدولة من حرفين وفق ISO 3166-1. الافتراضي `SA`.
`shipping_address`	`string`	لا	عنوان التسليم نصا حرا إذا اختلف عن العنوان الوطني، حتى 500 حرف. أرسل `null` لمسح القيمة.
`notes`	`string`	لا	ملاحظات حرة على العميل، حتى 2000 حرف. أرسل `null` لمسح القيمة.
`is_active`	`boolean`	لا	`false` تخفي الملف من حقول الاختيار ومن القائمة الافتراضية، ولا تؤثر في أي مستند. الافتراضي `true`.
`manufacturer_id`	`integer`	لا	معرف سجل المورد (الشركة المصنعة) للجهة نفسها، ويأتي من `manufacturers_list`. تربط الشركة المصنعة بعميل واحد فقط. أرسل `null` لفك الربط، وراجع `customers_link_vendor`.
`contacts`	`object[]`	لا	جهات الاتصال عند العميل، حتى 20. إذا أرسلت القائمة استبدلت الحالية كلها، وإن تركتها بقيت جهات الاتصال كما هي.
`contacts[].name`	`string`	نعم	اسم الشخص، من 1 إلى 200 حرف.
`contacts[].email`	`string`	لا	البريد الإلكتروني للشخص. أرسل `null` لمسح القيمة.
`contacts[].phone`	`string`	لا	هاتف الشخص، حتى 50 حرفا. أرسل `null` لمسح القيمة.
`contacts[].mobile`	`string`	لا	جوال الشخص، حتى 50 حرفا. أرسل `null` لمسح القيمة.
`contacts[].designation`	`string`	لا	المسمى الوظيفي، حتى 100 حرف. أرسل `null` لمسح القيمة.
`contacts[].is_primary`	`boolean`	لا	يعلم جهة الاتصال الأساسية. إذا لم تعلم أي جهة فالأولى في القائمة هي الأساسية.

{
  "id": 214,
  "city": "Jeddah",
  "postal_code": "21442",
  "contacts": [
    {
      "name": "Sara Alharbi",
      "mobile": "0551234567",
      "is_primary": true
    },
    {
      "name": "Omar Alqahtani",
      "designation": "Accountant"
    }
  ]
}

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

ما يعيده: الملف بعد التعديل في customer وجهات اتصاله في contacts.

يرد الخادم بـ404 not_found إذا لم يكن العميل في مؤسستك، وتسري أخطاء 400 و409 نفسها المذكورة في customers_create على الملف بعد التعديل.
تعديل الملف لا يغير مستندا كتب، وتأخذ المستندات الجديدة وحدها البيانات الجديدة.

customers_delete

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

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

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف العميل، ويأتي من `customers_list`.

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

يرد الخادم بـ404 not_found إذا لم يكن العميل في مؤسستك. ولإخفاء عميل عن حقول الاختيار دون حذفه عدله بـis_active تساوي false.

العميل الذي هو مورد أيضا

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

customers_link_vendor

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

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

ما يعيده: العميل بعد الربط في customer، وسجل المورد المرتبط في manufacturer (id وname).

عند ربط شركة موجودة يرد الخادم بـ404 manufacturer_not_found إذا لم تكن من مؤسستك، وبـ409 vendor_already_linked إذا كان عميل آخر مرتبطا بها. وإن كان للعميل سجل مورد سابق انتقل الرابط إلى الجديد.
عند الإنشاء من الملف يرد بـ409 already_linked إذا كان للعميل سجل مورد، وبـ409 manufacturer_exists إذا وجدت شركة مصنعة بالاسم نفسه (اسمه القانوني إن وجد وإلا الاسم المعروض): اربطها هي بدل إنشاء ثانية.
ينسخ إنشاء سجل المورد بيانات الملف مرة واحدة، ولا ينسخ أي تعديل لاحق على أحد السجلين إلى الآخر.

customers_unlink_vendor

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

المعامل	النوع	مطلوب	الوصف
`id`	`integer`	نعم	معرف العميل، ويأتي من `customers_list`.

ما يعيده: العميل بعد فك الربط في customer، وmanufacturer تساوي null.

يرد الخادم بـ404 not_found إذا لم يكن العميل في مؤسستك. واستدعاؤها لعميل بلا رابط لا يغير شيئا.