تكامل API TTN / الفاتورة مع نظام ERP: دليل شامل لـ Odoo و SAP و WooCommerce والأنظمة المخصصة

الفوترة الإلكترونية في تونس لم تعد اختيارية. مع توسيع الالتزام لمقدمي الخدمات (قانون المالية 2026) وعقوبات قد تصل إلى 50,000 دينار سنويًا، أصبح تكامل نظام إدارتك مع API TTN / الفاتورة أولوية تشغيلية.

نظرة عامة على API TTN

الهندسة العامة

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  نظام ERP   │────▶│  وسيط        │────▶│  توقيع       │
│  (الفوترة)   │     │  (تحقق       │     │  TUNTRUST    │
│              │     │   + TEIF)     │     │  (ANCE)      │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
                     ┌──────────────┐     ┌───────▼───────┐
                     │  الاستجابة   │◀────│  API TTN      │
                     │  (حالة،      │     │  الفاتورة     │
                     │   PDF، QR)   │     │               │
                     └──────────────┘     └───────────────┘

نقاط النهاية الرئيسية

المصادقة

API TTN تستخدم مصادقة بشهادة العميل (mutual TLS):

const agent = new https.Agent({
  cert: fs.readFileSync('/path/to/tuntrust-cert.pem'),
  key: fs.readFileSync('/path/to/private-key.pem'),
  ca: fs.readFileSync('/path/to/ance-ca.pem'),
});

السيناريو 1: تكامل Odoo

Odoo هو نظام ERP الأكثر انتشارًا في تونس للشركات الصغيرة والمتوسطة. نوصي بنهج قائم على الوسيط:

class AccountMove(models.Model):
    _inherit = 'account.move'
 
    elfatoora_status = fields.Selection([
        ('draft', 'مسودة'),
        ('submitted', 'مرسلة'),
        ('accepted', 'مقبولة'),
        ('rejected', 'مرفوضة'),
    ], string='حالة الفاتورة', default='draft')
    elfatoora_id = fields.Char('معرف الفاتورة')
 
    def action_submit_elfatoora(self):
        self.ensure_one()
        teif_data = self._generate_teif_xml()
        response = requests.post(
            'https://middleware.noqta.tn/api/v1/invoice/submit',
            json={'invoice_data': teif_data}
        )

السيناريو 2: SAP و Sage وأنظمة ERP أخرى

للأنظمة المغلقة (SAP, Sage, Microsoft Dynamics)، وسيط مخصص يترجم بين نسق بيانات ERP و TEIF XML.

السيناريو 3: أنظمة مخصصة (API مباشر)

للأنظمة المطورة حسب الطلب، راجع دليلنا التقني الكامل لتكامل API TTN.

السيناريو 4: التجارة الإلكترونية (WooCommerce, PrestaShop)

منصات التجارة الإلكترونية تتكامل عبر نهج webhook: عند إتمام الطلب، يستخرج الإضافة بيانات الفاتورة ويرسلها للوسيط.

المشاكل الشائعة

1. نسق المبالغ: TTN تتطلب 3 أرقام عشرية بالضبط (5000.000 وليس 5000.00)
2. المعرّف الجبائي: يجب أن يكون بالضبط XXXXXXXXA/M/NNN
3. انتهاء الشهادة: شهادات TUNTRUST تنتهي بعد سنتين
4. معالجة الأخطاء: نفّذ نظام إعادة المحاولة مع تأخير تصاعدي
5. ترقيم الفواتير: TTN تتحقق من التسلسل المتصل
6. إشعارات الدائن: يجب أن تشير إلى معرّف الفاتورة الأصلي في الفاتورة

نقطة: شريكك في تكامل TTN

أدمجنا API TTN في أكثر من 20 نظامًا مختلفًا. عرضنا:

• وسيط الفاتورة كخدمة — API REST موحد لجميع أنظمة ERP
• وحدات ERP جاهزة — Odoo، SAP، WooCommerce، PrestaShop
• تكامل مخصص — للأنظمة المطورة حسب الطلب
• تدريب ودعم — لفرقك التقنية والمحاسبية

📩 تواصل معنا للحصول على عرض سعر مجاني لتكامل TTN.

الأسئلة الشائعة

كم يستغرق تكامل TTN؟

لنظام ERP قياسي مع وسيطنا: 2-4 أسابيع. لنظام مخصص: 4-8 أسابيع.

كم تكلفة شهادة TUNTRUST؟

200-500 دينار حسب المزود المعتمد. صالحة لمدة سنتين.

هل يمكنني الاختبار قبل الانطلاق؟

نعم. TTN توفر بيئة sandbox. نضبط تكاملك في sandbox أولًا.

هل تقبل الفاتورة فواتير بالعملة الأجنبية؟

نسق TEIF بالدينار التونسي. الفواتير بالأورو/الدولار يجب أن تتضمن المبلغ المحول بسعر اليوم.

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

• التسجيل في الفاتورة: دليل خطوة بخطوة
• نسق TEIF: المواصفات التقنية
• تكامل API TTN للمطورين
• تدقيق امتثال الفوترة الإلكترونية
• الفوترة الإلكترونية في فرنسا — دليل للشركات التونسية