تخطَّ إلى المحتوى
AIMOCS

AIMOCS · أدلّة الحزم

دليل الحزمة

ربط وكيل Claude بفاتورة هيئة الزكاة المرحلة الثانية — الحزمة الإنتاجية للفوترة المُتَوافِقة

ربط وكيل Claude ببوّابة فاتورة يبدو بسيطاً حتى تكتشف أنَّ النموذج اللُّغوي لا يستطيع توليد البصمة التشفيريّة. هذه هي الحزمة التي نُحيط بها Claude كي يتولّى العمل اللُّغوي وتتولّى طبقةُ الالتزام الحتميّة دورها.

الحزمة

  • Anthropic Claude
  • Glama
  • Vercel
  • Supabase
  • Docker
  • MongoDB

تحديث · 2026-05-30

01الخلاصة
02الحزمة
  • L/01فهم النيّة واستخراج البيانات

    يأخذ Claude مدخلاً طبيعيّاً (محادثة واتساب، طلباً صوتيّاً، طلباً حرّاً) ويُنتج بيانات فاتورة مُهيكَلة: رقم العميل، الأصناف، الإجماليات، ضريبة القيمة المُضافة، طريقة الدفع. لا يكتب النموذج XML المُوقَّع مباشرة أبداً.

    • Anthropic Claude
  • L/02بوّابة الأدوات

    يكشف Glama عن أدوات نقاط البيع و ERP وملفّات العملاء أمام Claude عبر MCP. يقرأ الوكيل أسعار المنتجات، ويُراجع أرقام ضريبة القيمة المُضافة للعملاء، ويكتب حالة الطلب عبر سطح أدواتٍ موحَّد.

    • Glama
  • L/03وحدة EGS — طبقة التوقيع

    وحدة Electronic Generation Solution هي خدمة Node.js (أو أيِّ لغة) داخل حاوية Docker، قابلة للنشر على Vercel أو بنيةٍ تحتيّة داخل المملكة. تستقبل بيانات الفاتورة المُهيكَلة، تُولِّد XML بصيغة UBL 2.1 بشكلٍ حتمي، تُطبِّق SHA-256 + ECDSA-P256 بمفتاح CSID الخاص، ثُمَّ ترسل إلى واجهة الإقرار في فاتورة.

    • Docker
    • Vercel
  • L/04حالة كلِّ تاجر

    يحفظ Supabase حالة كلِّ وحدة EGS: شهادة CSID، مرحلة الإعداد (OTP، الامتثال، CSID الإنتاج)، روابط بوّابة فاتورة، آخر UUID صادر. صفٌّ واحد لكلِّ فرع أو وحدة EGS.

    • Supabase
  • L/05سجلُّ تدقيق غير قابل للتعديل

    يحمل MongoDB دورة حياة كلِّ فاتورة بالكامل: الإدخال الأصلي، البيانات المُستخرَجة، XML المُولَّد، التجزئة، استجابة الهيئة، أيّ إعادات. سجلٌّ إلحاقي فقط. هذا ما يطلبه المُدقِّقون والهيئة نفسها عند نشوء أيِّ نزاع.

    • MongoDB
03لماذا هذه الحزمة

النموذج اللُّغوي ليس في مسار التشفير

الإخفاق الأكثر شيوعاً للمرحلة الثانية هو محاولة جعل Claude يُولِّد XML المُوقَّع مباشرة. التوقيع يجب أن يكون حتميّاً وقابلاً للتحقّق. فصل الوكيل عن المُوقِّع هو القرار المعماري الذي يُتيح لك الإطلاق.

EGS لكلِّ فرع

تشترط الهيئة CSID منفصلاً لكلِّ وحدة Electronic Generation Solution. مطعمٌ بخمسة فروع يحتاج خمس وحدات EGS، خمس عمليّات إعداد، خمس سلاسل مفاتيح. هذا غير قابل للتفاوض؛ ضعه في نموذج البيانات من اليوم الأوّل.

إقرار، لا إبلاغ

فواتير B2B تستخدم نمط الإقرار: تُقَرّ كلُّ فاتورة عبر الهيئة قبل إصدارها. لا توجد دفعات. ابنِ من أجل استجابة متزامنة وإعادة محاولاتٍ لطيفة عند 5xx. فواتير B2C تُبلَّغ لاحقاً خلال 24 ساعة — مسار كود مختلف.

السجلّ الإلحاقي هو الإثبات

إذا اعترض عميلٌ على فاتورة مُقَرّة أو سألت الهيئة عن إرسالٍ مُعلَّم، سجلُّ MongoDB هو الإثبات. أيُّ قابليّة تعديل لأيِّ إدخالٍ تكسر السلسلة.

04أين تتألَّق
  • ◇/01

    طلبات واتساب للمطاعم حيث يجب أن يكون خطُّ الطلب-إلى-الفاتورة متوافقاً مع المرحلة الثانية من اليوم الأوّل.

  • ◇/02

    تجارة التجزئة والضيافة متعدّدة الفروع حيث كلُّ موقع وحدة EGS منفصلة بشهادة CSID خاصّة بها.

  • ◇/03

    خدمات B2B (مكاتب المحاماة، الوكالات، الاستشاريّون) حيث يبدأ تدفّق الفوترة من البريد أو الدردشة.

  • ◇/04

    أنظمة محاسبة المنشآت الصغيرة التي تُريد إضافة إدخال محادثاتي إلى تدفّق فوترةٍ قائم.

  • ◇/05

    منشآت الموجة 24 (حدّ 375 ألف ريال) المُواجِهة لموعد التكامل في 30 يونيو 2026.

05مقارنة

وكيل Claude + وحدة EGS مخصّصة (هذه الحزمة)

Pros

  • · النموذج يفعل ما يُجيده — الفهم الطبيعي — والتوقيع حتميٌّ قابل للتحقّق.
  • · يمكن إعادة نشر EGS دون إعادة تدريب الوكيل أو إعادة هندسة موجِّهاته.
  • · سجلُّ التدقيق سجلٌّ إلحاقيٌّ واحد عبر الطبقتَين اللُّغويّة والتشفيريّة.
  • · يُضيف خطَّ فوترةٍ متوافقاً للمرحلة الثانية إلى ERP قائمة دون اقتلاعها.

Cons

  • · خدمتان للتشغيل (الوكيل + EGS) بدل واحدة.
  • · إعداد CSID خطوةٌ يدويّةٌ لكلِّ فرع — لا يُمكن أتمتته بالكامل عبر الوكيل.

النموذج اللُّغوي فقط (يكتب XML المُوقَّع مباشرة)

Pros

  • · بنية أبسط على الورق.

Cons

  • · يفشل في تحقّق الهيئة فوراً — مخرجات النموذج غير حتميّة والتواقيع غير قابلة للتكرار.
  • · لا توجد وسيلة لتدقيق أيِّ XML تمَّ توقيعه فعلاً مقابل ما ادّعاه النموذج.
  • · سطرٌ واحد مُهلوَس في الفاتورة يُنتج مسؤوليّةً تنظيميّة.

وحدة ZATCA الأصليّة في ERP (SAP، Odoo، Foodics)

Pros

  • · يتولّى المُورِّد تجديد الشهادات وتحديثات المواصفات.
  • · لا كود مُخصّص للصيانة.

Cons

  • · مرتبط بـ ERP — إضافة سطح وكيل (واتساب، صوت) يتطلّب الجسر عبر ERP.
  • · تحكّمٌ محدود في التدفّق الموجَّه للعميل.
  • · في الغالب رسوم ترخيص إضافيّة لكلِّ فرع.

وسيط طرف ثالث "ZATCA كخدمة"

Pros

  • · يُلغي عبء إدارة الشهادات.
  • · إعداد أوّلي سريع.

Cons

  • · يُضيف طرفاً ثالثاً إلى السلسلة التشفيريّة — كلُّ فاتورة تمرّ عبر خادم المورِّد.
  • · تبعاتٌ على نظام PDPL لو عبرت بيانات العميل الحدود.
  • · تكلفةٌ مستمرّة لكلِّ فاتورة.
06ملاحظات التنفيذ
  1. 01

    شغّل وحدة EGS دائماً في توقيت Asia/Riyadh وإلا فقد تنحرف بصمات التوقيت الزمنيّ خارج النافذة المقبولة.

  2. 02

    لشهادة CSID صلاحيّة — جدول تدفّق التجديد قبل أوّل إعداد، لا بعد أوّل 90 يوماً.

  3. 03

    رابط بوّابة فاتورة في البيئة التجريبيّة مختلفٌ عن الإنتاجيّة. احفظهما في متغيّرات بيئة، لا في الكود. لقد رأينا CSID إنتاجيّاً يُرسَل إلى البيئة التجريبيّة بالخطأ أكثر من مرّة.

  4. 04

    حين تُعيد فاتورة استجابة 5xx، استخدم تراجعاً أسّيّاً بحدٍّ صارم. المحاولات المتكرّرة على نفس الفاتورة بنفس UUID قد تُدخِلك في حالة حجرٍ مع البوّابة.

  5. 05

    للمنشآت في الموجة 24 (حدّ 375 ألف ريال، موعد 30 يونيو 2026)، أعطِ الأولويّة لأبسط EGS ممكنة — فرعٌ واحد، CSID واحد، حاوية Docker واحدة — على سطح وكيلٍ مصقول. الموعد هو القيد، لا الوكيل.

07ذات صلة

القطاعات الملائمة

08أسئلة
  • هل يستطيع وكيل Claude توليد التوقيع التشفيري؟

    لا. التوقيع يجب أن يكون حتميّاً وقابلاً للتحقّق؛ النموذج اللُّغوي غير حتميّ بحكم التصميم. يجمع الوكيل البيانات ويُهيكِل الفاتورة؛ خدمةُ توقيعٍ منفصلة (وحدة EGS) تحسب التجزئة وتُوقِّع بمفتاح CSID الخاص. مواصفات الهيئة تفترض هذا الفصل.

  • هل نحتاج CSID منفصلاً لكلِّ فرع؟

    نعم. كلُّ وحدة Electronic Generation Solution تحصل على CSID خاصّة بها. مطعمٌ بخمسة فروع يعني خمس عمليّات OTP، خمس CSID امتثال، خمس CSID إنتاج. ضع نموذج EGS-متعدّد في طبقة بياناتك من اليوم الأوّل.

  • أيُّ مزوِّدي الذكاء الاصطناعي يمكن استخدامهم تحت نظام PDPL السعودي؟

    المزوِّدون بسيادة بيانات داخل المملكة هم الأبسط. لـ Anthropic عبر الواجهة العامّة، مرِّر فقط حقولاً مُهيكَلة غير مُعرِّفة عبر Claude واحفظ أسماء العملاء والتفاصيل المُعرِّفة في قاعدة بياناتك داخل المملكة. خطُّ التوقيع لا يرى بيانات بأسلوب الموجِّهات أبداً.

  • ما رابط البيئة التجريبيّة؟

    توفّر الهيئة بيئة تجريبيّة على sandbox.zatca.gov.sa/fatoora/onboarding. الانتقال إلى الإنتاج يحدث بعد اجتياز اختبار إقرار من CSID الخاصّة بك. CSID التجريبيّة والإنتاجيّة شهادتان منفصلتان — احفظهما في سلاسل مفاتيح منفصلة.

  • هل يمكننا تجميع الفواتير في دفعات؟

    لا توجد إقرارٌ بالدفعات لفواتير B2B — كلُّ فاتورة تُقَرّ منفردة قبل إصدارها. فواتير B2C يمكن إبلاغها لاحقاً في دفعاتٍ خلال 24 ساعة. خَطِّط لمسارَي كودٍ مختلفَين.

  • ماذا يحدث إذا رفضت فاتورة فاتورة مُقدَّمة؟

    تُعيد الهيئة خطأً مُهيكَلاً. على الوكيل ألاّ يُعيد المحاولة آلياً — أحِل إلى إنسان. الرفض الشائع (رقم ضريبة غير صحيح، سجلٌّ تجاريٌّ مفقود، تباين في التجزئة) يحتاج تصحيحاً في المصدر، لا إعادة محاولة بنفس الحمولة.

  • بمَ تختلف المرحلة الثانية عن المرحلة الأولى؟

    المرحلة الأولى (التوليد) اشترطت فواتير إلكترونيّة برمز QR وكان يمكن إصدارها دون اتصال. المرحلة الثانية (التكامل) تشترط إقراراً فوريّاً من بوّابة فاتورة عبر API. المرحلة الثانية تعني دائماً متّصلاً — صَمِّم للتعامل اللطيف مع زمن استجابة الإقرار.

  • ما أصغر حزمةٍ متوافقةٍ مع الهيئة؟

    لمنشأةٍ بفرعٍ واحد: خدمة Node.js EGS تعمل في Docker، CSID واحدة، تعريف أداة Claude واحد. التكلفة المستمرّة تُسيطر عليها تجديد CSID وبنيةٌ تحتيّةٌ بسيطة — أقلّ بكثير من 500 ريالٍ شهرياً. خطُّ الالتزام يعمل دون وكيل؛ إضافة الوكيل هي ما يجعل سطح العميل محادثاتيّاً.

09ابدأ

لا نقدّم استشارات في الذكاء الاصطناعي. نحن نُديره نيابةً عنك.

احجز استشارة

مُثبَت على بياناتك قبل أن تلتزم.