كل المستندات API

```html

مقدمة
 

واجهة برمجة التطبيقات (API) لجميع المستندات هي المحرك الأساسي لمعالجة المستندات في نظام Biz1.
هي مصممة كـطبقة API موحدة يتم من خلالها إنشاء وإدارة وربط وإرسال واسترداد ومراجعة جميع المستندات التجارية.
 

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

واجهة API هذي تدعم كل عملية تجارية وكل متطلبات مسك الدفاتر، بدون ما تجبر الأنظمة الخارجية إنها تكرر المنطق التجاري.
 

---

منو يستخدم واجهة API هذي
 

واجهة API لجميع المستندات مصممة عشان يستخدمونها:
 

• مواقع الويب ومنصات التجارة الإلكترونية

• تطبيقات الجوال

• أنظمة إدارة علاقات العملاء (CRM)

• أنظمة تخطيط موارد المؤسسات (ERP)

• تكاملات المحاسبة والمالية

• أنظمة نقاط البيع (POS)

• سكريبتات الأتمتة والمهام الخلفية
   

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

---

روابط URL الأساسية ونقاط الدخول
 

كل التعاملات تبدأ من واحد من هالدومينات الأساسية التالية:
 

• دومين الإنتاج
  
  https://biz1.co.il/

• دومين بديل
  
  https://bull36.com/
   

الدومينين يعرضون نفس سلوك الـ API.
 

---

روابط URL الرئيسية لإنشاء المستندات
 

add_order2 – نقطة نهاية رئيسية للإنشاء
 

https://biz1.co.il/api.php?api=add_order2
 

هذا هو الرابط الرئيسي الخارجي المستخدم لإنشاء المستندات.
 

هي المسؤولة عن:

 

• إنشاء الفواتير

• إنشاء الإيصالات

• إنشاء الطلبات

• إنشاء إيصالات التبرع

• إنشاء مستندات الإرجاع والائتمان

• تفعيل أتمتة سير العمل
   

الأنظمة الخارجية تتفاعل فقط مع رابط URL هذا عشان تسوي مستندات.
 

---

create_document – اسم مستعار لـ add_order2
 

https://biz1.co.il/api.php?api=create_document
 

رابط URL هذا متطابق وظيفيًا مع add_order2.
 

هي موجودة عشان:
 

• التوافق مع الإصدارات السابقة

• إعطاء اسم أوضح للتكاملات

• الدعم التاريخي
   

الرابطين يودّون لنفس المنطق الداخلي.
 

---

شنو يعني “مستندات” في Biz1
 

في Biz1، المستند هو أي توثيق تجاري رسمي يمثل واحد من الآتي:
 

• معاملة مالية

• التزام بالبيع أو الشراء

• تأكيد دفع

• شحن أو إرجاع بضاعة

• تبرع أو اشتراك
   

كل المستندات تشترك في هيكل داخلي مشترك، بس سلوكها يتغير حسب نوع المستند.
هذا يخلي Biz1 مرنة وهي تطبق قوانين المحاسبة والضريبة والقانون.
 

---

أنواع المستندات وهدفها
 

مستندات الفواتير
 

الفواتير تمثل أحداث الفوترة.

الفاتورة الضريبية تُصدر عند فوترة العميل.
فاتورة الائتمان تلغي أو تقلل من فاتورة سابقة.
الفاتورة الأولية (Proforma) هي فاتورة مبدئية تُستخدم للموافقة.
فاتورة الشحن توثّق البضائع المشحونة.
فاتورة الإرجاع توثّق البضائع المرتجعة.
مستند GR/IR يدعم مطابقة حسابات البضائع والفواتير.
 

مستندات الفواتير:
 

• ممكن تحتوي على منتجات

• ممكن تشمل ضريبة القيمة المضافة (VAT)

• دايمًا تولّد ملفات PDF

• تظهر في سجلات مسك الدفاتر
   

---

مستندات الإيصالات
 

الإيصالات تمثل أحداث الدفع.

الإيصال العادي يأكد الفلوس اللي انقبضت.
فاتورة ضريبية بإيصال تشمل تقارير ضريبية.
إيصال الدفع الجزئي يوثّق الدفعات الجزئية.
إيصال التبرع يوثّق التبرعات، وغالبًا يكون فيه معالجة ضريبية خاصة.
 

الإيصالات:
 

• ممكن تشمل منتجات أو بس مبلغ إجمالي

• دايمًا تمثل حركة نقدية

• تحدّث حالة الدفع للمستندات المرتبطة
   

---

مستندات الطلبات
 

الطلبات تمثل القصد وسير العمل، مو الدفع.
 

عروض الطلبات هي عروض أسعار.
أوامر الشراء تُصدر للموردين.
الطلبات المفصلة تخزن معلومات طلب منظمة.
 

الطلبات:
 

• ممكن تسوي فواتير في وقت لاحق

• غالبًا ترتبط بالإيصالات

• تتبع العملية التجارية قبل الدفع
   

---

كيف تعمل واجهة API لجميع المستندات داخليًا

لما نظام خارجي يستدعي:
 

https://biz1.co.il/api.php?api=add_order2
 

تدفق التنفيذ التالي يصير داخل Biz1.
 

---

الخطوة 1: المصادقة
 

واجهة API تصادق على الـ api_token.
 

إذا مو صالح:
 

• الطلب يوقف فورًا

• ما ينشأ أي مستند

• ما يتغير أي عميل
   

إذا صالح:
 

• يتم تحميل المستخدم

• يتم تطبيق إعدادات المنظمة

• يتم فرض الصلاحيات
   

---

الخطوة 2: تحديد نوع المستند
 

واجهة API تقرا الـ document_type وتحدد:
 

• أي محرك مستندات داخلي يستخدم

• شنو قواعد التحقق اللي تنطبق

• أي قالب PDF لازم ينختار

• هل المنتجات مطلوبة

• هل بيانات الدفع مطلوبة
   

الخطوة هذي تتحكم بكل شي يجي بعدها.
 

---

الخطوة 3: تحديد العميل
 

واجهة API تحدد لمن المستند يخص.
 

في خيارين:
 

إذا cust_id متوفر:
 

• يتم تحميل العميل الموجود مباشرة
   

إذا cust_id مو متوفر:
 

• واجهة API تستخدم الاسم، الإيميل، ورقم التلفون

• العميل الموجود يتم إعادة استخدامه إذا انوجد

• وإلا، عميل جديد ينشأ بشكل تلقائي
   

هذا يعني ما يحتاج واجهة API منفصلة لإنشاء العملاء.
 

---

الخطوة 4: معالجة كائن الطلب
 

كائن الـ JSON order يحدد سلوك المستند على مستوى المستند.
 

واجهة API:
 

• تحدد العملة

• تحدد نسبة ضريبة القيمة المضافة (VAT)

• تطبق الملاحظات

• تسجل الخصومات الشاملة
   

هذا يصير الأساس المالي للمستند.
 

---

الخطوة 5: التعامل مع المنتجات وبنود السطر
 

إذا نوع المستند يتطلب منتجات:
 

• كل رقم SKU يتم التحقق منه أو ينشأ بشكل تلقائي

• السعر والكمية يتم التحقق منهم

• يتم تطبيق الخصومات

• معالجة ضريبة القيمة المضافة (VAT) يتم التعامل معاها بشكل صحيح
   

النظام يحسب:
 

• مبالغ البنود

• تأثير الخصم

• القيم الضريبية
   

إذا كان المستند إيصال يستخدم all_items_total، هذي الخطوة تتخطى.
 

---

الخطوة 6: معالجة الدفع (مستندات الإيصال)
 

بالنسبة للمستندات اللي تعتمد على الإيصالات:
 

• يتم تسجيل طريقة الدفع

• يتم حفظ معرفات بطاقة الائتمان (آخر 4 أرقام)

• يتم التعامل مع الدفعات المقسّطة

• يتم تحديد المستندات كمدفوعة بالكامل أو جزئيًا
   

هذا يأثر مباشرة على:
 

• حالة مسك الدفاتر

• رصيد العميل

• حالة المستند المرتبط
   

---

الخطوة 7: أتمتة سير العمل
 

إذا كانت أعلام الأتمتة موجودة:
 

• invoice_create

• reciept_tax_invoice
   

النظام ينشئ مستندات إضافية بشكل تلقائي.
 

أمثلة:
 

• طلب → فاتورة

• طلب → فاتورة → إيصال
   

كل المستندات هي:
 

• مرتبطة مع بعض

• مخزنة بشكل ذري

• يتم التعامل معاها كمعاملة منطقية وحدة
   

---

الخطوة 8: حفظ المستند
 

المستند ينحفظ في قاعدة البيانات.
 

في هذي الخطوة:
 

• يتم إنشاء معرف مستند

• يتم حفظ العلاقات

• يتم تلخيص القيم المالية
   

---

الخطوة 9: إنشاء PDF
 

للمستندات النهائية:
 

• يتم اختيار قالب PDF الصحيح

• يتم تطبيق العلامة التجارية واللغة

• يتم معالجة ملف PDF

• الملف يتخزن بشكل آمن
   

ملف الـ PDF يصير المخرجات الرسمية للمستند.
 

---

الخطوة 10: التسليم (اختياري)
 

إذا كانت أعلام التسليم مفعلة:
 

• البريد الإلكتروني يرسل ملف PDF كمرفق

• الواتساب يرسل رابط آمن للمستند
   

التسليم يصير بشكل غير متزامن وما يعيق الإنشاء.
 

---

رابط URL لاسترداد المستندات
 

عشان تسترجع المستندات بعدين، الأنظمة تستدعي:
 

https://biz1.co.il/api/get_document
 

واجهة API هذي:
 

• تصادق على الطلب

• تفلتر حسب العميل

• تفلتر حسب نوع المستند

• تطبق فلاتر التاريخ

• ترجع بيانات المستند الوصفية ومسارات الـ PDF
   

تستخدم حق:
 

• بوابات العملاء

• لوحات معلومات المديرين

• تقارير

• مراجعات
   

---

رابط URL لعرض PDF
 

عشان تشوف أو تنزّل ملف PDF:
 

https://biz1.co.il/dashboard/api/filesview?url=ENCODED_PDF_PATH
 

رابط URL هذا:
 

• تَبث ملفات PDF بشكل آمن

• تمنع الوصول المباشر للملفات

• تدعم العرض والتنزيل عن طريق المتصفح
   

تستخدم في:
 

• روابط البريد الإلكتروني

• رسائل الواتساب

• واجهات الإدارة
   

---

مثال واقعي شامل من الألف للياء
 

عملية تجارية نموذجية تبين كالتالي:
 

1. عميل يكمل عملية شراء

2. النظام يستدعي add_order2

3. يتم إنشاء مستند طلب

4. فاتورة تنشأ بشكل تلقائي

5. يتم تأكيد الدفع

6. فاتورة ضريبية بإيصال تنشأ

7. يتم إنشاء ملف PDF

8. ملف PDF ينرسل بالإيميل والواتساب

9. مسؤول النظام يسترجع المستندات باستخدام get_document

10. ملف PDF يتم عرضه باستخدام filesview
     

كل هذا يتم عن طريق نظام API موحد واحد.
 

---

ليش تصميم الـ API هذا مهم
 

واجهة API لجميع المستندات:
 

• تزيل المنطق المحاسبي المكرر

• تمنع المستندات غير المتناسقة

• تضمن الالتزام بمعايير الضريبة

• تبسط التكاملات

• تناسب أحجام الشركات المختلفة

• تحافظ على مسار تدقيق نظيف
   

هي مصممة عشان تكون صامدة للمستقبل، قابلة للتوسع، وآمنة.
 

---

فهم نهائي
 

إذا أحد سأل:
 

“شنو تسوي واجهة API لجميع المستندات؟”
 

الجواب الصحيح هو:
 

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

```