ابدأ مجاناً

واجهة ⁦InkVoice⁩ البرمجية للفواتير الإلكترونية

أنشئ ملفات ⁦XRechnung⁩ و⁦ZUGFeRD⁩ من ⁦JSON⁩ وافحص ملفات الفواتير الإلكترونية من برنامجك الخاص. خطة المطوّرين بسعر ⁦19 €⁩ شهريًا، وتشمل ⁦1,000⁩ استدعاء للواجهة البرمجية.

أنشئ ملفات ⁦XRechnung⁩ و⁦ZUGFeRD⁩ وافحص ملفات الفواتير الإلكترونية من برنامجك الخاص، باستخدام رمز وصول شخصي.

ما تفعله الواجهة البرمجية وما لا تفعله
  • ⁦POST /xrechnung⁩ ينشئ ملف ⁦XRechnung⁩ بالإصدار ⁦3.0⁩ (صيغة ⁦CII⁩، ⁦EN 16931⁩)، وهو الإصدار الذي يغطيه إعداد ⁦XRechnung⁩ بالإصدار ⁦3.0.2⁩، ويعيده بنوع ⁦application/xml⁩.
  • ⁦POST /zugferd⁩ ينشئ ملف ⁦PDF⁩ بصيغة ⁦ZUGFeRD 2.x⁩ (ملف التعريف ⁦EN 16931⁩) يتضمّن ملف ⁦XML⁩، ومن دون أي إشارة إلى ⁦InkVoice⁩ على الصفحة.
  • ⁦POST /check⁩ يقرأ ملف ⁦PDF⁩ بصيغة ⁦ZUGFeRD⁩ أو ⁦Factur-X⁩، أو ملف ⁦XML⁩ بصيغة ⁦XRechnung⁩ أو ⁦CII⁩ أو ⁦UBL⁩، يُرسَل بوصفه متن الطلب نفسه (⁦application/pdf, application/xml, text/xml, application/octet-stream⁩؛ وتتلقى الأنواع الأخرى رمز الحالة ⁦415⁩).
  • ⁦GET /usage⁩ يعرض الاستدعاءات المحتسبة في أحدث فترة (الفترة الجارية ما دامت الخطة نشطة)، موزّعة حسب المسار. وقراءته ليست استدعاءً للواجهة البرمجية.
  • إرسال الفاتورة إلى مستلمها، أو أرشفتها نيابةً عنك.
  • فحص الملف عند إنشائه.
  • إنشاء فواتير دائنة أو تصحيحات، أو عدة نسب ضريبية في فاتورة واحدة، أو توريد داخل الاتحاد الأوروبي (⁦K⁩)، أو تصدير (⁦G⁩)، أو خصومات ورسوم على مستوى المستند.
  • تقديم استشارة ضريبية أو قانونية.

خطة المطوّرين

تكلّف خطة المطوّرين ⁦19 €⁩ شهريًا، وتشمل ⁦1,000⁩ استدعاء للواجهة البرمجية في كل فترة لمساحة العمل. ⁦InkVoice⁩ منشأة صغيرة (⁦Kleinunternehmer⁩) بموجب ⁦§ 19 UStG⁩ ولا تفرض ضريبة القيمة المضافة، لذا فالسعر هو السعر النهائي.

  • يُحتسب الاستدعاء الذي أعاد ملفًا أو حكمًا (accept أو reject) حتى لو لم تقرأ الرد. ولا تُحتسب الاستدعاءات المرفوضة أو الفاشلة، ولا عمليات الفحص التي نتيجتها not_checked، ولا قراءة الاستخدام.
  • بعد نفاد الاستدعاءات المشمولة، تُرفض الاستدعاءات التالية برمز الخطأ api_call_limit_reached حتى بدء الفترة التالية. وقد تتجاوز الاستدعاءات الجارية في الوقت نفسه الحدّ. وتسقط الاستدعاءات غير المستخدمة في نهاية الفترة، ولا يُفرض أي رسم على الاستدعاء الواحد.
  • إذا تجدّدت الخطة، تبقى الاستدعاءات غير المستخدمة من الفترة السابقة متاحة إلى أن يتلقى ⁦InkVoice⁩ بيانات الفترة الجديدة من ⁦Stripe⁩، لمدة تصل إلى ⁦3⁩ أيام بعد بدء الفترة الجديدة؛ ويُحتسب الاستدعاء الذي يُجرى في هذه المدة ضمن الفترتين كلتيهما.
  • لا توجد فترة تجريبية مجانية.

يشترك مالك مساحة العمل في الخطة من إعدادات مساحة العمل ويدفع عبر ⁦Stripe⁩. وخطة المطوّرين منفصلة عن خطة مساحة العمل (المجانية أو ⁦Pro⁩ أو ⁦Master⁩): فالاشتراك في إحداهما أو تغييرها أو إلغاؤها أو انتهاؤها لا يؤثر في الأخرى. ولا يمكن الاشتراك في الخطط المدفوعة إلا للعملاء الذين يقع مقرهم المسجَّل أو محل إقامتهم أو المنشأة التي يُشترك في الخطة لها في ألمانيا.

استدعاؤك الأول

  1. 1
    اشترك في خطة المطوّرين

    يشترك مالك مساحة العمل في الخطة من إعدادات مساحة العمل ويدفع عبر ⁦Stripe⁩.

  2. 2
    أنشئ رمز وصول

    أنشئ رمز وصول ضمن «رموز الوصول» بصلاحية «قراءة وكتابة». يُعرض الرمز مرة واحدة فقط، عند إنشائه.

  3. 3
    اسمح له باستخدام الواجهة البرمجية

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

  4. 4
    أرسل الفاتورة

    ضع طلب الفاتورة في invoice.json والرمز في متغير البيئة INKVOICE_TOKEN، ثم أرسل الطلب إلى /xrechnung. والرد هو ملف ⁦XRechnung⁩. وعند حدوث خطأ، ينتهي ⁦curl⁩ برمز خروج غير ⁦0⁩، ويحتوي الملف على متن الخطأ إن كان له متن (انظر «الأخطاء»)؛ ويتطلب --fail-with-body الإصدار ⁦7.76⁩ من ⁦curl⁩ أو أحدث.

    curl --fail-with-body -X POST https://api.inkvoice.net/api/v1/xrechnung \
      -H "Authorization: Bearer $INKVOICE_TOKEN" \
      -H "Content-Type: application/json" \
      --data @invoice.json -o xrechnung.xml

المسارات

تقع جميع المسارات تحت https://api.inkvoice.net/api/v1. ويحتاج كل استدعاء، باستثناء openapi.json، إلى رمز وصول شخصي بالصيغة Authorization: Bearer inkv_…. ولا تُقبل جلسة الويب، ولا يمكن للمتصفحات استدعاء الواجهة البرمجية (لا يوجد ⁦CORS⁩). ويحتاج الإنشاء والفحص إلى رمز بصلاحية «قراءة وكتابة»؛ أما الرمز المخصص للقراءة فقط فلا يمكنه إلا قراءة الاستخدام.

المسارالمتنالرد
POST /xrechnungطلب الفاتورة بصيغة ⁦JSON⁩ملف ⁦XRechnung⁩، application/xml
POST /zugferdطلب الفاتورة بصيغة ⁦JSON⁩ملف ⁦PDF⁩ بصيغة ⁦ZUGFeRD⁩، application/pdf
POST /checkالملف نفسه، بنوع application/pdf، application/xml، text/xml أو application/octet-streamما أبلغت عنه مجموعة القواعد، بصيغة ⁦JSON⁩
GET /usageلا شيءالاستدعاءات المحتسبة في أحدث فترة، حسب المسار، بصيغة ⁦JSON⁩. ليست استدعاءً للواجهة البرمجية
GET /openapi.jsonلا شيءوصف الواجهة البرمجية، بصيغة ⁦OpenAPI 3.1⁩، ويمكن قراءته دون رمز

طلب الفاتورة

الطلب بصيغة ⁦JSON⁩ بحجم أقصاه ⁦512 KiB⁩، ويتضمن number، issueDate، dueDate، currency، taxRate، taxCategoryCode، seller، buyer وlines (ولا يكون dueDate قبل تاريخ الإصدار). ويحتاج كل من البائع والمشتري إلى name وemail (العنوان الإلكتروني الذي يشترطه ⁦XRechnung⁩)، ويحتاج البائع أيضًا إلى taxNumber (رقم ضريبة القيمة المضافة أو الرقم الضريبي). وتكون قيمة taxRate أكبر من ⁦0⁩ للفئة ⁦S⁩، و⁦0⁩ للفئات ⁦Z⁩ و⁦E⁩ و⁦AE⁩. ويُشترط taxExemptionReason للفئتين ⁦E⁩ و⁦AE⁩، ويُرفض للفئتين ⁦S⁩ و⁦Z⁩. وفي الفئة ⁦AE⁩ يحتاج المشتري أيضًا إلى رقم ضريبة القيمة المضافة في taxNumber (⁦BT-48⁩). ويشترط /xrechnung أيضًا buyerReference (⁦BT-10⁩) وiban (⁦BR-DE-1⁩)، وهما اختياريان في /zugferd. وإذا أُغفل deliveryDate يُذكر تاريخ الإصدار بوصفه تاريخ التوريد. وفي /check يتلقى المتن الذي يتجاوز ⁦8 MiB⁩ رمز الحالة ⁦413⁩ request_too_large، ويتلقى ملف ⁦XML⁩، أو ملف ⁦XML⁩ داخل ملف ⁦PDF⁩، يتجاوز ⁦512 KiB⁩ رمز الحالة ⁦422⁩ e_invoice_file_xml_too_large.

{
  "number": "2026-0001",
  "issueDate": "2026-11-16",
  "dueDate": "2026-11-30",
  "currency": "EUR",
  "taxRate": 19,
  "taxCategoryCode": "S",
  "buyerReference": "04011000-1234512345-06",
  "iban": "DE02120300000000202051",
  "seller": {
    "name": "Muster GmbH",
    "email": "rechnung@example.com",
    "addressLine": "Musterstraße 1",
    "postalCode": "10115",
    "city": "Berlin",
    "country": "DE",
    "taxNumber": "DE123456789"
  },
  "buyer": {
    "name": "Beispiel AG",
    "email": "eingang@example.com",
    "addressLine": "Beispielweg 2",
    "postalCode": "20095",
    "city": "Hamburg",
    "country": "DE"
  },
  "lines": [
    {
      "description": "Beratung",
      "quantity": 8,
      "unitPrice": 95
    }
  ]
}

كل حقل، إلزاميًا كان أو اختياريًا، مشروح في وصف الواجهة البرمجية.

ما يبلّغ عنه الفحص

يشغّل الفحص، داخل ⁦InkVoice⁩، إعداد ⁦XRechnung⁩ من ⁦KoSIT⁩ (KoSIT rules، XRechnung 3.0.2 (2026-08-31)) وقواعد ⁦ZF_250⁩ من ⁦FeRD⁩ (ZUGFeRD rules، ZF_250, 1.09.2 (2026-08-04)). وإذا شُغّلت أيضًا ورقة الأنماط ⁦EN 16931 CII⁩ من ⁦CEN⁩، ينتهي الإعداد بـ , EN 16931 CII 1.3.16. ولا يشغّل أداة ⁦KoSIT Prüftool⁩ ولا ⁦Mustang⁩، ولا يختبر استيفاء ملف ⁦PDF⁩ لمعيار ⁦PDF/A⁩. ويذكر الحقل validator في الرد مجموعة القواعد وإصدارها اللذين حكما على الملف.

تتبع مجموعات القواعد الإصدارات التي يثبّتها ⁦InkVoice⁩، ويُعلَن عن أي تغيير فيها في openapi.json. وتسرد هذه الصفحة الإصدارات الحالية.

accept أو reject يبيّن ما أبلغت عنه مجموعة القواعد تلك بشأن الملف، مع رسائلها. ولا يعني أن الفاتورة تستوفي المتطلبات القانونية أو أن المستلم سيقبلها. أما not_checked، مع notCheckedReason، فيعني أنه لم تحكم أي مجموعة قواعد على الملف.

curl --fail-with-body -X POST https://api.inkvoice.net/api/v1/check \
  -H "Authorization: Bearer $INKVOICE_TOKEN" \
  -H "Content-Type: application/xml" \
  --data-binary @xrechnung.xml

ما تُختبر به الملفات المُنشأة

لا تُفحص الملفات المُنشأة عند إنشائها. أرسل ملفًا إلى /check لفحصه؛ وهذا استدعاء للواجهة البرمجية. وتُبنى الملفات بشيفرة المولّد المجاني في ⁦InkVoice⁩: فملف ⁦XML⁩ هو الملف الذي ينتجه المولّد المجاني للفاتورة نفسها، وملف ⁦PDF⁩ يتضمّن ملف ⁦XML⁩ هذا من دون سطر الإشارة. وفي مجموعة اختبارات المولّد المجاني، تقبل أداة ⁦KoSIT Prüftool 1.6.3⁩ كل سيناريو في جداول الاختبار (وهي توليفات زوجية لكل ملف تعريف) بإعداد ⁦XRechnung 3.0.2 (2026-08-31)⁩، كما تقبله أداة ⁦Mustang 2.26.0⁩ بوصفه ⁦EN 16931⁩ ضمن ⁦PDF/A-3b⁩. وتعمل الأداتان كلتاهما بوصفهما أداتين منفصلتين في الاختبارات، لا في الواجهة البرمجية.

لا يمكن للواجهة البرمجية إنشاء فواتير دائنة أو تصحيحات، أو عدة نسب ضريبية في فاتورة واحدة، أو توريد داخل الاتحاد الأوروبي (⁦K⁩)، أو تصدير (⁦G⁩)، أو خصومات ورسوم على مستوى المستند. وللفاتورة فئة ضريبية واحدة (⁦S⁩ أو ⁦Z⁩ أو ⁦E⁩ أو ⁦AE⁩) ونسبة واحدة لجميع البنود. ولا تغطي مجموعة الاختبارات النصوص المكتوبة بأنظمة كتابة لا يُرفق بها خط. وتُكتب المبالغ بمنزلتين عشريتين في كل عملة؛ وبالنسبة إلى ⁦JPY⁩ و⁦KWD⁩ تُظهر مجموعة الاختبارات أن مجموعات القواعد تقبل ذلك، لا أنه الوحدة الفرعية للعملة.

الأخطاء

متن الرفض المصحوب برمز خطأ هو { error, code, args }؛ وerror نص إنجليزي ثابت، لذا اعتمد في برنامجك على code.

الحالةرمز الخطأالمعنىيُحتسب
⁦400⁩–في الطلب أخطاء. والمتن { errors: [...] }، ويذكر مسارات مثل seller.name.لا
⁦401⁩–لا يوجد رمز وصول، أو أن الرمز غير مقبول. لا يوجد متن.لا
⁦403⁩–الرمز غير مسموح له باستخدام الواجهة البرمجية («السماح بواجهة المطوّرين البرمجية»، الخطوة ⁦3⁩)، أو استدعى رمز مخصص للقراءة فقط مسار إنشاء أو فحص. لا يوجد متن.لا
⁦404⁩–الواجهة البرمجية متوقفة، أو أن المسار غير موجود.لا
⁦413⁩request_too_largeالمتن أكبر مما يقبله المسار.لا
⁦415⁩–نوع محتوى المتن ليس نوعًا يقرأه المسار. لا يوجد متن.لا
⁦422⁩developer_plan_requiredلا توجد لمساحة العمل خطة مطوّرين نشطة.لا
⁦422⁩api_call_limit_reachedنفدت الاستدعاءات المشمولة. يذكر args.included الاستدعاءات المشمولة، وargs.date آخر يوم في الفترة بتوقيت ⁦UTC⁩.لا
⁦422⁩e_invoice_file_empty، e_invoice_file_encrypted، e_invoice_file_no_invoice_xml، e_invoice_file_not_an_invoice، e_invoice_file_not_xml، e_invoice_file_number_out_of_range، e_invoice_file_older_zugferd، e_invoice_file_several_invoice_xml، e_invoice_file_too_complex، e_invoice_file_too_large، e_invoice_file_unreadable، e_invoice_file_xml_too_largeفي /check: لا يمكن قراءة الملف بوصفه فاتورة.لا
⁦429⁩rate_limitedعدد كبير جدًا من الاستدعاءات. أعد المحاولة بعد Retry-After ثانية.لا
⁦429⁩e_invoice_check_busyفي /check: عدد كبير جدًا من عمليات الفحص في الوقت نفسه. أعد المحاولة بعد Retry-After ثانية.لا

الحدود

تحدّ الواجهة البرمجية من عدد الاستدعاءات التي يمكن أن يجريها رمز ومساحة عمل وعنوان في الدقيقة وفي الوقت نفسه. وعند تجاوز الحدّ تردّ برمز الحالة ⁦429⁩ مع Retry-After بالثواني، ولا يُحتسب الاستدعاء. ولا يُقدَّم أي التزام بشأن التوافر أو زمن الاستجابة أو معدل المعالجة.

وصف الواجهة البرمجية والإصدارات

وصف الواجهة البرمجية بصيغة ⁦OpenAPI 3.1⁩ على العنوان https://api.inkvoice.net/api/v1/openapi.json، ويمكن قراءته دون رمز. ولا يتغير v1 إلا بالإضافة (حقول اختيارية أو مسارات أو رموز أخطاء جديدة)؛ وأي تغيير آخر يصبح /api/v2.

الشروط

تسري ⁦AGB⁩ (الشروط العامة، ⁦Ziffer 4a⁩)، والملحق «⁦Entwickler-API⁩» (واجهة المطوّرين البرمجية) لـ⁦AVV⁩ (اتفاقية معالجة البيانات)، و⁦Datenschutzerklärung⁩ (سياسة الخصوصية). وهذه الصفحة ترجمة لوصف الخدمة (⁦Leistungsbeschreibung⁩) بموجب ⁦Ziffer 4a⁩ (البند ⁦4a⁩) من ⁦AGB⁩؛ والصفحة الألمانية هي الملزمة.

ابدأ بحساب مجاني

تشترك في خطة المطوّرين من إعدادات مساحة العمل الخاصة بك.

اقرأ أيضًا

آخر تحديث: 15 نوفمبر 2026. هذا المقال إرشاد عام ولا يُغني عن الاستشارة الضريبية أو القانونية.