جرّب فاتورة

الفوترة الإلكترونية المرحلة الثانية: دليل الربط مع زاتكا خطوة بخطوة

كتبه ، المهندس اللي بنى محرك ماثل · آخر تحديث

المرحلة الثانية من الفوترة الإلكترونية (الربط والتكامل) تعني إن برنامجك يرسل كل فاتورة لمنصة «فاتورة» في هيئة الزكاة والضريبة والجمارك. هذا الدليل يمشي معك من أول تجربة لين أول فاتورة معتمدة في الإنتاج، بنفس الخطوات اللي يسويها محرك ماثل.

وش هي المرحلة الثانية من الفوترة الإلكترونية؟

المرحلة الثانية (مرحلة الربط والتكامل) تُلزم المنشأة إن نظام الفوترة عندها يرسل كل فاتورة إلكترونية لمنصة «فاتورة» في هيئة الزكاة والضريبة والجمارك. الفاتورة الضريبية (B2B) تُعتمد من الهيئة (clearance) قبل ما تتسلّم للمشتري، والمبسّطة (B2C) تُبلّغ (reporting) خلال ٢٤ ساعة. المرحلة الأولى (الإصدار) بدأت في ٤ ديسمبر ٢٠٢١، والثانية بدأت في ١ يناير ٢٠٢٣ وتنطبق على المنشآت على موجات تعلنها الهيئة. تحقق إذا منشأتك داخلة في الموجة ٢٥.

وش هي منصة فاتورة؟

منصة «فاتورة» هي بوابة الهيئة للفوترة الإلكترونية (fatoora.zatca.gov.sa). صاحب المنشأة يدخلها بحسابه عشان يطلّع رمز OTP لتسجيل أجهزته، وعليها تستقبل الهيئة الفواتير من أنظمة المنشآت عبر الـ API. والمطورين عندهم بوابة منفصلة للتجربة.

وش متطلبات المرحلة الثانية؟

ماثل يسوي كل هذا في طلب واحد. الخطوات تحت هي الطريق من الصفر للإنتاج.

  1. افهم البيئات الثلاث

    الهيئة عندها ثلاث بوابات، ولكل وحدة شهادتها، فالشهادة من بيئة ما تشتغل في الثانية:

    • بوابة المطورين (sandbox): للتجربة. الـ OTP فيها قيمة تجريبية منشورة، ومجانية في ماثل.
    • المحاكاة (simulation): ببيانات منشأتك الحقيقية وبـ OTP من حسابها، بدون أثر نظامي.
    • الإنتاج (production): الفواتير النظامية، وتحتاج باقة أجهزة.

  2. جرّب فاتورة بدون شهادة

    قبل أي تسجيل، شوف الرد بعينك: أرسل فاتورة على "environment": "sandbox" بدون seller ولا csid، وماثل يرسلها لبوابة المطورين باسم منشأة تجريبية ويرجّع رد الهيئة الحقيقي. أو جرّبها من الصفحة الرئيسية بضغطة زر.

    curl https://matheel.app/api/v1/invoices -H "Authorization: Bearer $MATHEEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environment":"sandbox","invoice":{"type":"simplified","counter":1,"uuid":"…","number":"INV-1",
       "line_items":[{"name":"قهوة","quantity":2,"price":"50.00"}],
       "subtotal":"100.00","vat_amount":"15.00","total":"115.00"}}'

  3. جهّز بيانات المنشأة

    أغلب الرفض في الربط سببه بيانات المنشأة. جهّزها مرة وحدة صح:

    • الرقم الضريبي: ١٥ رقم، يبدأ وينتهي بـ ٣.
    • الاسم القانوني بالعربي، ورقم السجل التجاري (CRN).
    • العنوان الوطني كامل: الشارع، ورقم المبنى (٤ أرقام)، والحي، والمدينة، والرمز البريدي (٥ أرقام). العنوان الناقص يعطي BR-KSA-09 و BR-KSA-37.

  4. طلّع رمز OTP من منصة «فاتورة»

    للمحاكاة والإنتاج: صاحب المنشأة يدخل بوابة «فاتورة» بحسابه، ويختار تسجيل جهاز (Onboard new solution unit)، وينسخ رمز الـ OTP. الرمز صالح لوقت قصير، فاستخدمه على طول. وعلى بوابة المطورين ما تحتاج OTP، ماثل يستخدم القيمة التجريبية.

    الشهادة تطلع باسم المنشأة نفسها، فما تقدر تطلّعها عن عميلك بدون الـ OTP من حسابه. خطّط لهالخطوة مع أول عميل بدري.

  5. سجّل الجهاز (CSID) بطلب واحد

    التسجيل يدوياً أربع خطوات: CSR بمفتاح secp256k1، وشهادة امتثال مقابل الـ OTP، وست فحوصات امتثال (فاتورة وإشعار دائن ومدين، ضريبية ومبسّطة)، وبعدها شهادة الإنتاج. في ماثل كلها طلب واحد:

    curl https://matheel.app/api/v1/onboarding -H "Authorization: Bearer $MATHEEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environment":"simulation","otp":"123456","seller":{"vat_number":"3…3","legal_name_ar":"…","crn":"…",
       "address":{"street":"…","building_number":"1234","district":"…","city":"الرياض","postal_code":"12211"}}}'

    يرجع لك csid فيه private_key وbinary_security_token وsecret. احفظها عندك بأمان، ماثل ما يحتفظ فيها، وترسلها مع كل فاتورة.

  6. احفظ سلسلة الفواتير لكل جهاز

    كل جهاز (EGS) له سلسلة: عدّاد (ICV) يزيد واحد مع كل فاتورة، وهاش آخر فاتورة مقبولة (PIH) ترسله مع اللي بعدها.

    • زِد العدّاد واحفظ الهاش بعد رد 200 فقط.
    • الفاتورة المرفوضة ما تستهلك رقم: صلّحها وأرسلها بنفس العدّاد. غير كذا يطلع BR-KSA-16.
    • إعادة إرسال نفس الـ uuid تنحسب مرة وحدة.

  7. أرسل الفواتير واحفظ المستند

    كل فاتورة على POST /api/v1/invoices مع seller وcsid. الرد فيه:

    • invoice_xml: المستند النظامي المختوم، احفظه في أرشيفك.
    • qr: اطبعه على الفاتورة.
    • invoice_hash: للفاتورة اللي بعدها.
    • warnings وerrors: بنص الهيئة. التحذير ما يمنع القبول، والخطأ يرجع 422.

الضريبية والمبسّطة: وش يفرق في الربط؟

الضريبية (B2B، standard): تحتاج الرقم الضريبي للمشتري وعنوانه، وتنعمل لها clearance: الهيئة تختمها قبل ما تتسلّم للمشتري. المبسّطة (B2C، simplified): ما تحتاج بيانات المشتري، وتنعمل لها reporting خلال ٢٤ ساعة من إصدارها. ماثل يختار المسار حسب type.

أسئلة

هل أحتاج ترخيص من زاتكا عشان أربط برنامجي؟

ما فيه ترخيص لمزوّد الحل. المنشأة نفسها تسجّل أجهزتها بشهادة من حسابها في «فاتورة»، والحل لازم يطابق المتطلبات الفنية للهيئة.

كم ياخذ الربط؟

عن طريق ماثل: أول فاتورة على بوابة المطورين في دقيقة، وتسجيل الجهاز ثواني. الوقت الحقيقي هو ربط برنامجك بالـ API وتجربة أنواع فواتيرك.

وش أسوي لو الهيئة رفضت الفاتورة؟

اقرأ نص الخطأ اللي رجع، وشوف شرح أخطاء زاتكا الشائعة وحلولها.

ابدأ من الخطوة الثانية الحين

فاتورة حقيقية على بوابة المطورين، بدون شهادة ولا مفتاح.

جرّب فاتورة أو افتح التوثيق ←