Harici API V1 Dokümantasyonu

Fatura belgesini dönüştür

Yapılandırılmış veriyi dönüştür

Task durumunu sorgula

PDF, DOCX veya TXT fatura belgesi yükleyin ve asenkron dönüşümü başlatın. Polling için task_id döndürür. ZUGFeRD/Factur-X hibrit PDF indirmeleri PDF kaynak yüklemesi gerektirir; DOCX/TXT kaynakları XML sonuçları istemelidir. Gömülü fatura XML’i varsayılan olarak yok sayılır; use_embedded_xml=true değerini yalnızca entegrasyonunuz gömülü XML’i birincil çıkarma kaynağı olarak kabul ediyorsa ayarlayın. İstek: multipart/form-data; file (binary, zorunlu) — PDF, DOCX veya TXT fatura kaynak belgesi; eski DOC/RTF, görüntü ve diğer dosyalar reddedilir; format (string, zorunlu) — hedef çıktı formatı; aşağıdaki format matrisine bakın; profile (string, opsiyonel, deterministik entegrasyonlar için önerilir) — açık uyumluluk profili; büyük/küçük harf duyarsız eşleştirilir. Her formatın kapalı bir kabul listesi ve tek bir varsayılanı vardır: XRECHNUNG → [XRECHNUNG] (varsayılan XRECHNUNG); EN16931 → [EN16931] (varsayılan EN16931); UBL → [XRECHNUNG, PEPPOL, EN16931] (varsayılan EN16931); CII → [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (varsayılan EN16931); ZUGFERD → [ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (varsayılan ZUGFERD_EN16931). ZUGFERD, FACTURX, FACTUR-X ve FACTUR_X, ZUGFERD_EN16931 için alias’tır; ZUGFERD-XRECHNUNG ise ZUGFERD_XRECHNUNG için alias’tır. Kabul listesi dışındaki bir değer 422 OUTPUT_PROFILE_CONFLICT, tanınmayan bir profil adı ise details.allowed_profiles ile 422 INVALID_PROFILE döndürür; jurisdiction (string, opsiyonel) — doğrulama/danışma kontrolleri için açık ISO 3166-1 alpha-2 yargı bağlamı; profili geçersiz kılmaz; transaction_scope (string, opsiyonel) — B2G gibi açık işlem kapsamı bağlamı; kuyruğa alınan task’a uygulanır; delivery_channel (string, opsiyonel) — PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, UNKNOWN değerlerinden biri; kuyruğa alınan task’a uygulanır; client_reference veya external_invoice_id (string, opsiyonel) — kabul edilen yüklemelerde ve task durum yanıtlarında dönen müşteri tarafı fatura/iş referansı; source_system (string, opsiyonel) — kabul edilen yüklemelerde ve task durum yanıtlarında dönen üst sistem ERP veya faturalama etiketi; email_input (serbest metin, opsiyonel, yalnızca PDF kaynakları) — herhangi bir dilde, en fazla 10.000 karakter müşteri talimatı; e-posta blok işaretleri olmadan gönderilir; tüm yapay zekâ çıkarım ve düzeltme adımları bunu fatura kaynak metninden ayrı alır; use_embedded_xml=true ile birlikte kullanılamaz, idempotens için istek kimliğinin parçasıdır ve invoices:convert-structured tarafından desteklenmez; standart fatura doğrulaması geçerli kalır; use_seller_master_data (boolean, opsiyonel) — belirtilmezse tenant profil varsayılanı geçerlidir; false bu istek için kayıtlı satıcı varsayılanlarını yok sayar, true satıcı varsayılanlarını sağlar/kullanır; seller_master_data (JSON nesne dizesi, opsiyonel) — yalnızca use_seller_master_data=true olduğunda kullanılan satıcı varsayılanları; şirket, adres, vergi, iletişim ve ödeme alanlarını destekler (payment_means_code 30/42/58, payment_iban, payment_bic, payment_account_name, payment_terms_note); her profil değeri ilgili çıkarılan değerin yerini alır, profil olmayan alanlar değişmez ve farklar engelleyici olmayan uyarılar oluşturur; electronic_address ve electronic_address_scheme birlikte gönderilmeli veya ikisi de atlanmalıdır; use_embedded_xml (boolean, opsiyonel, varsayılan false) — gömülü Factur-X, ZUGFeRD veya XRechnung XML’i açıkça true ayarlanmadıkça yok sayılır; yalnızca entegrasyon gömülü XML’i birincil çıkarma kaynağı olarak kabul ediyorsa kullanın. Yanıt: 202 Accepted.

Taşıyıcı PDF ile CSV, JSON, XML, XLSX veya TXT fatura verisini yükleyin ve yapılandırılmış veriden asenkron dönüşümü başlatın. data_file parçaları tek semantik kaynaktır; PDF eksik fatura alanlarını tamamlamaz. ZUGFeRD/Factur-X için taşıyıcı PDF olarak kullanılır, XML odaklı çıktılarda ise gönderilen PDF artefaktı olarak saklanır. Her fatura için bir dönüşüm isteği kullanın; data_file alanını yalnızca aynı faturaya ait bölünmüş ERP dışa aktarımları için tekrarlayın. İstek: multipart/form-data; pdf_file (binary, zorunlu) — ZUGFeRD/Factur-X gömme için kullanılan ve XML odaklı çıktılarda saklanan taşıyıcı PDF; data_file (binary, zorunlu, tekrarlanabilir) — tek semantik kaynak olarak kullanılan CSV, JSON, XML, XLSX veya TXT fatura verisi; .xls, PDF ve görüntü dosyaları data_file olarak reddedilir; aynı faturanın bölünmüş başlık/satır dışa aktarımları için tekrarlayın; data_files ve data_files[] aliasları kabul edilir; yapılandırılmış veri toplam boyutu — tüm data_file parçaları genelinde en fazla 2 MB; format (string, zorunlu) — hedef çıktı formatı; XRECHNUNG, ZUGFERD, EN16931, UBL ve CII desteklenir; profile (string, opsiyonel, deterministik entegrasyonlar için önerilir) — açık uyumluluk profili; büyük/küçük harf duyarsız eşleştirilir. Her formatın kapalı bir kabul listesi ve tek bir varsayılanı vardır: XRECHNUNG → [XRECHNUNG] (varsayılan XRECHNUNG); EN16931 → [EN16931] (varsayılan EN16931); UBL → [XRECHNUNG, PEPPOL, EN16931] (varsayılan EN16931); CII → [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (varsayılan EN16931); ZUGFERD → [ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (varsayılan ZUGFERD_EN16931). Kabul listesi dışındaki bir değer 422 OUTPUT_PROFILE_CONFLICT, tanınmayan bir profil adı ise details.allowed_profiles ile 422 INVALID_PROFILE döndürür; jurisdiction (string, opsiyonel) — doğrulama/danışma kontrolleri için açık ISO 3166-1 alpha-2 yargı bağlamı; profili geçersiz kılmaz; transaction_scope (string, opsiyonel) — B2G gibi açık işlem kapsamı bağlamı; kuyruğa alınan task’a uygulanır; delivery_channel (string, opsiyonel) — PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, UNKNOWN değerlerinden biri; kuyruğa alınan task’a uygulanır; client_reference veya external_invoice_id (string, opsiyonel) — kabul edilen yüklemelerde ve task durum yanıtlarında dönen müşteri tarafı fatura/iş referansı; source_system (string, opsiyonel) — kabul edilen yüklemelerde ve task durum yanıtlarında dönen üst sistem ERP veya faturalama etiketi; use_seller_master_data (boolean, opsiyonel) — belirtilmezse tenant profil varsayılanı geçerlidir; false bu istek için kayıtlı satıcı varsayılanlarını yok sayar, true satıcı varsayılanlarını sağlar/kullanır; seller_master_data (JSON nesne dizesi, opsiyonel) — yalnızca use_seller_master_data=true olduğunda kullanılan satıcı varsayılanları; şirket, adres, vergi, iletişim ve ödeme alanlarını destekler (payment_means_code 30/42/58, payment_iban, payment_bic, payment_account_name, payment_terms_note); her profil değeri ilgili çıkarılan değerin yerini alır, profil olmayan alanlar değişmez ve farklar engelleyici olmayan uyarılar oluşturur; electronic_address ve electronic_address_scheme birlikte gönderilmeli veya ikisi de atlanmalıdır. Yanıt: 202 Accepted.

Bir dönüşüm task’ının mevcut durumunu sorgulayın. pending (kabul edilmiş ve kuyrukta, henüz başlamamış), processing, completed veya failed döndürür. Rate limit 10/min ve 120/hour; polling için bağlayıcı kısıt budur: kabul edilen 202 sonrası ilk çağrı için yaklaşık 20 saniye bekleyin, ardından aralıkları artırın (20s, 30s, 45s, 60s ve sonrasında 60s) ve completed veya failed durumunda durun. Tamamlanan task’lar, istemcilerin hangi XML/PDF artefaktlarının kullanılabilir, önbelleğe alınmış ve doğrulama kanıtlı olduğunu görebilmesi için result_artifacts tanılarını içerir. Tamamlanan task payload’ları, kaynak kanıt eksik, şüpheli veya kesilmiş olduğunda SOURCE_CONTEXT_* kural ID’leri içeren ek _processing_warnings ve _validation_warnings girdileri içerebilir; bunları hata değil inceleme sinyali olarak ele alın. failed olduğunda cevap, hata nedenini içeren bir error alanı içerir. İstek: yok (GET); task_id (path, zorunlu) — convert endpoint’inin döndürdüğü UUID; include_validation_report_html (query, opsiyonel) — true veya false (varsayılan false); true olduğunda durum yanıtı, mevcutsa geçerli katı artefaktın arındırılmış HTML doğrulama raporunu satır içi döndürür. Yanıt: 200 OK.

Oluşturulan dosyayı indirin (XML veya PDF). Sonuç söz dizimi özgün task formatıyla eşleşir: XRECHNUNG/EN16931/UBL UBL XML, CII/ZUGFERD CII XML döndürür; ZUGFERD + download=pdf hibrit PDF/A-3 döndürür. Diğer formatlarda download=pdf render edilmiş bir PDF döndürebilir; tamamlanan bir task’ta download=xml beklenen-kullanılabilir artefakttır, garantili değildir. Doğrulama kanıtı hâlâ güncelse tekrarlı indirmeler önbelleğe alınmış artefaktlardan sunulabilir. İşleme devam ederken uç nokta standart hata zarfını taşıyan bir 202 döndürür ({"code":"TASK_NOT_READY","message":"Strict conversion is still processing. No validated artifact is available yet.","correlation_id":"<uuid>"}); engelleyici doğrulama hataları 422 VALIDATION_FAILED, yeniden denenebilir bağımlılık eksikleri 503, kalıcı dönüşüm hataları nedeni details.code içinde olacak şekilde 500 TASK_FAILED ve artefakt invariant hataları 500 INTERNAL_ARTIFACT_INVARIANT_FAILED döndürür; bu durumlarda dosya gövdesi yoktur. Başarılı indirmeler X-Correlation-ID, Content-Disposition, Cache-Control: no-store, X-Artifact-Sha256, X-Validation-Proof-Id, X-Artifact-Proof-Id, X-Artifact-State, X-Validation-State, X-Proof-Status ve X-Validator-Bundle-Id taşır; X-Task-Id bu uç noktada ayarlanmaz. Rate limit 10/min ve yaklaşık 134/hour. İstek: yok (GET); task_id (path, zorunlu) — convert endpoint’inin döndürdüğü UUID; download (query, zorunlu) — xml veya pdf. Yanıt: 200 OK.

Geçerli doğrulanmış sonuç artefaktının raporunu indirin. Rapor, sıkı dönüşüm güncel kanıtlı bir artefaktı kaydettikten sonra kullanılabilir; aksi halde endpoint 202 veya 404 döndürür. Yanıt header’ları artefaktı ve rapor kanıtını tanımlar. X-Artifact-Sha256 rapor dosyasını değil, sonuç artefaktını tanımlar. Rate limit: 10/dakika ve 120/saat. İstek: yok (GET); task_id (path, zorunlu) — dönüşüm endpoint’inin döndürdüğü UUID; download (query, isteğe bağlı) — html veya xml. Yanıt: 200 OK.

seller_master_data artık electronic_address ve electronic_address_scheme alanlarını isteğe bağlı tek bir çift olarak işler. Her iki alanı da gönderin veya ikisini de atlayın; eksik bir çift 400 INVALID_SELLER_MASTER_DATA döndürür.

Fiyat belgesi düzeltmesi: 1.000 ön ödemeli kredi 400 EUR tutarındadır (kredi başına 0,40 EUR). 100, 200 ve 500 kredilik paketler 50, 100 ve 250 EUR olarak kalır. Uygulanan fiyatlar ve mevcut satın alımlar değişmez.

Belge dönüşümü artık gömülü fatura XML’ini varsayılan olarak yok sayar. use_embedded_xml=true değerini yalnızca entegrasyon gömülü XML’i birincil çıkarma kaynağı olarak açıkça kabul ediyorsa ayarlayın. E-posta İçe Aktarma gömülü fatura XML’ini her zaman yok sayar. use_embedded_xml değişikliği idempotency istek karmasını değiştirir; bu seçeneği değiştirdiğinizde yeni bir Idempotency-Key kullanın.

Satıcı ana verileri bir alanı doldurduğunda, o alandaki kalan çıkarma bayrakları görünür kalır ancak sıkı E-posta İçe Aktarma veya External API’yi engellemez. Alıcı, satırlar, vergi, teslimat, vade, erken ödeme, havale referansı, doldurulmayan profil alanları ve geçersiz profil değerleri engelleyici kalır.

Enterprise, aylık 50 EUR veya yıllık 420 EUR ile doğrudan satın almaya açıldı. Enterprise ayda 100 ortak E-posta/API dönüşümü içerir; ek dönüşümler 0,40–0,50 EUR ön ödemeli kredi kullanır. API anahtarları artık manuel onay gerektirmez.

Güncel hata kataloğu ve koda özgü yeniden deneme kuralları yayımlandı. 500 yanıtı otomatik olarak yeniden denenmez; code, details.code ve details.retryable alanlarını inceleyin. 402 INSUFFICIENT_API_CREDITS için iki details biçimi ve farklı 409 idempotency kurtarma yolları belgelendi. Doğrulama raporu kanıt header’ları, 24 saatlik saklama, task timeout’ları ve endpoint bazlı rate limit’ler yayımlandı. Kapalı format/profil tablosu yayımlandı; indirme, METHOD_NOT_ALLOWED ve PROFILE_MISMATCH yönlendirmeleri düzeltildi.

API dönüşümü, birden fazla fatura içerdiği doğrulanan kaynağı artık kalıcı MULTIPLE_INVOICES_IN_DOCUMENT ile reddeder. Doğrulanmış çoklu faturaları ayırın. Belirsiz sinyal ise inceleme için 422 VALIDATION_FAILED döndürür.

Etkin satıcı ana verileri artık eşleşen çıkarılmış satıcı veya ödeme değerlerini değiştirir. Profilde olmayan alanlar çıkarılmış değerleri korur; farklar engellemeyen inceleme uyarıları olarak kalır.

2026-07-26 ile geçersiz kılındı: Satıcı ana verileri artık yalnızca eksikleri doldurmak yerine eşleşen çıkarılmış değerleri değiştirir.

Dokümantasyon tamamlaması; çalışma zamanı davranışında değişiklik yok. Hata kataloğu artık daha önce belgelenmemiş çalışma zamanı hata kodlarını belgeliyor: API_CREDIT_SERVICE_UNAVAILABLE, TASK_NOT_FOUND, INVALID_CLIENT_METADATA, INVALID_SELLER_MASTER_DATA, PROFILE_MISMATCH, ZUGFERD_SOURCE_PDF_REQUIRED, VALIDATION_REPORT_NOT_FOUND, VALIDATION_REPORT_FAILED, INVALID_QUERY_PARAMETER ve METHOD_NOT_ALLOWED dahil. Hata yanıtlarını makine tarafından okunabilir code alanıyla ayrıştıran istemciler için değişiklik gerekmez; sabit kod listesine göre çalışan istemciler yeni belgelenen değerleri eklemelidir. Changelog tarihleri düzeltildi: DOCX/TXT kaynak desteği 2026-07-06 değil 2026-06-30 tarihinde yayınlandı.

Tamamlanan task payload’ları, kaynak kanıt çıkarımdan önce eksik, şüpheli veya kesilmiş olduğunda SOURCE_CONTEXT_* kural ID’leri içeren ek _processing_warnings ve _validation_warnings girdileri içerebilir. SOURCE_CONTEXT_* girdilerini müşteri tarafı istisna yönetimi için inceleme sinyali olarak ele alın; katı artefakt indirmeleri doğrulama kanıtı ve artefakt kontrolleriyle korunmaya devam eder.

Katı ZUGFeRD ön koşul hataları (hibrit üretim için zorunlu alan eksikleri) artık yeniden denenebilir 503 yerine engelleyici kural ID’leriyle 422 VALIDATION_FAILED olarak başarısız olur; bunları retry döngüsüne değil veri düzeltme akışına yönlendirin. Yalnızca XML üreten formatlarda (XRECHNUNG, EN16931, UBL, CII) PDF görüntüsü artık en iyi çaba esaslı bir kolaylık artefaktıdır: tamamlanan task’larda download=xml belirleyici ve erişilebilir kalır, XML üretiminden sonra render başarısız olursa download=pdf kullanılamayabilir. Çözülmemiş engelleyici kaynak çatışmaları olan dönüşümler artık artefakt üretmek yerine blocking_source_conflict girdileriyle 422 VALIDATION_FAILED olarak başarısız olur.

POST /api/v1/invoices:convert artık file alanında PDF, DOCX ve TXT fatura kaynak belgelerini kabul eder. Eski DOC, RTF, görüntü ve desteklenmeyen diğer kaynak dosyalar dönüşüm başlamadan önce reddedilir. ZUGFeRD/Factur-X hibrit PDF indirmeleri hâlâ PDF kaynak yüklemesi gerektirir; DOCX/TXT kaynak dönüşümleri için XML indirmelerini kullanın. GET /api/v1/tasks/{task_id} üzerinde, mevcut olduğunda arındırılmış HTML doğrulama raporunu satır içi döndüren opsiyonel include_validation_report_html=true eklendi. Dönüşüm yüklemeleri artık her iki endpoint’te opsiyonel use_seller_master_data ve seller_master_data alanlarını kabul eder; onaylı tenant’lar kayıtlı veya istek kapsamlı satıcı varsayılanlarını etkinleştirebilir.

Geçerli katı sonuç artefaktı kanıtına bağlı doğrulama raporunu almak için GET /api/v1/tasks/{task_id}/validation-report?download=html|xml eklendi. Doğrulama raporu yanıtları task ID, artefakt SHA-256, doğrulama kanıtı ID, rapor kanıtı ID, rapor içerik türü ve korelasyon ID header’larını içerir.

Gönderilen fatura verisi artık hibrit ZUGFeRD çıktısının veri kaynağıdır; deterministik temizleme ve vergi normalleştirmesi sürer. Task’lar sabit beş dakikalık timeout yerine ilerleme durduğunda veya 15 dakikalık üst sınırda başarısız olur.

Kullanım kaydı hataları hazır doğrulanmış yanıtı engellemez veya ek kredi tüketmez; başarısız olaylar mutabakat için sıraya alınır.

External API erişimi artık sınırsız anahtar oluşturma yerine onaylı erişim olarak belgelenir. Order form içinde kararlaştırılmadıkça resmi SLA, servis kredisi veya sözleşmesel ceza olmadığı netleştirildi. format artık iki dönüşüm endpoint’inde de zorunludur; eksik değerler 400 FORMAT_REQUIRED, desteklenmeyen değerler 422 INVALID_FORMAT döndürür. download artık task-result isteklerinde zorunludur; eksik değerler 400 DOWNLOAD_FORMAT_REQUIRED, desteklenmeyen değerler 400 INVALID_DOWNLOAD_FORMAT döndürür. Dönüşüm yüklemeleri artık müşteri tarafı mutabakat için client_reference/external_invoice_id ve source_system kabul eder. Kabul edilen dönüşüm ve task durum yanıtları artık status_url, primary_result_format, primary_result_url ve gönderilen mutabakat alanlarını içerir.

Yapılandırılmış dönüşüm artık tüm herkese açık çıktı formatlarını kabul eder: XRECHNUNG, ZUGFeRD, EN16931, UBL ve CII. Yapılandırılmış dönüşüm artık bölünmüş ERP dışa aktarımları için tekrarlanabilir data_file parçalarını ve data_files ile data_files[] aliaslarını kabul eder. Yapılandırılmış çok dosyalı paketler tam olarak tek bir faturayı tanımlamalıdır; çelişkili veya eksik paket fatura ID’lerinde erken hata verir. Birden fazla fatura belgesinin her biri kendi idempotency key’ine sahip ayrı dönüşüm task’ları olarak gönderilmesi gerektiği netleştirildi.

Desteklenen çıktı formatlarında taşıyıcı PDF ve CSV/JSON/XML/XLSX/TXT yapılandırılmış veri dönüşümü için POST /api/v1/invoices:convert-structured eklendi. Bu endpoint’te yapılandırılmış verinin tek semantik kaynak olduğu; PDF’nin hibrit gömme için kullanıldığı belgelendi. Yapılandırılmış dönüşüm için OpenAPI ve Postman artefaktları güncellendi.

Sıkı XML ve hibrit PDF artefaktlarına iç parite verisi eklendi; hazır olma ve doğrulama durumu için result_artifacts kullanın. Belgelenen üretim base URL’si https://www.invoice-converter.com/api/v1 olarak değişti.

GET /api/v1/tasks/{task_id}/result yalnızca indirme yapar; dosya üretmez, onarmaz veya doğrulamaz. Sıkı task’lar yalnızca doğrulanmış artefakt kaydedildikten sonra tamamlanır; güncel kanıt yoksa sistem kapalı biçimde hata verir. External API dönüşümü taslak veya uyarı geçersiz kılma olmadan sıkı üretime sabitlendi. Task durumuna result_artifacts tanıları ve belgelenmiş delivery_channel değerleri eklendi.

Enterprise olmayan tenant’lar için ön ödemeli External API kredileri eklendi. Enterprise order form faturalandırması veya ön ödemeli kredisi olmayan onaylı tenant’lar için 402 INSUFFICIENT_API_CREDITS belgelendi. İdempotent replay’lerin ek API kredisi tüketmediği doğrulandı. External API V1 model yönlendirmesinin sunucu tarafında yönetildiği, profil ve teslimat bağlamının ise çağıran tarafından kontrol edildiği netleştirildi.

Task durumuna XML/PDF artefakt hazır olma tanıları eklendi. Sıkı sonuç indirmeleri yalnızca sunucu tarafı artefakt kontrollerinden sonra dosya döndürür.

Başarılı sonuç indirmelerine dönen artefakt için sunucu tarafı doğrulama kanıtı eklendi. Eksik doğrulama veya kanıt bağımlılıkları 503 AUTHORITATIVE_VALIDATION_UNAVAILABLE döndürür. Önbellekteki indirmeler yalnızca kayıtlı doğrulama kanıtı güncelse yeniden kullanılır.

Task-result indirmeleri CII ve ZUGFERD çıktıları için formata sadık hale getirildi. Aynı task’ın tekrarlı XML/PDF indirmeleri için önbelleğe alınmış sonuç artefaktlarının yeniden kullanımı eklendi. Polling kotaları endpoint kapsamlı ağırlıklı rate-limit bucket’ları ile hizalandı.

Tüm endpoint’lerde daha açık ve tutarlı API hata cevapları eklendi. Convert seçenekleri genişletildi ve task sonuçları için XML/PDF indirme davranışı belgelendi. Daha sıkı idempotency gereksinimleri ve doğrulama ile retry güvenliği iyileştirildi. OpenAPI/Postman artefaktları güncel API davranışıyla hizalandı.