المصادقة

أرسل مفتاح الـ API في الـ Header Authorization بصيغة Bearer مع كل طلب:

Authorization: Bearer ksr_live_3f9a...

يبدأ المفتاح بـ ksr_live_ وبعده 64 حرفاً بالنظام الست عشري (hex)، أما مفتاح الاختبار فيبدأ بـ ksr_test_ ولا يصل إلا إلى بيئة الاختبار (راجع وضع الاختبار). احفظه على السيرفر عندك فقط، لأن أي شخص يحصل عليه يستطيع التصرف باسم التاجر.

الصلاحيات

يحدد التاجر لكل مفتاح مستوى صلاحية على كل مورد، بالصيغة resource:level:

الصلاحية	ماذا تتيح
customers:read	عرض قائمة العملاء وبيانات كل عميل
customers:write	كل ما سبق، بالإضافة إلى إنشاء العملاء وتعديلهم
sales_invoices:read	عرض فواتير المبيعات وتحميلها بصيغة PDF و XML
sales_invoices:write	كل ما سبق، بالإضافة إلى إصدار فواتير المبيعات
payments:read	عرض المدفوعات وبيانات كل دفعة
payments:write	كل ما سبق، بالإضافة إلى تسجيل المدفوعات
credit_notes:read	عرض الإشعارات الدائنة وبيانات كل إشعار، مع ملفي PDF و XML
credit_notes:write	كل ما سبق، بالإضافة إلى إصدار الإشعارات الدائنة

صلاحية write تشمل read تلقائياً. إذا أرسلت طلباً لا يملك المفتاح صلاحيته، يرجع الخطأ 403 missing_permission، ويوضح الحقل requiredPermission الصلاحية المطلوبة. ستُضاف موارد أخرى مع توسّع الـ API.

الفروع

قد يحصر التاجر المفتاح في فروع معيّنة. أي طلب يخص فرعاً خارجها يرجع بالخطأ 403 branch_not_allowed.

متى يُرفض المفتاح

الكود	الحالة	السبب
missing_api_key	401	الـ Header Authorization: Bearer غير موجود
invalid_api_key	401	صيغة المفتاح خاطئة أو المفتاح غير موجود
revoked_api_key	401	ألغى التاجر المفتاح
expired_api_key	401	انتهت صلاحية المفتاح
tenant_suspended	403	حساب التاجر في كسور موقوف

إعادة المحاولة لن تحل أياً من هذه الحالات. اطلب من التاجر مفتاحاً جديداً، أو أن يعيد تفعيل حسابه.