⏰ متبقي 18 يوماً على موعد الموجة 24 (30 يونيو 2026).
راجع صفحة العد التنازلي وقائمة الجاهزية أو ابدأ الامتثال مع فاتورة Fattourh الآن.
ترميز TLV في رمز QR لفاتورة زاتكا: شرح تقني مبسط
الجواب المختصر
ترميز TLV (وسم-طول-قيمة) يحوّل حقول الفاتورة الخمسة إلى سلسلة بايتات: لكل حقل بايت يحدد الوسم (1-5)، وبايت يحدد طول القيمة بالبايت، ثم القيمة نفسها بترميز UTF-8. تُسلسل الحقول الخمسة ثم تُحوَّل Base64 وتوضع في رمز QR.
الخطأ الأكثر شيوعاً: طول النص العربي
الطول في TLV يُحسب بالبايت لا بالحرف. اسم بائع عربي من 10 أحرف يستهلك نحو 20 بايت لأن الحرف العربي في UTF-8 يشغل بايتين. حساب الطول بعدد الأحرف يكسر الرمز ويفشل التحقق — هذا أكثر سبب نراه لرموز QR مرفوضة.
فاتورة Fattourh يحسب الأطوال على مستوى البايت ويختبر كل رمز قبل إصداره، فلا تحتاج للتعامل مع هذه التفاصيل يدوياً.
مثال عملي مصغّر
لحقل الإجمالي "1150.00" (وسم 4): البايت الأول 0x04، طول القيمة 7 بايت أي 0x07، ثم بايتات النص. تُكرر العملية للحقول الخمسة بالترتيب، تُسلسل البايتات، ثم Base64. الناتج هو حمولة رمز QR التي يقرأها تطبيق الهيئة.
4 خطوات عملية
- جهّز القيم الخمس: اسم البائع، الرقم الضريبي، طابع ISO 8601، الإجمالي، ومبلغ الضريبة — بالصيغ الدقيقة.
- رمّز كل حقل TLV: وسم (بايت) + طول بالبايت (بايت) + القيمة UTF-8.
- سلسل وحوّل Base64: اربط الحقول الخمسة بالترتيب وحوّل الناتج إلى Base64.
- ولّد رمز QR واختبره: ضع سلسلة Base64 في الرمز وامسحه بتطبيق الهيئة للتحقق.
ابدأ الامتثال مجاناً الآن
5 فواتير شهرياً مجاناً — رمز QR وXML متوافقان في كل فاتورة.
أنشئ حسابك مجاناًأو راجع الأسعار أو منهجية التوافق التقني.
أسئلة شائعة
لماذا TLV وليس JSON أو رابطاً؟
TLV أصغر حجماً وأسرع قراءة ولا يحتاج اتصالاً بالإنترنت للتحقق، ويسمح بإضافة وسوم جديدة (كوسوم المرحلة الثانية) دون كسر القارئات القديمة.
ما وسوم المرحلة الثانية الإضافية؟
تضيف مواصفات المرحلة الثانية وسوماً لهاش XML والختم التشفيري والمفتاح العام وفق ما تنشره الهيئة في المواصفة الأمنية. راجع أحدث نسخة من المواصفات على zatca.gov.sa.
هل أحتاج لبرمجة هذا بنفسي؟
لا — أنظمة الفوترة المتوافقة مثل فاتورة Fattourh تتولى الترميز كاملاً. هذا الشرح للمطورين ولأصحاب المنشآت الذين يريدون فهم ما يحدث داخل الرمز.
TLV Encoding for ZATCA QR Codes: A Technical Walkthrough — English summary
TLV (Tag-Length-Value) encoding turns the five invoice fields into a byte string: one byte for the tag (1-5), one byte for the value length in bytes, then the UTF-8 value. The five fields are concatenated and Base64-encoded into the QR payload.
- Each TLV field = 1 tag byte + 1 length byte (in BYTES, not characters) + UTF-8 value.
- Arabic characters take 2 bytes in UTF-8 — character-count lengths are the #1 cause of invalid QR codes.
- Concatenate tags 1-5 in order, Base64-encode, embed in the QR code, verify with the ZATCA app.
Fattourh is an independent platform and is not affiliated with, certified by, or endorsed by ZATCA or any Saudi government body. This content is general guidance, not legal advice — always verify against official sources at zatca.gov.sa.
أدلة أخرى قد تهمّك
- دليل المرحلة الأولى من الفوترة الإلكترونية (مرحلة الإصدار)
- دليل المرحلة الثانية من الفوترة الإلكترونية (الربط والتكامل)
- الموجة 24 من الفوترة الإلكترونية — الموعد النهائي 30 يونيو 2026
- ما هي زاتكا (هيئة الزكاة والضريبة والجمارك)؟ دليل المبتدئين
- رمز QR في الفاتورة الإلكترونية: كيف يعمل وماذا يحتوي؟
- العد التنازلي لموعد الموجة 24
- برنامج الفوترة الإلكترونية المتوافق
فاتورة Fattourh منصة مستقلة وغير مرتبطة بهيئة الزكاة والضريبة والجمارك ولا تدّعي أي اعتماد أو شراكة رسمية. المعلومات هنا للتوعية العامة وليست استشارة قانونية — راجع دائماً المصادر الرسمية على zatca.gov.sa.