ربط تاجر

يقوم التاجر بالخطوات الأولى من لوحة تحكم كسور، وتكمل أنت الباقي. إذا لم يُصدر التاجر مفتاحاً من قبل، فأرسل له هذه الصفحة.

1. يدخل التاجر إلى لوحة التحكم

يدخل التاجر إلى لوحة تحكم كسور بمستخدم يملك الصلاحية integration.api_keys.management. وبدونها لا تظهر المطوّرون في قائمة الإعدادات.

2. يفتح الإعدادات ← المطوّرون

في صفحة المطوّرون خمسة تبويبات:

التبويب	ماذا فيه
نظرة عامة	مفاتيح التاجر، وبيئة الاختبار، والطلبات خلال آخر 30 يوماً
مفاتيح الربط	كل المفاتيح: إصدارها وتعديلها وإبطالها
سجل الطلبات	كل طلب أرسله مفتاح خلال آخر 30 يوماً
Webhooks	الـ Endpoints التي سجّلتها المفاتيح، وكل حدث أُرسل إليها. التفاصيل في Webhooks
بيئة الاختبار	النسخة المنفصلة من البيانات الأساسية التي تصل إليها مفاتيح الاختبار

3. ينشئ بيئة الاختبار

من تبويب بيئة الاختبار يضغط التاجر إنشاء بيئة الاختبار. تنسخ كسور إليها فروع التاجر وأصنافه وطرق الدفع وشجرة الحسابات، ولا تنسخ عملاءه ولا فواتيره. يستغرق التجهيز بضع دقائق، وترجع مفاتيح الاختبار 503 sandbox_unavailable حتى يظهر في التبويب بيئة الاختبار جاهزة.

تحتفظ بيئة الاختبار بالمعرّفات الفعلية لما تنسخه، فمعرّف الفرع أو الصنف أو طريقة الدفع الذي تستخدمه في بيئة الاختبار هو نفسه في البيانات الفعلية. أما العملاء فلا يُنسخون، فمعرّفاتهم مختلفة.

4. يُصدر مفتاح اختبار

من تبويب مفاتيح الربط يضغط التاجر إصدار مفتاح ويعبّئ النموذج:

الحقل	ماذا يختار
نوع المفتاح	اختبار. مفتاح الاختبار لا يصل إلا إلى بيئة الاختبار، ولا يمكن اختياره إلا بعد إنشائها.
اسم المفتاح	اسم نظامك. بالاسم يعرف التاجر أيّ نظام يستعمل المفتاح يوم يحتاج إلى إبطاله.
الصلاحيات	لكل مورد: بلا أو قراءة أو قراءة وكتابة. امنح أقل ما يكفي، والجدول في الأسفل يوضح ما تحتاجه كل مهمة.
الفروع	الفروع التي يعمل فيها المفتاح. إذا تُركت كلها فارغة يعمل المفتاح في جميع الفروع.
ينتهي في	اختياري. يتوقف المفتاح عند بداية هذا اليوم، وترسل كسور تذكيراً بالبريد قبله بـ 14 يوماً ثم بـ 3 أيام.

يظهر المفتاح مرة واحدة فقط، ومعه التنبيه انسخ المفتاح الآن: لن يظهر مرة أخرى. ينسخه التاجر ويرسله إليك. وبعد إغلاق هذه الرسالة لا يمكن عرض المفتاح مرة أخرى: إذا فُقد، يبطله التاجر ويصدر مفتاحاً جديداً. ولا يزيد عدد المفاتيح النشطة لدى التاجر على 50 مفتاحاً من كل نوع.

الصلاحيات التي تحتاجها كل مهمة

المهمة	الصلاحيات
قراءة الكتالوج: الفروع والأصناف وطرق الدفع	branches:read و items:read و payment_methods:read
البحث عن العملاء وإنشاؤهم	customers:write
إصدار فواتير المبيعات	sales_invoices:write
تسجيل المدفوعات بعد البيع	payments:write
إصدار الإشعارات الدائنة	credit_notes:write
القراءة فقط، مثل نسخ البيانات إلى نظام ERP	مستوى read لكل مورد تقرؤه

صلاحية write تشمل read. والطلب الذي لا يملك المفتاح صلاحيته يرجع 403 missing_permission، ويوضح الحقل requiredPermission في الخطأ الصلاحية المطلوبة. التفاصيل في المصادقة.

5. أرسل أول طلب

اقرأ أحد العملاء الموجودين في كل بيئة اختبار، بمفتاح الاختبار:

curl -i https://api.kosoor.com.sa/v1/customers/5a4db0c5-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer ksr_test_..."

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Kosoor-Mode: test
Request-Id: req_01JC3W8Z9Q4M2T7XKD5R6VBN0P

{
  "id": "5a4db0c5-0000-4000-8000-000000000001",
  "object": "customer",
  "type": "person",
  "referenceId": null,
  "firstName": "Sandbox Person",
  "lastName": null,
  "phone": "+966500000001",
  "email": null,
  "isActive": true,
  "branchId": null,
  "company": null,
  "address": {
    "street": null,
    "buildingNumber": null,
    "postalCode": null,
    "district": null,
    "city": null,
    "country": null
  },
  "metadata": {},
  "standardInvoiceMissing": null,
  "createdAt": "2026-11-07T09:12:40.513Z"
}

الـ Header Kosoor-Mode: test يعني أن الطلب وصل إلى بيئة الاختبار. وردود المفتاح الفعلي لا تحمله.

6. ابحث عن الطلب في سجل الطلبات

في تبويب سجل الطلبات يرى التاجر كل طلب أرسله مفتاح خلال آخر 30 يوماً، الأحدث أولاً. ويمكن التصفية حسب نوع المفتاح (فعلي أو اختبار) والمفتاح والحالة والمسار والتاريخ. ويعرض زر التفاصيل الـ Request-Id للطلب. ولا يُحفظ جسم الطلب والرد إلا للطلبات المرفوضة والفاشلة.

7. ابنِ الربط على بيئة الاختبار

ابنِ كل الخطوات بمفتاح الاختبار: تسجيل عملية بيع، واسترجاع أو تصحيح عملية بيع، وكل ما يقوم به نظامك. وفي بيئة الاختبار عملاء جاهزون بنتائج معروفة، فتستطيع اختبار رفض الهيئة وحالات الرفض الأخرى دون أن تجهّز البيانات بنفسك. التفاصيل في وضع الاختبار.

8. التشغيل الفعلي

عندما يعمل نظامك على بيئة الاختبار:

1. يُصدر التاجر مفتاحاً ثانياً، نوع المفتاح فيه فعلي، بالصلاحيات والفروع نفسها.
2. تستبدل مفتاح الاختبار بالمفتاح الفعلي. ولا يتغير شيء آخر: نفس الـ Host ونفس المسارات ونفس معرّفات الفروع والأصناف وطرق الدفع.
3. ترسل طلباً فعلياً واحداً، ويتحقق منه التاجر في سجل الطلبات تحت فعلي.

راجع قائمة التحقق قبل التشغيل الفعلي قبل أول عملية بيع حقيقية.

ولإيقاف مفتاح، يبطله التاجر من تبويب مفاتيح الربط، فيتوقف فوراً كل نظام يستعمله، ويرجع 401 revoked_api_key.