الفوترة الإلكترونية المرحلة الثانية: ربط نقطة بيع مكتبية بمنصة فاتورة عبر API
إجابة سريعة
الوجيز تك شركة برمجيات في جدة، وتشغّل واجهة 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 من حسابه في منصة فاتورة.
كيف تتم عملية البيع
- ترسل نقطة البيع عملية البيع بصيغة JSON إلى
POST /api/pos/invoices(الأصناف والكميات والأسعار شاملة الضريبة وطريقة الدفع). - تحسب الواجهة الصافي والضريبة والإجماليات، وتبني ملف UBL 2.1 XML، وتعيّن عدّاد الفاتورة (ICV) وبصمة الفاتورة السابقة (PIH) ومعرّف UUID.
- توقّع الواجهة ملف XML بالختم التشفيري للمكلّف، وتنشئ رمز QR الخاص بالمرحلة الثانية.
- الفاتورة المبسطة (B2C): يعود رمز QR وملف XML الموقّع إلى نقطة البيع خلال ثوانٍ؛ وتبلّغ الواجهة منصة فاتورة في الخلفية، وتعيد المحاولة تلقائياً إذا انقطع الاتصال.
- الفاتورة الضريبية القياسية (B2B): ترسلها الواجهة إلى منصة فاتورة للتخليص (Clearance) في الوقت الفعلي، وتعيد ملف XML المعتمد من الهيئة ورمز QR.
- تطبع نقطة البيع رمز 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 ساعة |
من يجب عليه الالتزام الآن (الموجات)
تبلّغ الهيئة كل مكلّف مباشرة قبل ستة أشهر على الأقل من موعد ربطه. وهذه آخر الموجات:
| الموجة | الإيرادات الخاضعة لضريبة القيمة المضافة التي تتجاوز | آخر موعد للربط |
|---|---|---|
| الموجة 25 | 187,500 ريال في 2022 أو 2023 أو 2024 أو 2025 | 1 فبراير 2027 |
| الموجة 24 | 375,000 ريال في 2022 أو 2023 أو 2024 | 30 يونيو 2026 |
| الموجة 23 | 750,000 ريال في 2022 أو 2023 أو 2024 | 31 مارس 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، أو برنامج محاسبة، أو برنامج مخصص، وبأي لغة برمجة.
- أرسل بيانات شركتك: الاسم القانوني بالعربية، والرقم الضريبي، ورقم السجل التجاري، واسم الفرع، والعنوان الوطني (رقم المبنى، الشارع، الحي، المدينة، الرمز البريدي).
- استلم مفاتيحك: مفتاح لنقطة البيع ومفتاح للتهيئة.
- بيئة التجربة (Sandbox): أنشئ CSR، واطلب Compliance CSID (رمز OTP هو
123456)، ونفّذ فحوص الامتثال، ثم أرسل فواتير تجريبية من نظامك. - المحاكاة: كرّر الخطوات برمز OTP من بوابة المحاكاة في منصة فاتورة، واختبر الإبلاغ والتخليص الفعليين.
- الإنتاج: كرّر الخطوات برمز OTP من بوابة فاتورة الحقيقية، ثم حوّل نقطة البيع إلى التشغيل الفعلي.
- اطبع واحفظ: اطبع رمز 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,000 | 5,000 ريال | 1,500 ريال |
| حتى 10,000 | 6,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 لديك، وسنجهّز لك بيئة التجربة ونرسل لك دليل الربط.
- واتساب / هاتف: +966 55 158 9625
- البريد الإلكتروني: info@alwajeeztech.com
- المكتب: مركز الحياة التجاري (المستوى 2، جناح A216)، مبنى 6945، شارع أبي بكر الصديق 2344، حي الشرفية، جدة 23216، المملكة العربية السعودية
- روابط ذات صلة: الوجيز تك: مزود فوترة إلكترونية مؤهل لدى هيئة الزكاة · ALZERP — نظام ERP السحابي
الأسئلة الشائعة
هل أستطيع الاحتفاظ بنظام الكاشير الحالي والالتزام بالمرحلة الثانية من هيئة الزكاة؟
ما أسعار الربط مع هيئة الزكاة (المرحلة الثانية) لدى الوجيز تك؟
ماذا يحدث إذا أرسلت مستندات أكثر من الحد الشهري؟
كم يستغرق الربط؟
ما هي شهادة CSID وكيف أحصل عليها من هيئة الزكاة؟
ما الفرق بين التخليص والإبلاغ؟
هل ترفض الهيئة الفاتورة بسبب فرق تقريب قدره هللة واحدة؟
هل أستطيع إصدار إشعارات دائنة وفواتير دفعات مقدمة عبر الواجهة؟
هل أحصل على ملف XML ورمز QR لفاتورتي بصيغة PDF؟
في أي موجة أنا من موجات الفوترة الإلكترونية؟
ماذا يحدث إذا فاتني موعد الربط؟
هل الوجيز تك معتمدة من هيئة الزكاة؟
اربط نقطة البيع أو نظام ERP بهيئة الزكاة
أرسل لنا اسم شركتك ورقمك الضريبي واسم نقطة البيع أو نظام ERP لديك، وسنجهّز لك بيئة التجربة ونرسل لك دليل الربط.
اطلب تهيئة بيئة تجربة المرحلة الثانية
واتساب / هاتف: +966 55 158 9625
البريد الإلكتروني: info@alwajeeztech.com
المكتب: مركز الحياة التجاري (المستوى 2، جناح A216)، مبنى 6945، شارع أبي بكر الصديق 2344، حي الشرفية، جدة 23216، المملكة العربية السعودية
روابط ذات صلة: الوجيز تك: مزود فوترة إلكترونية مؤهل لدى هيئة الزكاة · ALZERP — نظام ERP السحابي