مواصفات تكامل واجهة برمجة التطبيقات
التكامل: طلبات المتجر إلى المحاسبة
الإصدار: 1.0
أعدّه: حمزة الإدريسي
التاريخ: 5 أبريل 2029
1. الغرض
إرسال كل طلب مدفوع من المتجر الإلكتروني إلى نظام المحاسبة كفاتورة مبيعات، حتى لا تعيد المالية إدخاله يدويًا.
2. الأنظمة
- يرسل البيانات: المتجر الإلكتروني (API v2)
- يستقبل البيانات: نظام المحاسبة (REST API)
3. تدفق البيانات
1. يدفع العميل ثمن الطلب.
2. يرسل المتجر webhook إلى خدمة التكامل.
3. تحوّل الخدمة الطلب إلى فاتورة وتستدعي API المحاسبة.
4. يعيد نظام المحاسبة رقم الفاتورة، وتحفظه الخدمة على الطلب.
4. نقاط النهاية والرسائل
| الطريقة والمسار | ماذا يفعل | الحقول الرئيسية | ماذا يُرجع |
|---|---|---|---|
| POST /invoices | إنشاء فاتورة | Body: العميل، البنود، الضريبة، الإجمالي | يعيد: معرّف الفاتورة ورقمها |
| GET /customers?email= | البحث عن عميل | يعيد: معرّف العميل أو فراغًا | |
| POST /customers | إنشاء عميل | Body: الاسم، البريد الإلكتروني، العنوان |
5. ربط الحقول
order.total_paid → invoice.total
order.billing_email → customer.email
order.items[].sku → line.product_code
6. المصادقة والأمان
OAuth 2.0 client credentials. تستمر الرموز ساعة واحدة. تُحفظ الأسرار في الخزنة، ولا تُوضع في الشيفرة أبدًا. تستخدم جميع الاستدعاءات HTTPS. تُوقَّع طلبات webhook ويُتحقق من التوقيع.
لا تُرسل البيانات الشخصية إلا عند الحاجة، ولا تُكتب في السجلات، وتشملها شروط الخصوصية في النظامين.
7. الأخطاء وإعادة المحاولة
أعد المحاولة عند 429 و5xx حتى 5 مرات بتأخيرات متزايدة. لا تعد المحاولة عند أخطاء 4xx؛ سجّلها ونبّه المالية. لكل فاتورة مفتاح فريد حتى لا تنشئ إعادة المحاولة نسخة مكررة.
8. الحدود والأحجام
يسمح API المحاسبة بـ60 استدعاءً في الدقيقة. المتوقع 400 طلب يوميًا، وحتى 2000 في أيام التخفيضات.
9. الاختبار
استخدم بيئة الاختبار (sandbox) لنظام المحاسبة. اختبر طلبًا عاديًا، وطلبًا بخصم، واستردادًا، وعميلًا موجودًا مسبقًا، وانقطاعًا في API.
10. المسؤولون والدعم
المسؤول: فريق التجارة الإلكترونية. الدعم: حمزة الإدريسي. التصعيد: مكتب دعم مزوّد نظام المحاسبة.
11. التغييرات وإدارة الإصدارات
يُخطر أي طرف الآخر قبل 30 يومًا بأي تغيير جذري.