Ücretsiz başla

InkVoice e-fatura API’si

JSON’dan XRechnung ve ZUGFeRD dosyaları oluşturun ve e-fatura dosyalarını kendi kodunuzdan kontrol ettirin. Geliştirici planı, aylık ⁦€19⁩, ⁦1.000⁩ API çağrısı dahil.

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.

API’nin yaptıkları ve yapmadıkları
  • ⁦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 (accept ya da reject) döndüren çağrı, yanıtı okumasanız bile sayılır. Reddedilen veya başarısız olan çağrılar, sonucu not_checked olan 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_reached koduyla 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

  1. 1
    Geliş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.

  2. 2
    Bir 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.

  3. 3
    Belirtece 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.

  4. 4
    Faturayı gönderin

    Fatura isteğini invoice.json dosyasına, belirteci INKVOICE_TOKEN ortam değişkenine koyun ve isteği /xrechnung rotası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-body iç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.

RotaGövdeYanıt
POST /xrechnungJSON olarak fatura isteğiXRechnung dosyası, application/xml
POST /zugferdJSON olarak fatura isteğiZUGFeRD PDF’i, application/pdf
POST /checkDosyanın kendisi: application/pdf, application/xml, text/xml veya application/octet-streamKural setinin bildirdikleri, JSON olarak
GET /usageYokEn son dönemde sayılan çağrılar, rotaya göre, JSON olarak. API çağrısı değildir
GET /openapi.jsonYokAPI 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.xml

Oluş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.

DurumKodAnlamı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_largeGö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_reachedDahil 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.

Ücretsiz bir hesapla başlayın

Geliştirici planı, çalışma alanınızın ayarlarından satın alınır.

Devamını okuyun

Son güncelleme: 15 Kasım 2026. Bu yazı genel bir yönlendirmedir ve vergi veya hukuk danışmanlığı yerine geçmez.