# Harici API V1 Dokümantasyonu Faturaları kendi sistemlerinizden doğrulanmış e-faturalara dönüştürün: PDF, DOCX veya TXT belge – ya da yapılandırılmış ERP verisi – yükleyin ve doğrulama geçtikten sonra XRechnung, ZUGFeRD, EN 16931, UBL veya CII çıktısını indirin. Bu sayfa eksiksiz entegrasyon sözleşmesidir: erişim modeli, uç noktalar, hata kataloğu ve limitler. > Beş REST uç noktası PDF, DOCX veya TXT faturaları – ya da yapılandırılmış ERP verisini – doğrulanmış XRechnung, ZUGFeRD, EN 16931, UBL ve CII e-faturalarına dönüştürür. Etkin Enterprise aboneleri anahtarları doğrudan oluşturur; ayda 100 ortak E-posta/API dönüşümü dahildir, ardından her dönüşüm 0,50 € ön ödemeli kredi kullanır. ## Genel görünüm API multipart yüklemeleri kabul eder, JSON yanıtları döndürür ve Bearer kimlik doğrulamasıyla standart HTTP durum kodlarını kullanır. Her dönüşüm eşzamansız çalışır: belgeyi gönderin, task’i sorgulayın, sonucu indirin. Dosya yalnızca doğrulama geçtikten sonra teslim edilir; doğrulanmamış çıktı yoktur. PDF, DOCX veya TXT fatura belgesi ya da yapılandırılmış fatura verisini bir dönüşüm uç noktasına gönderin. Invoice-Converter buradan çıkarma, doğrulama ve artefakt üretimi için asenkron bir task başlatır. Sonuç uç noktası yalnızca istenen artefakt doğrulanmış, kontrol edilmiş ve çıktıya hazır olduğunda dosya döndürür; işleme devam ederken 202 TASK_NOT_READY, engelleyici doğrulama hatalarında 422 VALIDATION_FAILED döndürür. > **Durum: Enterprise erişimi**: Temel yol: /api/v1. Son senkronizasyon 2026-08-07. ## Temel yetenekler - PDF faturalar ve yapılandırılmış fatura verileri için yükleme uç noktaları - Yapay zeka destekli fatura veri çıkarımı - Otomatik EN 16931 ve KoSIT doğrulaması - XRechnung, ZUGFeRD, EN16931, UBL ve CII çıktı biçimleri - Polling ile eşzamansız işleme; küçük faturalar çoğu zaman yaklaşık 30 saniyede, daha büyük faturalar 1-2 dakikaya kadar tamamlanır - Güvenli tekrar denemeler için idempotent yazma işlemleri ## Enterprise API erişimini başlatın Her etkin Enterprise abonesi üretim API anahtarlarını doğrudan profilden oluşturabilir. 1. Bir hesap oluşturun ve fiyatlandırma sayfasından aylık 50 € veya yıllık 420 € karşılığında Enterprise’ı başlatın. 2. Aylık dahil olan 100 ortak E-posta/API dönüşümünü kullanın; ek dönüşümler ön ödemeli kredilerle dönüşüm başına 0,50 €’dur. 3. Profilinizin API erişimi bölümünden canlı bir API anahtarı oluşturun. 4. İlk isteği sunucu tarafı kimlik bilgileriyle çalıştırın; ardından kullanımı izleyin ve anahtarları profilinizden döndürün. ## Enterprise’ı başlatın - [Enterprise planı ve fiyatlar](/pricing) ## Hızlı başlangıç Üç API çağrısı bir dönüşümü tamamlar. Yükleme uç noktası /api/v1 altında sunulur ve kimlik doğrulama gerektirir. ### POST /api/v1/invoices:convert (Canlı) Fatura belgesini dönüştür ### POST /api/v1/invoices:convert-structured (Canlı) Yapılandırılmış veriyi dönüştür ### GET /api/v1/tasks/{task_id} (Canlı) Task durumunu sorgula ## curl ile hızlı başlangıç $API_KEY değerini canlı anahtarınızla, $TASK_ID değerini ilk yanıttaki task_id ile değiştirin. Aynı üç çağrı her çıktı formatı için geçerlidir. ### 1. Dönüşümü başlatın ``` curl -X POST "https://www.invoice-converter.com/api/v1/invoices:convert" \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: inv-2026-0001" \ -F "file=@invoice.pdf" \ -F "format=XRECHNUNG" ``` ### 2. Task completed olana kadar sorgulayın ``` curl "https://www.invoice-converter.com/api/v1/tasks/$TASK_ID" \ -H "Authorization: Bearer $API_KEY" ``` ### 3. Doğrulanmış dosyayı indirin ``` curl -o invoice.xml \ "https://www.invoice-converter.com/api/v1/tasks/$TASK_ID/result?download=xml" \ -H "Authorization: Bearer $API_KEY" ``` ## Base URL ve API anahtarları - Üretim temel URL’si: `https://www.invoice-converter.com/api/v1`. - Live anahtarlar üretim hostunu ve `icp_...` önekini kullanır. - Üretim hacmi göndermeden önce onboarding ve doğrulama isteklerini canlı anahtarınızla çalıştırın. - Anahtarları server-side secret olarak ele alın. Browser veya mobil istemcilere gömmeyin. ## İlk başarılı istek Bir API anahtarı oluşturduktan sonra bu akışı minimum başarılı yol olarak kullanın. - Yükleme: `Authorization`, `Idempotency-Key`, `file=@invoice.pdf` (veya `.docx`/`.txt`) ve `format=XRECHNUNG` ile `POST /api/v1/invoices:convert`. - Backoff ile sorgulayın: `202` sonrası yaklaşık `20 saniye` bekleyin, ardından durum `completed` veya `failed` olana kadar `GET /api/v1/tasks/{task_id}` çağrısını 20s, 30s, 45s, 60s ve 60s aralıklarıyla yapın. `10/min` ve `120/hour` durum kotası içinde kalın ve yaklaşık 16 dakika sonra vazgeçin. - İndirme: `GET /api/v1/tasks/{task_id}/result?download=xml`; destek takibi için `X-Correlation-ID` değerini saklayın. - ZUGFeRD PDF çıktısı için convert sırasında `format=ZUGFERD`, result sırasında `download=pdf` isteyin; hibrit PDF çıktısı PDF kaynak yüklemesi gerektirir. - Yapılandırılmış giriş için `pdf_file=@invoice.pdf`, `data_file=@invoice-data.json` ve hedef `format` ile `POST /api/v1/invoices:convert-structured` çağırın. - ERP mutabakatı için isteğe bağlı olarak `client_reference` veya `external_invoice_id` ve `source_system` gönderin. - Tek faturaya ait bölünmüş ERP dışa aktarımları için `data_file` alanını tekrarlayın; birden fazla fatura için her fatura adına kendi idempotency key’i olan ayrı bir task başlatın. - XML/PDF artefaktlarının doğrulanmış, önbelleğe alınmış veya bağımlılıklar nedeniyle henüz kullanılamaz olup olmadığını görmek için durum yanıtındaki `result_artifacts` bilgisini saklayın. ## Yaygın payload örnekleri - `XRECHNUNG`: `format=XRECHNUNG` gönderin. - `ZUGFERD`: `format=ZUGFERD` gönderin; hibrit PDF/A-3 çıktısı için result üzerinde `download=pdf` kullanın. - `Yapılandırılmış giriş`: `pdf_file` ile bir veya daha fazla `data_file` parçası gönderin; kabul edilen veri formatları CSV, JSON, XML, XLSX ve TXT’dir ve tüm desteklenen hedef formatlarla kullanılabilir. data_file parçaları tüm zorunlu verileri içermelidir; PDF eksik alanları tamamlamaz. - `Birden fazla fatura`: ayrı convert istekleri gönderin ve dönen her `task_id` değerini izleyin; tekrarlanan `data_file` parçaları yalnızca aynı faturanın bölünmüş dışa aktarımları içindir. - `UBL`: `format=UBL` gönderin; kabul edilen profiller `XRECHNUNG`, `PEPPOL` ve `EN16931`, varsayılan `EN16931`. - `CII`: `format=CII` gönderin; kabul edilen profiller `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931` ve `ZUGFERD_XRECHNUNG`, varsayılan `EN16931`. - `format` x `profile` kapalı bir tablodur: `XRECHNUNG` `[XRECHNUNG]` kabul eder (varsayılan `XRECHNUNG`), `EN16931` `[EN16931]` kabul eder (varsayılan `EN16931`), `UBL` `[XRECHNUNG, PEPPOL, EN16931]` kabul eder (varsayılan `EN16931`), `CII` `[XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_XRECHNUNG]` kabul eder (varsayılan `EN16931`) ve `ZUGFERD` `[ZUGFERD_EN16931, ZUGFERD_XRECHNUNG]` kabul eder (varsayılan `ZUGFERD_EN16931`). Profiller büyük/küçük harf duyarsız eşleştirilir; `ZUGFERD`, `FACTURX`, `FACTUR-X` ve `FACTUR_X`, `ZUGFERD_EN16931` için alias’tır, `ZUGFERD-XRECHNUNG` ise `ZUGFERD_XRECHNUNG` için alias’tır. ## Gerekli başlıklar - Authorization: Bearer ## Kimlik doğrulama kuralları Etkin Enterprise aboneleri profilden API anahtarları oluşturabilir ve bunları Bearer token olarak kullanabilir. Ortak E-posta/API kotası ayda 100 dönüşüm içerir; ek dönüşümler ön ödemeli kredilerle dönüşüm başına 0,50 €’dur. - API anahtarları aktif Enterprise abonelikleri için tenant kapsamlı canlı kimlik bilgileridir. Mevcut üretim öneki `icp_...`. - Enterprise aktifken anahtarları profilinizden oluşturun, döndürün ve iptal edin. Düz metin anahtarlar yalnızca bir kez gösterildiği için yeni anahtarları hemen kopyalayın. - Eksik veya geçersiz API anahtarları `401` döndürür. - `/api/v1` çağrıları, eksikse otomatik olarak `X-Correlation-ID` alır. - Yazma çağrıları `Idempotency-Key` gerektirir; bu değeri tekrar denemelerde sabit tutun. - Backend’inizden server-to-server entegrasyon kullanın. Browser-origin erişimi production’da kısıtlıdır. ## İdempotency sözleşmesi - Her yazma çağrısında `Idempotency-Key` gönderin. - Idempotency key’leri `[A-Za-z0-9._:-]+` ile eşleşmeli ve en fazla 200 karakter olmalıdır. - Kendi key’inizi sağlarsanız aynı key + aynı payload önbellekteki cevabı döndürür. - Aynı key + farklı payload `409 IDEMPOTENCY_CONFLICT` döndürür; bu yeniden denenemez — yeni payload için yeni bir key kullanın. - İlk istek hâlâ işlenirken aynı key ile gönderilen ikinci istek `409 IDEMPOTENCY_IN_PROGRESS` döndürür; kısa bir bekleme sonrası aynı key ile yeniden deneyin. Takılı kalan bir in-progress talep `15 dakika` sonra serbest bırakılır. - Özgün task 24 saatlik saklama süresini aştıysa replay `409 IDEMPOTENCY_REPLAY_EXPIRED` döndürür; yeni bir key ile yeni bir dönüşüm başlatın. - Idempotency kayıtları `24 saat` yaşar ve task saklama süresiyle eşleşir. ## Uç nokta referansı Tüm endpoint’ler /api/v1 altında kullanılabilir. Timeout’lar 504, diğer geçici bağlantı hataları 502 olarak görünür; korelasyon ID’leri support ekibinin istekleri uçtan uca izlemesine yardımcı olur. ### POST /api/v1/invoices:convert (Canlı) 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; 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_XRECHNUNG] (varsayılan EN16931); ZUGFERD → [ZUGFERD_EN16931, 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; 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. ### POST /api/v1/invoices:convert-structured (Canlı) 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_XRECHNUNG] (varsayılan EN16931); ZUGFERD → [ZUGFERD_EN16931, 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. Yanıt: 202 Accepted. ### GET /api/v1/tasks/{task_id} (Canlı) 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. ### GET /api/v1/tasks/{task_id}/result (Canlı) 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":""}); 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. ### GET /api/v1/tasks/{task_id}/validation-report (Canlı) 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. A 202 carries the standard TASK_NOT_READY error envelope, not a file body. Successful responses carry 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, X-Validator-Bundle-Id, plus X-Task-Id, X-Validation-Report-Proof-Id, X-Validation-Report-Content-Type, X-Validation-Report-Format, X-Validation-Report-Source, and X-Report-Source-Artifact-Format. Those artifact-level diagnostics describe the validated result artifact the report covers, not the returned report bytes: X-Artifact-Sha256 is the SHA-256 of that source artifact and must not be used to checksum the downloaded report, while X-Validation-Report-Proof-Id identifies the proof that supplied the report payload. Rate limit 10/min and 120/hour. İstek: none (GET); task_id (path, required) — UUID returned by the convert endpoint; download (query, optional) — html or xml. Yanıt: 200 OK. ## Çıktı biçimi matrisi | Biçim | Söz dizimi | Sürüm / Profil | Content-Type | Uzantı | | --- | --- | --- | --- | --- | | XRECHNUNG | UBL 2.1 XML | XRechnung 3.0.2 | application/xml | .xml | | ZUGFERD | CII XML (download=xml) / hibrit PDF/A-3 (download=pdf) | ZUGFeRD 2.3.2 / Factur-X 1.07.2 | application/xml veya application/pdf | .xml / .pdf | | EN16931 | UBL 2.1 XML | EN 16931 | application/xml | .xml | | UBL | UBL 2.1 XML | OASIS UBL 2.1 | application/xml | .xml | | CII | UN/CEFACT CII XML | D16B | application/xml | .xml | ## Hata sözleşmesi | Kod | HTTP | Tekrar denenebilir | Notlar | | --- | --- | --- | --- | | AUTHENTICATION_REQUIRED | 401 | Hayır | Bearer token eksik/boş | | INVALID_API_KEY | 401 | Hayır | API anahtarı bulunamadı, iptal edildi veya süresi doldu | | API_NOT_ENABLED_FOR_TENANT | 403 | Hayır | Key is valid but External API access is not enabled for the account; contact support instead of retrying | | INSUFFICIENT_API_CREDITS | 402 | Hayır | Pakete dahil aylık kontenjan ile ön ödemeli API kredileri isteği karşılayamadı. İki details biçimi vardır: ön ödemeli (remaining, minimum_purchase 100) ve dahil kontenjan (included_remaining, credit_remaining, shortfall, minimum_purchase 100). code alanına göre ayrıştırın ve mevcut olan anahtarları okuyun | | IDEMPOTENCY_KEY_REQUIRED | 400 | Hayır | Yazma endpoint’i Idempotency-Key olmadan çağrıldı | | INVALID_IDEMPOTENCY_KEY | 400 | Hayır | Idempotency key [A-Za-z0-9._:-]+ ile eşleşmeli ve en fazla 200 karakter olmalıdır | | IDEMPOTENCY_CONFLICT | 409 | Hayır | Key daha önce farklı bir payload ile kullanılmış ya da idempotent talep başlatılamamış; yeni payload için yeni bir key kullanın | | IDEMPOTENCY_IN_PROGRESS | 409 | Evet | Bu key ile gönderilen ilk istek hâlâ işleniyor; kısa bir bekleme sonrası AYNI key ile yeniden deneyin. Takılı kalan bir in-progress talep 15 dakika sonra serbest bırakılır | | IDEMPOTENCY_REPLAY_EXPIRED | 409 | Hayır | The original task is past its 24-hour retention and cannot be recovered; start a new conversion with a new key | | FORMAT_REQUIRED | 400 | Hayır | Dönüşüm isteğinde zorunlu format eksik | | INVALID_FORMAT | 422 | Hayır | Desteklenmeyen dönüşüm formatı | | CLIENT_REFERENCE_CONFLICT | 400 | Hayır | client_reference ve external_invoice_id farklı | | INVALID_CLIENT_METADATA | 400 | Hayır | client_reference, external_invoice_id veya source_system uzunluk limitini aşıyor ya da kontrol karakterleri içeriyor | | INVALID_SELLER_MASTER_DATA | 400 | Hayır | use_seller_master_data veya seller_master_data ayrıştırılamıyor ya da alan doğrulamasından geçemiyor | | METHOD_NOT_ALLOWED | 405 | Hayır | Dönüşüm yolları yalnızca POST, task yolları yalnızca GET kabul eder; yanıt Allow: POST, OPTIONS (dönüşüm) veya Allow: GET, OPTIONS (task) içerir | | DOWNLOAD_FORMAT_REQUIRED | 400 | Hayır | Task sonuç isteğinde zorunlu download sorgusu eksik | | INVALID_DOWNLOAD_FORMAT | 400 | Hayır | download xml veya pdf olmalıdır | | AUTH_SERVICE_UNAVAILABLE | 503 | Evet | Auth backend kullanılamıyor | | RATE_LIMIT_SERVICE_UNAVAILABLE | 503 | Evet | Rate-limit servisine ulaşılamadı; backoff ile yeniden deneyin | | PLAN_TIER_CHECK_FAILED | 503 | Evet | Plan/API access could not be verified right now; retry with backoff | | API_CREDIT_SERVICE_UNAVAILABLE | 503 | Evet | Ön ödemeli API kredisi veya kanal kontenjanı doğrulaması dönüşüm yüklemelerinde geçici olarak kullanılamıyor | | RATE_LIMITED | 429 | Evet | Retry-After değerine uyun. Retry-After, X-RateLimit-Limit-Minute ve X-RateLimit-Limit-Hour yalnızca 429 yanıtlarında döner; gövde details.minute_count, details.hour_count, details.limit_minute ve details.limit_hour taşır | | BAD_REQUEST | 400 | Hayır | Geçersiz JSON veya geçersiz UUID path parametresi | | INVALID_QUERY_PARAMETER | 400 | Hayır | include_validation_report_html true veya false olmalıdır | | PAYLOAD_TOO_LARGE | 413 | Hayır | Yükleme boyutu limitini aşıyor | | INVALID_UPLOAD | 400 | Hayır | Yükleme okunamadı/ayrıştırılamadı | | UPLOAD_FAILED | 422 | Hayır | Opsiyonel bir bağlam alanı (jurisdiction, transaction_scope, delivery_channel) tanınmayan bir değer içeriyordu; izin verilen değerler message alanında yer alır | | INVALID_PROFILE | 422 | Hayır | The value is not a recognized profile name; details.allowed_profiles lists the accepted set | | TASK_NOT_READY | 202 | Evet | Asenkron tamamlama için tekrar poll edin | | TASK_NOT_FOUND | 404 | Hayır | Task bilinmiyor, tenant’a ait değil ya da terminal duruma ulaştıktan sonra 24 saatlik saklama süresini aşmış | | VALIDATION_FAILED | 422 | Hayır | Katı ZUGFeRD ön koşul hataları ve çözülmemiş blocking_source_conflict girdileri dahil engelleyici doğrulama sorunları devam ediyor; tekrar denemeden önce fatura verilerini düzeltin | | AUTHORITATIVE_VALIDATION_UNAVAILABLE | 503 | Evet | Yetkili doğrulama, kanıt kaydı veya hibrit üretim bağımlılığı kullanılamıyor; daha sonra tekrar deneyin | | TASK_STATUS_FAILED | 4xx/5xx | Koşullu | Geçici servis koşulu varsa yeniden deneyin | | TASK_RESULT_FAILED | 4xx/5xx | Koşullu | Geçici servis koşulu varsa yeniden deneyin | | TASK_FAILED | 500 | Koşullu | Sonuç uç noktasında bildirilen dönüşüm hatası. details.code ve details.retryable değerlerini okuyun: MULTIPLE_INVOICES_IN_DOCUMENT, NO_INVOICE_DETECTED, INSUFFICIENT_INVOICE_SIGNAL, SCHEMA_PARSE_FAILED ve ARTIFACT_PARITY_FAILED kalıcıdır; PROVIDER_ERROR ve tanınmayan her details.code, details.retryable değerine uyar ve details.retryable=true, aynı task’ı yeniden pollamak yerine yeni bir Idempotency-Key ile YENİ bir dönüşüm başlatmanız gerektiği anlamına gelir. Başarısız dönüşüm bir faturalandırma birimi tüketmez | | MULTIPLE_INVOICES_IN_DOCUMENT | 500 (details code) | Hayır | Terminal: the source document contains more than one invoice, corroborated by distinct invoice identifiers or a reported invoice count. details.retryable and details.can_review are false. Split the PDF into one file per invoice and start a separate conversion for each invoice | | NO_INVOICE_DETECTED | 500 (details code) | Hayır | Terminal: the document does not look like an invoice. Route to human handling | | INSUFFICIENT_INVOICE_SIGNAL | 500 (details code) | Hayır | Terminal: not enough invoice data for reliable extraction. Supply a better source document or use structured conversion | | SCHEMA_PARSE_FAILED | 500 (details code) | Hayır | Terminal for that input: extraction returned a payload that failed schema parsing. Start a new conversion; escalate if it repeats on the same document | | PROVIDER_ERROR | 500 (details code) | Koşullu | Extraction-provider failure; details.retryable is authoritative. When details.classification is provider_context_too_large, use a smaller source document | | XML_GENERATION_FAILED | 500 | Evet | Geçici XML üretim hatası veya zaman aşımı | | PDF_GENERATION_FAILED | 500 | Evet | Geçici PDF üretim hatası veya zaman aşımı | | ARTIFACT_GENERATION_RERUN_REQUIRED | 503 | Hayır | Katı artifact üretimi sunucu tarafı retry denemelerinden sonra başarısız oldu; bağımlılık düzeldikten sonra yeni bir dönüştürme başlatın | | EXTRACTION_INCOMPLETE_GROUP_FAILURE | 503 | Hayır | Extraction finished with one or more failed field groups. The same task will not recover: start a NEW conversion. details carries type "dependency", dependency "parallel_extraction", stage "extraction", retryable true, same_task_retryable false, recovery "start_new_conversion", and failed_groups | | ARTIFACT_GENERATION_FAILED | 503 (details code) | Hayır | Yeniden denenebilir katı üretim hataları için başarısız task’lara kaydedilir; sonuç indirmeleri details içinde bu kodla 503 ARTIFACT_GENERATION_RERUN_REQUIRED döndürür | | ARTIFACT_PARITY_FAILED | 500 (details code) | Hayır | Katı artefakt, nihai incelenmiş fatura verisiyle eşleşmediğinde 500 TASK_FAILED details içinde bildirilir; korelasyon ID’si ile destek ekibine iletin | | INTERNAL_ARTIFACT_INVARIANT_FAILED | 500 | Hayır | Tamamlanan katı task’ın istenen indirme için güvenli kayıtlı artefaktı yok; korelasyon ID’si ile destek ekibine iletin | | PROFILE_MISMATCH | 422 | Hayır | İstenen profil, sonuç indirmede kayıtlı sonucun CustomizationID değeriyle eşleşmiyor | | ZUGFERD_SOURCE_PDF_INCOMPATIBLE | 422 | Hayır | Katı hibrit PDF üretimi XML verisini yüklenen kaynak PDF içine gömemiyor | | ZUGFERD_SOURCE_PDF_REQUIRED | 422 | Hayır | ZUGFERD için download=pdf bir PDF kaynak yüklemesi gerektirir (DOCX/TXT kaynakları hibrit PDF taşıyamaz); bunun yerine download=xml isteyin | | VALIDATION_REPORT_NOT_FOUND | 404 | Hayır | Geçerli teslim edilen artefakt kanıtına bağlı doğrulama raporu yok | | VALIDATION_REPORT_FAILED | 4xx/5xx | Koşullu | Doğrulama raporu alınamadı; yalnızca geçici 5xx durumlarında yeniden deneyin | | OUTPUT_PROFILE_REQUIRED | 422 | Hayır | Net bir varsayılan belirlenemediğinde genel çıktı sözleşmesi açık profil gerektirir | | OUTPUT_PROFILE_CONFLICT | 422 | Hayır | Profil seçilen çıktı formatı veya açık varyantla çelişiyor | | PROXY_ERROR | 502/504 | Evet | Dönüşüm sonucu değil, taşıma katmanı hatası: proxy/upstream hatası (timeout için 504). Backoff ve aynı idempotency key ile yeniden deneyin | ## Yaygın hatalar ve yapılacaklar - Backoff ile tekrar deneyin: `429`, `502`, `504`, yeniden denenebilir kod taşıyan `503` ve `TASK_FAILED` ya da `INTERNAL_ARTIFACT_INVARIANT_FAILED` olmayan geçici `500` hataları. `500 TASK_FAILED` yalnızca `details.retryable` `true` olduğunda ve yalnızca yeni bir dönüşüm olarak yeniden denenebilir. - Yeniden denemeyin: `400`, `401`, `402`, `403`, `404`, `405`, `413`, `422`, `409 IDEMPOTENCY_CONFLICT`, `409 IDEMPOTENCY_REPLAY_EXPIRED`, `details.retryable` `true` olmadığında `500 TASK_FAILED` ve `500 INTERNAL_ARTIFACT_INVARIANT_FAILED`. - İstek veya kaynak veriyi düzeltin: `400`, `413`, `422`. - Erişim veya kimlik bilgilerini düzeltin: `401 INVALID_API_KEY`. `403 API_NOT_ENABLED_FOR_TENANT`, anahtarın geçerli olduğunu ancak hesap için External API erişiminin açık olmadığını gösterir — destek ekibine başvurun. - Pakete dahil aylık kontenjanı doğrulayın veya ön ödemeli API kredi paketi satın alın: `402 INSUFFICIENT_API_CREDITS`. Mevcut olan `details` anahtarlarını okuyun (ön ödemeli hesaplarda `remaining`; dahil kontenjan uygulanıyorsa `included_remaining`/`credit_remaining`/`shortfall`). - Daha sonra polling yapmaya devam edin: `202 TASK_NOT_READY`. - `500 TASK_FAILED` için `details.code` ve `details.retryable` değerlerini okuyun. `MULTIPLE_INVOICES_IN_DOCUMENT`, `NO_INVOICE_DETECTED`, `INSUFFICIENT_INVOICE_SIGNAL`, `SCHEMA_PARSE_FAILED` ve `ARTIFACT_PARITY_FAILED` kalıcıdır; `PROVIDER_ERROR` ve tanınmayan her kod `details.retryable` değerine uyar; `true` ise aynı task’ı yeniden pollamak yerine YENİ bir dönüşüm başlatın. Başarısız dönüşüm bir faturalandırma birimi tüketmez. - `422 VALIDATION_FAILED` için alanı, kural ID’sini ve düzeltme önerisini insan inceleyiciye gösterin; düzeltilmiş fatura verisiyle sonra tekrar deneyin. - `503 AUTHORITATIVE_VALIDATION_UNAVAILABLE` için aynı task sonucunu daha sonra yeniden alın; doğrulanmamış artefakt teslim edilmemiştir. `503 ARTIFACT_GENERATION_RERUN_REQUIRED` ve `503 EXTRACTION_INCOMPLETE_GROUP_FAILURE` için bunun yerine yeni bir dönüşüm başlatın. - `502` ve `504 PROXY_ERROR` dönüşüm sonucu değil taşıma katmanı hatasıdır; backoff ve aynı idempotency key ile yeniden deneyin. ## Hız ve yük limitleri API anahtarı bazlı rate limit’ler ve payload boyutu sınırları tüm API çağrıları için uygulanır. Reddedilen dönüşümler ön ödemeli API kredisi tüketmez; rate limit’ler uç nokta bazında ayrı hesaplanır. - Uç nokta bazlı limitler maliyet ağırlıklıdır ve her uç noktanın kendi bucket’ı vardır; böylece polling dönüşüm kapasitesini tüketemez. API anahtarı başına varsayılanlar: `POST /invoices:convert` ve `POST /invoices:convert-structured` `30/min` ve `500/hour`; `GET /tasks/{task_id}` `10/min` ve `120/hour`; `GET /tasks/{task_id}/result` `10/min` ve yaklaşık `134/hour`; `GET /tasks/{task_id}/validation-report` `10/min` ve `120/hour`. - Kota header’ları yalnızca `429 RATE_LIMITED` yanıtlarında döner. Başarılı yanıtlar kota header’ı taşımaz; bu nedenle yukarıdaki tabloyu geçerli sözleşme kabul edin ve tam etkin değerleri bir `429` yanıtından okuyun. - Polling için bağlayıcı kısıt durum bucket’ıdır: kabul edilen `202` sonrası ilk durum çağrısı 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. Her 10 saniyede bir sorgulamayın; bu şekilde sorgulanan tek bir task saatlik bütçesinin tamamını 20 dakikada tüketir. - Kaynak belge yükleme maksimum boyutu: PDF, DOCX veya TXT dosyaları için `20 MB`. - Maksimum yapılandırılmış veri yükleme boyutu: tüm `data_file` parçaları genelinde toplam `2 MB`. - Maksimum JSON payload boyutu: `1 MB` - `429` yanıtları `Retry-After`, `X-RateLimit-Limit-Minute` ve `X-RateLimit-Limit-Hour` ile birlikte `details.minute_count`, `details.hour_count`, `details.limit_minute` ve `details.limit_hour` içerir. ## Yeniden deneme rehberi - Jitter ile üstel backoff kullanın ve bir yazma isteğinin her yeniden denemesinde aynı `Idempotency-Key` değerini kullanın. - Kararınızı makine tarafından okunabilir `code` alanına — `500 TASK_FAILED` için ayrıca `details.code` ve `details.retryable` alanlarına — göre verin; asla yalnızca HTTP durumuna göre değil. Bu API’de `500` otomatik olarak yeniden denenebilir değildir. - Yeniden denenebilir: `429`, `502`, `504`, yeniden denenebilir kod taşıyan `503`, `TASK_FAILED` ya da `INTERNAL_ARTIFACT_INVARIANT_FAILED` OLMAYAN geçici `500` hataları ve `details.retryable` `true` olduğunda `500 TASK_FAILED` (geçici sağlayıcı hataları: rate limit, timeout, taşıma hatası) — bu durumu aynı task’ı yeniden pollayarak değil, yeni bir `Idempotency-Key` ile YENİ bir dönüşüm olarak tekrarlayın. - Asla yeniden denemeyin: `400`, `401`, `402`, `403`, `404`, `405`, `413`, `422`, `409 IDEMPOTENCY_CONFLICT`, `409 IDEMPOTENCY_REPLAY_EXPIRED`, `details.retryable` `true` olmadığında `500 TASK_FAILED` ve `500 INTERNAL_ARTIFACT_INVARIANT_FAILED`. Kalıcı olarak başarısız olan bir dönüşüm faturalandırma birimi tüketmez. - `409 IDEMPOTENCY_IN_PROGRESS`, kısa bir bekleme sonrası AYNI key ile yeniden denenebilir; takılı kalan bir in-progress talep 15 dakika sonra serbest bırakılır. - `503 ARTIFACT_GENERATION_RERUN_REQUIRED` ve `503 EXTRACTION_INCOMPLETE_GROUP_FAILURE`, aynı task’ın yeniden denenmesini değil YENİ bir dönüşümü gerektirir. ## Görev yaşam döngüsü ve saklama - Bir task ve saklanan artefaktları, task terminal duruma (`completed` veya `failed`) ulaştıktan sonra `24 saat` saklanır ve ardından silinir. Silme sonrası durum, sonuç ve doğrulama raporu istekleri `404 TASK_NOT_FOUND` döndürür. - Sabit bir dönüşüm zaman aşımı yoktur. Bir task, aşama veya ilerleme güncellemesi olmadan `5 dakika` duraklama penceresi dolduğunda ya da toplam işleme süresi mutlak `15 dakika` üst sınırını aştığında başarısız olur. - İstemci tarafı zaman aşımınızı, kabul edilen `202` anından itibaren yaklaşık `16 dakika` olarak ayarlayın. Dönüşümlerin çoğu iki dakikanın çok altında tamamlanır. - Idempotency kayıtları `24 saat` yaşar ve task saklama süresiyle eşleşir. Takılı kalan bir istek `15 dakika` sonra serbest bırakılır. - Rate-limit sayaçları kayan pencereye göre sıfırlanır. ## Destek modeli - Mesai saatlerinde ticari olarak makul çaba temelinde destek. - Order form içinde kararlaştırılmadıkça resmi SLA, servis kredisi veya yanıt süresi taahhüdü yoktur. ## Değişiklik günlüğü Dışa açık son API değişiklikleri. ### 2026-08-07 Documentation release 1.13.0: Enterprise is available through direct checkout for EUR 50 per month or EUR 420 per year. Every active Enterprise subscription includes 100 conversion units per month shared by Email Import and External API V1; additional units use prepaid credits at EUR 0.50 each. Email Import and External API V1 no longer require manual account approval. Email Import still requires profile enablement and a verified sender. ### 2026-07-29 Documentation release 1.12.0. No runtime behavior changed on this date; these entries document behavior that was already live. MULTIPLE_INVOICES_IN_DOCUMENT is now published in the error catalog. It is returned as 500 TASK_FAILED with details.code=MULTIPLE_INVOICES_IN_DOCUMENT, details.retryable=false, and details.can_review=false. It is terminal: split the source into one document per invoice. The failed attempt does not consume a billing unit. Retry guidance corrected: a 500 is not automatically retryable. Branch on code, and on details.code plus details.retryable for 500 TASK_FAILED, instead of on the HTTP status alone. Treat 500 TASK_FAILED as terminal unless details.retryable is true (transient provider failures such as rate limiting, timeouts, and transport errors), in which case start a new conversion with a new Idempotency-Key rather than re-polling the same task. Never retry 500 INTERNAL_ARTIFACT_INVARIANT_FAILED. Billing is documented as included-allowance-then-credits, so 402 INSUFFICIENT_API_CREDITS has two details shapes: prepaid (remaining, minimum_purchase) and included allowance (included_remaining, credit_remaining, shortfall, minimum_purchase). Newly documented runtime error codes that were already being returned: 403 API_NOT_ENABLED_FOR_TENANT, 409 IDEMPOTENCY_IN_PROGRESS, 409 IDEMPOTENCY_REPLAY_EXPIRED, 422 INVALID_PROFILE, 422 UPLOAD_FAILED, 400 INVALID_IDEMPOTENCY_KEY, 503 PLAN_TIER_CHECK_FAILED, 503 RATE_LIMIT_SERVICE_UNAVAILABLE, and 503 EXTRACTION_INCOMPLETE_GROUP_FAILURE. The 409 class is split by retry semantics: IDEMPOTENCY_IN_PROGRESS is retryable with the same key after a short delay, while IDEMPOTENCY_CONFLICT and IDEMPOTENCY_REPLAY_EXPIRED require a new key. Validation-report header passthrough fixed, and X-Validation-Report-Format, X-Validation-Report-Source, and X-Report-Source-Artifact-Format are now published. On the validation-report endpoint, X-Artifact-Sha256 is the SHA-256 of the result artifact the report validates, not of the returned report bytes; X-Validation-Report-Proof-Id identifies the proof that supplied the report payload. Added retention and lifecycle statements: 24-hour task/artifact retention after a terminal state, 24-hour idempotency records, a 15-minute in-progress reclaim, a 5-minute stall window, a 15-minute hard cap, and a recommended ~16-minute client timeout. Rate limits and polling guidance replaced with per-endpoint numbers, including the previously missing validation-report bucket. Quota headers are returned on 429 responses only, and the former "poll every 10-15 seconds" advice is replaced with a first-poll delay plus backoff. Published a closed format x profile compatibility table with the default profile for each format, and corrected download=xml on a completed task from "always available" to expected-available. Corrected 405 METHOD_NOT_ALLOWED to return Allow: POST, OPTIONS on conversion paths and Allow: GET, OPTIONS on task paths, and corrected 422 PROFILE_MISMATCH: there is no profile query parameter, and the fix is to start a new conversion with an aligned profile. ### 2026-07-28 External API conversions now run the same document-scope gate as the interactive product, including on forced extraction modes that previously skipped it. A source document whose extraction reports multiple invoices, corroborated by two or more distinct invoice identifiers or by an invoice count with no identifiers, now fails terminally with MULTIPLE_INVOICES_IN_DOCUMENT. The failure is not retryable: split the source into one document per invoice and submit each separately. An uncorroborated multiple_invoices verdict no longer fails the conversion. On strict API issuance it returns 422 VALIDATION_FAILED with a blocking_source_conflict issue entry, which covers duplicate renditions such as an original plus its copy, a reprint, or a second-language rendition. ### 2026-07-26 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. ### 2026-07-25 Superseded by the 2026-07-26 entry above. Seller master data filled missing seller and payment fields only; explicit invoice values remained unchanged, and material profile/source conflicts blocked strict issuance until review. Since 2026-07-26 every supplied profile value replaces the corresponding extracted value instead. ### 2026-07-10 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ı. ### 2026-07-06 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. ### 2026-07-03 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. ### 2026-06-30 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. ### 2026-06-29 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. ### 2026-06-10 Invoice data you submit is now the source of truth during hybrid ZUGFeRD generation; the server no longer overrides submitted quantities or totals with values recovered from the uploaded PDF. Deterministic cleanup and tax normalization still apply. Long-running conversions are no longer failed at a fixed 5-minute processing timeout. Tasks now fail only when they stop making progress for the stall window or exceed the absolute 15-minute hard cap, and extraction retries are bounded by a total wall-clock budget. ### 2026-06-09 Clarified that usage-tracking persistence failures are fail-open for response delivery: ready validated artifact responses are not denied, no extra prepaid API credit is consumed, and failed usage events are queued internally for reconciliation. ### 2026-06-02 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. ### 2026-06-01 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. ### 2026-05-27 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. ### 2026-05-26 Strict XML and hybrid ZUGFeRD PDF result artifacts now carry internal artifact parity metadata; public clients should use task-status result_artifacts for artifact readiness and validation-state diagnostics. Updated the documented production base URL to https://www.invoice-converter.com/api/v1. ### 2026-05-19 Task-result downloads are now strict retrieval-only: no XML/PDF generation, AI call, repair, or validation runs on GET /api/v1/tasks/{task_id}/result. Strict tasks complete only after a validated artifact is stored; completed tasks without a current proof fail closed with 500 INTERNAL_ARTIFACT_INVARIANT_FAILED. External API conversions are permanently pinned to strict issuance: no draft output, no warning override, and artifact validation always required. Conversions run on a dedicated processing tier chosen by the service. Added additive result_artifacts diagnostics to the task status response, and documented the canonical delivery_channel values PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, and UNKNOWN. Documented 422 ZUGFERD_SOURCE_PDF_INCOMPATIBLE, and clarified that missing XRechnung/Peppol target metadata such as BT-10, BT-49, and BG-16 is a validation correction flow rather than a transport retry. ### 2026-05-08 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. ### 2026-03-28 Task status responses expose artifact readiness diagnostics for XML/PDF result availability. Documented that strict result downloads only return files after server-side artifact gates pass. ### 2026-03-26 Successful task-result downloads are backed by a server-side validation proof for the returned bytes. The result endpoint returns 503 AUTHORITATIVE_VALIDATION_UNAVAILABLE when required authoritative validation, proof persistence, or hybrid-generation dependencies are unavailable. Cached task-result downloads are reused only when the cached artifact still has a persisted validation proof. ### 2026-03-06 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ı. ### 2026-02-23 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ı. ## Teslimat çıktıları Developer API için makine tarafından okunabilir entegrasyon çıktıları indirin. - [OpenAPI JSON](/developer-api/v1/openapi.json) - [Postman koleksiyonu](/developer-api/v1/postman.json) ## Postman ve OpenAPI kullanımı - Postman koleksiyonunu içe aktarın ve `base_url`, `api_key` ve `idempotency_key` koleksiyon değişkenlerini ayarlayın. - Koleksiyonu sırayla çalıştırın: convert, durum sorgulama, ardından sonucu alma. - OpenAPI JSON ile typed client üretin; dosya yükleme, polling ve binary result işleme için entegrasyon testleri tutun. - Support’un istekleri uçtan uca izleyebilmesi için `X-Correlation-ID` değerini loglarda saklayın. ## Teknik geri bildirim gönderin Uygulama sorularınızı, riskleri ve gerekli sözleşme değişikliklerini ekibimizle paylaşın. - [Teknik geri bildirim e-postası gönder](mailto:contact@invoice-converter.com?subject=Harici%20API%20V1%20teknik%20inceleme%20geri%20bildirimi&body=Merhaba%20Invoice-Converter%20ekibi%2C%0D%0A%0D%0AHarici%20API%20V1%20dok%C3%BCmantasyonunu%20inceledik%20ve%20a%C5%9Fa%C4%9F%C4%B1daki%20geri%20bildirimlerimiz%20var%3A%0D%0A%0D%0A1)%20%0D%0A2)%20%0D%0A3)%20%0D%0A%0D%0ASayg%C4%B1lar%C4%B1m%C4%B1zla%2C)