# Kosoor Merchant API — كسور للمطورين

> يتيح لك Kosoor Merchant API ربط نظامك ببيانات منشأة تستخدم كسور: العملاء وفواتير المبيعات والمدفوعات والإشعارات الدائنة. رابط الـ API هو `https://api.kosoor.com.sa`، وكل المسارات تبدأ بـ `/v1`، والطلبات والردود بصيغة JSON وأسماء الحقول بصيغة camelCase، عبر HTTPS فقط.

الدعم: عبر واتساب فقط على الرقم [+966 12 606 1770](https://wa.me/966126061770)، بلا مكالمات ولا بريد إلكتروني. أرفق الـ `Request-Id` للطلب الذي تسأل عنه.

## تعليمات لوكلاء الذكاء الاصطناعي (AI agents)

- أرسل مع كل طلب الـ Header `Authorization: Bearer <key>`. التاجر هو من يصدر المفتاح، ولا توجد طريقة دخول أخرى.
- ابنِ واختبر بمفتاح اختبار (`ksr_test_...`)، فهو لا يصل إلا إلى بيئة الاختبار الخاصة بالتاجر. تأكد أثناء البناء أن كل رد يحمل الـ Header `Kosoor-Mode: test`، ولا تنتقل إلى المفتاح الفعلي (`ksr_live_...`) إلا عندما يكون التاجر جاهزاً للتشغيل الفعلي.
- أرسل الـ Header `Idempotency-Key` مع كل طلب `POST` و`PATCH`. أنشئ مفتاحاً واحداً لكل عملية (UUID يكفي)، وأرسل المفتاح نفسه عند إعادة محاولة العملية نفسها.
- اعتمد على `code` في الخطأ، وليس على `message`، لأن `message` نص موجّه للمستخدم وتتغيّر لغته حسب `Accept-Language`.
- خذ معرّفات الفروع والأصناف وطرق الدفع من Endpoints الكتالوج: `GET /v1/branches` و`GET /v1/items` و`GET /v1/payment-methods`. لا تخمّنها ولا تكتبها ثابتة في الكود.
- أرسل الحقول والـ Query Parameters الموثّقة فقط، وأي شيء آخر يُرفض بـ `400 unknown_parameter`.
- اقرأ المبالغ من الرد وليس من طلبك: الخصم الذي ينزل بالسعر عن الحد الأدنى للصنف يُخفَّض، والأسعار الشاملة للضريبة تُحوَّل وتُقرَّب إلى الهللة.
- اقرأ `zatca.status` في كل فاتورة مبيعات وإشعار دائن. القيمة `pending` ليست فشلاً.
- إذا حدث خطأ لا تشرحه الصفحات، اطلب من المستخدم التواصل مع دعم كسور عبر واتساب (+966 12 606 1770، https://wa.me/966126061770) مع الـ `Request-Id`.

## الأدلة

- [ابدأ من هنا](https://docs.kosoor.com.sa/ar/start-here.md): ما هو كسور، ومن يعطيك صلاحية الوصول، والمصطلحات التي يستخدمها الـ API، وكيف تظهر الفوترة الإلكترونية في السعودية (ZATCA) فيه.
- [مقدمة](https://docs.kosoor.com.sa/ar/index.md): رابط الـ API، وكيف تحصل على مفتاح، وأول طلب، والقواعد التي يتبعها كل طلب.
- [ربط تاجر](https://docs.kosoor.com.sa/ar/onboarding.md): كل الخطوات من دخول التاجر إلى لوحة تحكم كسور حتى أول طلب ترسله بمفتاح اختبار، ثم التشغيل الفعلي.
- [البناء بمساعدة الذكاء الاصطناعي](https://docs.kosoor.com.sa/ar/ai-agents.md): نسخ Markdown والملفان llms.txt و llms-full.txt التي يقدمها الموقع لأدوات الذكاء الاصطناعي، والأزرار في كل صفحة، والـ Agent skill التي يمكنك تثبيتها.

## خطوات العمل

- [تسجيل عملية بيع](https://docs.kosoor.com.sa/ar/record-a-sale.md): خطوات عملية البيع كاملة مع كل طلب ورد، من قراءة الكتالوج والبحث عن العميل أو إنشائه، إلى إصدار الفاتورة واستلام المبلغ عند الإصدار أو لاحقاً.
- [استرجاع أو تصحيح عملية بيع](https://docs.kosoor.com.sa/ar/refunds.md): إصدار إشعار دائن على فاتورة مبيعات صادرة كلها أو جزء منها، مع إرجاع المبلغ للعميل أو خصمه من المستحق عليه، مع الطلبات والردود كاملة.
- [مزامنة نظام ERP](https://docs.kosoor.com.sa/ar/erp-sync.md): نسخ فواتير التاجر ومدفوعاته وإشعاراته الدائنة إلى نظامك بلا نقص ولا تكرار، والكتابة في كسور بأمان باستخدام معرّفاتك الخاصة.
- [نتائج الهيئة](https://docs.kosoor.com.sa/ar/zatca.md): معنى كل حالة لدى هيئة الزكاة والضريبة والجمارك في الفاتورة أو الإشعار الدائن، وماذا يفعل نظامك مع كل حالة، وكيف تصلك النتائج التي تأتي لاحقاً.
- [قائمة التحقق قبل التشغيل الفعلي](https://docs.kosoor.com.sa/ar/go-live.md): ما يجب التحقق منه في الربط قبل أن تمر عن طريقه أول عملية بيع حقيقية للتاجر.

## الموارد

- [العملاء](https://docs.kosoor.com.sa/ar/customers.md): إنشاء عميل فرد أو شركة، والحقول المطلوبة لكل نوع، وأنواع الهوية، والبحث عن العميل برقم الجوال أو بمعرّفك الخاص، وقواعد التعديل.
- [فواتير المبيعات](https://docs.kosoor.com.sa/ar/sales-invoices.md): إصدار فاتورة المبيعات في طلب واحد، والحقول المطلوبة، والفاتورة الضريبية والمبسطة، والأسعار والضريبة، والدفع عند الإصدار، وقراءة الفواتير.
- [المدفوعات](https://docs.kosoor.com.sa/ar/payments.md): تسجيل دفعة من العميل، وتخصيصها على الفواتير، وحالات الرفض، وقراءة المدفوعات.
- [الإشعارات الدائنة](https://docs.kosoor.com.sa/ar/credit-notes.md): إصدار إشعار دائن على فاتورة مبيعات صادرة، وإرجاع المبلغ أو خصمه من المستحق، والحد الأقصى للإشعار، ونتيجة هيئة الزكاة والضريبة والجمارك، وحالات الرفض، وقراءة الإشعارات.

## الأساسيات

- [المصادقة](https://docs.kosoor.com.sa/ar/authentication.md): كيف ترسل مفتاح الـ API، والصلاحيات التي يحملها المفتاح، وحصره في فروع معيّنة، ومتى يتوقف المفتاح عن العمل.
- [منع تكرار الطلبات (Idempotency)](https://docs.kosoor.com.sa/ar/idempotency.md): كيف يجعل الـ Header Idempotency-Key إعادة محاولة طلبات POST و PATCH آمنة، وماذا ترجع إعادة المحاولة، ومتى تعيد المحاولة.
- [تقسيم النتائج (Pagination)](https://docs.kosoor.com.sa/ar/pagination.md): كيف ترجع القوائم أحدث السجلات أولاً، صفحة في كل طلب، باستخدام limit و startingAfter و hasMore.
- [Webhooks](https://docs.kosoor.com.sa/ar/webhooks.md): اجعل كسور ترسل نتائج هيئة الزكاة والضريبة والجمارك إلى نظامك فور وصولها، وتحقّق من كل طلب، وتعامل مع إعادة الإرسال والتكرار.
- [وضع الاختبار](https://docs.kosoor.com.sa/ar/test-mode.md): بناء الربط على بيئة الاختبار الخاصة بالتاجر بمفتاح اختبار، وماذا تحتوي، ومتى تكون مشغولة، والعملاء الجاهزون بنتائج معروفة.
- [أكواد الأخطاء](https://docs.kosoor.com.sa/ar/errors.md): كل أكواد الأخطاء التي يرجعها Merchant API، مع الـ HTTP Status ومعنى كل كود، وشكل الخطأ الموحّد.
- [سياسة الإصدارات](https://docs.kosoor.com.sa/ar/versioning.md): ما الذي يمكن أن يتغير في v1 دون إشعار، وما الذي لا يتغير أبداً، وكيف يأتي التغيير الذي يكسر التوافق.
- [سجل التغييرات](https://docs.kosoor.com.sa/ar/changelog.md): كل تغيير في Kosoor Merchant API، الأحدث أولاً.

## مرجع الـ API

- [إنشاء عميل](https://docs.kosoor.com.sa/ar/api/create-customer.md): `POST /v1/customers`
- [قائمة العملاء](https://docs.kosoor.com.sa/ar/api/list-customers.md): `GET /v1/customers`
- [بيانات عميل](https://docs.kosoor.com.sa/ar/api/get-customer.md): `GET /v1/customers/{id}`
- [تعديل عميل](https://docs.kosoor.com.sa/ar/api/update-customer.md): `PATCH /v1/customers/{id}`
- [إصدار فاتورة مبيعات](https://docs.kosoor.com.sa/ar/api/create-sales-invoice.md): `POST /v1/sales-invoices`
- [قائمة فواتير المبيعات](https://docs.kosoor.com.sa/ar/api/list-sales-invoices.md): `GET /v1/sales-invoices`
- [بيانات فاتورة مبيعات](https://docs.kosoor.com.sa/ar/api/get-sales-invoice.md): `GET /v1/sales-invoices/{id}`
- [تحميل الفاتورة بصيغة PDF](https://docs.kosoor.com.sa/ar/api/get-sales-invoice-pdf.md): `GET /v1/sales-invoices/{id}/pdf`
- [تحميل ملف XML المرسل للهيئة](https://docs.kosoor.com.sa/ar/api/get-sales-invoice-xml.md): `GET /v1/sales-invoices/{id}/xml`
- [تسجيل دفعة](https://docs.kosoor.com.sa/ar/api/create-payment.md): `POST /v1/payments`
- [قائمة المدفوعات](https://docs.kosoor.com.sa/ar/api/list-payments.md): `GET /v1/payments`
- [بيانات دفعة](https://docs.kosoor.com.sa/ar/api/get-payment.md): `GET /v1/payments/{id}`
- [إصدار إشعار دائن](https://docs.kosoor.com.sa/ar/api/create-credit-note.md): `POST /v1/credit-notes`
- [قائمة الإشعارات الدائنة](https://docs.kosoor.com.sa/ar/api/list-credit-notes.md): `GET /v1/credit-notes`
- [بيانات إشعار دائن](https://docs.kosoor.com.sa/ar/api/get-credit-note.md): `GET /v1/credit-notes/{id}`
- [تحميل الإشعار بصيغة PDF](https://docs.kosoor.com.sa/ar/api/get-credit-note-pdf.md): `GET /v1/credit-notes/{id}/pdf`
- [تحميل ملف XML المرسل للهيئة](https://docs.kosoor.com.sa/ar/api/get-credit-note-xml.md): `GET /v1/credit-notes/{id}/xml`
- [بيانات فرع](https://docs.kosoor.com.sa/ar/api/get-branch.md): `GET /v1/branches/{id}`
- [قائمة الفروع](https://docs.kosoor.com.sa/ar/api/list-branches.md): `GET /v1/branches`
- [بيانات صنف](https://docs.kosoor.com.sa/ar/api/get-item.md): `GET /v1/items/{id}`
- [قائمة الأصناف](https://docs.kosoor.com.sa/ar/api/list-items.md): `GET /v1/items`
- [بيانات طريقة دفع](https://docs.kosoor.com.sa/ar/api/get-payment-method.md): `GET /v1/payment-methods/{id}`
- [قائمة طرق الدفع](https://docs.kosoor.com.sa/ar/api/list-payment-methods.md): `GET /v1/payment-methods`
- [إنشاء Webhook Endpoint](https://docs.kosoor.com.sa/ar/api/create-webhook-endpoint.md): `POST /v1/webhook-endpoints`
- [قائمة الـ Webhook Endpoints](https://docs.kosoor.com.sa/ar/api/list-webhook-endpoints.md): `GET /v1/webhook-endpoints`
- [بيانات Webhook Endpoint](https://docs.kosoor.com.sa/ar/api/get-webhook-endpoint.md): `GET /v1/webhook-endpoints/{id}`
- [حذف Webhook Endpoint](https://docs.kosoor.com.sa/ar/api/delete-webhook-endpoint.md): `DELETE /v1/webhook-endpoints/{id}`
- [تغيير سر Webhook Endpoint](https://docs.kosoor.com.sa/ar/api/rotate-webhook-endpoint-secret.md): `POST /v1/webhook-endpoints/{id}/rotate-secret`
- [إرسال حدث تجريبي](https://docs.kosoor.com.sa/ar/api/test-webhook-endpoint.md): `POST /v1/webhook-endpoints/{id}/test`

## Optional

- [llms-full.txt](https://docs.kosoor.com.sa/ar/llms-full.txt): كل الأدلة وكل عقود الـ Endpoints في ملف واحد
- [Agent skill](https://docs.kosoor.com.sa/skill/kosoor-merchant-api/SKILL.md): ملف SKILL.md يثبّته وكيل البرمجة (AI coding agent) ليعمل مع هذا الـ API