بالنسبة للمطورين وأصحاب الأعمال المهتمين بالتكنولوجيا، تفتح SmartPOS AI REST API عالمًا من عمليات التكامل المخصصة. سواء كنت تريد مزامنة المنتجات مع نظام تخطيط موارد المؤسسات (ERP)، أو سحب بيانات المبيعات إلى لوحة معلومات BI، أو إنشاء واجهة أمامية مخصصة بالكامل، فإن واجهة برمجة التطبيقات (API) تمنحك وصولاً برمجيًا إلى المنتجات والإيصالات والورديات. يغطي هذا الدليل المصادقة ونقاط النهاية الأساسية وأفضل الممارسات لبناء عمليات تكامل موثوقة.
الحصول على مفتاح API الخاص بك
يتضمن كل حساب SmartPOS AI في خطة مدفوعة (سعر البدء 29 يورو شهريًا وما فوق) الوصول إلى واجهة برمجة التطبيقات (API). قم بتسجيل الدخول إلى المكتب الخلفي وانتقل إلى الإعدادات ← API ← إنشاء مفتاح API. يقوم النظام بإنشاء X-API-Key الذي ستدرجه في رأس كل طلب. تعامل مع هذا المفتاح ككلمة مرور، وقم بتخزينه في متغيرات البيئة، ولا تلزمه مطلقًا بالتحكم في الإصدار، وقم بتدويره بشكل دوري. إذا تم اختراق أحد المفاتيح، فيمكنك إبطاله وإنشاء مفتاح جديد على الفور من نفس الشاشة دون أي توقف عن عمليات التكامل النشطة.
فهم عنوان URL الأساسي والمصادقة
يتم إرسال جميع طلبات واجهة برمجة التطبيقات (API) إلى https://api.smartposai.com/v1/ عبر HTTPS. تتم معالجة المصادقة عبر رأس X-API-Key - لا يلزم وجود رموز OAuth المميزة أو ملفات تعريف الارتباط للجلسة. تستخدم كل استجابة رموز حالة HTTP القياسية: 200 للنجاح، و201 لإنشاء الموارد، و400 للطلبات السيئة، و401 لفشل المصادقة، و429 عندما تصل إلى الحد الأقصى للمعدل. يتم إرجاع الاستجابات بتنسيق JSON مع حقول مغلف متسقة (success، data، error) بحيث يمكن لرمز التكامل الخاص بك استخدام نمط تحليل واحد عبر جميع نقاط النهاية.
نقطة نهاية المنتجات
تتيح لك نقطة نهاية المنتجات سرد العناصر الموجودة في الكتالوج الخاص بك وإنشائها وتحديثها وحذفها. تقوم مكالمة GET /products بإرجاع قائمة مقسمة إلى صفحات تحتوي على عوامل تصفية للفئة والرمز الشريطي وحالة المخزون ونطاق السعر. استخدم POST /products مع نص JSON لإنشاء منتج جديد، بما في ذلك حقول الاسم والسعر ومعدل الضريبة والرمز الشريطي وكمية المخزون الأولية. تدعم طريقة PATCH /products/{id} التحديثات الجزئية - وهي مفيدة لمزامنة تغيرات الأسعار من نظام خارجي دون الكتابة فوق الحقول الأخرى. تؤدي كل طفرة إلى تشغيل حدث webhook إذا كان لديك حدث مسجل.
نقاط نهاية الإيصالات والورديات
توفر نقطة نهاية الإيصالات إمكانية الوصول للقراءة إلى المبيعات المكتملة. GET /receipts يدعم تصفية النطاق الزمني، وتصفية طريقة الدفع، والبحث عن النص الكامل حسب رقم الإيصال. يحتوي كل كائن إيصال على بنود السطر وإجماليات الضرائب وتفاصيل الدفع والموظف المرتبط ومعرف الوردية. تعرض نقطة نهاية الورديات أوقات فتح/إغلاق الوردية، وبيانات التسوية النقدية، وملخصات المبيعات لكل نوبة. توفر نقطتا النهاية هاتان معًا أدوات ذكاء الأعمال أو عمليات التكامل المحاسبية (QuickBooks وFreshBooks وXero وZohoBooks) كل ما تحتاجه لمسك الدفاتر الآلي.
تتيح لنا واجهة برمجة التطبيقات (API) توصيل SmartPOS AI بنظام المستودعات الخاص بنا في فترة ما بعد الظهر - والوثائق بهذا الوضوح.
حدود المعدل ومعالجة الأخطاء
يفرض SmartPOS AI حدًا للمعدل يبلغ 100 طلب في الدقيقة لكل مفتاح API. عندما تقترب من الحد الأقصى، تتضمن الاستجابة رؤوس X-RateLimit-Remaining وX-RateLimit-Reset بحيث يمكن التحكم في التعليمات البرمجية الخاصة بك بشكل استباقي. إذا تجاوزت الحد، فستتلقى استجابة 429 Too Many Requests - قم بتنفيذ التراجع الأسي وأعد محاولة المنطق للتعامل مع هذا بأمان. بالنسبة للعمليات المجمعة مثل مزامنة الكتالوج، استخدم نقاط النهاية المجمعة أو جدولة المكالمات خلال ساعات خارج أوقات الذروة. ستوفر لك المعالجة القوية للأخطاء وتسجيلها من البداية ساعات من تصحيح الأخطاء لاحقًا.