Kendi yazılımınızdan, kişisel bir erişim belirteciyle XRechnung ve ZUGFeRD dosyaları oluşturun ve e-fatura dosyalarını kontrol ettirin.
- POST /xrechnung, XRechnung yapılandırması 3.0.2 sürümünün kapsadığı sürüm olan XRechnung 3.0 biçiminde bir dosya (CII sözdizimi, EN 16931) oluşturur ve onu application/xml olarak döndürür.
- POST /zugferd, XML’i gömülü ve sayfasında InkVoice ibaresi olmayan bir ZUGFeRD 2.x PDF’i (EN 16931 profili) oluşturur.
- POST /check, bir ZUGFeRD veya Factur-X PDF’ini ya da bir XRechnung, CII veya UBL XML dosyasını okur; dosyanın kendisi isteğin gövdesi olarak gönderilir (application/pdf, application/xml, text/xml, application/octet-stream; diğer türler 415 alır).
- GET /usage, en son dönemde (plan etkinken içinde bulunulan dönem) sayılan çağrıları rotaya göre bildirir. Bunu okumak bir API çağrısı değildir.
- Bir faturayı alıcısına göndermek veya sizin için arşivlemek.
- Bir dosyayı oluştururken kontrol etmek.
- İade veya düzeltme faturası, tek faturada birden fazla vergi oranı, AB içi teslim (K), ihracat (G) ya da belge düzeyinde indirim ve ek ücret oluşturmak.
- Vergi veya hukuk danışmanlığı vermek.
Geliştirici planı
Geliştirici planı aylık €19 tutarındadır ve çalışma alanı için dönem başına 1.000 API çağrısı içerir. InkVoice, § 19 UStG kapsamında bir Kleinunternehmer (küçük işletme) olup KDV almaz; bu nedenle fiyat nihai fiyattır.
- Bir dosya veya bir karar (
acceptya dareject) döndüren çağrı, yanıtı okumasanız bile sayılır. Reddedilen veya başarısız olan çağrılar, sonucunot_checkedolan kontroller ve kullanımın okunması sayılmaz. - Dahil olan çağrılar tükendikten sonra, sonraki dönem başlayana kadar yeni çağrılar
api_call_limit_reachedkoduyla reddedilir. Aynı anda çalışan çağrılar sınırı aşabilir. Kullanılmayan çağrılar dönem sonunda düşer ve çağrı başına ücret alınmaz. - Plan yenilendiğinde, önceki dönemin kullanılmayan çağrıları Stripe yeni dönemin bilgilerini InkVoice’a iletene kadar, yeni dönem başladıktan sonra en fazla 3 gün kullanılabilir kalır; bu sırada yapılan bir çağrı her iki döneme de sayılır.
- Ücretsiz deneme süresi yoktur.
Geliştirici planını çalışma alanının sahibi, çalışma alanının ayarlarından satın alır ve Stripe üzerinden öder. Geliştirici planı, çalışma alanının planından (Ücretsiz, Pro veya Master) ayrıdır: birini satın almak, değiştirmek, iptal etmek veya sona erdirmek diğerini etkilemez. Ücretli planları yalnızca kanuni merkezi, ikametgâhı veya planın kendisi için satın alındığı işyeri Almanya’da bulunan müşteriler satın alabilir.
İlk çağrınız
- 1Geliştirici planını satın alın
Geliştirici planını çalışma alanının sahibi, çalışma alanının ayarlarından satın alır ve Stripe üzerinden öder.
- 2Bir erişim belirteci oluşturun
“Erişim belirteçleri” altında “Okuma ve yazma” yetkisiyle bir erişim belirteci oluşturun. Belirteç yalnızca bir kez, oluşturulduğunda gösterilir.
- 3Belirtece API izni verin
Bir belirteç, API ile ancak çalışma alanının sahibi onun için “Erişim belirteçleri” altında “Geliştirici API'sine izin ver” seçeneğini açtıktan sonra çalışır. Bu seçenek hiçbir belirteçte baştan açık değildir.
- 4Faturayı gönderin
Fatura isteğini
invoice.jsondosyasına, belirteciINKVOICE_TOKENortam değişkenine koyun ve isteği/xrechnungrotasına gönderin. Yanıt XRechnung dosyasıdır. Hata durumunda curl sıfırdan farklı bir çıkış koduyla sonlanır ve hatanın bir gövdesi varsa dosya bu gövdeyi içerir (bkz. “Hatalar”);--fail-with-bodyiçin curl 7.76 veya üstü gerekir.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
Rotalar
Tüm rotalar https://api.inkvoice.net/api/v1 altındadır. openapi.json dışındaki her çağrı, Authorization: Bearer inkv_… biçiminde kişisel bir erişim belirteci gerektirir. Web oturumu kabul edilmez ve tarayıcılar API’yi çağıramaz (CORS yok). Oluşturma ve kontrol için “Okuma ve yazma” yetkili bir belirteç gerekir; salt okunur bir belirteç yalnızca kullanımı okuyabilir.
| Rota | Gövde | Yanıt |
|---|---|---|
POST /xrechnung | JSON olarak fatura isteği | XRechnung dosyası, application/xml |
POST /zugferd | JSON olarak fatura isteği | ZUGFeRD PDF’i, application/pdf |
POST /check | Dosyanın kendisi: application/pdf, application/xml, text/xml veya application/octet-stream | Kural setinin bildirdikleri, JSON olarak |
GET /usage | Yok | En son dönemde sayılan çağrılar, rotaya göre, JSON olarak. API çağrısı değildir |
GET /openapi.json | Yok | API tanımı, OpenAPI 3.1, belirteç olmadan okunabilir |
Fatura isteği
İstek en fazla 512 KiB boyutunda bir JSON’dur ve şunları içerir: number, issueDate, dueDate, currency, taxRate, taxCategoryCode, seller, buyer ve lines (dueDate düzenleme tarihinden önce olamaz). Satıcı ve alıcının her biri bir name ve bir email (XRechnung’un istediği elektronik adres), satıcı ayrıca bir taxNumber (KDV kimlik numarası veya vergi numarası) gerektirir. taxRate değeri S için 0 değerinden büyüktür, Z, E ve AE için 0 olur. taxExemptionReason E ve AE için zorunludur, S ve Z için reddedilir. AE için alıcı da taxNumber alanında bir KDV kimlik numarası (BT-48) gerektirir. /xrechnung ayrıca buyerReference (BT-10) ve iban (BR-DE-1) ister; bunlar /zugferd için isteğe bağlıdır. deliveryDate verilmezse teslim tarihi olarak düzenleme tarihi belirtilir. /check rotasında 8 MiB üzerindeki bir gövde 413 request_too_large alır; 512 KiB üzerindeki bir XML dosyası veya bir PDF içindeki XML ise 422 e_invoice_file_xml_too_large alır.
{
"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
}
]
}Zorunlu ve isteğe bağlı her alan API tanımında açıklanmıştır.
Kontrolün bildirdikleri
Kontrol, InkVoice içinde KoSIT’in XRechnung yapılandırmasını (KoSIT rules, XRechnung 3.0.2 (2026-08-31)) ve FeRD’in ZF_250 kurallarını (ZUGFeRD rules, ZF_250, 1.09.2 (2026-08-04)) çalıştırır. CEN’in EN 16931 CII stil sayfası da çalıştıysa yapılandırma , EN 16931 CII 1.3.16 ile biter. KoSIT Prüftool’u veya Mustang’i çalıştırmaz ve bir PDF’in PDF/A standardını karşılayıp karşılamadığını test etmez. Yanıttaki validator alanı, dosyayı değerlendiren kural setini ve sürümünü belirtir.
Kural setleri InkVoice’un sabitlediği sürümleri izler ve bunlardaki bir değişiklik openapi.json içinde duyurulur. Bu sayfa güncel sürümleri listeler.
accept veya reject, o kural setinin dosya için bildirdiğini mesajlarıyla birlikte aktarır. Faturanın yasal gereklilikleri karşıladığını veya bir alıcının onu kabul edeceğini söylemez. not_checked, bir notCheckedReason ile birlikte, hiçbir kural setinin dosyayı değerlendirmediği anlamına gelir.
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.xmlOluşturulan dosyalar neyle test ediliyor
Oluşturulan dosyalar oluşturulurken kontrol edilmez. Kontrol ettirmek için bir dosyayı /check rotasına gönderin; bu bir API çağrısıdır. Dosyalar InkVoice’un ücretsiz oluşturucusunun koduyla oluşturulur: XML, aynı fatura için ücretsiz oluşturucunun XML’idir ve PDF bu XML’i ibare satırı olmadan gömer. Ücretsiz oluşturucunun test paketinde, test tablolarındaki her senaryo, profil başına ikili kombinasyonlarla (pairwise), KoSIT Prüftool 1.6.3 tarafından XRechnung 3.0.2 yapılandırmasıyla (2026-08-31) ve Mustang 2.26.0 tarafından PDF/A-3b içinde EN 16931 olarak kabul edilir. İkisi de API’de değil, testlerde ayrı araçlar olarak çalışır.
API iade veya düzeltme faturası, tek faturada birden fazla vergi oranı, AB içi teslim (K), ihracat (G) ya da belge düzeyinde indirim ve ek ücret oluşturamaz. Bir faturanın tek bir vergi kategorisi (S, Z, E veya AE) ve tüm kalemler için tek bir oranı vardır. Test paketi, birlikte yazı tipi gelmeyen yazı sistemlerindeki metinleri kapsamaz. Tutarlar her para biriminde iki ondalık basamakla yazılır; JPY ve KWD için test paketi kural setlerinin bunu kabul ettiğini gösterir, bunun para biriminin alt birimi olduğunu değil.
Hatalar
Kodlu bir ret şu gövdeye sahiptir: { error, code, args }. error sabit bir İngilizce metindir, bu yüzden programınızda code değerine bakın.
| Durum | Kod | Anlamı | Sayılır mı |
|---|---|---|---|
| 400 | – | İstekte hatalar var. Gövde { errors: [...] } biçimindedir ve seller.name gibi yolları belirtir. | Hayır |
| 401 | – | Erişim belirteci yok veya belirteç kabul edilmiyor. Gövde yok. | Hayır |
| 403 | – | Belirtecin API için izni yok (“Geliştirici API'sine izin ver”, 3. adım) veya salt okunur bir belirteç bir oluşturma ya da kontrol rotasını çağırdı. Gövde yok. | Hayır |
| 404 | – | API kapalı veya rota mevcut değil. | Hayır |
| 413 | request_too_large | Gövde, rotanın kabul ettiğinden büyük. | Hayır |
| 415 | – | Gövdenin içerik türü rotanın okuduğu bir tür değil. Gövde yok. | Hayır |
| 422 | developer_plan_required | Çalışma alanının etkin bir geliştirici planı yok. | Hayır |
| 422 | api_call_limit_reached | Dahil olan çağrılar tükendi. args.included dahil olan çağrıları, args.date dönemin UTC olarak son gününü verir. | Hayır |
| 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 üzerinde: dosya fatura olarak okunamıyor. | Hayır |
| 429 | rate_limited | Çok fazla çağrı. Retry-After saniye sonra yeniden deneyin. | Hayır |
| 429 | e_invoice_check_busy | /check üzerinde: aynı anda çok fazla kontrol. Retry-After saniye sonra yeniden deneyin. | Hayır |
Sınırlar
API, bir belirtecin, bir çalışma alanının ve bir adresin dakikada ve aynı anda kaç çağrı yapabileceğini sınırlar. Sınır aşıldığında saniye cinsinden Retry-After ile 429 yanıtı verir ve çağrı sayılmaz. Kullanılabilirlik, yanıt süresi veya iş hacmi için hiçbir taahhüt yoktur.
API tanımı ve sürümler
API tanımı, https://api.inkvoice.net/api/v1/openapi.json adresinde OpenAPI 3.1 biçimindedir ve belirteç olmadan okunabilir. v1 yalnızca ekleme yoluyla değişir (yeni isteğe bağlı alanlar, rotalar veya kodlar); diğer her değişiklik /api/v2 olur.
Koşullar
AGB (genel işlem koşulları, Ziffer 4a), AVV’nin (veri işleme sözleşmesi) “Entwickler-API” (Geliştirici API’si) eki ve Datenschutzerklärung (gizlilik politikası) uygulanır. Bu sayfa, AGB’nin (genel işlem koşulları) Ziffer 4a (4a maddesi) kapsamındaki Leistungsbeschreibung’u (hizmet tanımı) çevirir; bağlayıcı olan Almanca sayfadır.
Geliştirici planı, çalışma alanınızın ayarlarından satın alınır.