كيفية ربط متجر أو نظام بواجهة API للفواتير
7 دقائق قراءة
عندما يكون الطلب أو العميل موجودًا أصلًا في متجر أو CRM، فإن إعادة كتابته داخل برنامج الفواتير تضاعف العمل. واجهة API تنقل البيانات من النظام المصدر إلى الفاتورة، لكن التكامل الجيد يحتاج قواعد واضحة للهوية والصلاحيات ومنع التكرار.
حدد هدف التكامل قبل كتابة الكود
- إنشاء فاتورة عند اكتمال طلب
- قراءة حالة الفاتورة من النظام الداخلي
- مزامنة رقم الفاتورة ورابطها مع سجل العميل
- إنشاء فواتير لخدمة أو اشتراك من نظام آخر
الخطوة الأولى: أنشئ مفتاحًا بأقل صلاحية
إذا كان النظام يحتاج عرض الفواتير فقط، استخدم مفتاح قراءة. امنح الكتابة فقط للتكامل الذي يجب أن يصدر فواتير. سمِّ المفتاح باسم النظام والبيئة، ولا تستخدم مفتاح الإنتاج في الاختبارات المحلية.
اربط نظامك بواجهة فواتير آمنة
اقرأ الفواتير أو أنشئها بمفاتيح محددة الصلاحية وقابلة للإلغاء.
الخطوة الثانية: خزّن المفتاح على الخادم
لا تضع مفتاح API في JavaScript الذي يعمل داخل المتصفح أو تطبيق مكشوف. خزّنه كمتغير بيئة على خادم المتجر، وأرسله في ترويسة Authorization عند الاتصال.
الخطوة الثالثة: طابق حقول الفاتورة
حدد نوع الفاتورة وإعداد الضريبة وبيانات المشتري والبنود والكميات والأسعار. تحقق من أن النظام المصدر يرسل الريال والقيم الرقمية بدقة، وأن الفاتورة الضريبية للشركات تحتوي بيانات المشتري المطلوبة.
لا تسمح للعميل البرمجي باختيار مساحة عمل من جسم الطلب. يجب أن يحدد الخادم المنشأة من مفتاح API نفسه لمنع الوصول المتقاطع.
الخطوة الرابعة: امنع إصدار فاتورتين للطلب نفسه
احفظ رقم الفاتورة الناتج داخل الطلب في نظامك. قبل إعادة المحاولة بعد انقطاع الشبكة، تحقق هل تم الإصدار سابقًا. صمم عملية إعادة المحاولة لتتعامل مع الردود المؤقتة دون إنشاء نسخة ثانية.
الخطوة الخامسة: تعامل مع الأخطاء بوضوح
- 401 أو 403: المفتاح غير صالح أو لا يملك الصلاحية
- 400: بيانات الفاتورة ناقصة أو غير صحيحة
- 429: تجاوز معدل الطلبات ويجب الانتظار
- 5xx: خطأ مؤقت يستحق إعادة محاولة محدودة مع تسجيل الحدث
المراقبة وتدوير المفاتيح
راجع آخر استخدام لكل مفتاح، وألغ المفتاح عند خروج مطور أو إيقاف النظام، وأنشئ بديلًا عند الاشتباه بتسربه. لا تخزن المنصة المفتاح الخام بعد إنشائه، لذلك انسخه مرة واحدة إلى مخزن أسرارك.
اختبار قبل الإنتاج
اختبر فاتورة مبسطة وأخرى ضريبية، وحالة عميل بلا رقم ضريبي، وبندًا متعدد الكمية، وفشلًا متعمدًا. راجع PDF والضريبة ورقم الفاتورة والرابط الناتج قبل ربط الحدث بطلبات العملاء الحقيقية.
أسئلة شائعة
هل يمكن إنشاء مفتاح قراءة فقط؟
نعم. يمكنك تحديد صلاحية قراءة فقط أو قراءة وكتابة حسب حاجة التكامل.
أين يجب تخزين مفتاح API؟
على خادم النظام أو في مخزن أسرار، وليس في كود المتصفح أو مستودع عام.
هل يستطيع المفتاح اختيار منشأة أخرى؟
لا. يحدد فوتّر مساحة العمل من المفتاح نفسه ولا يقبل هوية منشأة من العميل البرمجي.
اربط نظامك بواجهة فواتير آمنة
اقرأ الفواتير أو أنشئها بمفاتيح محددة الصلاحية وقابلة للإلغاء.
استكشف واجهة API