تنسيق TEIF والمواصفات التقنية للفاتورة الإلكترونية في تونس

فريق نقطة
بواسطة فريق نقطة ·

جاري تحميل مشغل تحويل النص إلى كلام الصوتي...

تعتمد الفاتورة الإلكترونية في تونس على تنسيق بيانات موحّد يُعرف بـ TEIF — Tunisian Electronic Invoice Format. يُعدّ فهم هذا التنسيق أمرًا لا غنى عنه لكل مطوّر أو مسؤول تقني مكلّف بدمج منصة الفاتورة في نظام المعلومات. يتناول هذا الدليل هيكل XML، والحقول الإلزامية، والتوقيع الرقمي، ورمز QR، ونمطَي التكامل المتاحَين.

هذا الدليل هو الحلقة الخامسة من سلسلتنا الفاتورة الإلكترونية في تونس. ويفترض أنك مسجّل مسبقًا على منصة الفاتورة. إن لم يكن ذلك كذلك، فراجع أولًا الحلقة الرابعة: دليل التسجيل خطوة بخطوة.


ما هو TEIF؟

TEIF (Tunisian Electronic Invoice Format) هو المعيار الوطني التونسي لتبادل الفواتير إلكترونيًا بين الشركات وبين الشركات والجهات الحكومية (B2B وB2G). وقد حدّدته شركة Tunisie TradeNet (TTN) بالتنسيق مع المديرية العامة للضرائب (DGI) والوكالة الوطنية للمصادقة الإلكترونية (ANCE).

يستند TEIF إلى لغة XML (eXtensible Markup Language) ويُحكم ببنية XSD (XML Schema Definition) التي تحدد الهيكل الإلزامي وقواعد التحقق من كل وثيقة.

الإصدارات الحالية:

  • الإصدار 1.8.7: الإصدار المستقر في الإنتاج منذ يناير 2026
  • الإصدار 1.9.x: قيد الإنهاء، لم يُنشر بعد في بيئة الإنتاج

يتوافق TEIF مع المعايير الدولية للفوترة الإلكترونية، ولا سيما UBL 2.1 (Universal Business Language) وCII (Cross Industry Invoice)، مع مراعاة الخصوصيات الضريبية التونسية (TVA التونسية، رسوم الطابع الجبائي، الضرائب على المواد الخاضعة لأنظمة خاصة).


هيكل مخطط XML/XSD

وثيقة TEIF هي ملف XML منظّم في أقسام هرمية متعددة. إليك الهيكل العام:

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:tn:gov:dgi:teif:1.8"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="urn:tn:gov:dgi:teif:1.8 TEIF_v1.8.7.xsd">
 
  <!-- القسم 1: رأس الفاتورة -->
  <Header>
    <InvoiceID>FAC-2026-001234</InvoiceID>
    <IssueDate>2026-02-22</IssueDate>
    <IssueTime>14:30:00</IssueTime>
    <InvoiceTypeCode>380</InvoiceTypeCode>
    <DocumentCurrencyCode>TND</DocumentCurrencyCode>
    <TaxCurrencyCode>TND</TaxCurrencyCode>
  </Header>
 
  <!-- القسم 2: الأطراف (المُصدِر والمستلِم) -->
  <Parties>
    <Supplier>...</Supplier>
    <Customer>...</Customer>
  </Parties>
 
  <!-- القسم 3: بنود الفاتورة -->
  <InvoiceLines>
    <InvoiceLine>...</InvoiceLine>
  </InvoiceLines>
 
  <!-- القسم 4: الإجماليات الضريبية -->
  <TaxTotal>...</TaxTotal>
 
  <!-- القسم 5: المبالغ الإجمالية -->
  <LegalMonetaryTotal>...</LegalMonetaryTotal>
 
  <!-- القسم 6: التوقيع الرقمي (يُضاف بعد التوليد) -->
  <Signature>...</Signature>
 
  <!-- القسم 7: الختم الإلكتروني المرئي (رمز QR) -->
  <VisibleElectronicSeal>...</VisibleElectronicSeal>
 
</Invoice>

الحقول الإلزامية وقواعد التحقق

يُميّز مخطط TEIF بين ثلاثة مستويات من الحقول: إلزامية (M — Mandatory) وشرطية (C — Conditional) واختيارية (O — Optional).

قسم Header — الحقول الإلزامية

الحقلالنوعالوصفمثال
InvoiceIDString (max 50)الرقم الفريد للفاتورةFAC-2026-001234
IssueDateDate (YYYY-MM-DD)تاريخ الإصدار2026-02-22
IssueTimeTime (HH:MM:SS)وقت الإصدار14:30:00
InvoiceTypeCodeCode (3 أرقام)نوع الوثيقة380 (فاتورة)، 381 (إشعار دائن)
DocumentCurrencyCodeISO 4217عملة الفاتورةTND
DueDateDateتاريخ استحقاق الدفع2026-03-22

رموز أنواع الوثائق

الرمزنوع الوثيقة
380فاتورة تجارية قياسية
381إشعار دائن (avoir)
383إشعار مدين
386دفعة مقدمة / فاتورة دفع مسبق
389الفوترة الذاتية

قسم Supplier (المُصدِر) — الحقول الإلزامية

<Supplier>
  <PartyIdentification>
    <ID schemeID="TN_MF">12345678A000000</ID> <!-- المعرّف الجبائي -->
  </PartyIdentification>
  <PartyName>
    <Name>Société Exemple SARL</Name>
  </PartyName>
  <PostalAddress>
    <StreetName>Avenue Habib Bourguiba</StreetName>
    <CityName>Tunis</CityName>
    <PostalZone>1000</PostalZone>
    <CountrySubentity>Tunis</CountrySubentity>
    <Country>
      <IdentificationCode>TN</IdentificationCode>
    </Country>
  </PostalAddress>
  <TaxScheme>
    <ID>TVA</ID>
    <TaxTypeCode>VAT</TaxTypeCode>
  </TaxScheme>
</Supplier>

قواعد مهمة:

  • schemeID="TN_MF" إلزامي للمعرّف الجبائي التونسي
  • يجب أن يتطابق العنوان تمامًا مع ما هو مُصرَّح به لدى المديرية العامة للضرائب
  • رمز البلد يجب أن يكون TN للشركات التونسية

قسم InvoiceLine — هيكل البند

<InvoiceLine>
  <ID>1</ID> <!-- الرقم التسلسلي للبند -->
  <InvoicedQuantity unitCode="C62">10</InvoicedQuantity>
  <LineExtensionAmount currencyID="TND">500.000</LineExtensionAmount>
  <Item>
    <Name>Prestation de développement web</Name>
    <SellersItemIdentification>
      <ID>PROD-001</ID>
    </SellersItemIdentification>
    <ClassifiedTaxCategory>
      <ID>S</ID> <!-- S=قياسي، Z=صفري، E=معفى -->
      <Percent>19</Percent>
      <TaxScheme>
        <ID>TVA</ID>
      </TaxScheme>
    </ClassifiedTaxCategory>
  </Item>
  <Price>
    <PriceAmount currencyID="TND">50.000</PriceAmount>
    <BaseQuantity unitCode="C62">1</BaseQuantity>
  </Price>
</InvoiceLine>

نسب TVA التونسية المعمول بها

الرمزالنسبةالتطبيق
S (قياسي)19%النسبة العامة
S (مخفّض 1)13%الخدمات المالية والتأمين
S (مخفّض 2)7%المواد الغذائية الأساسية والأدوية
Z (صفري)0%الصادرات والمنتجات المعفاة
E (معفى)-قطاعات معفاة بموجب القانون

دمج التوقيع الرقمي

التوقيع الرقمي هو الآلية التي تضمن صحة وسلامة فاتورة TEIF. ويستند إلى معيار XMLDSig (XML Digital Signature) الصادر عن W3C، باستخدام خوارزمية RSA-SHA256.

كيفية دمج التوقيع في XML

يُضاف التوقيع في قسم <Signature> من وثيقة XML بعد توليد محتوى الفاتورة:

<Signature Id="TEIF-SIG-001">
  <SignedInfo>
    <CanonicalizationMethod
      Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
    <SignatureMethod
      Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
    <Reference URI="">
      <Transforms>
        <Transform
          Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
      </Transforms>
      <DigestMethod
        Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
      <DigestValue>
        <!-- بصمة SHA256 للوثيقة بعد المعيرة -->
        7H3fKpL2mN9oQr1sT4uVwX6yZ8aB0cD2eF4gH6iJ8kL=
      </DigestValue>
    </Reference>
  </SignedInfo>
  <SignatureValue>
    <!-- قيمة توقيع RSA مُشفَّرة بـ Base64 -->
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
  </SignatureValue>
  <KeyInfo>
    <X509Data>
      <X509Certificate>
        <!-- شهادة TUNTRUST بـ Base64 -->
        MIIDpDCCAoygAwIBAgIUX7k2Y...
      </X509Certificate>
    </X509Data>
  </KeyInfo>
</Signature>

عملية التوقيع في 4 خطوات

  1. توليد XML الفاتورة (دون قسم Signature)
  2. معيرة وثيقة XML وفق خوارزمية C14N
  3. حساب بصمة SHA-256 للوثيقة المعيَّرة
  4. تشفير البصمة بالمفتاح الخاص لشهادة TUNTRUST ← قيمة التوقيع

تتبع عملية التحقق من التوقيع من قِبل TTN المسار العكسي: إعادة حساب البصمة وفكّ تشفير التوقيع بالمفتاح العام للشهادة.

مهم: يُبطل التوقيعُ أي تعديل لاحق على الوثيقة. فاتورة معدَّلة بعد التوقيع يجب إعادة توقيعها.


توليد رمز QR (الختم الإلكتروني المرئي)

الختم الإلكتروني المرئي (CEV) هو رمز QR يُطبع على الفاتورة يتيح لأي طرف ثالث (عميل، مراجع حسابات، إدارة ضريبية) التحقق السريع من صحة الفاتورة عبر مسح الرمز.

المحتوى المشفَّر في رمز QR

يحتوي رمز QR على رابط تحقق يشير إلى بوابة الفاتورة، مع المعاملات التالية مُشفَّرة:

المعاملالوصف
iidالمعرّف الفريد TTN للفاتورة (بصمة)
sidمعرّف المورّد (المعرّف الجبائي)
dtتاريخ ووقت الإصدار
amtالمبلغ الإجمالي شامل TVA
sigتوقيع التحكم (بصمة مختصرة)

مثال على الرابط المُشفَّر في رمز QR:

https://verify.elfatoora.tn/v?iid=a3f7e2b1c9d4&sid=12345678A000000&dt=20260222143000&amt=619.000&sig=f4e2a1b3

الدمج في XML TEIF

<VisibleElectronicSeal>
  <QRCode format="QR_CODE" version="2">
    <!-- بيانات رمز QR مُشفَّرة بـ Base64 -->
    aHR0cHM6Ly92ZXJpZnkuZWxmYXRvb3JhLnRuL3Y/...
  </QRCode>
  <SealDescription>Facture électronique certifiée TTN</SealDescription>
  <SealDate>2026-02-22T14:30:00</SealDate>
</VisibleElectronicSeal>

يجب توليد رمز QR بعد التوقيع الرقمي، إذ يتضمن مرجعًا لبصمة الفاتورة الموقّعة.


أنماط التكامل: Web Mode وEDI Mode

Web Mode

في Web Mode، تجري عملية الفوترة بالكامل عبر واجهة الويب لبوابة الفاتورة:

  1. يسجّل المستخدم دخوله على elfatoora.tn
  2. يُدخل بيانات الفاتورة في نموذج
  3. تُولّد البوابة XML TEIF تلقائيًا
  4. يوقّع المستخدم إلكترونيًا عبر شهادته (أو Mobile-ID)
  5. تُرسَل الفاتورة وتُتحقق منها في الوقت الفعلي

المزايا: لا حاجة لأي تطوير، جاهز للنشر فورًا القيود: لا أتمتة، إدخال يدوي فقط

EDI Mode (API)

في EDI Mode، يُولّد نظام المعلومات لديك فواتير TEIF ويُرسلها تلقائيًا عبر API REST الخاصة بـ TTN:

تدفق التكامل:

نظام ERP/CRM الخاص بك
    │
    ▼ (يُولّد XML TEIF)
وسيط التوقيع
    │
    ▼ (XML موقَّع)
API TTN (HTTPS/REST)
    │
    ▼ (تحقق + توثيق زمني)
منصة الفاتورة ──► DGI (تصريح ضريبي تلقائي)
    │
    ▼ (وصل استلام)
نظامك (تخزين + أرشفة)

نقاط الوصول API TTN (EDI Mode)

نقطة الوصولالطريقةالوصف
/api/v1/auth/tokenPOSTالحصول على رمز وصول OAuth2
/api/v1/invoicesPOSTإرسال فاتورة جديدة
/api/v1/invoices/{id}GETاسترجاع حالة فاتورة
/api/v1/invoices/{id}/ackGETتنزيل وصل الاستلام
/api/v1/invoices/{id}/pdfGETتنزيل النسخة بصيغة PDF
/api/v1/invoices/searchGETالبحث في الفواتير

الروابط الأساسية:

  • بيئة الاختبار: https://api-sandbox.elfatoora.tn
  • الإنتاج: https://api.elfatoora.tn

دورة حياة الفاتورة

تمرّ فاتورة TEIF بعدة حالات طوال دورة حياتها:

CREATED → SIGNED → SUBMITTED → VALIDATING → VALID
                                    │
                                    └── INVALID (مع رمز الخطأ)
الحالةالوصفالإجراء المطلوب
CREATEDXML مُوَلَّد، لم يُوقَّع بعدتوقيع الوثيقة
SIGNEDموقَّعة، لم تُرسَل بعدالإرسال إلى API
SUBMITTEDمستلَمة من TTN، التحقق جارٍالانتظار
VALIDATINGالتحقق جارٍ (أقل من 30 ثانية)الانتظار
VALIDمقبولة ومُؤرشَفةالاحتفاظ بوصل الاستلام
INVALIDمرفوضة لعدم المطابقةالتصحيح وإعادة الإرسال
CANCELLEDمُلغاة بإصدار إشعار دائنمراجعة الإشعار المرتبط

أرشفة الفواتير

تفرض اللوائح التونسية مدة أرشفة دنيا لا تقل عن 5 سنوات لجميع الفواتير الإلكترونية. تقدّم TTN خدمة أرشفة مُدارة بالتعريفات التالية:

الخدمةالتعريفة
تخزين XML/البيانات0,190 دت لكل شريحة 50 كيلوبايت
نسخة PDF من الفاتورة0,250 دت للوحدة
نسخة XML من الفاتورة0,250 دت للوحدة
الاستشارة عبر البوابةمشمولة في الاشتراك
تصدير الأرشيفاتبناءً على الطلب، تعريفة متغيرة

تقدير الكلفة: يتراوح حجم ملف XML TEIF المتوسط بين 5 و15 كيلوبايت حسب عدد البنود. لمؤسسة تُصدر 500 فاتورة شهريًا، تبلغ كلفة الأرشفة تقريبًا 0,95 إلى 2,85 دت/شهر، وهو مبلغ ضئيل للغاية.

خيارات الأرشفة:

  1. أرشفة TTN (موصى بها): تتولى TTN الحفظ والأمن والإتاحة
  2. أرشفة ذاتية: تحتفظ بملفات XML وPDF على خوادمك الخاصة، شريطة استيفاء معايير أمان DGI
  3. أرشفة هجينة: TTN + نسخة محلية متزامنة

مثال كامل لفاتورة TEIF

إليك فاتورة بسيطة لكنها كاملة بتنسيق TEIF 1.8.7، لخدمة مع TVA بنسبة 19%:

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:tn:gov:dgi:teif:1.8"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="urn:tn:gov:dgi:teif:1.8 TEIF_v1.8.7.xsd">
 
  <Header>
    <InvoiceID>FAC-2026-001234</InvoiceID>
    <IssueDate>2026-02-22</IssueDate>
    <IssueTime>14:30:00</IssueTime>
    <InvoiceTypeCode>380</InvoiceTypeCode>
    <DocumentCurrencyCode>TND</DocumentCurrencyCode>
    <TaxCurrencyCode>TND</TaxCurrencyCode>
    <DueDate>2026-03-22</DueDate>
    <Note>Facture pour services de développement web — Projet NoqtaApp v2</Note>
  </Header>
 
  <Parties>
    <Supplier>
      <PartyIdentification>
        <ID schemeID="TN_MF">12345678A000000</ID>
      </PartyIdentification>
      <PartyName>
        <Name>Tech Solutions SARL</Name>
      </PartyName>
      <PostalAddress>
        <StreetName>12 Rue des Entrepreneurs</StreetName>
        <CityName>Tunis</CityName>
        <PostalZone>1002</PostalZone>
        <CountrySubentity>Tunis</CountrySubentity>
        <Country><IdentificationCode>TN</IdentificationCode></Country>
      </PostalAddress>
      <Contact>
        <Telephone>+216 71 000 000</Telephone>
        <ElectronicMail>facturation@tech-solutions.tn</ElectronicMail>
      </Contact>
    </Supplier>
 
    <Customer>
      <PartyIdentification>
        <ID schemeID="TN_MF">98765432B000111</ID>
      </PartyIdentification>
      <PartyName>
        <Name>Client Entreprise SA</Name>
      </PartyName>
      <PostalAddress>
        <StreetName>45 Avenue de la République</StreetName>
        <CityName>Sfax</CityName>
        <PostalZone>3000</PostalZone>
        <CountrySubentity>Sfax</CountrySubentity>
        <Country><IdentificationCode>TN</IdentificationCode></Country>
      </PostalAddress>
    </Customer>
  </Parties>
 
  <InvoiceLines>
    <InvoiceLine>
      <ID>1</ID>
      <InvoicedQuantity unitCode="HUR">20</InvoicedQuantity>
      <LineExtensionAmount currencyID="TND">1000.000</LineExtensionAmount>
      <Item>
        <Name>Développement front-end React</Name>
        <ClassifiedTaxCategory>
          <ID>S</ID>
          <Percent>19</Percent>
          <TaxScheme><ID>TVA</ID></TaxScheme>
        </ClassifiedTaxCategory>
      </Item>
      <Price>
        <PriceAmount currencyID="TND">50.000</PriceAmount>
        <BaseQuantity unitCode="HUR">1</BaseQuantity>
      </Price>
    </InvoiceLine>
 
    <InvoiceLine>
      <ID>2</ID>
      <InvoicedQuantity unitCode="HUR">10</InvoicedQuantity>
      <LineExtensionAmount currencyID="TND">400.000</LineExtensionAmount>
      <Item>
        <Name>Intégration API et tests</Name>
        <ClassifiedTaxCategory>
          <ID>S</ID>
          <Percent>19</Percent>
          <TaxScheme><ID>TVA</ID></TaxScheme>
        </ClassifiedTaxCategory>
      </Item>
      <Price>
        <PriceAmount currencyID="TND">40.000</PriceAmount>
        <BaseQuantity unitCode="HUR">1</BaseQuantity>
      </Price>
    </InvoiceLine>
  </InvoiceLines>
 
  <TaxTotal>
    <TaxAmount currencyID="TND">266.000</TaxAmount>
    <TaxSubtotal>
      <TaxableAmount currencyID="TND">1400.000</TaxableAmount>
      <TaxAmount currencyID="TND">266.000</TaxAmount>
      <TaxCategory>
        <ID>S</ID>
        <Percent>19</Percent>
        <TaxScheme><ID>TVA</ID></TaxScheme>
      </TaxCategory>
    </TaxSubtotal>
  </TaxTotal>
 
  <LegalMonetaryTotal>
    <LineExtensionAmount currencyID="TND">1400.000</LineExtensionAmount>
    <TaxExclusiveAmount currencyID="TND">1400.000</TaxExclusiveAmount>
    <TaxInclusiveAmount currencyID="TND">1666.000</TaxInclusiveAmount>
    <PayableAmount currencyID="TND">1666.000</PayableAmount>
  </LegalMonetaryTotal>
 
  <!-- أقسام التوقيع ورمز QR تُضاف بواسطة عملية التوقيع -->
 
</Invoice>

نقاط جديرة بالملاحظة في هذا المثال:

  • تستخدم المبالغ 3 خانات عشرية (تنسيق الدينار التونسي: 1400.000)
  • رمز الوحدة HUR يوافق الساعات (وفق معيار UN/ECE 20)
  • مبالغ البند (LineExtensionAmount) لا تشمل TVA
  • TaxInclusiveAmount = TaxExclusiveAmount + TaxAmount (1400 + 266 = 1666)

قائمة التحقق قبل الإرسال

قبل إرسال أي فاتورة TEIF، تحقق دائمًا من هذه النقاط:

  • نجاح التحقق من XSD (لا أخطاء في المخطط)
  • المعرّف الجبائي للمُصدِر مطابق لتنسيق TN_MF
  • مجموع LineExtensionAmount = TaxExclusiveAmount
  • TaxInclusiveAmount = TaxExclusiveAmount + إجمالي TaxAmount
  • تاريخ الإصدار بتنسيق ISO 8601 (YYYY-MM-DD)
  • التوقيع الرقمي صالح (تحقق بالمفتاح العام)
  • رمز QR مُولَّد بعد التوقيع

التنقل في السلسلة

للاطلاع على تطبيق تقني كامل مع أمثلة كود Node.js/TypeScript، راجع الحلقة السابعة: دمج API TTN للمطورين.

هل تحتاج إلى دمج مخصص للفاتورة الإلكترونية في نظامك؟ تُرافق noqta.tn الشركات التونسية في تحولها الرقمي. تواصل مع فريقنا التقني للحصول على تدقيق مجاني لنظامك الحالي.


هل تريد قراءة المزيد من الدروس التعليمية؟ تحقق من أحدث درس تعليمي لدينا على إنشاء موقع على Google Sites مجاناً 2026 - دليل شامل خطوة بخطوة.

ناقش مشروعك معنا

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

دعنا نجد أفضل الحلول لاحتياجاتك.

مقالات ذات صلة