إضافة طلب فاتورة إلى برنامج المحاسبة عبر JSON:

الهدف من العملية

تُستخدم هذه العملية لإرسال طلب جديد (Order) إلى برنامج المحاسبة من خلال واجهة برمجة التطبيقات (API).
يتم ذلك عبر بروتوكول HTTP باستخدام تنسيق JSON لإرسال البيانات واستقبال الرد من الخادم.

هذه الطريقة تسمح بربط برنامج آخر (مثل تطبيق موبايل أو موقع إلكتروني) مع نظام المحاسبة، بحيث يمكن إنشاء الطلبات والفواتير مباشرة.

تفاصيل الاتصال

• العنوان (Server):
  http://127.0.0.1:1818/
  هذا هو عنوان الخادم الذي يستقبل الطلبات، وغالباً يكون محليًا أثناء الاختبار.
• طريقة الإرسال (Method):
  POST
  أي أن البيانات تُرسل ضمن جسم الطلب (Body) وليس في الرابط نفسه.

معلومات الرأس (Header)

 Version: 1.0

Type: OrderAdd

Username: JSON

Password: 00000

الشرح:

• Version: رقم إصدار الاتصال (1.0).
• Type: نوع العملية المطلوبة، وهنا هي (OrderAdd) أي إضافة طلب جديد.
• Username: اسم المستخدم الذي يقوم بالاتصال بالنظام.
• Password: كلمة المرور الخاصة بالمستخدم للتحقق من الهوية.

جسم الطلب (Body)

يُرسل جسم الطلب بصيغة JSON ويحتوي على جميع تفاصيل الفاتورة أو الطلب.

{

  "date": "2025-10-21 00:00:00",

  "datetime": "2025-10-21 08:15:22",

  "orderGUID": "00000000-0000-0000-0000-000000000000",

  "customerGUID": "AFFC4BBB-FC3F-4D4F-A96F-CC653477EA25",

  "payTypeID": 0,

  "typeBill": 3,

  "billGUID": "00000000-0000-0000-0000-000000000000",

  "tableGUID": "00000000-0000-0000-0000-000000000000",

  "addressID": 0,

  "custName": "",

  "custPhone": "",

  "custAddress": "",

  "sourceID": 0,

  "extra": 0,

  "disc": 0,

  "notes": "",

  "orderID": 0,

  "items": [

    {

      "materialGUID": "2EAC6375-FCF5-468B-91FA-45FEF1908512",

      "price": 1.0,

      "qty": 1.0,

      "notes": ""

    }

  ]

}


الحقل      الوصف

date     تاريخ الطلب

datetime         التاريخ والوقت الكامل للطلب.

orderGUID       المعرّف الفريد للطلب (يُرسل فارغاً أو بصفر عند الإضافة الجديدة).

customerGUID المعرّف الفريد للعميل.

payTypeID        نوع الدفع (0 نقدي – 1 بطاقة – 2 تحويل بنكي... حسب إعداد النظام).

typeBill            نوع الفاتورة (3 عادة تشير إلى فاتورة توصيل).

billGUID           معرّف الفاتورة (يُرسل فارغًا عند الطلب الجديد).

tableGUID       رقم الطاولة (في حالة المطاعم).

addressID        رقم العنوان إذا كان مرتبطًا بعميل معين.

custName / custPhone / custAddress معلومات العميل (اختيارية).

sourceID          مصدر الطلب (تطبيق، موقع، كاشير...).

extra / disc      قيمة الإضافات والخصومات على الطلب.

notes   ملاحظات إضافية.

orderID            رقم داخلي للطلب (عادة يُترك 0).

items   قائمة المواد المضمنة في الطلب.


تفاصيل المواد (items)

كل مادة داخل الطلب تحتوي على:

• materialGUID:  المعرّف الفريد للمادة.
• price:  سعر الوحدة.
• qty:  الكمية المطلوبة.
• notes:  ملاحظات خاصة بالمادة (مثل: بدون سكر، إضافي جبن...).

استجابة الخادم  (Response)

بعد إرسال الطلب، يردّ الخادم ببيانات بصيغة JSON، كما يلي:

{

  "number": 2,

  "guid": "92719D15-F207-4438-B531-792DB18A29C2",

  "code": "Success",

  "message": ""

}



شرح الاستجابة:
الحقل      المعنى

number           رقم الفاتورة أو الطلب الذي تم إنشاؤه داخل النظام.

guid     المعرّف الفريد الذي تم توليده للطلب الجديد.

code    نتيجة العملية (Success تعني نجاح العملية).

message          رسالة إضافية (تُستخدم لعرض الأخطاء أو الملاحظات).


 النتيجة النهائية

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