Tarawud jofotara Tarawud jofotara API
English تسجيل الدخول

واجهة الفوترة الإلكترونية

Issue electronic invoices to the Jordanian, Saudi, and Egyptian tax authorities from your own system. One API key, one consistent response shape.

🇯🇴 الأردن — جوفوترة 4 🇸🇦 السعودية — هيئة الزكاة والضريبة والجمارك 6 🇪🇬 Egypt — ETA 2

البدء

  1. 1 أنشئ حساب شركة وأكمل التسجيل.
  2. 2 Choose your tax authority — Jordan, Saudi Arabia, or Egypt — during registration.
  3. 3 Complete the integration setup for that authority: JoFotara credentials, ZATCA certificate onboarding, or ETA OAuth and eSeal.
  4. 4 انسخ مفتاح الواجهة المشفّر من «واجهات API للشركة» في لوحة التحكم.
  5. 5 أرسل فاتورتك الأولى عبر النقاط أدناه.
النقاط التي تستخدمها تعتمد على جهتك الضريبية. الطلب المُرسل للمجموعة الخطأ يُرفض برسالة توضّح المجموعة الصحيحة.

المصادقة

كل طلب يجب أن يحمل مفتاح API المشفّر. أي من الطرق الثلاث يعمل — اختر ما يناسب عميل HTTP لديك.

X-Api-Key: YOUR_API_KEY — ترويسة الطلب (مستحسن)
Authorization: Bearer YOUR_API_KEY — توكن Bearer
"api_key": "YOUR_API_KEY" — حقل داخل جسم JSON
تعامل مع المفتاح كأنه كلمة مرور. هو مرتبط بشركة واحدة وبيئة واحدة — لا تنشره في كود يعمل على المتصفح.

البيئات

لكل شركة بيئة تجريبية وأخرى حيّة، ولكل منهما مفتاح مختلف. إرسالات البيئة التجريبية لا تُقدَّم للجهة الضريبية إطلاقاً.

البيئة السلوك
تجريبي تتحقق من بياناتك وتحفظ الفاتورة دون إرسالها للجهة الضريبية. استخدمها أثناء التطوير.
حي توقّع الفاتورة وترسلها للجهة الضريبية. وتُعيد المعرّف الفريد ورمز QR الرسميين.

شكل الاستجابة

كل استجابة بنفس الشكل، فتستطيع قراءة status و message مهما حدث. عند الفشل يحوي errors مدخلاً لكل حقل غير صحيح.

نجاح 
{
    "status": "success",
    "message": "Invoice reported to ZATCA.",
    "data": {
        "invoice_number": "SA-001",
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "zatca_status": "REPORTED",
        "invoice_hash": "NWZlMzJkNGE5ZDIwYzM4...",
        "qr_code": "AQ4tYXJhd3VkIENvbXBhbnkC..."
    }
}
فشل 
{
    "status": "error",
    "message": "The submitted invoice data is invalid.",
    "errors": {
        "buyer.vat_number": [
            "The buyer VAT number must be 15 digits, starting and ending with 3."
        ]
    },
    "data": []
}

🇯🇴 الأردن — جوفوترة

تفرّق جوفوترة بين الفواتير العامة وفواتير الدخل، ولكل منهما إشعار دائن. وأرقام الضريبة على مستوى البند يرسلها العميل.

الرابط الأساسي: https://jofotara.theonesystemco.com/api/integration/user د.أ ضريبة 16%
POST /api/integration/user/general

فاتورة عامة

فاتورة ضريبية عام (B2C)

الحقل النوع مطلوب الوصف
invoice_no string مطلوب رقم فاتورتك. يجب أن يكون فريداً داخل كل بيئة.
issue_date date مطلوب تاريخ الإصدار بصيغة YYYY-MM-DD.
payment_method_code string مطلوب 012 أو 022 للفواتير العامة، و011 أو 021 لفواتير الدخل.
customer_name string مطلوب اسم المشتري.
customer_id string اختياري الرقم الضريبي أو الوطني للمشتري.
amount number مطلوب إجمالي الخصم، كما يتطلبه مخطط الفاتورة العامة.
tax_amount number مطلوب إجمالي الضريبة على الفاتورة.
items[].name string مطلوب وصف البند.
items[].quantity number مطلوب الكمية. الكسور مسموحة، مثل 1.5.
items[].price number مطلوب سعر الوحدة قبل الضريبة.
items[].discount number اختياري الخصم على البند. الافتراضي 0.
items[].tax_percent number مطلوب نسبة الضريبة، وعادة 16% لجهتك الضريبية.
items[].total number مطلوب إجمالي البند شاملاً الضريبة.
items[].line_extension_amount number مطلوب إجمالي البند قبل الضريبة وبعد الخصم.
items[].tax_amount number مطلوب قيمة الضريبة على البند.
tax_exclusive_amount number مطلوب إجمالي الفاتورة قبل الضريبة.
tax_inclusive_amount number مطلوب إجمالي الفاتورة شاملاً الضريبة.
allowance_total_amount number مطلوب إجمالي الخصومات على الفاتورة.
payable_amount number مطلوب المبلغ المستحق على المشتري.
مثال على الطلب 
{
    "invoice_no": "INV-001",
    "issue_date": "2026-08-05",
    "payment_method_code": "012",
    "customer_name": "عميل تجريبي",
    "items": [
        {
            "name": "منتج 1",
            "quantity": 1,
            "price": 100,
            "discount": 0,
            "line_extension_amount": 100,
            "tax_percent": 16,
            "tax_amount": 16,
            "total": 116
        }
    ],
    "amount": 0,
    "tax_amount": 16,
    "tax_exclusive_amount": 100,
    "tax_inclusive_amount": 116,
    "allowance_total_amount": 0,
    "payable_amount": 116
}
POST /api/integration/user/general-credit

مرتجع عام

مرتجع عام / إشعار دائن

الحقل النوع مطلوب الوصف
original_invoice_no string مطلوب رقم الفاتورة المراد إرجاعها.
original_uid string مطلوب المعرّف الفريد الذي أُعيد عند إرسال الفاتورة الأصلية.
description_return_reason string مطلوب سبب إرجاع الفاتورة.
مثال على الطلب 
{
    "invoice_no": "RET-001",
    "original_invoice_no": "INV-001",
    "original_uid": "550e8400-e29b-41d4-a716-446655440000",
    "issue_date": "2026-08-05",
    "description_return_reason": "مرتجع بضاعة",
    "items": [
        {
            "name": "منتج 1",
            "quantity": 1,
            "price": 100,
            "discount": 0,
            "line_extension_amount": 100,
            "tax_percent": 16,
            "tax_amount": 16,
            "total": 116
        }
    ],
    "amount": 0,
    "tax_amount": 16,
    "tax_exclusive_amount": 100,
    "tax_inclusive_amount": 116,
    "allowance_total_amount": 0,
    "payable_amount": 116
}
POST /api/integration/user/income

فاتورة دخل

فاتورة ضريبية دخل (B2B)

الحقل النوع مطلوب الوصف
invoice_no string مطلوب رقم فاتورتك. يجب أن يكون فريداً داخل كل بيئة.
issue_date date مطلوب تاريخ الإصدار بصيغة YYYY-MM-DD.
payment_method_code string مطلوب 012 أو 022 للفواتير العامة، و011 أو 021 لفواتير الدخل.
customer_name string مطلوب اسم المشتري.
items[].name string مطلوب وصف البند.
items[].quantity number مطلوب الكمية. الكسور مسموحة، مثل 1.5.
items[].price number مطلوب سعر الوحدة قبل الضريبة.
items[].discount number اختياري الخصم على البند. الافتراضي 0.
items[].tax_percent number اختياري نسبة الضريبة، وعادة 16% لجهتك الضريبية.
items[].total number مطلوب إجمالي البند شاملاً الضريبة.
tax_exclusive_amount number مطلوب إجمالي الفاتورة قبل الضريبة.
tax_inclusive_amount number مطلوب إجمالي الفاتورة شاملاً الضريبة.
allowance_total_amount number مطلوب إجمالي الخصومات على الفاتورة.
payable_amount number مطلوب المبلغ المستحق على المشتري.
مثال على الطلب 
{
    "invoice_no": "INC-001",
    "issue_date": "2026-08-05",
    "payment_method_code": "011",
    "customer_name": "عميل تجريبي",
    "items": [
        {
            "name": "خدمة 1",
            "quantity": 1,
            "price": 100,
            "discount": 0,
            "tax_percent": 16,
            "total": 116
        }
    ],
    "tax_exclusive_amount": 100,
    "tax_inclusive_amount": 116,
    "allowance_total_amount": 0,
    "payable_amount": 116
}
POST /api/integration/user/income-credit

مرتجع دخل

مرتجع دخل / إشعار دائن

الحقل النوع مطلوب الوصف
original_invoice_no string مطلوب رقم الفاتورة المراد إرجاعها.
original_uid string مطلوب المعرّف الفريد الذي أُعيد عند إرسال الفاتورة الأصلية.
original_total_amount number مطلوب إجمالي الفاتورة الأصلية.
description_return_reason string اختياري سبب إرجاع الفاتورة.
مثال على الطلب 
{
    "invoice_no": "INC-RET-001",
    "original_invoice_no": "INC-001",
    "original_uid": "550e8400-e29b-41d4-a716-446655440002",
    "original_total_amount": 116,
    "issue_date": "2026-08-05",
    "payment_method_code": "011",
    "description_return_reason": "مرتجع خدمة",
    "items": [
        {
            "name": "خدمة 1",
            "quantity": 1,
            "price": 100,
            "discount": 0,
            "tax_percent": 16,
            "total": 116
        }
    ],
    "tax_exclusive_amount": 100,
    "tax_inclusive_amount": 116,
    "allowance_total_amount": 0,
    "payable_amount": 116
}

🇸🇦 السعودية — هيئة الزكاة والضريبة والجمارك

تفرّق الهيئة بين الفاتورة الضريبية التي تعتمدها قبل تسليمها للمشتري، والفاتورة المبسّطة التي يُبلَّغ عنها بعد الإصدار. والمجاميع تُحسب من البنود، فلا ترسلها.

الرابط الأساسي: https://jofotara.theonesystemco.com/api/integration/zatca ر.س ضريبة 15%
POST /api/integration/zatca/standard-invoice

فاتورة ضريبية

بين المنشآت — تعتمدها الهيئة قبل التسليم

الحقل النوع مطلوب الوصف
invoice_number string مطلوب رقم المستند لديك. يجب أن يكون فريداً داخل الشركة.
issue_date date مطلوب تاريخ الإصدار بصيغة YYYY-MM-DD.
issue_time time اختياري وقت الإصدار بصيغة HH:MM:SS. الافتراضي وقت الإرسال.
notes string اختياري ملاحظة حرة تظهر على المستند.
buyer.name string مطلوب اسم المشتري.
buyer.vat_number string مطلوب الرقم الضريبي للمشتري — 15 رقماً يبدأ وينتهي بـ 3.
buyer.street string مطلوب اسم الشارع.
buyer.building_number string مطلوب رقم المبنى، عادة أربعة أرقام.
buyer.district string مطلوب الحي.
buyer.city string مطلوب المدينة.
buyer.postal_code string مطلوب الرمز البريدي، عادة خمسة أرقام.
buyer.country_code string اختياري رمز الدولة من حرفين. الافتراضي SA.
lines[].name string مطلوب وصف البند.
lines[].quantity number مطلوب الكمية. الكسور مسموحة، مثل 1.5.
lines[].unit_price number مطلوب سعر الوحدة قبل الضريبة.
lines[].discount number اختياري الخصم على البند. الافتراضي 0.
lines[].vat_rate number مطلوب نسبة الضريبة — 15 للنسبة الأساسية، و0 للمعفى أو صفري النسبة.
مثال على الطلب 
{
    "invoice_number": "SA-001",
    "issue_date": "2026-08-05",
    "issue_time": "14:30:00",
    "buyer": {
        "name": "شركة المشتري",
        "vat_number": "300000000000003",
        "street": "King Fahd Road",
        "building_number": "1234",
        "district": "Al Olaya",
        "city": "Riyadh",
        "postal_code": "12345",
        "country_code": "SA"
    },
    "lines": [
        {
            "name": "منتج 1",
            "quantity": 1,
            "unit_price": 100,
            "discount": 0,
            "vat_rate": 15
        }
    ]
}
POST /api/integration/zatca/simplified-invoice

فاتورة مبسّطة

للمستهلك — يُبلَّغ عنها بعد الإصدار

الحقل النوع مطلوب الوصف
invoice_number string مطلوب رقم المستند لديك. يجب أن يكون فريداً داخل الشركة.
issue_date date مطلوب تاريخ الإصدار بصيغة YYYY-MM-DD.
issue_time time اختياري وقت الإصدار بصيغة HH:MM:SS. الافتراضي وقت الإرسال.
notes string اختياري ملاحظة حرة تظهر على المستند.
buyer.name string اختياري اسم المشتري.
buyer.vat_number string اختياري الرقم الضريبي للمشتري — 15 رقماً يبدأ وينتهي بـ 3.
buyer.street string اختياري اسم الشارع.
buyer.building_number string اختياري رقم المبنى، عادة أربعة أرقام.
buyer.district string اختياري الحي.
buyer.city string اختياري المدينة.
buyer.postal_code string اختياري الرمز البريدي، عادة خمسة أرقام.
buyer.country_code string اختياري رمز الدولة من حرفين. الافتراضي SA.
lines[].name string مطلوب وصف البند.
lines[].quantity number مطلوب الكمية. الكسور مسموحة، مثل 1.5.
lines[].unit_price number مطلوب سعر الوحدة قبل الضريبة.
lines[].discount number اختياري الخصم على البند. الافتراضي 0.
lines[].vat_rate number مطلوب نسبة الضريبة — 15 للنسبة الأساسية، و0 للمعفى أو صفري النسبة.
مثال على الطلب 
{
    "invoice_number": "SA-001",
    "issue_date": "2026-08-05",
    "issue_time": "14:30:00",
    "lines": [
        {
            "name": "منتج 1",
            "quantity": 1,
            "unit_price": 100,
            "discount": 0,
            "vat_rate": 15
        }
    ]
}
POST /api/integration/zatca/standard-credit-note

إشعار دائن ضريبي

إشعار دائن مقابل فاتورة ضريبية

الحقل النوع مطلوب الوصف
invoice_number string مطلوب رقم المستند لديك. يجب أن يكون فريداً داخل الشركة.
issue_date date مطلوب تاريخ الإصدار بصيغة YYYY-MM-DD.
issue_time time اختياري وقت الإصدار بصيغة HH:MM:SS. الافتراضي وقت الإرسال.
notes string اختياري ملاحظة حرة تظهر على المستند.
original_invoice_number string مطلوب رقم المستند المراد تعديله.
original_invoice_uuid string مطلوب المعرّف الفريد المُعاد عند إرسال المستند الأصلي.
reason string مطلوب سبب تعديل المستند.
buyer.name string مطلوب اسم المشتري.
buyer.vat_number string مطلوب الرقم الضريبي للمشتري — 15 رقماً يبدأ وينتهي بـ 3.
buyer.street string مطلوب اسم الشارع.
buyer.building_number string مطلوب رقم المبنى، عادة أربعة أرقام.
buyer.district string مطلوب الحي.
buyer.city string مطلوب المدينة.
buyer.postal_code string مطلوب الرمز البريدي، عادة خمسة أرقام.
buyer.country_code string اختياري رمز الدولة من حرفين. الافتراضي SA.
lines[].name string مطلوب وصف البند.
lines[].quantity number مطلوب الكمية. الكسور مسموحة، مثل 1.5.
lines[].unit_price number مطلوب سعر الوحدة قبل الضريبة.
lines[].discount number اختياري الخصم على البند. الافتراضي 0.
lines[].vat_rate number مطلوب نسبة الضريبة — 15 للنسبة الأساسية، و0 للمعفى أو صفري النسبة.
مثال على الطلب 
{
    "invoice_number": "SA-001",
    "issue_date": "2026-08-05",
    "issue_time": "14:30:00",
    "original_invoice_number": "SA-001",
    "original_invoice_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "مرتجع بضاعة",
    "buyer": {
        "name": "شركة المشتري",
        "vat_number": "300000000000003",
        "street": "King Fahd Road",
        "building_number": "1234",
        "district": "Al Olaya",
        "city": "Riyadh",
        "postal_code": "12345",
        "country_code": "SA"
    },
    "lines": [
        {
            "name": "منتج 1",
            "quantity": 1,
            "unit_price": 100,
            "discount": 0,
            "vat_rate": 15
        }
    ]
}
POST /api/integration/zatca/simplified-credit-note

إشعار دائن مبسّط

إشعار دائن مقابل فاتورة مبسّطة

الحقل النوع مطلوب الوصف
invoice_number string مطلوب رقم المستند لديك. يجب أن يكون فريداً داخل الشركة.
issue_date date مطلوب تاريخ الإصدار بصيغة YYYY-MM-DD.
issue_time time اختياري وقت الإصدار بصيغة HH:MM:SS. الافتراضي وقت الإرسال.
notes string اختياري ملاحظة حرة تظهر على المستند.
original_invoice_number string مطلوب رقم المستند المراد تعديله.
original_invoice_uuid string مطلوب المعرّف الفريد المُعاد عند إرسال المستند الأصلي.
reason string مطلوب سبب تعديل المستند.
buyer.name string اختياري اسم المشتري.
buyer.vat_number string اختياري الرقم الضريبي للمشتري — 15 رقماً يبدأ وينتهي بـ 3.
buyer.street string اختياري اسم الشارع.
buyer.building_number string اختياري رقم المبنى، عادة أربعة أرقام.
buyer.district string اختياري الحي.
buyer.city string اختياري المدينة.
buyer.postal_code string اختياري الرمز البريدي، عادة خمسة أرقام.
buyer.country_code string اختياري رمز الدولة من حرفين. الافتراضي SA.
lines[].name string مطلوب وصف البند.
lines[].quantity number مطلوب الكمية. الكسور مسموحة، مثل 1.5.
lines[].unit_price number مطلوب سعر الوحدة قبل الضريبة.
lines[].discount number اختياري الخصم على البند. الافتراضي 0.
lines[].vat_rate number مطلوب نسبة الضريبة — 15 للنسبة الأساسية، و0 للمعفى أو صفري النسبة.
مثال على الطلب 
{
    "invoice_number": "SA-001",
    "issue_date": "2026-08-05",
    "issue_time": "14:30:00",
    "original_invoice_number": "SA-001",
    "original_invoice_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "مرتجع بضاعة",
    "lines": [
        {
            "name": "منتج 1",
            "quantity": 1,
            "unit_price": 100,
            "discount": 0,
            "vat_rate": 15
        }
    ]
}
POST /api/integration/zatca/standard-debit-note

إشعار مدين ضريبي

إشعار مدين مقابل فاتورة ضريبية

الحقل النوع مطلوب الوصف
invoice_number string مطلوب رقم المستند لديك. يجب أن يكون فريداً داخل الشركة.
issue_date date مطلوب تاريخ الإصدار بصيغة YYYY-MM-DD.
issue_time time اختياري وقت الإصدار بصيغة HH:MM:SS. الافتراضي وقت الإرسال.
notes string اختياري ملاحظة حرة تظهر على المستند.
original_invoice_number string مطلوب رقم المستند المراد تعديله.
original_invoice_uuid string مطلوب المعرّف الفريد المُعاد عند إرسال المستند الأصلي.
reason string مطلوب سبب تعديل المستند.
buyer.name string مطلوب اسم المشتري.
buyer.vat_number string مطلوب الرقم الضريبي للمشتري — 15 رقماً يبدأ وينتهي بـ 3.
buyer.street string مطلوب اسم الشارع.
buyer.building_number string مطلوب رقم المبنى، عادة أربعة أرقام.
buyer.district string مطلوب الحي.
buyer.city string مطلوب المدينة.
buyer.postal_code string مطلوب الرمز البريدي، عادة خمسة أرقام.
buyer.country_code string اختياري رمز الدولة من حرفين. الافتراضي SA.
lines[].name string مطلوب وصف البند.
lines[].quantity number مطلوب الكمية. الكسور مسموحة، مثل 1.5.
lines[].unit_price number مطلوب سعر الوحدة قبل الضريبة.
lines[].discount number اختياري الخصم على البند. الافتراضي 0.
lines[].vat_rate number مطلوب نسبة الضريبة — 15 للنسبة الأساسية، و0 للمعفى أو صفري النسبة.
مثال على الطلب 
{
    "invoice_number": "SA-001",
    "issue_date": "2026-08-05",
    "issue_time": "14:30:00",
    "original_invoice_number": "SA-001",
    "original_invoice_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "مرتجع بضاعة",
    "buyer": {
        "name": "شركة المشتري",
        "vat_number": "300000000000003",
        "street": "King Fahd Road",
        "building_number": "1234",
        "district": "Al Olaya",
        "city": "Riyadh",
        "postal_code": "12345",
        "country_code": "SA"
    },
    "lines": [
        {
            "name": "منتج 1",
            "quantity": 1,
            "unit_price": 100,
            "discount": 0,
            "vat_rate": 15
        }
    ]
}
POST /api/integration/zatca/simplified-debit-note

إشعار مدين مبسّط

إشعار مدين مقابل فاتورة مبسّطة

الحقل النوع مطلوب الوصف
invoice_number string مطلوب رقم المستند لديك. يجب أن يكون فريداً داخل الشركة.
issue_date date مطلوب تاريخ الإصدار بصيغة YYYY-MM-DD.
issue_time time اختياري وقت الإصدار بصيغة HH:MM:SS. الافتراضي وقت الإرسال.
notes string اختياري ملاحظة حرة تظهر على المستند.
original_invoice_number string مطلوب رقم المستند المراد تعديله.
original_invoice_uuid string مطلوب المعرّف الفريد المُعاد عند إرسال المستند الأصلي.
reason string مطلوب سبب تعديل المستند.
buyer.name string اختياري اسم المشتري.
buyer.vat_number string اختياري الرقم الضريبي للمشتري — 15 رقماً يبدأ وينتهي بـ 3.
buyer.street string اختياري اسم الشارع.
buyer.building_number string اختياري رقم المبنى، عادة أربعة أرقام.
buyer.district string اختياري الحي.
buyer.city string اختياري المدينة.
buyer.postal_code string اختياري الرمز البريدي، عادة خمسة أرقام.
buyer.country_code string اختياري رمز الدولة من حرفين. الافتراضي SA.
lines[].name string مطلوب وصف البند.
lines[].quantity number مطلوب الكمية. الكسور مسموحة، مثل 1.5.
lines[].unit_price number مطلوب سعر الوحدة قبل الضريبة.
lines[].discount number اختياري الخصم على البند. الافتراضي 0.
lines[].vat_rate number مطلوب نسبة الضريبة — 15 للنسبة الأساسية، و0 للمعفى أو صفري النسبة.
مثال على الطلب 
{
    "invoice_number": "SA-001",
    "issue_date": "2026-08-05",
    "issue_time": "14:30:00",
    "original_invoice_number": "SA-001",
    "original_invoice_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "مرتجع بضاعة",
    "lines": [
        {
            "name": "منتج 1",
            "quantity": 1,
            "unit_price": 100,
            "discount": 0,
            "vat_rate": 15
        }
    ]
}

🇪🇬 Egypt — ETA

ETA uses a two-step flow: prepare the canonical document and SHA-256 digest, sign it with an approved Egyptian eSeal using CAdES-BES, then submit the unchanged document.

الرابط الأساسي: https://jofotara.theonesystemco.com/api/integration/eta EGP ضريبة 14%
POST /api/integration/eta/prepare

Prepare ETA document

Validates, canonicalizes, and returns the digest that must be signed.

الحقل النوع مطلوب الوصف
invoice_number string مطلوب رقم المستند لديك. يجب أن يكون فريداً داخل الشركة.
document_type string مطلوب i = invoice, c = credit note (return), d = debit note.
date_time_issued datetime مطلوب UTC issue time in ISO-8601 format.
receiver.id string مطلوب Receiver tax registration or national identifier.
receiver.name string مطلوب Receiver legal name.
lines[].description string مطلوب Item or service description.
lines[].item_type string مطلوب GS1 or EGS.
lines[].item_code string مطلوب Approved GS1 or EGS code.
lines[].unit_type string مطلوب ETA unit type, for example EA.
lines[].quantity number مطلوب Quantity.
lines[].unit_price number مطلوب سعر الوحدة قبل الضريبة.
lines[].tax_rate number مطلوب VAT percentage, normally 14.
مثال على الطلب 
{
    "invoice_number": "EG-001",
    "document_type": "i",
    "date_time_issued": "2026-08-11T13:30:45Z",
    "receiver": {
        "type": "B",
        "id": "123456789",
        "name": "Example Buyer",
        "country": "EG",
        "governate": "Cairo",
        "region_city": "Nasr City",
        "street": "Example Street",
        "building_number": "10"
    },
    "lines": [
        {
            "description": "Consulting service",
            "item_type": "EGS",
            "item_code": "EG-123456789-001",
            "unit_type": "EA",
            "quantity": 1,
            "unit_price": 100,
            "discount_amount": 0,
            "tax_rate": 14
        }
    ]
}
POST /api/integration/eta/submit

Submit signed ETA document

Submits the prepared document after verifying that its canonical digest has not changed.

الحقل النوع مطلوب الوصف
document_id uuid مطلوب Internal document ID returned by the prepare endpoint.
signature base64 مطلوب CAdES-BES signature produced by the approved eSeal.
مثال على الطلب 
{
    "document_id": "550e8400-e29b-41d4-a716-446655440000",
    "signature": "BASE64_CADES_BES_SIGNATURE"
}

الاستجابات ورموز الأخطاء

الرمز المعنى ما يجب فعله
200 / 201 مقبولة تم إرسال الفاتورة. احفظ المعرّف الفريد المُعاد — إشعار الدائن يحتاجه.
401 غير مُصادق مفتاح API مفقود أو غير صحيح أو أُعيد توليده. انسخه مجدداً من هذه الصفحة.
409 تعارض Either the invoice number already exists, or onboarding is not finished.
422 بيانات غير صحيحة اقرأ كائن errors؛ كل مفتاح فيه هو الحقل الذي فشل.
429 طلبات كثيرة جداً الحد 60 طلباً في الدقيقة. أعد المحاولة بعد توقف قصير.
500 خطأ في الخادم أعد المحاولة لاحقاً. إن استمر، تواصل مع الدعم مع رقم الفاتورة.

أمثلة برمجية

curl -X POST https://jofotara.theonesystemco.com/api/integration/zatca/simplified-invoice \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "invoice_number": "SA-001",
    "issue_date": "2026-08-05",
    "lines": [
      { "name": "Coffee", "quantity": 1, "unit_price": 100, "vat_rate": 15 }
    ]
  }'
<?php

$response = Http::withHeaders([
    'X-Api-Key' => env('TARAWUD_API_KEY'),
    'Accept'    => 'application/json',
])->post('https://jofotara.theonesystemco.com/api/integration/zatca/simplified-invoice', [
    'invoice_number' => 'SA-001',
    'issue_date'     => now()->format('Y-m-d'),
    'lines' => [
        ['name' => 'Coffee', 'quantity' => 1, 'unit_price' => 100, 'vat_rate' => 15],
    ],
]);

if ($response->successful()) {
    $uuid = $response->json('data.uuid');   // keep it: credit notes need it
    $qr   = $response->json('data.qr_code');
}
const res = await fetch('https://jofotara.theonesystemco.com/api/integration/zatca/simplified-invoice', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.TARAWUD_API_KEY,
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    invoice_number: 'SA-001',
    issue_date: '2026-08-05',
    lines: [
      { name: 'Coffee', quantity: 1, unit_price: 100, vat_rate: 15 },
    ],
  }),
});

const body = await res.json();
if (body.status === 'success') {
  console.log(body.data.uuid, body.data.qr_code);
} else {
  console.error(body.message, body.errors);
}
import os, requests

res = requests.post(
    "https://jofotara.theonesystemco.com/api/integration/zatca/simplified-invoice",
    headers={
        "X-Api-Key": os.environ["TARAWUD_API_KEY"],
        "Accept": "application/json",
    },
    json={
        "invoice_number": "SA-001",
        "issue_date": "2026-08-05",
        "lines": [
            {"name": "Coffee", "quantity": 1, "unit_price": 100, "vat_rate": 15},
        ],
    },
    timeout=30,
)

body = res.json()
if body["status"] == "success":
    print(body["data"]["uuid"], body["data"]["qr_code"])
else:
    print(body["message"], body.get("errors"))

جاهز للبدء؟

أنشئ حساب شركة للحصول على مفتاح الواجهة.

تسجيل شركة