أوامر البيع والشراء

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

أوامر البيع

تمر حالة أمر البيع بالترتيب: new (جديد) ثم confirmed (مؤكد) ثم in_progress (قيد التنفيذ) ثم fulfilled (مكتمل)، أو cancelled (ملغى). ويرقم كل أمر ترقيما متسلسلا لمؤسستك: SO-000001 ثم SO-000002 وهكذا.

sales_orders_list

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

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

ما يعيده: صفحة من الأوامر مع total وtotal_pages. لكل أمر رقمه وعميله وحالته وتواريخه وعملته وtotal_amount ومنافسته وعرض سعره.

• يرى المشاهد بدون تسعير الأوامر لكن بلا الحقل total_amount.
• حالة غير معروفة في status ترد بخطأ 400.

sales_orders_get

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

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

ما يعيده: الأمر في sales_order، وبنوده في items، ثم fulfilment وdeviations وtender وquotation وdeliveries وpurchase_orders وdocuments.

• لكل بند delivered_quantity (على تسليمات علمت كمسلمة) وpending_quantity (على تسليمات ما زالت مسودة أو مجدولة أو في الطريق) وremaining_quantity وexcess_quantity (ما سلم فوق المطلوب). والتسليم الملغى لا يحتسب في شيء.
• deviations تعدد كل اختلاف بين التسليمات والطلب: over_delivered (بند سلم أكثر من المطلوب) وextra_lines (بنود سلمت خارج الطلب) وsubstitutions (شحن منتج مختلف عن منتج البند) وlate_deliveries (تسليم سلم أو جدول بعد due_on) وclosed_short (أمر علم مكتملا وفيه كميات لم تسلم)، مع count للمجموع. وهي تنبيه لا يمنع كتابة شيء.
• يرى المشاهد بدون تسعير الأمر دون total_amount وunit_price في البنود. وتعود purchase_orders فارغة (null) لدور المبيعات والمشاهد بدون تسعير، لأن أوامر الشراء تسمي الموردين وتكلفتهم.
• documents هي المستندات المحفوظة على الأمر، وأولها أمر شراء العميل بصيغة PDF. لكل مستند path وname وsize وurl، والرابط صالح لنحو ساعة. وبالمسار تحذف المستند بـ`sales_order_document_delete`. ويراها كل دور يرى أوامر البيع.
• أمر غير موجود في مؤسستك يرد بخطأ 404.

sales_orders_create

يسجل طلبا ورد من عميل مع بنوده، ويعطيه رقما متسلسلا ويبدؤه بحالة new. ويحسب إجماليه من البنود المسعرة فقط.

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

{
  "customer_name": "Al Noor Hospital",
  "customer_reference": "PO-2026-0457",
  "tender_id": 48213,
  "quotation_id": 1207,
  "ordered_on": "2026-10-04",
  "due_on": "2026-11-15",
  "items": [
    {
      "description": "Sterile syringe 5 ml, box of 100",
      "quantity": 200,
      "unit": "box",
      "unit_price": 36.5,
      "tender_item_id": 902114
    },
    {
      "description": "Nitrile gloves, medium, box of 100",
      "quantity": 500,
      "unit": "box",
      "unit_price": 21
    }
  ]
}

ما يعيده: sales_order_id وorder_number للأمر الجديد.

• الاسم مطلوب: أرسل customer_name، أو customer_id فيأخذ الأمر اسم العميل من ملفه. والاسم الذي ترسله يسبق اسم الملف. وإن لم ترسل أيا منهما رد الأداة بخطأ 400.
• يحسب total_amount من البنود التي لها unit_price فقط. وإن لم يسعر أي بند فلا إجمالي للأمر.
• منافسة لا تراها، أو عرض سعر أو عميل أو منتج ليس لمؤسستك، يرد بخطأ 404.
• لتنفيذ الأمر أنشئ تسليمات مرتبطة به بـ`deliveries_create`. ينتقل الأمر إلى in_progress عند وجود أول تسليم، وإلى fulfilled حين تسلم كل البنود.

sales_orders_update

يعدل عميل الأمر أو تواريخه أو ارتباطاته أو ملاحظاته أو بنوده. لا يتغير إلا ما ترسله، وnull يمسح الحقل الاختياري. أما الرقم والحالة فلا يعدلان هنا: للحالة استخدم `sales_orders_set_status`.

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

{
  "id": 214,
  "due_on": "2026-11-30",
  "items": [
    {
      "id": 1881,
      "description": "Sterile syringe 5 ml, box of 100",
      "quantity": 250,
      "unit": "box",
      "unit_price": 36.5
    },
    {
      "description": "Examination gloves, large, box of 100",
      "quantity": 100,
      "unit": "box",
      "unit_price": 21
    }
  ]
}

ما يعيده: sales_order_id للأمر المعدل.

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

sales_orders_set_status

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

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

{
  "id": 214,
  "status": "confirmed"
}

ما يعيده: تأكيد مع status الجديدة.

• الدخول إلى fulfilled يسجل fulfilled_at، والخروج منها يمسحه.
• تحرك التسليمات المرتبطة الأمر بنفسها، لكن إلى الأمام فقط: إلى in_progress حين يوجد أول تسليم، وإلى fulfilled حين تسلم كل البنود. ولا ترجعه ولا تخرجه من cancelled أو fulfilled.

sales_orders_delete

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

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

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

sales_orders_create_deliveries

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

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

{
  "id": 1042,
  "warehouse_id": 3,
  "destinations": [
    {
      "ship_to": "NUPCO C.WH in Jeddah for MOH - MOH - Taif",
      "contact_name": "Receiving desk",
      "contact_phone": "+966500000000"
    }
  ]
}

ما يعيده: deliveries: لكل مسودة delivery_id وdelivery_number وdestination_name وdue_on ومعرفات بنود الأمر فيها. ثم skipped: البنود التي لم تخطط وسبب كل منها، وهو no_ship_to أو fully_planned.

• يخطط فقط ما لا يحمله أي تسليم قائم، فتكرار الاستدعاء لا ينشئ شيئا جديدا، والبند الذي شحن بعضه تخطط له مسودة لما بقي. والبند بلا ship_to يتخطى ويذكر في skipped.
• كل مسودة تجدول عند الظهيرة بتوقيت الرياض في يوم استحقاق بنودها، والبند الذي لا موعد له يوضع على تاريخ استحقاق الأمر كما في التقويم. وتبقى حالة الأمر كما هي حتى يعمل على أحد التسليمات.
• يتطلب دور المدير أو المالك لأنه ينشئ تسليمات، ويتطلب نطاقي orders.write وlogistics.write معا. وأمر ملغى يرد بخطأ 409، وكذلك أمر تخطط تسليماته في اللحظة نفسها من مكان آخر: انتظر دقيقة ثم أعد الاستدعاء ليخطط ما بقي.
• إن فشل إنشاء مسودة توقف الطلب وذكر عدد ما أنشئ قبلها. وما أنشئ يبقى، وتعيد الاستدعاء فيخطط لما تبقى فقط.

sales_orders_mark_delivered

يسجل أمر البيع مسلما بالكامل، كالأمر الذي صدرت فاتورته في Zoho Books: كل تسليم مفتوح للأمر يصبح مسلما، وما بقي دون تسليم ينشأ له تسليم لكل جهة ويسجل مسلما في الحال، ثم يغلق الأمر منفذا.

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

{
  "id": 1042
}

ما يعيده: delivered: معرفات التسليمات التي جعلها مسلمة. وcreated: معرفات التسليمات التي أنشأها.

• التسليمات الملغاة تبقى كما هي، والأمر المسلم بالكامل لا يتغير، فتكرار الاستدعاء آمن. والأمر الملغى يرد بخطأ 409. ولتسجيل جزء من الأمر استخدم deliveries_create وdeliveries_set_status لتلك البنود.
• يتطلب دور المدير أو المالك لأنه ينشئ تسليمات ويغير حالتها، ويتطلب نطاقي orders.write وlogistics.write معا.

sales_orders_calendar

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

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

{
  "from": "2026-11-01",
  "to": "2026-11-30"
}

ما يعيده: events مرتبة بالتاريخ. لكل مدخل: date وsales_order_id وorder_number وorder_status وcustomer_name وcustomer_reference (رقم أمر شراء العميل) وdestination وarea وstate وdays_until وline_count وopen_line_count وitems وdeliveries. ثم today وfrom وto وopen_only وsummary (overdue وsoon وunplanned) وtruncated.

• المدخل هو ما يحمله تسليم واحد مخطط: بنود أمر واحد إلى جهة واحدة في يوم واحد، ولا يفرق بين الحروف الكبيرة والصغيرة أو المسافات الزائدة في اسم الجهة. ويضم items أول 20 بندا فقط، وline_count هو العدد الكلي، و`sales_orders_get` يعرضها كلها.
• يوضع البند على due_on الخاص به، فإن لم يكن له تاريخ فعلى due_on الأمر. والبند الذي لا تاريخ له ولا لأمره لا يظهر، وكذلك أوامر البيع الملغاة. والأيام بتوقيت الرياض.
• state هو overdue (بقي بند مفتوح وفات اليوم) أو upcoming (قادم) أو delivered (شحنت كل البنود على تسليمات علمت كمسلمة، أو أغلق الأمر كمكتمل). وdays_until سالب للمتأخر وفارغ بعد التسليم. وsummary.soon هو ما يستحق خلال 3 أيام.
• area هي منطقة المملكة التي تقع فيها الجهة، تقرأ من كلماتها بأول مكان تسميه: riyadh وmakkah وmadinah وeastern وqassim وasir وtabuk وhail وnorthern_borders وjazan وnajran وal_bahah وal_jouf. وهي null إن لم تسم الجهة مكانا تعرفه المنصة. وعليها تقوم خريطة تقويم التسليمات في التطبيق.
• deliveries هي التسليمات غير الملغاة التي تحمل بنود المدخل، ومنها المسودة والمجدولة والتي في الطريق. فمدخل مفتوح بلا تسليمات ما زال يحتاج إلى `sales_orders_create_deliveries`، وsummary.unplanned يعد هذه المدخلات.
• يعيد حتى 500 مدخل. فإن زادت النافذة على ذلك صارت truncated تساوي true، فضيق النافذة. ولا تحمل المدخلات أي أسعار.

أوامر الشراء

تمر حالة أمر الشراء بالترتيب: draft (مسودة) ثم sent (مرسل) ثم confirmed (مؤكد) ثم partially_received (مستلم جزئيا) ثم received (مستلم)، أو cancelled (ملغى). ويرقم ترقيما متسلسلا: PO-000001 ثم PO-000002.

purchase_orders_list

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

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

ما يعيده: صفحة من الأوامر مع total وtotal_pages. لكل أمر رقمه ومورده وحالته وتواريخه وعملته وtotal_amount ومنافسته وأمر البيع المرتبط.

• أوامر الشراء بيانات تكلفة: لا يراها دور المبيعات ولا الفني ولا المشاهد بدون تسعير.

purchase_orders_get

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

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

ما يعيده: الأمر في purchase_order، وبنوده في items (لكل بند received_quantity وremaining_quantity)، ثم receipt وmanufacturer وtender وsales_order.

• receipt فيه ordered وreceived وremaining وcomplete. ومعرفات البنود هنا هي التي تستخدمها `purchase_orders_receive`.
• أمر غير موجود في مؤسستك يرد بخطأ 404.

purchase_orders_create

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

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

{
  "manufacturer_id": 87,
  "supplier_reference": "PI-2026-0331",
  "tender_id": 48213,
  "sales_order_id": 214,
  "expected_on": "2026-11-01",
  "items": [
    {
      "description": "Sterile syringe 5 ml, box of 100",
      "quantity": 200,
      "unit": "box",
      "unit_price": 24.8
    }
  ]
}

ما يعيده: purchase_order_id وorder_number للأمر الجديد.

• إن أرسلت manufacturer_id نسخ الأمر اسم الشركة إلى supplier_name فيبقى الأمر مقروءا حتى لو حذفت الشركة من الدليل. وإن لم ترسل أيا منهما رد الأداة بخطأ 400.
• شركة مصنعة أو أمر بيع أو منتج ليس لمؤسستك، أو منافسة لا تراها، يرد بخطأ 404.
• تبدأ كل البنود بلا استلام. سجل الوارد بـ`purchase_orders_receive`.

purchase_orders_update

يعدل مورد الأمر أو تواريخه أو ارتباطاته أو ملاحظاته أو بنوده. لا يتغير إلا ما ترسله، وnull يمسح الحقل الاختياري. للحالة استخدم `purchase_orders_set_status`، وللوارد `purchase_orders_receive`.

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

{
  "id": 98,
  "supplier_reference": "PI-2026-0331-R1",
  "expected_on": "2026-11-10"
}

ما يعيده: purchase_order_id للأمر المعدل.

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

purchase_orders_set_status

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

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

{
  "id": 98,
  "status": "sent"
}

ما يعيده: تأكيد مع status الجديدة.

• الدخول إلى received يسجل received_at، والخروج منها يمسحه. لكن الكميات المستلمة على البنود تبقى كما هي، فالانتقال اليدوي إلى received يقول إن البضاعة وصلت ولا يغير ما سجل على البنود.
• الأمر الملغى لا يقبل تسجيل استلام. أعده إلى draft أولا.

purchase_orders_delete

يحذف أمر الشراء مع بنوده وما سجل عليها من استلام. لا يمكن التراجع عن ذلك.

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

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

تسجيل الاستلام

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

purchase_orders_receive

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

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

{
  "id": 98,
  "lines": [
    {
      "item_id": 4410,
      "quantity": 120
    },
    {
      "item_id": 4411,
      "quantity": 40
    }
  ],
  "received_at": "2026-10-12T09:30:00+03:00"
}

ما يعيده: تأكيد مع status الجديدة للأمر، وفي items المجموع المستلم الجديد (received_quantity) لكل بند مسه الاستلام.

• يرفض الاستلام كله ولا يحفظ شيء إذا سمى بندا ليس على الأمر، أو إذا تجاوز بند ما طلب منه. والبند المذكور مرتين يجمع مقداره.
• أمر ملغى يرد بخطأ 409. أعده إلى draft بـ`purchase_orders_set_status` ثم سجل الاستلام.
• ينتقل الأمر إلى الأمام من حالته الحالية، ومنها draft. ولا يسجل received_at إلا مرة واحدة، فإن كان الأمر قد علم مستلما من قبل لم يتغير تاريخه.