ابدأ من هنا

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

ما هو كسور

كسور نظام نقاط بيع وإدارة أعمال للمنشآت في السعودية، وكثير منها مغاسل سيارات ومراكز خدمة. تبيع المنشأة عن طريق كسور من نقطة البيع، ومن الكشك الذاتي (Kiosk)، ومن متجرها الإلكتروني، ومن لوحة تحكم كسور. ويحفظ كسور عملاءها وفواترها ومدفوعاتها وحساباتها، ويرسل فواترها إلى هيئة الزكاة والضريبة والجمارك (ZATCA).

يتيح Merchant API لنظام آخر أن يقرأ هذه البيانات ويكتب فيها: العملاء وفواتير المبيعات والمدفوعات والإشعارات الدائنة.

التاجر والشريك

• التاجر (Merchant): منشأة تستخدم كسور، وبياناتها في حسابها الخاص في كسور.
• الشريك (Partner): أنت. شركتك تبني نظاماً، مثل ERP أو تطبيق حجوزات أو بوابة لأساطيل السيارات، يعمل مع بيانات التاجر عن طريق هذا الـ API.

كل مفتاح API مرتبط بتاجر واحد. وإذا كنت تعمل مع أكثر من تاجر، فلكل تاجر مفتاح خاص به.

كيف يتم الوصول

1. يُصدر التاجر مفتاح API من لوحة تحكم كسور، من الإعدادات ← المطوّرون، ثم يعطيك إياه. الخطوات بالتفصيل في ربط تاجر.
2. ترسل المفتاح مع كل طلب. المفتاح وحده يحدد التاجر الذي يخصه الطلب، فلا ترسل أي معرّف للتاجر، ولا تحتاج حساباً أو تسجيل دخول خاصاً بك في كسور.
3. يحمل المفتاح الصلاحيات التي منحها التاجر فقط، وقد يكون مقصوراً على بعض فروعه. ويستطيع التاجر إبطاله في أي وقت.

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

مصطلحات الـ API

المصطلح	المعنى
الفرع (Branch)	أحد مواقع التاجر، مثل محل أو مركز خدمة. كل فاتورة ودفعة تتبع فرعاً، وقد يكون المفتاح مقصوراً على فروع معيّنة.
الصنف (Item)	ما يبيعه التاجر: منتج أو خدمة أو اشتراك. بند الفاتورة يحدد الصنف بمعرّفه.
نقطة البيع (POS)	مكان البيع في الفرع، حيث يستلم الكاشير المبلغ. البيع من هناك يظهر في الـ API بقيمة createdVia: "pos".
طريقة الدفع (Payment method)	الطريقة التي يدفع بها العميل كما أعدّها التاجر، مثل النقد أو البطاقة.
الخزينة (Treasury)	مكان المال في دفاتر التاجر، مثل صندوق نقدي أو حساب بنكي. كل طريقة دفع تُرحَّل إلى خزينة، وقد تختلف الخزينة من فرع لآخر.
مركز التكلفة (Cost centre)	تصنيف يستخدمه محاسب التاجر لتجميع الإيرادات والتكاليف، مثل قسم أو مشروع. ويمكن أن تحمل الفاتورة مركز تكلفة في costCentreId.
حجم السيارة (Car size)	كثير من التجار يسعّرون الخدمة حسب حجم السيارة. الصنف المسعّر حسب حجم السيارة ليس له سعر واحد في الكتالوج، فيجب أن يرسل بنده في الفاتورة unitPrice.
الاشتراك (Subscription)	باقة زيارات يشتريها العميل، مثل عدد من غسلات السيارة. الـ API لا يبيع الاشتراكات، والبند الذي يحمل اشتراكاً يرجع 422 item_not_sellable.
العميل (Customer)	فرد أو شركة. كل فاتورة تُنشأ عن طريق الـ API يجب أن تحدد عميلاً.
الريال (SAR)	الريال السعودي، وكل المبالغ في الـ API بالريال (currency: "SAR").
الهللة (Halala)	جزء من مئة من الريال. تحفظ كسور المبالغ مقرّبة إلى الهللة، أي بمنزلتين عشريتين على الأكثر.
ضريبة القيمة المضافة (VAT)	النسبة الأساسية في السعودية 15%. ولكل صنف في كسور نسبته الخاصة، ويعرضها كل بند في الفاتورة في vatRate، مثل 15.
الرقم الضريبي (VAT number)	رقم تسجيل المنشأة في ضريبة القيمة المضافة: 15 رقماً تبدأ بـ 3 وتنتهي بـ 3.
السجل التجاري (CR)	رقم تسجيل الشركة في السعودية. والعميل من نوع شركة بلا رقم ضريبي يمكن تعريفه بالسجل التجاري بدلاً منه (idType: "CRN").

هيئة الزكاة والضريبة والجمارك في خمس دقائق

منصة الفوترة الإلكترونية التابعة لهيئة الزكاة والضريبة والجمارك (ZATCA) اسمها «فاتورة» (Fatoora)، وتستقبل كل فاتورة وإشعار دائن تصدره منشأة سعودية. كسور يتولى هذا الجزء عن التاجر: لا تتصل أنت بالهيئة، ولا توقّع ملف XML، ولا تبني رمز QR. كل ما عليك هو قراءة النتيجة.

الفاتورة الضريبية والمبسطة

عند الهيئة نوعان من الفواتير، وفي كسور نوع العميل هو الذي يحدد نوع الفاتورة:

	الفاتورة الضريبية (standard)	الفاتورة المبسطة (simplified)
العميل	شركة	فرد
إجراء الهيئة	الاعتماد (clearance): تفحص الهيئة الفاتورة وتعتمدها قبل أن تصل إلى المشتري	التبليغ (reporting): تصدر الفاتورة أولاً ثم تُبلَّغ بها الهيئة
في الـ API	تعتمدها كسور قبل أن ترد عليك	تبلّغ بها كسور بعد أن ترد عليك

ويوضح الحقل zatca.kind في الرد نوعها: standard أو simplified. والإشعار الدائن من نوع الفاتورة التي صدر عليها.

معنى كل حالة

zatca.status	المعنى
pending	لم تقبل الهيئة المستند بعد. المستند المبسط يبقى pending حتى تبلّغ به كسور. أما الضريبي فلا يكون pending إلا إذا لم ترد الهيئة في الوقت المحدد، وتعيد كسور إرساله لاحقاً.
cleared	اعتمدت الهيئة هذا المستند الضريبي، ويحمل zatca.qr رمز QR الذي أرجعته الهيئة.
reported	قبلت الهيئة التبليغ بهذا المستند المبسط.
rejected	رفضت الهيئة المستند، ورسائلها في zatca.errors.

الحالة pending ليست فشلاً. المستند صادر، ورقمه ومبالغه لا تتغير. والمستند الضريبي الذي ترفضه الهيئة أثناء الاعتماد لا يُحفظ أصلاً، ويرجع الطلب 422 zatca_rejected. لذلك لا يصبح المستند المحفوظ rejected إلا بعد أن كان pending.

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

الخطوة التالية

1. مقدمة: رابط الـ API والقواعد التي يتبعها كل طلب.
2. ربط تاجر: من لوحة تحكم التاجر إلى أول طلب ترسله.
3. تسجيل عملية بيع: الخطوات كاملة، مع كل طلب ورد.