BenimPOS API: المفاتيح وحساب الاختبار والتوثيق
الحصول على مفاتيح API، وحساب الاختبار المشترك، وتوثيق المطورين (benimpos.com/developers)، والأسئلة الشائعة.
تتيح لك واجهة BenimPOS API الوصول إلى بيانات حسابك من برنامجك الخاص: يمكنك نقل المنتجات والمخزون والأسعار إلى متجرك الإلكتروني، وتسجيل طلبات الموقع في BenimPOS كمبيعات، وجلب بيانات المبيعات والعملاء والموردين وفواتير المشتريات والإيرادات والمصروفات إلى نظام المحاسبة أو التقارير لديك.
وحدة API مدفوعة سنويًا بمبلغ 1.800,00 TL وتُشترى من تبويب عمليات التكامل › تكامل API. لا توجد بيئة اختبار منفصلة؛ يمكنك استخدام حساب الاختبار المشترك للتجارب (أدناه). لا يمكن إرسال إيصالات إلى جهاز الكاشير المالي (yazarkasa) عبر API؛ فتكاملات أجهزة الكاشير المالية تعمل داخل تطبيقات BenimPOS فقط.
توثيق API
جميع الخدمات والمعاملات وأمثلة الطلبات والاستجابات ورموز الأخطاء وحدود الاستخدام موجودة في صفحة المطورين لدينا: benimpos.com/developers. الصفحة باللغتين التركية والإنجليزية. يمكنك تشغيل كل عملية من المتصفح بزر جرّب في الصفحة ورؤية استجابتها.
تُعلن الخدمات المضافة إلى API والتغييرات في صفحة الجديد. لم يعد مستند PDF القديم يُحدَّث؛ اعتمد على صفحة المطورين لأسماء الحقول والسلوك.
الحصول على مفاتيح API
اشترِ الوحدة
في لوحة الويب افتح تبويب تكامل API في صفحة عمليات التكامل في أسفل القائمة اليسرى، وأتمّ الشراء عبر شراء في البطاقة.
افتح بياناتك
بعد الشراء يظهر سطر تكامل API في الجدول أعلى الصفحة. اضغط رمز القلم في السطر؛ تُفتح نافذة بيانات تكامل API الخاصة بك.
انسخ القيم
في النافذة ثلاث قيم: Branch ID (رمز المتجر)، وApi Key، وSecret Key. انسخها برمز النسخ وأدخلها في إعدادات تطبيقك.
المفاتيح تمنح وصولًا كاملًا إلى حسابك: لا تكتبها في مستودع الشيفرة ولا في شيفرة تعمل في المتصفح (JavaScript) ولا في الرسائل؛ احفظها على جهة الخادم فقط. إذا ظننت أن المفتاح تسرّب فأنشئ مفتاحًا جديدًا برمز التجديد في النافذة؛ يصبح المفتاح القديم غير صالح فورًا، فلا تنسَ تحديث القيمة في تطبيقك.
- كل فرع حساب منفصل وله Branch ID ومفاتيح خاصة به. تُفعَّل وحدة API بشكل منفصل في كل حساب فرع ستصل إلى بياناته.
- عند انتهاء مدة الوحدة تعمل الخدمات 3 أيام أخرى، ثم تُرفض الطلبات. جدّد المدة عبر تمديد المدة في صفحة عمليات التكامل.
حساب الاختبار
الطلبات تقرأ البيانات الحقيقية لحسابك وتغيّرها. أثناء تطوير التكامل استخدم حساب الاختبار المشترك حتى لا تمسّ بياناتك. بيانات الدخول موجودة في قسم حساب الاختبار في توثيق API: سجّل الدخول وخذ المفاتيح من سطر عمليات التكامل › تكامل API، واستخدمها في تطبيقك أو في شاشة جرّب في التوثيق.
حساب الاختبار متاح للجميع؛ ويمكن لأي شخص رؤية بياناته وتغييرها. لا تُدخل بيانات عملاء أو مبيعات حقيقية.
ملخص قصير
| الموضوع | القيمة |
|---|---|
| العنوان | https://dev.benimpos.com/api/<servis> (مثلًا /api/products) |
| الطريقة | POST، جسم JSON، بحد أقصى 2 MB |
| المصادقة | ترويسات HTTP: Branch-ID، Api-Key، Secret-Key |
| اختيار العملية | الحقل processType في الجسم (مثلًا "list"، "create") |
| الخدمات | المنتجات وفواتير المشتريات (products)، العملاء (customers)، المبيعات (sales)، الموردون (firms)، الفئات (categories)، طرق الدفع (paymentTypes)، الإيرادات والمصروفات (incomeExpenses) |
الأسئلة الشائعة
هل يمكنني إنشاء فاتورة مشتريات عبر API؟
نعم. عملية createPurchaseInvoice في خدمة المنتجات تحفظ الفاتورة وتُدخل المنتجات إلى المخزون، وفي الفاتورة على الحساب الآجل تسجّل المبلغ في حساب المورد. إذا أُرسلت الفاتورة نفسها مرة ثانية فلا يُنشأ سجل جديد.
هل يمكنني تعيين مجموعة (فئة) للمنتج عبر API؟
لا، لا يوجد حقل للمجموعة في إضافة المنتج وتحديثه. يمكنك قراءة المجموعات بخدمة categories، وتعيين المجموعة للمنتجات من لوحة الويب أو عبر Excel.
ماذا أفعل حتى لا يُسجَّل الطلب نفسه كبيع مرتين؟
عند إنشاء البيع اكتب رقم طلبك في الحقل externalRef. الطلب الثاني بالرقم نفسه لا يفتح بيعًا جديدًا، بل يعيد رمز البيع الأول.
متى يظهر في API البيع الذي أجريته في تطبيق سطح المكتب؟
بعد أن يرسل تطبيق سطح المكتب البيانات إلى الويب (المزامنة). يمكنك بدء المزامنة فورًا من بطاقة تكامل البيانات في الصفحة الرئيسية لتطبيق سطح المكتب. أما المبيعات في تطبيقي الويب والجوال فتظهر فورًا.
كيف أحصل على دعم تقني؟
اكتب سؤالك إلى [email protected]. أرفق وقت الطلب وعنوانه وجسمه (من دون المفاتيح) ورمز حالة HTTP ورسالة الاستجابة، وترويسات الاستجابة التي تبدأ بـ X-BP- إن وُجدت. لا تشارك مفاتيح API الخاصة بك.