الربط البرمجي API: المفاتيح وأمثلة الطلبات
أنشئ مفاتيح ربط آمنة ليتصل متجرك أو تطبيقك بدفّة، مع شرح كل مسار وأمثلة عملية
الربط البرمجي (API) يتيح لأنظمة أخرى (متجرك الخاص، تطبيق المندوبين، نظام شركة شقيقة) أن تقرأ من دفّة الأصناف والأرصدة والعملاء والفواتير، وأن تنشئ عملاء وفواتير مباشرة. تمنح المبرمج مفتاحًا بصلاحيات تحددها، وتلغيه متى شئت.
قبل أن تبدأ
- صلاحية مفاتيح الربط API (لمالك الحساب افتراضيًا).
- مبرمج يتعامل مع واجهات REST وصيغة JSON.
إنشاء مفتاح
- افتح الإعدادات ← التكاملات والفوترة الإلكترونية ثم تبويب الربط البرمجي API.
- في بطاقة مفتاح جديد اكتب الاسم (مثال: متجر سلة، تطبيق المندوبين).
- حدد الصلاحيات: قراءة (أصناف، أرصدة، عملاء، فواتير) و/أو كتابة (إنشاء فواتير وعملاء).
- اضغط إنشاء.
- يظهر المفتاح مرة واحدة فقط. اضغط نسخ واحفظه في مكان آمن.
إدارة المفاتيح
يعرض الجدول لكل مفتاح: الاسم ومن أنشأه، والبادئة (أول أحرف المفتاح للتعرف عليه)، والصلاحيات، وآخر استخدام، والحالة. زر إلغاء يوقف المفتاح فورًا ونهائيًا.
طريقة الاتصال (للمبرمج)
- العنوان الأساسي يظهر في جدول التوثيق السريع، وصيغته:
https://نطاقك/rest.php?r=المسار - أرسل المفتاح في الترويسة:
Authorization: Bearer awj_... - الردود JSON بترميز UTF-8، وتحتوي دائمًا الحقل ok.
- طلبات الإنشاء ترسل جسمًا بصيغة JSON.
المسارات المتاحة
| الطلب | المسار | الوظيفة | الصلاحية |
|---|---|---|---|
| GET | ?r=items&q=&page=1 | الأصناف مع السعر والرصيد (100 لكل صفحة) | قراءة |
| GET | ?r=item&code=XXXX | صنف بالكود أو الباركود + الرصيد لكل مستودع | قراءة |
| GET | ?r=stock&warehouse=W1 | أرصدة المخزون (اختياريًا لمستودع بكوده) | قراءة |
| GET | ?r=customers&q= | العملاء وأرصدتهم | قراءة |
| POST | ?r=customers | إنشاء عميل | كتابة |
| GET | ?r=invoices&from=2026-01-01&to=2026-12-31 | فواتير المبيعات لفترة | قراءة |
| GET | ?r=invoice&number=INV-26-00001 | فاتورة بالتفاصيل ورمز QR | قراءة |
| POST | ?r=invoices | إنشاء فاتورة وترحيلها | كتابة |
| GET | ?r=balance&customer_code=C00002 | رصيد عميل وفواتيره المفتوحة | قراءة |
أمثلة
قراءة صنف بالباركود: أرسل GET إلى rest.php?r=item&code=6901234567890 مع ترويسة المفتاح، فيعود الصنف بالاسم والسعر ونسبة الضريبة والرصيد الإجمالي وجدول warehouses بالرصيد في كل مستودع.
إنشاء عميل: أرسل POST إلى rest.php?r=customers بالجسم:
{"name": "مؤسسة النور التجارية", "mobile": "0551234567", "vat_no": "310123456700003", "city": "جدة"}
فيعود id والكود الجديد للعميل (مثل C00045).
إنشاء فاتورة: أرسل POST إلى rest.php?r=invoices بالجسم:
{"customer_code": "C00045", "pay_method": "credit", "reference": "WEB-1001", "lines": [{"code": "LD-A2502", "qty": 2, "price": 50}]}
- customer_code اختياري؛ بدونه تُسجَّل على العميل النقدي.
- pay_method: cash أو card أو bank أو credit.
- price اختياري؛ بدونه يُستخدم سعر البيع المعرّف للصنف. ويمكن إضافة discount.
يعود رقم الفاتورة والإجمالي والضريبة ورمز QR ورابط عرض الفاتورة.
الأثر عند إنشاء فاتورة عبر API
تُرحَّل الفاتورة فورًا: يُخصم المخزون، ويُسجَّل القيد المحاسبي، وتُرسل لمنصة «فاتورة» إن كان الربط مفعّلًا، ويُرسل واتساب الآلي إن كان مفعّلًا. تخضع لنفس قواعد النظام (الرقابة الائتمانية، حماية هامش الربح، الاعتمادات).
رموز الأخطاء
| الرمز | المعنى |
|---|---|
| 401 | المفتاح مفقود أو غير صالح أو ملغى |
| 402 | اشتراك المنشأة منتهٍ |
| 403 | المفتاح لا يملك صلاحية القراءة أو الكتابة المطلوبة |
| 404 | المسار أو السجل غير موجود |
| 409 | المستند يحتاج اعتمادًا قبل الترحيل |
| 422 | خطأ في البيانات، مثل صنف غير معروف أو اسم عميل مفقود |
أسئلة شائعة
هل يمكن ربط متجر سلة بالـ API؟
يمكن، لكن الأسهل استخدام ربط متجر سلة الجاهز، فهو يحوّل الطلبات ويزامن المخزون دون برمجة.
هل الاتصال آمن؟
نعم، ما دام عبر https والمفتاح محفوظ لدى المبرمج فقط. وكل استخدام يُحدّث عمود آخر استخدام.