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. İ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. Varsayılan değerler formata göre belirlenir; izin verilen değerler arasında XRECHNUNG, PEPPOL, EN16931 ve desteklenen ZUGFeRD/Factur-X profilleri bulunur; 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. 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. Varsayılan değer formata göre seçilir; 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. Yanıt: 202 Accepted.

Bir dönüşüm task’ının mevcut durumunu sorgulayın. pending, processing, completed veya failed döndürür. 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. Doğrulama kanıtı hâlâ güncelse tekrarlı indirmeler önbelleğe alınmış artefaktlardan sunulabilir. İşleme devam ederken uç nokta 202 TASK_NOT_READY; engelleyici doğrulama hataları 422 VALIDATION_FAILED, yeniden denenebilir bağımlılık eksikleri 503 ve artefakt invariant hataları 500 döndürür; bu durumlarda dosya gövdesi yoktur. İstek: yok (GET); task_id (path, zorunlu) — convert endpoint’inin döndürdüğü UUID; download (query, zorunlu) — xml veya pdf. Yanıt: 200 OK.

Download the validation report tied to the current validated result artifact. The report is available only after strict conversion has produced a cached artifact with current validation proof, and returns 404 when no report is bound to the delivered artifact. İstek: none (GET); task_id (path, required) — UUID returned by the convert endpoint; download (query, optional) — html or xml. Yanıt: 200 OK.

When seller master data is enabled, every supplied profile value replaces the corresponding extracted seller or payment value. Fields absent from the profile remain unchanged. Source differences are non-blocking review warnings.

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.

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.

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-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ı.