تنسيق 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 — الحقول الإلزامية
| الحقل | النوع | الوصف | مثال |
|---|---|---|---|
InvoiceID | String (max 50) | الرقم الفريد للفاتورة | FAC-2026-001234 |
IssueDate | Date (YYYY-MM-DD) | تاريخ الإصدار | 2026-02-22 |
IssueTime | Time (HH:MM:SS) | وقت الإصدار | 14:30:00 |
InvoiceTypeCode | Code (3 أرقام) | نوع الوثيقة | 380 (فاتورة)، 381 (إشعار دائن) |
DocumentCurrencyCode | ISO 4217 | عملة الفاتورة | TND |
DueDate | Date | تاريخ استحقاق الدفع | 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 خطوات
- توليد XML الفاتورة (دون قسم Signature)
- معيرة وثيقة XML وفق خوارزمية C14N
- حساب بصمة SHA-256 للوثيقة المعيَّرة
- تشفير البصمة بالمفتاح الخاص لشهادة 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، تجري عملية الفوترة بالكامل عبر واجهة الويب لبوابة الفاتورة:
- يسجّل المستخدم دخوله على elfatoora.tn
- يُدخل بيانات الفاتورة في نموذج
- تُولّد البوابة XML TEIF تلقائيًا
- يوقّع المستخدم إلكترونيًا عبر شهادته (أو Mobile-ID)
- تُرسَل الفاتورة وتُتحقق منها في الوقت الفعلي
المزايا: لا حاجة لأي تطوير، جاهز للنشر فورًا القيود: لا أتمتة، إدخال يدوي فقط
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/token | POST | الحصول على رمز وصول OAuth2 |
/api/v1/invoices | POST | إرسال فاتورة جديدة |
/api/v1/invoices/{id} | GET | استرجاع حالة فاتورة |
/api/v1/invoices/{id}/ack | GET | تنزيل وصل الاستلام |
/api/v1/invoices/{id}/pdf | GET | تنزيل النسخة بصيغة PDF |
/api/v1/invoices/search | GET | البحث في الفواتير |
الروابط الأساسية:
- بيئة الاختبار:
https://api-sandbox.elfatoora.tn - الإنتاج:
https://api.elfatoora.tn
دورة حياة الفاتورة
تمرّ فاتورة TEIF بعدة حالات طوال دورة حياتها:
CREATED → SIGNED → SUBMITTED → VALIDATING → VALID
│
└── INVALID (مع رمز الخطأ)
| الحالة | الوصف | الإجراء المطلوب |
|---|---|---|
CREATED | XML مُوَلَّد، لم يُوقَّع بعد | توقيع الوثيقة |
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 دت/شهر، وهو مبلغ ضئيل للغاية.
خيارات الأرشفة:
- أرشفة TTN (موصى بها): تتولى TTN الحفظ والأمن والإتاحة
- أرشفة ذاتية: تحتفظ بملفات XML وPDF على خوادمك الخاصة، شريطة استيفاء معايير أمان DGI
- أرشفة هجينة: 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 الشركات التونسية في تحولها الرقمي. تواصل مع فريقنا التقني للحصول على تدقيق مجاني لنظامك الحالي.
ناقش مشروعك معنا
نحن هنا للمساعدة في احتياجات تطوير الويب الخاصة بك. حدد موعدًا لمناقشة مشروعك وكيف يمكننا مساعدتك.
دعنا نجد أفضل الحلول لاحتياجاتك.
مقالات ذات صلة

دمج API TTN في نظامك: دليل المطوّر التقني
دليل تقني متقدم للمطورين: دمج API TTN للفوترة الإلكترونية في تونس، توقيع TUNTRUST، توليد XML TEIF مع أمثلة كود Node.js/TypeScript.

التسجيل في الفاتورة: دليل عملي خطوة بخطوة
دليل شامل خطوة بخطوة للتسجيل في منصة الفاتورة لتونس تريدنت: المتطلبات الأولية، الوثائق اللازمة، بوابة الانتساب والتحقق التقني.

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