التجزئة ونقاط البيع الزكاة والامتثال المالي المملكة العربية السعودية · رؤية 2030

الفوترة الإلكترونية المرحلة الثانية: ربط نقطة بيع مكتبية بمنصة فاتورة عبر API

فريق هندسة الوجيز تك • نُشر في 18 نوفمبر 2026 • آخر تحقق: 18 نوفمبر 2026
شارك:
⚡

إجابة سريعة

الوجيز تك شركة برمجيات في جدة، وتشغّل واجهة API مستضافة للفوترة الإلكترونية في المرحلة الثانية من هيئة الزكاة والضريبة والجمارك. ترسل نقطة البيع أو نظام ERP لديك كل عملية بيع بصيغة JSON، فتبني الواجهة ملف UBL 2.1 XML، وتوقّعه، وتضيف رمز QR الخاص بالمرحلة الثانية، ثم ترسله إلى منصة فاتورة للتخليص أو الإبلاغ. الإعداد والسنة الأولى 5,000 ريال لمرة واحدة، ثم 1,500 ريال تجديداً سنوياً ابتداءً من السنة الثانية، وتشمل حتى 5,000 مستند شهرياً.

يعرض هذا المشروع كيف ربطنا نظام نقطة بيع مكتبي خاصاً بعميل بالمرحلة الثانية من هيئة الزكاة والضريبة والجمارك دون تغيير نظام الفوترة لديه. وتعمل الواجهة نفسها مع أي نقطة بيع أو نظام كاشير أو ERP أو برنامج مخصص قادر على إرسال طلب HTTPS.

لمحة سريعة

البندالتفاصيل
العميلغير معلن
نظام العميلبرنامج فوترة / نقطة بيع مكتبي خاص به (يبقى كما هو)
خدمتناواجهة API مستضافة للمرحلة الثانية + تهيئة CSID + دليل الربط
المستندات المشمولةفواتير ضريبية مبسطة وقياسية، إشعارات دائنة، إشعارات مدينة، فواتير الدفعات المقدمة
النتيجةاجتازت أنواع المستندات الستة كلها فحص الهيئة بدون أي أخطاء وبدون أي تحذيرات قبل التشغيل الفعلي
السعرالإعداد والسنة الأولى 5,000 ريال، ثم 1,500 ريال تجديداً سنوياً، شاملة ضريبة القيمة المضافة، حتى 5,000 مستند شهرياً

المشروع: المرحلة الثانية بدون استبدال نقطة البيع

التحدي. كان لدى العميل برنامج فوترة مكتبي خاص به ولم يرغب في استبداله. وكان يحتاج من مزود الخدمة أربعة أشياء:

  • إرسال كل عملية بيع إلى الهيئة عبر API، دون تغيير طريقة عمل الكاشير.
  • استلام رمز QR الخاص بالمرحلة الثانية لحظة البيع، لطباعته على الإيصال.
  • استلام ملف XML الموقّع، ليبني برنامجه نسخة PDF/A-3 من الفاتورة.
  • دعم باقات الخدمات المدفوعة مسبقاً (الدفعات المقدمة) والإشعارات الدائنة.

وأسعاره شاملة ضريبة القيمة المضافة أصلاً، لذلك سأل أيضاً: هل يؤدي فرق تقريب قدره هللة واحدة إلى رفض الفاتورة؟

الحل. وفّرنا للعميل نسخة مستضافة ومخصصة من واجهة الوجيز تك للمرحلة الثانية، بقاعدة بيانات خاصة ومفاتيح تشفير خاصة ومفتاحَي API: أحدهما لنقطة البيع والآخر للتهيئة. وينتقل العميل بنفسه عبر بيئات الهيئة الثلاث — بيئة المطورين التجريبية (sandbox) ثم المحاكاة ثم الإنتاج — من شاشة Swagger، باستخدام رموز OTP من حسابه في منصة فاتورة.

كيف تتم عملية البيع

  1. ترسل نقطة البيع عملية البيع بصيغة JSON إلى POST /api/pos/invoices (الأصناف والكميات والأسعار شاملة الضريبة وطريقة الدفع).
  2. تحسب الواجهة الصافي والضريبة والإجماليات، وتبني ملف UBL 2.1 XML، وتعيّن عدّاد الفاتورة (ICV) وبصمة الفاتورة السابقة (PIH) ومعرّف UUID.
  3. توقّع الواجهة ملف XML بالختم التشفيري للمكلّف، وتنشئ رمز QR الخاص بالمرحلة الثانية.
  4. الفاتورة المبسطة (B2C): يعود رمز QR وملف XML الموقّع إلى نقطة البيع خلال ثوانٍ؛ وتبلّغ الواجهة منصة فاتورة في الخلفية، وتعيد المحاولة تلقائياً إذا انقطع الاتصال.
  5. الفاتورة الضريبية القياسية (B2B): ترسلها الواجهة إلى منصة فاتورة للتخليص (Clearance) في الوقت الفعلي، وتعيد ملف XML المعتمد من الهيئة ورمز QR.
  6. تطبع نقطة البيع رمز QR وتحفظ ملف XML لنسخة PDF/A-3؛ وتحتفظ الواجهة بسجل الإرسال كاملاً.

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

المرحلة الأولى مقابل المرحلة الثانية: ما الذي تطلبه الهيئة

جعلت المرحلة الأولى (الإصدار) الفواتير الإلكترونية إلزامية من 4 ديسمبر 2021. أما المرحلة الثانية (الربط والتكامل) فسارية منذ 1 يناير 2023، وتربط نظامك بالهيئة، وتُطبَّق على موجات.

المتطلبالمرحلة الأولى – الإصدارالمرحلة الثانية – الربط والتكامل
البداية4 ديسمبر 2021، جميع المسجلين في ضريبة القيمة المضافة1 يناير 2023، على موجات بحسب الإيرادات
صيغة الفاتورةإلكترونية منظمة؛ لا فواتير مكتوبة بخط اليدملف UBL 2.1 XML (قياسية ومبسطة)
الاتصال بالهيئةلا يوجدربط عبر API بمنصة فاتورة
تسجيل الجهازلا يوجدتهيئة كل وحدة إصدار بمعرّف الختم المشفر CSID
التوقيع الرقميغير مطلوبتوقيع كل فاتورة (الختم التشفيري)
رمز QRرمز QR أساسي على الفواتير المبسطة (البائع، الرقم الضريبي، الوقت، الإجماليات)رمز QR موسّع يتضمن بصمة الفاتورة والتوقيع والمفتاح العام
الحماية من التلاعبأساسيةسلسلة بصمات الفواتير (PIH) والعدّاد (ICV) ومعرّف UUID في كل فاتورة
فواتير B2B (القياسية)تصدر محلياًتُخلَّص لدى الهيئة في الوقت الفعلي قبل مشاركتها مع المشتري
فواتير B2C (المبسطة)تصدر محلياًتُبلَّغ للهيئة خلال 24 ساعة

من يجب عليه الالتزام الآن (الموجات)

تبلّغ الهيئة كل مكلّف مباشرة قبل ستة أشهر على الأقل من موعد ربطه. وهذه آخر الموجات:

الموجةالإيرادات الخاضعة لضريبة القيمة المضافة التي تتجاوزآخر موعد للربط
الموجة 25187,500 ريال في 2022 أو 2023 أو 2024 أو 20251 فبراير 2027
الموجة 24375,000 ريال في 2022 أو 2023 أو 202430 يونيو 2026
الموجة 23750,000 ريال في 2022 أو 2023 أو 202431 مارس 2026

كما في 18 نوفمبر 2026

خفّضت الموجة 25 الحد إلى النصف، لذلك تدخل المرحلة الثانية الآن محلات صغيرة وصالونات ومغاسل ومطاعم كثيرة. المصادر: Grant Thornton KSA – Wave 25، KPMG – Wave 25، EY – Phase 2 waves، LookupTax – Wave 23، Alvarez & Marsal – Wave 24.

المتطلبات التقنية للمرحلة الثانية (CSID وUBL والتوقيع)

يجب أن تكون كل فاتورة في المرحلة الثانية ملف UBL 2.1 XML موقّعاً، مرتبطاً بالفاتورة التي قبله، وصادراً من وحدة مسجلة لدى الهيئة. وتتولى واجهتنا كل جزء من ذلك:

المتطلبماذا يعنيكيف تتعامل معه واجهتنا
CSRطلب شهادة يحمل رقمك الضريبي وسجلك التجاري وفرعك وعنوانكيُنشأ من بيانات الشركة التي تدخلها في شاشة التهيئة
Compliance CSID (CCSID)شهادة مؤقتة تصدر برمز OTP من حسابك في منصة فاتورةتطلبها الواجهة عندما ترسل رمز OTP
فحوص الامتثالفواتير وإشعارات دائنة ومدينة تجريبية يجب أن تقبلها الهيئةتُنفَّذ تلقائياً لأنواع B2B وB2C
Production CSID (PCSID)الشهادة الفعلية لتوقيع الفواتير الحقيقيةتُطلب بعد نجاح الفحوص، وتُخزَّن مشفّرة
UBL 2.1 XMLصيغة بيانات الفاتورة لدى الهيئةيُبنى من JSON الخاص بك؛ لا تكتب XML أبداً
الختم التشفيريتوقيع ECDSA (secp256k1) على كل فاتورةيُطبَّق بمفتاحك الخاص المحفوظ مشفّراً على خادمنا
بصمة الفاتورة وICV وPIH وUUIDتحمل كل فاتورة بصمتها وعدّاداً متسلسلاً وبصمة الفاتورة السابقةتُعيَّن بترتيب صارم، وتعمل بأمان مع كثرة المبيعات المتزامنة
رمز QR للمرحلة الثانيةBase64 TLV يضم البائع والرقم الضريبي والوقت والإجماليات والبصمة والتوقيع والمفتاح العاميعود في كل استجابة جاهزاً للطباعة
التخليص (B2B)فواتير قياسية تعتمدها الهيئة قبل أن يستلمها المشترياتصال في الوقت الفعلي؛ ويعود ملف XML المعتمد من الهيئة
الإبلاغ (B2C)فواتير مبسطة تُبلَّغ للهيئة خلال 24 ساعةإبلاغ في الخلفية مع إعادة محاولة تلقائية
الإشعارات الدائنة والمدينةيجب أن تشير إلى الفاتورة الأصلية وتذكر السببحقلا originalInvoiceNumber وreason
الدفعات المقدمةفاتورة دفعة مقدمة (النوع 386)، ثم فاتورة نهائية تخصمهامدعومة، بما فيها أسطر مرجع الدفعة المقدمة التي تتحقق منها الهيئة
نسخة الأرشيفXML موقّع؛ وPDF/A-3 مع XML مضمّن هو النسخة المقروءة المعتادةيعود XML بصيغة Base64 لبناء PDF/A-3

كيف تربط نقطة البيع أو نظام ERP

يستطيع أي نظام يرسل طلب HTTPS بصيغة JSON أن يتصل — نقطة بيع مكتبية أو سحابية، أو ERP، أو برنامج محاسبة، أو برنامج مخصص، وبأي لغة برمجة.

  1. أرسل بيانات شركتك: الاسم القانوني بالعربية، والرقم الضريبي، ورقم السجل التجاري، واسم الفرع، والعنوان الوطني (رقم المبنى، الشارع، الحي، المدينة، الرمز البريدي).
  2. استلم مفاتيحك: مفتاح لنقطة البيع ومفتاح للتهيئة.
  3. بيئة التجربة (Sandbox): أنشئ CSR، واطلب Compliance CSID (رمز OTP هو 123456)، ونفّذ فحوص الامتثال، ثم أرسل فواتير تجريبية من نظامك.
  4. المحاكاة: كرّر الخطوات برمز OTP من بوابة المحاكاة في منصة فاتورة، واختبر الإبلاغ والتخليص الفعليين.
  5. الإنتاج: كرّر الخطوات برمز OTP من بوابة فاتورة الحقيقية، ثم حوّل نقطة البيع إلى التشغيل الفعلي.
  6. اطبع واحفظ: اطبع رمز QR العائد على كل إيصال، واحتفظ بملف XML العائد (أو بنسخة PDF/A-3 التي بنيتها منه).

مثال على الطلب (فاتورة مبسطة بأسعار شاملة الضريبة)

POST /api/pos/invoices
X-Api-Key: <your POS key>

{
  "invoiceNumber": "INV-000123",
  "issueDateTime": "2026-11-18T14:30:00+03:00",
  "documentType": "invoice",
  "invoiceKind": "simplified",
  "pricesIncludeVat": true,
  "expectedTotalIncludingVat": 46.00,
  "paymentMeans": "cash",
  "lines": [
    { "name": "Item A", "quantity": 2, "unitPrice": 15.00, "vatCategory": "S", "vatRate": 15 },
    { "name": "Item B", "quantity": 1, "unitPrice": 16.00, "vatCategory": "S", "vatRate": 15 }
  ]
}

تعيد الاستجابة qrCode وxmlBase64 وuuid وicv وinvoiceHash وtotals المحسوبة وstatus (وهو PENDING_REPORT أو REPORTED أو CLEARED أو FAILED مع رسائل الهيئة). وإعادة إرسال رقم الفاتورة نفسه تعيد النتيجة المخزّنة، فلا يسبب انقطاع الاتصال فاتورة مكررة.

الأسعار والحدود والحصة الشهرية

تشمل جميع الباقات: واجهة API مستضافة، وتهيئة CSID في البيئات الثلاث، وأنواع المستندات الستة، ودليل الربط، ودعم واتساب لرقم ضريبي واحد وفرع واحد.

المستندات شهرياًالإعداد والسنة الأولىالتجديد السنوي (من السنة الثانية)
حتى 5,0005,000 ريال1,500 ريال
حتى 10,0006,500 ريال3,000 ريال

تحتاج أكثر؟ كل 5,000 مستند إضافية شهرياً تضيف 1,500 ريال إلى السنة الأولى و1,500 ريال إلى التجديد السنوي. تواصل معنا. جميع الأسعار شاملة ضريبة القيمة المضافة. الإعداد والسنة الأولى يُدفعان مرة واحدة.

هل تستخدم أصلاً نظام الوجيز ERP أو نقطة البيع من الوجيز؟ المرحلة الثانية هناك إضافة بسعر 2,000 ريال تُدفع مرة واحدة. أما هذه الباقة فهي لربط نقطة البيع أو نظام ERP الخاص بك.

حدود تعرفها قبل أن تشترك

  • تحتاج نقطة البيع إلى اتصال بالإنترنت للوصول إلى الواجهة؛ فرمز QR تنشئه الواجهة، ولا يُنشأ دون اتصال على الجهاز.
  • الفواتير القياسية (B2B) تحتاج أن تكون منصة الهيئة متاحة لحظة البيع، لأن التخليص يتم في الوقت الفعلي؛ وإذا كانت الهيئة متوقفة تعيد الواجهة FAILED فتعيد الإرسال.
  • الفواتير المبسطة (B2C) لا يوقفها تعطل منصة الهيئة: يعود رمز QR فوراً، ويُعاد الإبلاغ في الخلفية ضمن مهلة الـ 24 ساعة لدى الهيئة.
  • تحتاج التهيئة إلى رمز OTP من حسابك أنت في منصة فاتورة للمحاكاة وللإنتاج؛ ولا نستطيع طلبه نيابة عنك.
  • لكل بيئة عدّاد فواتير وسلسلة بصمات خاصة بها؛ ويبدأ الإنتاج دائماً من الفاتورة رقم 1.
  • الإجماليات الشاملة الضريبة: تُمتص فروق التقريب حتى 0.05 ريال في حقل التقريب الرسمي؛ أما الفروق الأكبر فتُرفض مع رسالة واضحة.
  • إذا غادرتنا، نسلّمك سجل الإرسال كاملاً (ملفات XML ورموز QR والحالات). المفاتيح الخاصة لا تُنقل؛ فيهيّئ مزودك التالي وحدة جديدة برمز OTP جديد، وتبقى الفواتير السابقة صالحة.

اربط نقطة البيع أو نظام ERP بهيئة الزكاة

أرسل لنا اسم شركتك ورقمك الضريبي واسم نقطة البيع أو نظام ERP لديك، وسنجهّز لك بيئة التجربة ونرسل لك دليل الربط.

?

الأسئلة الشائعة

هل أستطيع الاحتفاظ بنظام الكاشير الحالي والالتزام بالمرحلة الثانية من هيئة الزكاة؟

نعم. تستمر نقطة البيع بالعمل كما هي، وتضيف فقط استدعاء API واحداً لكل عملية بيع. تتولى الواجهة إنشاء ملف XML والتوقيع ورمز QR والاتصال بمنصة فاتورة.

ما أسعار الربط مع هيئة الزكاة (المرحلة الثانية) لدى الوجيز تك؟

الإعداد والسنة الأولى 5,000 ريال لمرة واحدة، وتشمل حتى 5,000 مستند شهرياً وأنواع المستندات الستة. ابتداءً من السنة الثانية يكون التجديد السنوي 1,500 ريال. جميع الأسعار شاملة ضريبة القيمة المضافة.

ماذا يحدث إذا أرسلت مستندات أكثر من الحد الشهري؟

لا يتوقف شيء. تستمر الواجهة في تخليص فواتيرك والإبلاغ عنها. ونرسل لك بريداً إلكترونياً تلقائياً عند تجاوز حدك الشهري.

كم يستغرق الربط؟

يكون جانب الواجهة جاهزاً بمجرد إدخال بيانات شركتك. ويذهب معظم الوقت في إضافة مطوّرك استدعاء API إلى نقطة البيع، وتتيح بيئة التجربة (sandbox) اختباره بأصناف حقيقية من اليوم الأول.

ما هي شهادة CSID وكيف أحصل عليها من هيئة الزكاة؟

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

ما الفرق بين التخليص والإبلاغ؟

التخليص (Clearance) للفواتير الضريبية القياسية (B2B): تعتمدها الهيئة في الوقت الفعلي قبل أن يستلمها المشتري. أما الإبلاغ (Reporting) فللفواتير المبسطة (B2C): تسلّم الإيصال فوراً، وتُبلَّغ الفاتورة للهيئة خلال 24 ساعة.

هل ترفض الهيئة الفاتورة بسبب فرق تقريب قدره هللة واحدة؟

لا. عندما تكون أسعارك شاملة ضريبة القيمة المضافة، تضع الواجهة الفروق الصغيرة (حتى 0.05 ريال) في حقل التقريب الرسمي، فيطابق المبلغ المستحق إجمالي نقطة البيع لديك.

هل أستطيع إصدار إشعارات دائنة وفواتير دفعات مقدمة عبر الواجهة؟

نعم. تشير الإشعارات الدائنة والمدينة إلى الفاتورة الأصلية وتذكر السبب. وفواتير الدفعات المقدمة والفواتير النهائية التي تخصمها مدعومة كلتاهما.

هل أحصل على ملف XML ورمز QR لفاتورتي بصيغة PDF؟

نعم. تتضمن كل استجابة نص رمز QR وملف XML الموقّع (Base64)، فيستطيع برنامجك طباعة الرمز وبناء ملف PDF/A-3 يضم XML.

في أي موجة أنا من موجات الفوترة الإلكترونية؟

الموجة 25 تشمل المنشآت التي تجاوزت إيراداتها الخاضعة لضريبة القيمة المضافة 187,500 ريال في أي سنة من 2022 إلى 2025، وموعد الربط 1 فبراير 2027. وتبلغ الهيئة كل منشأة مباشرة قبل ستة أشهر على الأقل.

ماذا يحدث إذا فاتني موعد الربط؟

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

هل الوجيز تك معتمدة من هيئة الزكاة؟

لا تصدر الهيئة شهادة للبرامج. هي تعتمد مزودي البرامج للفوترة الإلكترونية. والوجيز تك مزود حلول فوترة إلكترونية مؤهل لدى الهيئة.

اربط نقطة البيع أو نظام ERP بهيئة الزكاة

أرسل لنا اسم شركتك ورقمك الضريبي واسم نقطة البيع أو نظام ERP لديك، وسنجهّز لك بيئة التجربة ونرسل لك دليل الربط.

اطلب تهيئة بيئة تجربة المرحلة الثانية

واتساب / هاتف: +966 55 158 9625

البريد الإلكتروني: info@alwajeeztech.com

المكتب: مركز الحياة التجاري (المستوى 2، جناح A216)، مبنى 6945، شارع أبي بكر الصديق 2344، حي الشرفية، جدة 23216، المملكة العربية السعودية

روابط ذات صلة: الوجيز تك: مزود فوترة إلكترونية مؤهل لدى هيئة الزكاة · ALZERP — نظام ERP السحابي

تعتبر Alwajeez Tech العلامة التجارية للتسويق التجاري لشركة الأفق الواعدة، حيث تقدم حلول الذكاء الاصطناعي والبرمجيات المؤسسية الموجهة للمملكة العربية السعودية بما يتوافق مع الأهداف الاستراتيجية لـ رؤية السعودية 2030. نحن نساهم في قيادة قطاع التقنية في المملكة بالتوافق مع إرشادات وزارة الاتصالات وتقنية المعلومات (MCIT)، مع ضمان توافق منصاتنا مع معايير الهيئة السعودية للبيانات والذكاء الاصطناعي (SDAIA) لخصوصية البيانات وأخلاقيات الذكاء الاصطناعي. تلتزم حلولنا بالامتثال الكامل لأنظمة الفوترة الإلكترونية (فاتورة) ومعايير الضرائب السعودية لـ هيئة الزكاة والضريبة والجمارك (ZATCA). كما نلتزم بتسجيلات مقدمي الخدمات السحابية ومعايير الاتصالات لـ هيئة الاتصالات والفضاء والتقنية (CST)، وندعم مبادرات التحول الرقمي ومبادرة 'الحكومة كمنصة' التابعة لـ هيئة الحكومة الرقمية (DGA). تمكن هياكلنا السحابية الجهات الحكومية والخاصة من تحديث العمليات ودفع النمو المستدام.

تمكين المملكة العربية السعودية بحلول برمجية وذكاء اصطناعي محلية وموثوقة