أنشئ ملفات 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اشترك في خطة المطوّرين
يشترك مالك مساحة العمل في الخطة من إعدادات مساحة العمل ويدفع عبر Stripe.
- 2أنشئ رمز وصول
أنشئ رمز وصول ضمن «رموز الوصول» بصلاحية «قراءة وكتابة». يُعرض الرمز مرة واحدة فقط، عند إنشائه.
- 3اسمح له باستخدام الواجهة البرمجية
لا يعمل الرمز مع الواجهة البرمجية إلا بعد أن يفعّل مالك مساحة العمل خيار «السماح بواجهة المطوّرين البرمجية» له ضمن «رموز الوصول». ولا يكون هذا الخيار مفعّلًا مسبقًا لأي رمز.
- 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؛ والصفحة الألمانية هي الملزمة.