الانتقال إلى المحتوى الرئيسي

مقدمة

يتيح لك Kosoor Merchant API ربط نظامك ببيانات التاجر في كسور. يمكنك إدارة العملاء، وإصدار فواتير المبيعات، وتسجيل المدفوعات، وإصدار الإشعارات الدائنة.

رابط الـ API​

https://api.kosoor.com.sa

تبدأ جميع الـ Endpoints بـ /v1، ويتم الاتصال عبر HTTPS فقط. الطلبات والردود بصيغة JSON، وأسماء الحقول بصيغة camelCase.

الحصول على مفتاح API​

يُنشئ التاجر المفتاح من لوحة تحكم كسور، من شاشة مفاتيح الربط، ثم يرسله إليك. كل مفتاح مرتبط بتاجر واحد، ويحمل الصلاحيات التي اختارها التاجر فقط، وقد يكون مقصوراً على فروع معيّنة. التفاصيل في صفحة المصادقة.

أول طلب​

curl https://api.kosoor.com.sa/v1/customers?limit=1 \
  -H "Authorization: Bearer ksr_live_..."
{
  "data": [],
  "hasMore": false
}

كل كائن يحدد نوعه​

كل كائن يرجعه الـ API يحمل الحقل object، وهو نص ثابت يحدد نوع الكائن، مثل customer أو salesInvoice أو payment أو creditNote، وقيمته لا تتغير للنوع الواحد. استخدمه عندما يستقبل جزء واحد من الكود عندك أكثر من نوع، مثل حفظ الردود أو تسجيلها، بدل أن تستنتج النوع من الرابط أو من الحقول الموجودة.

{
  "id": "3f1c2a6e-8b4d-4e2a-9c1f-5d7e8a9b0c12",
  "object": "salesInvoice",
  "number": "INV-1042"
}

قواعد عامة لكل الطلبات​

  • Request-Id: يصلك في كل Response، سواء نجح الطلب أو فشل. أرفقه عند التواصل مع دعم كسور بخصوص أي طلب.
  • اللغة: أرسل Accept-Language: ar لتصلك رسائل الأخطاء بالعربية، وإلا فستصلك بالإنجليزية. اللغة تغيّر نص الرسالة فقط، أما الأكواد وأسماء الحقول فلا تتغيّر.
  • تحقق صارم من المدخلات: أي حقل في الـ Body أو أي Query Parameter لا يعرفه الـ API يُرفض بالكود unknown_parameter، حتى لا يمرّ خطأ إملائي دون أن تنتبه له.
  • الـ Body: يجب أن يكون Content-Type: application/json، وألا يتجاوز حجمه 1 ميغابايت.
  • طلبات الإنشاء والتعديل: كل طلب POST وPATCH يجب أن يحمل الـ Header Idempotency-Key، حتى لا تؤدي إعادة المحاولة إلى تسجيل العملية مرتين. التفاصيل في منع تكرار الطلبات.
  • الأخطاء: جميع الأخطاء ترجع بالشكل نفسه، ومعها code ثابت يمكنك الاعتماد عليه في الكود. القائمة الكاملة في أكواد الأخطاء.