# Invoice Converter Harici API Sürüm: 1.20.0 · Son güncelleme: 2026-10-02 · Temel URL: `https://www.invoice-converter.com/api/v1` Fatura belgelerini (PDF, DOCX, TXT) veya ERP, faturalama ya da CRM sisteminizdeki yapılandırılmış fatura verilerini doğrulanmış XRechnung, ZUGFeRD/Factur-X, EN 16931, UBL veya CII e-faturalarına dönüştürün. **Temel URL** `https://www.invoice-converter.com/api/v1` · **Kimlik doğrulama** `Authorization: Bearer ` · **Sözleşme** OpenAPI 3.1 (bu belge) Bu sayfa eksiksiz dokümantasyondur: aşağıdaki kılavuz bölümleri akışı açıklar; uç nokta ve şema bölümleri her alanı, değeri ve yanıtı listeler. ## Genel bakış API, istek başına bir faturayı doğrulanmış bir e-faturaya dönüştürür. Her dönüşüm asenkrondur: 1. **Dönüştürün.** `POST /invoices:convert` (PDF, DOCX veya TXT belgesi) veya `POST /invoices:convert-structured` (fatura verileriniz ve bir taşıyıcı PDF). Yanıt: `task_id` içeren `202`. 2. **Sorgulayın.** `status` değeri `completed` veya `failed` olana kadar `GET /tasks/{task_id}`. 3. **İndirin.** `GET /tasks/{task_id}/result?download=xml|pdf`. İsteğe bağlı: `GET /tasks/{task_id}/validation-report?download=html|xml`. Bir görev yalnızca çıktı dosyası istenen profil için doğrulamadan geçtiğinde tamamlanır. Taslak çıktı veya uyarıları geçersiz kılan bir çıktı yoktur. V1’de webhook, toplu işlem uç noktası ve görev listesi uç noktası yoktur. | Uç nokta | Amaç | API anahtarı başına hız limiti | |---|---|---| | `POST /invoices:convert` | Bir belgeyi dönüştürür | 30/dk, 500/saat | | `POST /invoices:convert-structured` | Yapılandırılmış veriyi dönüştürür | 30/dk, 500/saat | | `GET /tasks/{task_id}` | Görev durumu | 60/dk, 1.500/saat | | `GET /tasks/{task_id}/result` | Çıktı dosyasını indirir | 60/dk, 1.000/saat | | `GET /tasks/{task_id}/validation-report` | Doğrulama raporunu indirir | 30/dk, 500/saat | ## Kimlik doğrulama ve erişim - Başlık: `Authorization: Bearer `. - Anahtarlar, `icp_...` önekine sahip ve kiracıya (tenant) bağlı canlı kimlik bilgileridir. Etkin bir Enterprise aboneliğiyle anahtarları profil sayfasında oluşturun, yenileyin ve iptal edin. Ayrı bir onay gerekmez. - Anahtarları sunucunuzda tutun. Anahtarları asla tarayıcı veya mobil uygulama koduna, loglara veya destek taleplerine koymayın. - Eksik token: `401 AUTHENTICATION_REQUIRED`. Bilinmeyen veya iptal edilmiş anahtar: `401 INVALID_API_KEY`. API erişimi olmayan geçerli anahtar: `403 API_NOT_ENABLED_FOR_TENANT`. Silinmiş bir hesaba ait anahtar: `410 ACCOUNT_DELETED` (silme kalıcıdır; yeniden denemeyin). ## Hızlı başlangıç ```bash # 1. Convert curl -X POST 'https://www.invoice-converter.com/api/v1/invoices:convert' \ -H 'Authorization: Bearer ' \ -H 'Idempotency-Key: erp-inv-2026-0001' \ -F 'file=@invoice.pdf' \ -F 'format=XRECHNUNG' \ -F 'client_reference=ERP-2026-0001' # 2. Poll (first call about 20 s later) curl 'https://www.invoice-converter.com/api/v1/tasks/' \ -H 'Authorization: Bearer ' # 3. Download download_tmp=$(mktemp) || exit 1 download_meta=$(curl --silent --show-error --output "$download_tmp" \ --write-out '%{http_code} %{content_type}' --dump-header headers.txt \ 'https://www.invoice-converter.com/api/v1/tasks//result?download=xml' \ -H 'Authorization: Bearer ') || { rm -f "$download_tmp"; exit 1; } case "$download_meta" in '200 application/xml'|'200 application/xml;'*|'200 text/xml'|'200 text/xml;'*) mv "$download_tmp" invoice.xml ;; *) rm -f "$download_tmp" printf 'Download not saved (%s). Continue polling on 202.\n' "$download_meta" >&2 exit 1 ;; esac ``` `202` gövdesi `task_id`, `status` (`pending` veya `processing`), `status_url` ve `primary_result_url` içerir. Mantığınızı `message` değerine göre değil, `status` değerine göre kurun. Her yanıttaki `X-Correlation-ID` değerini saklayın; destek ekibi bu değere ihtiyaç duyar. Tamamlanmış bir durum yanıtı (kısaltılmış): ```json { "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "completed", "progress": 100, "created_at": "2026-09-30T08:00:00+00:00", "completed_at": "2026-09-30T08:01:12+00:00", "error": null, "client_reference": "ERP-2026-0001", "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "result_artifacts": { "xml": { "state": "cached", "artifact_state": "compliant", "validation_state": "passed" } } } ``` `failed` durumunda `error` bir özet içerir (metin veya nesne); türü belirli hatayı almak için `/result` çağrısını yapın. ## Formatlar ve profiller `format` zorunludur ve sözdizimini ile kapsayıcıyı seçer. `profile` isteğe bağlıdır ve kural setini seçer. `profile` göndermezseniz formatın varsayılanı uygulanır. | `format` | Kabul edilen `profile` | Varsayılan | `download=xml` | `download=pdf` | |---|---|---|---|---| | `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | görselleştirilmiş PDF (en iyi çaba) | | `EN16931` | `EN16931` | `EN16931` | UBL | görselleştirilmiş PDF (en iyi çaba) | | `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | görselleştirilmiş PDF (en iyi çaba) | | `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | görselleştirilmiş PDF (en iyi çaba) | | `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | hibrit ZUGFeRD/Factur-X PDF | - `format` ve `profile` büyük/küçük harfe duyarlı değildir. Takma adlar: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`. - Format için listelenmeyen bir profil: `422 OUTPUT_PROFILE_CONFLICT`. Bilinmeyen bir profil adı: `details.allowed_profiles` ile birlikte `422 INVALID_PROFILE`. - XML formatlarında birincil çıktı dosyası `download=xml` ile alınır. PDF görselleştirmesi bir kolaylıktır ve kullanılamayabilir. - `format=ZUGFERD` bir PDF kaynağı gerektirir. Bir DOCX veya TXT yüklemesi, yükleme sırasında `422 ZUGFERD_SOURCE_PDF_REQUIRED` ile reddedilir. - `jurisdiction` (ISO 3166-1 alpha-2), `transaction_scope` (`B2B`, `B2G`, `B2C`) ve `delivery_channel` (`PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN`) isteğe bağlı bağlam bilgileridir. Alman B2G veya Peppol akışlarında çağıran tarafın bağlamını yükleme sırasında gönderin. Geçersiz bir değer `422 UPLOAD_FAILED` döndürür. ## Belge dönüştürme `POST /invoices:convert`, `multipart/form-data`: - `file` (zorunlu): `.pdf`, `.docx` veya `.txt`. Dosya başına bir fatura. Birden fazla fatura içeren bir belge `500 TASK_FAILED`, `details.code=MULTIPLE_INVOICES_IN_DOCUMENT` ile başarısız olur. - `format` (zorunlu), `profile` ve yukarıdaki bağlam alanları. - `client_reference` (≤ 200 karakter) veya takma adı `external_invoice_id` ile `source_system` (≤ 100 karakter): `202` yanıtında ve görev durumunda aynen geri döndürülür. - `use_embedded_xml` (varsayılan `false`): Bir PDF’e gömülü Factur-X/ZUGFeRD/XRechnung XML’i, bu değer `true` olmadıkça yok sayılır. - `email_input`: Veri çıkarımı için isteğe bağlı serbest metin talimatlar (yalnızca PDF, ≤ 10.000 karakter, `use_embedded_xml=true` ile birlikte kullanılamaz). - `use_seller_master_data` ve `seller_master_data`: bkz. *Satıcı ana verileri*. Veri çıkarımı belgeyi okur. Yasal veriler, vergi verileri, yönlendirme verileri, banka verileri veya alıcı referansı uydurmaz. Zorunlu veriler eksikse görev başarısız olur ve `/result` `422 VALIDATION_FAILED` döndürür. ## Yapılandırılmış fatura verisi `POST /invoices:convert-structured`, ERP, faturalama veya CRM sisteminizdeki (örneğin Salesforce) verileri dönüştürür. - `pdf_file` (zorunlu): taşıyıcı PDF. `ZUGFERD` için doğrulanmış XML bu PDF’e gömülür; XML formatlarında PDF orijinal PDF olarak saklanır. **Hiçbir zaman fatura verisi sağlamaz.** - `data_file` (zorunlu, tekrarlanabilir; takma adlar `data_files`, `data_files[]`): `.json`, `.csv`, `.xml`, `.xlsx` veya `.txt`, toplamda ≤ 2 MB. - `format`, `profile`, bağlam, müşteri referansı ve satıcı ana verisi alanları belge dönüştürmedeki gibidir. `email_input` ve `use_embedded_xml` kabul edilmez. ### Deterministik ve yorumlanan eşleme | Girdi | Eşleme | Sonuç | |---|---|---| | Kanonik fatura JSON formatında, en üst düzeyde veya `invoice_data` içine sarılmış **tek** bir JSON `data_file` | Deterministik, yapay zekâ yok | Aynı girdi, aynı çıktı | | Tek bir UBL 2.1 Invoice veya CII D16B XML dosyası | Deterministik, yapay zekâ yok | Mevcut fatura XML ayrıştırıcısı | | Birden fazla tutarlı kanonik JSON `data_file` parçası | Deterministik birleştirme, yapay zekâ yok | Ayrı alanlar ve satırlar birleştirilir | | CSV, XLSX, TXT, diğer XML, özel veya düz JSON ya da karma formatlı parçalar | Yapay zekâ ile eşleme | Açık etiketlerle çalışır; deterministik değildir | Tekrarlanabilir bir entegrasyon için tek bir kanonik JSON dosyası gönderin: - JSON Schema: - Örnek (Alman B2G XRechnung; EN 16931, XRechnung ve katı ZUGFeRD kontrollerinden geçer): Format, UBL 2.1 / EN 16931 öğe adlarını kullanır. Kanonik yol, `ID`, `IssueDate`, `InvoiceTypeCode`, `DocumentCurrencyCode`, `AccountingSupplierParty`, `AccountingCustomerParty`, `TaxTotal`, `LegalMonetaryTotal`, `InvoiceLine` üst düzey anahtarlarından en az 3’ü mevcut olduğunda algılanır; bunlardan biri `ID`, `InvoiceLine` veya `LegalMonetaryTotal` olmalıdır. Kanonik JSON içindeki bilinmeyen alanlar, görev oluşturulmadan önce `400 INVALID_UPLOAD` döndürür. `details.unknown_paths` en fazla 100 hatalı JSON yolunu listeler; `details.unknown_path_count` toplam sayıyı verir. Tanımlanmamış alanların atılmasına güvenmek yerine bu alanları kaldırın. Yapay zekâ eşlemesine eksik alanları uydurmaması talimatı verilir. Bu nedenle eksik veriler tahmin edilmez, doğrulamada başarısız olur. **Bölünmüş dışa aktarımlar.** Birden fazla dosyaya bölünmüş tek bir fatura için (örneğin başlık ve satırlar) `data_file` alanını tekrarlayın. Her fatura için bir istek gönderin. - Her parça, `invoice number`, `invoice no`, `invoice no.`, `invoice id`, `rechnungsnr`, `rechnungsnr.`, `rechnung nr`, `rechnung nr.`, `belegnr` veya `belegnr.` adlı bir sütunda ya da anahtarda aynı fatura numarasını içermelidir. - Adlar büyük/küçük harfe duyarlı değildir; `_` ve `-` boşluk sayılır, bu nedenle `Invoice_Number` çalışır. `document no` ve `document number` daha zayıf bir yedek seçenektir. - `invoiceNumber` gibi camelCase adlar ve `Invoice_Number__c` gibi Salesforce API adları tanınır. - Eksik veya çelişen bir numara, `details.reason` `bundle_invoice_id_missing` veya `bundle_invoice_id_mismatch` ile `400 INVALID_UPLOAD` döndürür. Kanonik JSON parçaları aynı üst düzey `ID` değerini kullanır. Her parça yukarıdaki kanonik algılama kuralını karşılamalıdır. Satırlar her parça içinde benzersiz ve açık `InvoiceLine[].ID` değerlerine ihtiyaç duyar. Parçalar arasında aynı şekilde tekrarlanan satırlar tekilleştirilir; çelişen değerler veya aynı ID ile farklı satırlar `400 INVALID_UPLOAD`, `details.reason=canonical_bundle_conflict` ve `details.path` döndürür. Sunucu çelişen değerlerden birini seçmez veya toplamları yeniden hesaplamaz. Başka bir parça ilgili bilgiyi sağlıyorsa null değeri eksik kabul edilir. ### Zorunlu veriler | Her zaman | XRechnung için (ayrıca `XRECHNUNG` profilli `UBL`/`CII` ve `ZUGFERD_XRECHNUNG`) | Katı ZUGFeRD için | |---|---|---| | `ID`, `IssueDate`, `InvoiceTypeCode`, `DocumentCurrencyCode`, satıcı ve alıcı adı, KDV dökümü, toplamlar, en az bir satır | `BuyerReference` (Leitweg-ID, BR-DE-15); `PaymentMeans` (BR-DE-1); satıcı irtibat kişisinin adı, telefonu, e-postası (BR-DE-2/5/6/7); satıcı ve alıcının şehri ile posta kodu; `@schemeID` ile satıcı ve alıcı `EndpointID`; her ara toplam için KDV `Percent`; satıcının KDV kimlik numarası veya vergi numarası | Bir teslim tarihi, bir faturalama dönemi veya satır dönemleri; gerektiğinde bir teslimat ülkesi | Eksik veriler görevi `failed` olarak sonlandırır; `/result`, `details.items[]` (`field`, `rule_id`, `severity`, `source`, `suggestion`) ile `422 VALIDATION_FAILED` döndürür. ### En çok kullanılan JSON yolları `AccountingSupplierParty.Party` kısaca `Seller`, `AccountingCustomerParty.Party` kısaca `Buyer` olarak yazılmıştır. XR = XRechnung için zorunlu. | JSON yolu | EN 16931 | XR | |---|---|---| | `ID` | BT-1 | evet | | `IssueDate` | BT-2 | evet | | `InvoiceTypeCode` (örneğin `380` ticari fatura) | BT-3 | evet | | `DocumentCurrencyCode` | BT-5 | evet | | `DueDate` | BT-9 | – | | `BuyerReference` | BT-10 | evet | | `OrderReference.ID` | BT-13 | – | | `InvoicePeriod.StartDate` / `.EndDate` | BT-73 / BT-74 | – | | `PaymentTerms.Note` | BT-20 | – | | `Seller.PartyLegalEntity.RegistrationName` | BT-27 | evet | | `Seller.PartyTaxScheme.CompanyID` (KDV kimlik numarası) | BT-31 | evet¹ | | `Seller.EndpointID` (`#text`, `@schemeID`) | BT-34 | evet | | `Seller.PostalAddress.StreetName` | BT-35 | – | | `Seller.PostalAddress.CityName` / `.PostalZone` | BT-37 / BT-38 | evet | | `Seller.PostalAddress.Country.IdentificationCode` | BT-40 | evet | | `Seller.Contact.Name` / `.Telephone` / `.ElectronicMail` | BT-41 / BT-42 / BT-43 | evet | | `Buyer.PartyLegalEntity.RegistrationName` | BT-44 | evet | | `Buyer.EndpointID` (`#text`, `@schemeID`) | BT-49 | evet | | `Buyer.PostalAddress.CityName` / `.PostalZone` | BT-52 / BT-53 | evet | | `Buyer.PostalAddress.Country.IdentificationCode` | BT-55 | evet | | `Delivery.ActualDeliveryDate` | BT-72 | – | | `PaymentMeans.PaymentMeansCode` | BT-81 | evet | | `PaymentMeans.PayeeFinancialAccount.ID` (IBAN) | BT-84 | kredi transferinde | | `TaxTotal.TaxAmount` | BT-110 | evet | | `TaxTotal.TaxSubtotal[].TaxableAmount` / `.TaxAmount` | BT-116 / BT-117 | evet | | `TaxTotal.TaxSubtotal[].TaxCategory.ID` / `.Percent` | BT-118 / BT-119 | evet | | `LegalMonetaryTotal.LineExtensionAmount` / `.TaxExclusiveAmount` | BT-106 / BT-109 | evet | | `LegalMonetaryTotal.TaxInclusiveAmount` / `.PayableAmount` | BT-112 / BT-115 | evet | | `InvoiceLine[].ID` / `.InvoicedQuantity` / `.unitCode` | BT-126 / BT-129 / BT-130 | evet | | `InvoiceLine[].LineExtensionAmount` | BT-131 | evet | | `InvoiceLine[].Price.PriceAmount` | BT-146 | evet | | `InvoiceLine[].Item.Name` | BT-153 | evet | | `InvoiceLine[].Item.ClassifiedTaxCategory.ID` / `.Percent` | BT-151 / BT-152 | evet | ¹ Satıcının KDV kimlik numarası (BT-31) veya vergi numarası (BT-32, `TaxScheme.ID` `FC` ile `PartyTaxScheme`). ## Satıcı ana verileri `seller_master_data` bir JSON nesnesi dizesidir. Yalnızca `use_seller_master_data=true` olduğunda uygulanır; bayrak gönderilmezse hesabın varsayılanı uygulanır. Anahtarlar: `business_name`, `trading_name`, `street`, `additional_address`, `postal_code`, `city`, `country`, `vat_id`, `tax_number`, `electronic_address`, `electronic_address_scheme`, `contact_name`, `contact_email`, `contact_phone`, `payment_means_code` (`30`, `42` veya `58`), `payment_iban`, `payment_bic`, `payment_account_name`, `payment_terms_note`. OpenAPI şeması `SellerMasterData`, her anahtarın EN 16931 terimini belirtir. - Gönderilen her değer, çıkarılan satıcı veya ödeme değerinin yerine geçer. Gönderilmeyen anahtarlar faturayı değiştirmez. - `electronic_address` ve `electronic_address_scheme` bir çifttir: ikisini birlikte gönderin veya hiçbirini göndermeyin. - Geçersiz JSON, bilinmeyen anahtarlar veya eksik bir çift: `400 INVALID_SELLER_MASTER_DATA`. ## Idempotency ve yeniden denemeler - `Idempotency-Key` her iki POST uç noktasında zorunludur. Format: 1–200 karakter; ilk karakter harf veya rakam, ardından harfler, rakamlar, `.`, `_`, `:` veya `-` (`^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`). İyi bir anahtar, fatura kimliğiniz ile bir sürüm numarasının birleşimidir, örneğin `sf-a0B5g00000XyZ12-v1`. - Kapsam: tek tek API anahtarı değil, kiracı ve uç nokta. Kayıtlar 24 saat saklanır. - Her yeniden denemede aynı anahtarı **ve** aynı istek içeriğini kullanın. Bir tekrar (replay), ikinci bir ücretlendirme olmadan `Idempotency-Replayed: true` ile orijinal `202` yanıtını döndürür. - **Bir anahtar, bir görev.** Bir yükleme kabul edildikten sonra, aynı anahtar ve aynı istek içeriğiyle yapılan her yeniden deneme o görevi döndürür: aynı `task_id` ve aynı `202` gövdesi. Bu, ilk yanıtı almadığınızda veya görev kabul edildikten sonra bir `5xx` aldığınızda da geçerlidir. Bir yeniden deneme hiçbir zaman ikinci bir görev başlatmaz ve hiçbir zaman ikinci bir birim ayırmaz veya ücretlendirmez. - Aynı anahtara sahip istekler sırayla tek tek çalışır: diğerleri `409 IDEMPOTENCY_IN_PROGRESS` alır. Görev başarısız olduktan sonraki bir yeniden deneme o başarısız görevi döndürür; tekrar denemek için yeni bir anahtar kullanın. - Aynı anahtar, farklı bir istek içeriğiyle: `409 IDEMPOTENCY_CONFLICT`. İlk istek hâlâ çalışıyor: `409 IDEMPOTENCY_IN_PROGRESS` (aynı anahtarla daha sonra yeniden deneyin). Orijinal görev zaten silinmiş: `409 IDEMPOTENCY_REPLAY_EXPIRED` (yeni anahtar). - `429` veya bir `5xx` yanıtını aynı anahtarla yeniden denemek güvenlidir: bu yanıtlar anahtarı engellemez. Aynı anahtarla yapılan bir yeniden deneme hiçbir zaman iki kez ücretlendirmez: bir görev zaten kabul edilmişse o görevi döndürür; aksi takdirde yüklemeyi yeniden çalıştırır. Tek başına bir `5xx`, bir görevin kabul edilip edilmediğini göstermez; bu nedenle her zaman aynı anahtarla yeniden deneyin. ## Limitler, sorgulama ve yoğun yükler **Hız limitleri** API anahtarı başına, her uç nokta için bir kova (bucket) olarak (tablo: *Genel bakış*), sabit takvim dakikası ve takvim saati pencerelerinde uygulanır. Reddedilen bir istek sayılmaz. `429 RATE_LIMITED`; `Retry-After`, `X-RateLimit-Limit-Minute`, `X-RateLimit-Limit-Hour` ile `details.minute_count`, `hour_count`, `limit_minute`, `limit_hour` içerir. Başarılı yanıtlar kota başlığı içermez. **Sorgulama.** İlk durum çağrısını `202` yanıtından yaklaşık 20 sn sonra yapın, ardından 20, 30, 45 ve 60 sn sonra, sonra her 60 sn’de bir sorgulayın. `completed` veya `failed` durumunda durun. Dönüşümlerin çoğu iki dakika içinde tamamlanır. Sunucu, 5 dakika boyunca ilerleme olmayan veya toplam 15 dakikayı aşan bir görevi başarısız sayar; bu nedenle istemci zaman aşımınızı yaklaşık 16 dakikaya ayarlayın. **Boyut.** `www.invoice-converter.com` üzerindeki iki yükleme yolu, Vercel Function olmadan doğrudan backend’e yönlenir. Varsayılan limitler: kaynak `file` veya taşıyıcı `pdf_file` ≤ 20.000.000 bayt (20 MB); `data_file` parçaları toplamda ≤ 2.000.000 bayt (2 MB). Multipart gövde için 1.000.000 bayt ek alan vardır: belge yüklemeleri için 21 MB, yapılandırılmış yüklemeler için 23 MB. En fazla 20 dosya parçası ve 50 metin alanı (`400 INVALID_UPLOAD`). Dosya veya gövde limiti aşılırsa `details.limit_bytes` içeren JSON `413 PAYLOAD_TOO_LARGE` döner. Kimlik doğrulama, gövde kabulünden önce yapılır. Altyapı hataları yine JSON olmayan yanıtlar döndürebilir. **Yoğunluk artışları** (örneğin ayın ilk günü yüzlerce tekrarlayan fatura): kabul edilen görevler ortak bir işlem kuyruğunda bekler. API yüklemeleri birlikte, her backend sürecinde yapılandırılmış yuvaların en fazla yarısını, aşağı yuvarlanmış olarak kullanır. Varsayılan sekiz yuvalı kuyruk dört API görevi kabul eder ve web veya diğer kanallara dört yuva bırakır. Bu, kabul kapasitesini korur; işlem hızı veya öncelik garantisi vermez. Dolu kuyruk veya API payı, dönüştürme hız kotasını tüketmeden veya bir birim ayırmadan önce `Retry-After: 15` ile `503 SERVER_BUSY` döndürür. Kabul edilen görevin tekrarı ek kuyruk yuvası gerektirmez. Önerilen istemci düzeni: 1. İstemci tarafında yaklaşık 2–4 eşzamanlı dönüştürme içeren bir kuyruk tutun; `SERVER_BUSY` yanıtına göre ayarlayın. 2. `429` ve `503 SERVER_BUSY` için `Retry-After` kadar bekleyin, sonra **aynı** `Idempotency-Key` ile tekrar deneyin. 3. Her görevi yukarıdaki artan bekleme düzeniyle sorgulayın; biri bittiğinde sonraki dönüştürmeyi başlatın. V1 tamamlanma webhook’u, toplu işlem veya görev listesi uç noktası sunmaz. ## Hatalar Her JSON hatası `code`, `message`, `correlation_id` ve genellikle `details` içerir. Mantığınızı `code` değerine göre kurun; `500 TASK_FAILED` için ayrıca `details.code` ve `details.retryable` değerlerine göre. `details.type` genellikle mevcuttur, ancak her zaman değil. Mantığınızı asla yalnızca HTTP durumuna veya `message` değerine göre kurmayın. Eksiksiz katalog (HTTP durumu, yeniden deneme kuralı ve yapılacak işlemle birlikte her kod), OpenAPI referansındaki `ErrorEnvelope.code` alanıdır. En sık karşılaşacağınız kodlar: | Kod | HTTP | Yeniden deneme? | Yapılacak işlem | |---|---|---|---| | `AUTHENTICATION_REQUIRED`, `INVALID_API_KEY` | 401 | hayır | Anahtarı düzeltin. | | `ACCOUNT_DELETED` | 410 | hayır | Bu anahtarın hesabı silindi. Silme kalıcıdır. | | `IDEMPOTENCY_KEY_REQUIRED`, `INVALID_IDEMPOTENCY_KEY` | 400 | hayır | Geçerli bir `Idempotency-Key` gönderin. | | `FORMAT_REQUIRED` / `INVALID_FORMAT` | 400 / 422 | hayır | Desteklenen bir `format` gönderin. | | `OUTPUT_PROFILE_CONFLICT`, `INVALID_PROFILE` | 422 | hayır | Tablodaki bir profili kullanın veya profili göndermeyin. | | `INVALID_UPLOAD` | 400 / 415 | hayır | Multipart gövdeyi, dosya türünü veya bölünmüş dışa aktarımın fatura numaralarını düzeltin. | | `FUNCTION_PAYLOAD_TOO_LARGE` (düz metin) / `PAYLOAD_TOO_LARGE` | 413 | hayır | Daha küçük bir istek gönderin. | | `INSUFFICIENT_API_CREDITS` | 402 | hayır | Kredi satın alın veya bir sonraki ayı bekleyin. | | `IDEMPOTENCY_IN_PROGRESS` | 409 | aynı anahtarla | Kısa bir süre sonra yeniden deneyin. | | `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_EXPIRED` | 409 | hayır | Yeni bir anahtar kullanın. | | `RATE_LIMITED` | 429 | aynı anahtarla | `Retry-After` süresini bekleyin. | | `SERVER_BUSY` | 503 | aynı anahtarla | İşleme kuyruğu dolu. `Retry-After` süresini bekleyin. | | `UPLOAD_FAILED` | 503 / 500 | aynı anahtarla | Yükleme kabul edilmedi veya kabul edildi ancak ilk yanıtı yeniden oluşturulamadı. Backoff ile ve aynı anahtarla yeniden deneyin. | | `UPLOAD_FAILED` | 422 | hayır | Geçersiz `jurisdiction`, `transaction_scope` veya `delivery_channel`. | | `TASK_NOT_READY` | 202 | sorgulayın | Durumu sorgulamaya devam edin. | | `VALIDATION_FAILED` | 422 | hayır | Verileri düzeltin (`details.items`), ardından yeniden dönüştürün. | | `TASK_FAILED` | 500 | `details.retryable` ise | `details.code` değerini okuyun. Yeniden denenebilirse: yeni bir anahtarla yeni bir dönüşüm. | | `AUTHORITATIVE_VALIDATION_UNAVAILABLE` | 503 | evet | Aynı indirmeyi daha sonra yeniden deneyin. | | `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 503 | yeni görev | Yeni bir dönüşüm başlatın. | | `INTERNAL_ARTIFACT_INVARIANT_FAILED` | 500 | hayır | Korelasyon kimliğiyle destek ekibine iletin. | | `TASK_NOT_FOUND` | 404 | hayır | Bilinmeyen görev, başka bir kiracının görevi veya 24 saat sonra silinmiş görev. | | `PROXY_ERROR` | 502 / 504 | aynı anahtarla | Backoff ile yeniden deneyin. | `details.code` içindeki `500 TASK_FAILED` nedenleri: `MULTIPLE_INVOICES_IN_DOCUMENT`, `NO_INVOICE_DETECTED`, `INSUFFICIENT_INVOICE_SIGNAL`, `SCHEMA_PARSE_FAILED`, `ARTIFACT_PARITY_FAILED` (kalıcı); `SOURCE_TEXT_UNAVAILABLE`, `PROVIDER_ERROR` (`details.retryable` değerine uyun). Başarısız bir görev başarısız kalır: yalnızca yeni bir dönüşüm ve yeni bir anahtarla kurtarın. ## Sonuçlar, kanıtlar ve doğrulama raporu - `/result` yalnızca veri alır. Yalnızca güncel bir doğrulama kanıtına sahip, saklanmış bir çıktı dosyası için `200` döndürür. - Yanıt başlıklarını kaydedin: `X-Correlation-ID`, `X-Artifact-Sha256` (teslim edilen baytların hash değeri), `X-Validation-Proof-Id`, `X-Artifact-State` (`compliant`), `X-Validation-State` (`passed`). - `/validation-report?download=html|xml` (zorunlu parametre), teslim edilen çıktı dosyasına bağlı raporu döndürür: KoSIT raporunu veya Factur-X için `source="facturx_php"` içeren bir `validation-evidence` XML’ini. Factur-X kanıtı yalnızca saklanan XML’in doğrulamasını kanıtlar; kaynağa sadakati veya PDF/A uyumluluğunu kanıtlamaz. Bu uç noktada `X-Artifact-Sha256`, raporun değil doğrulanmış sonuç dosyasının hash değeridir. Güncel çıktı dosyası için rapor yoksa: `404 VALIDATION_REPORT_NOT_FOUND`. - Görev durumundaki `result_artifacts..state`: `cached`, `not_ready`, `validation_failed`, `dependency_failed`, `artifact_generation_rerun_required`, `artifact_invariant_failed`. ## Saklama, faturalandırma ve arşivleme - **Saklama.** Görevler, çıktı dosyaları ve idempotency kayıtları, görev bittikten 24 saat sonra silinir. Bundan sonra her görev uç noktası `404 TASK_NOT_FOUND` döndürür. Kalite güvencesi kanıtları, [Veri İşleme Sözleşmesi](https://www.invoice-converter.com/tr/dpa) bölüm 9’daki saklama planına tabidir. - **Faturalandırma.** Kabul edilen her dönüşüm bir birim kullanır. Enterprise, takvim ayı başına E-posta İçe Aktarma ile paylaşılan 100 birim içerir. Ek birimler ön ödemeli kredi kullanır: 100 birim 50 EUR, 200 birim 100 EUR, 500 birim 250 EUR, 1.000 birim 400 EUR. Tekrarlar (replay), başarısız dönüşümler ve tüm görev çağrıları ücretsizdir. Bir birimi karşılayacak bir şey yoksa: `402 INSUFFICIENT_API_CREDITS` (iki `details` yapısı, bkz. OpenAPI `PaymentRequired` yanıtı). - **Arşivleme.** Arşiv paketinizi sonradan değil, akış sırasında oluşturun: orijinal PDF, oluşturulan XML veya hibrit PDF, doğrulama raporu ve `task_id`, `client_reference`, format/profil, `X-Artifact-Sha256`, `X-Validation-Proof-Id`, `X-Validation-Report-Proof-Id`, `created_at`/`completed_at` ile korelasyon kimliklerini içeren bir meta veri kaydı. ## Destek ve sözleşme - İletişim: `contact@invoice-converter.com`. `X-Correlation-ID` değerini belirtin. - API, standart Kullanım Koşulları ve Veri İşleme Sözleşmesi (DPA) ile varsa Enterprise sipariş formu kapsamında sunulur. Bir sipariş formunda belirtilmedikçe çalışma süresi, işleme süresi veya destek için SLA uygulanmaz. - Kalitesiz kaynak belgeler ve uç durumlar insan incelemesi gerektirir. İstisnalar, düzeltme, teslim ve arşivleme için kendi sürecinizi sürdürün. - API erişimi kendi ticari kullanımınız içindir. Yeniden satış, beyaz etiket (white-label) veya hizmet bürosu kullanımı bir iş ortaklığı sözleşmesi gerektirir. ## Referans dosyaları - OpenAPI 3.1: - Postman koleksiyonu: (`base_url`, `api_key`, `idempotency_key` değerlerini ayarlayın) - Yapılandırılmış fatura JSON Schema’sı ve örneği: bkz. *Yapılandırılmış fatura verisi* - E-posta fatura kanalı: - Markdown olarak bu dokümantasyon (LLM’ler ve çevrimdışı okuma için): ## Uç noktalar ### POST /invoices:convert — Bir fatura belgesini dönüştürün Bir fatura belgesi yükleyin ve katı bir dönüşüm başlatın. - `file`: `.pdf`, `.docx` veya `.txt`, dosya başına bir fatura. Kaynak dosya ≤ 20 MB (20.000.000 bayt); multipart gövdenin tamamı ≤ 21 MB. - `format` zorunludur; `profile` isteğe bağlıdır (format başına varsayılan aşağıdadır). - Bir PDF’e gömülü XML, `use_embedded_xml=true` olmadıkça yok sayılır. - Hız limiti: API anahtarı başına 30/dk ve 500/saat. | `format` | Kabul edilen `profile` | Varsayılan | `download=xml` | `download=pdf` | |---|---|---|---|---| | `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | görselleştirilmiş PDF (en iyi çaba) | | `EN16931` | `EN16931` | `EN16931` | UBL | görselleştirilmiş PDF (en iyi çaba) | | `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | görselleştirilmiş PDF (en iyi çaba) | | `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | görselleştirilmiş PDF (en iyi çaba) | | `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | hibrit ZUGFeRD/Factur-X PDF | **Parametreler** | Ad | Konum | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | --- | | `Idempotency-Key` | header | string | evet | Her iki POST uç noktasında zorunludur. Her yeniden denemede aynı anahtarı aynı istek içeriğiyle yeniden kullanın; bir tekrar, ikinci bir ücretlendirme olmadan orijinal `202` yanıtını döndürür. Kapsam: kiracı + uç nokta, 24 saat saklanır. Eksik → `400 IDEMPOTENCY_KEY_REQUIRED`; hatalı biçim → `400 INVALID_IDEMPOTENCY_KEY`; aynı anahtar başka bir istek içeriğiyle → `409 IDEMPOTENCY_CONFLICT`. | | `X-Correlation-ID` | header | string (uuid) | | İzleme için isteğe bağlı UUID. Eksik veya UUID olmayan bir değer, sunucunun oluşturduğu bir UUID ile değiştirilir. `X-Correlation-ID` yanıt başlığında döndürülür; destek ekibine bu değeri belirtin. | **İstek gövdesi** (`multipart/form-data`) | Ad | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | | `file` | string (binary) | evet | Fatura belgesi: `.pdf`, `.docx` veya `.txt`, dosya başına bir fatura. `.doc`, `.rtf` ve görseller reddedilir (`400 INVALID_UPLOAD`). `format=ZUGFERD` bir PDF gerektirir (`422 ZUGFERD_SOURCE_PDF_REQUIRED`). | | `format` | string: `XRECHNUNG`, `ZUGFERD`, `EN16931`, `UBL`, `CII` | evet | Hedef çıktı formatı. Zorunludur; varsayılan değer yoktur. Büyük/küçük harfe duyarsız eşleştirilir. Eksik → `400 FORMAT_REQUIRED`; bilinmeyen → `422 INVALID_FORMAT`. | | `profile` | string: `XRECHNUNG`, `PEPPOL`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | | Çıktı dosyasının doğrulandığı kural seti. İsteğe bağlı: her `format` için bir varsayılan vardır (bkz. işlem tablosu). Büyük/küçük harfe duyarsız eşleştirilir. Takma adlar: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Bu format için kabul edilmeyen profil → `422 OUTPUT_PROFILE_CONFLICT`; bilinmeyen ad → `422 INVALID_PROFILE`. | | `jurisdiction` | string | | İşlemin ISO 3166-1 alpha-2 ülke kodu, örneğin `DE`. İsteğe bağlı bağlam bilgisi. Geçersiz → `422 UPLOAD_FAILED`. | | `transaction_scope` | string: `B2B`, `B2G`, `B2C` | | İsteğe bağlı bağlam bilgisi. Geçersiz → `422 UPLOAD_FAILED`. | | `delivery_channel` | string: `PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN` | | İsteğe bağlı bağlam bilgisi: hibrit PDF teslimi için `EMAIL_PDF`, doğrudan XML entegrasyonu için `DIRECT_XML`, ağ üzerinden teslim için `PEPPOL`. Geçersiz → `422 UPLOAD_FAILED`. | | `client_reference` | string | | Fatura veya iş referansınız. 202 yanıtında ve görev durumunda aynen geri döndürülür. Kontrol karakteri içeremez. `external_invoice_id` takma ad olarak kabul edilir; ikisi birlikte gönderilirse eşleşmeleri gerekir, aksi takdirde `400 CLIENT_REFERENCE_CONFLICT`. | | `source_system` | string | | Çağıran ERP veya faturalama sisteminin etiketi. 202 yanıtında ve görev durumunda aynen geri döndürülür. | | `use_embedded_xml` | boolean | | PDF’e gömülü Factur-X/ZUGFeRD/XRechnung XML’ini veri çıkarımı kaynağı olarak kullanır. Varsayılan `false`: gömülü XML yok sayılır ve görünür belge okunur. | | `email_input` | string | | Veri çıkarımı için herhangi bir dilde serbest metin talimatlar (yalnızca PDF kaynağı). `use_embedded_xml=true` ile birlikte kullanılamaz. Idempotency kimliğinin bir parçasıdır. Geçersiz → `400 INVALID_EMAIL_INPUT`. | | `use_seller_master_data` | boolean | | Satıcı ana verilerini uygular. Gönderilmezse: hesabın varsayılanı uygulanır. `false`: bu istek için kayıtlı satıcı verilerini yok sayar. `true`: kayıtlı verileri ve `seller_master_data` değerini uygular. | | `seller_master_data` | string | | JSON nesnesi dizesi (şema: `SellerMasterData`). Yalnızca `use_seller_master_data=true` olduğunda uygulanır. Gönderilen her değer, çıkarılan satıcı veya ödeme değerinin yerine geçer; gönderilmeyen anahtarlar faturayı değiştirmez. Geçersiz → `400 INVALID_SELLER_MASTER_DATA`. | ```json { "$ref": "#/components/schemas/ConvertInvoiceRequest" } ``` **Yanıtlar** - `202`: Kabul edildi. `status_url` adresini sorgulayın. Aynı Idempotency-Key ve aynı istek içeriğiyle yapılan bir yeniden deneme, zaten kabul edilmiş olan görevi döndürür: aynı task_id ve aynı 202 gövdesi, Idempotency-Replayed: true başlığıyla. Bu, ilk yanıt kaybolduğunda veya görev kabul edildikten sonra bir 5xx olduğunda ve görev başarısız olduktan sonra da geçerlidir. Hiçbir zaman ikinci bir görev başlatmaz ve hiçbir zaman ikinci bir birim ayırmaz veya ücretlendirmez. `application/json` ```json { "$ref": "#/components/schemas/ConvertAcceptedResponse" } ``` - `400`: Geçersiz istek. Yeniden denenemez: isteği düzeltin. Tüm 400 kodları için bkz. `ErrorEnvelope.code`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `401`: Kimlik doğrulama başarısız oldu. Yeniden denenemez. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `402`: `402 INSUFFICIENT_API_CREDITS`. Yeniden denenemez: ön ödemeli bir kredi paketi satın alın veya bir sonraki aylık kotayı bekleyin. İki `details` yapısı vardır; mevcut olan anahtarları okuyun. `application/json` ```json { "oneOf": [ { "$ref": "#/components/schemas/InsufficientApiCreditsPrepaidError" }, { "$ref": "#/components/schemas/InsufficientApiCreditsAllowanceError" } ] } ``` - `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Yeniden denenemez: destek ekibiyle iletişime geçin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `405`: `405 METHOD_NOT_ALLOWED`: dönüştürme yolları POST kabul eder; OPTIONS 204 döndürür. Desteklenmeyen yöntemler için backend `correlation_id` içeren bir JSON hatası döndürür. HEAD gövde döndürmez. `application/json` ```json { "$ref": "#/components/schemas/EdgeError" } ``` - `409`: Idempotency çakışması. `IDEMPOTENCY_IN_PROGRESS`: kısa bir süre sonra aynı anahtarla yeniden deneyin (takılı kalan bir talep 15 dk sonra serbest bırakılır). `IDEMPOTENCY_CONFLICT` ve `IDEMPOTENCY_REPLAY_EXPIRED`: yeni bir anahtar kullanın. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `410`: 410 ACCOUNT_DELETED. API anahtarı hâlâ kimlik doğrulamasından geçer, ancak hesabı silinmiştir. Silme kalıcıdır; bu nedenle bunu bildiren her yolda yanıt 410 Gone olur. Yeniden denenemez. İptal edilmiş bir anahtar bunun yerine 401 INVALID_API_KEY döndürür. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `413`: İstek çok büyük. Tekrarlanamaz: daha küçük bir istek gönderin. Yüklemeler doğrudan backend’e yönlenir. Dosya ve multipart gövde limitleri `details.limit_bytes` içeren JSON `413 PAYLOAD_TOO_LARGE` döndürür. Varsayılan limitler: kaynak veya taşıyıcı dosya 20 MB, yapılandırılmış veri parçaları toplamda 2 MB; multipart gövdenin tamamı belge yüklemeleri için 21 MB veya yapılandırılmış yüklemeler için 23 MB (1 MB ek alan dahil). `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` `text/plain` ```json { "type": "string" } ``` - `415`: `415 INVALID_UPLOAD`: `multipart/form-data` gönderin. Yeniden denenemez. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `422`: Yükleme veya istek seçeneği doğrulaması başarısız oldu. Yeniden denenemez: isteği düzeltin. Kodlar: `INVALID_FORMAT`, `INVALID_PROFILE`, `OUTPUT_PROFILE_CONFLICT`, `OUTPUT_PROFILE_REQUIRED`, `UPLOAD_FAILED` (geçersiz bağlam değeri), `ZUGFERD_SOURCE_PDF_REQUIRED`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `429`: `429 RATE_LIMITED`. Yeniden denenebilir: `Retry-After` saniye bekleyin ve aynı Idempotency-Key ile yeniden deneyin. Limitler API anahtarı ve uç nokta başına, sabit takvim dakikası ve takvim saati pencerelerinde uygulanır. Reddedilen istekler sayılmaz. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `500`: Sunucu tarafı hata. Bir 500 varsayılan olarak yeniden denenemez. `TASK_FAILED`: `details.code` değerini okuyun; yalnızca `details.retryable: true` yeniden denemeye izin verir ve yalnızca yeni bir Idempotency-Key ile YENİ bir dönüşüm olarak. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: destek ekibine iletin. Yüklemede `UPLOAD_FAILED`: aynı anahtarla yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `502`: `502 PROXY_ERROR`: edge katmanı backend’e ulaşamadı. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `503`: Geçici olarak kullanılamıyor. Aynı Idempotency-Key ile yeniden deneyin. `SERVER_BUSY`: işleme kuyruğu dolu; `Retry-After` saniye bekleyin. `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `API_CREDIT_SERVICE_UNAVAILABLE`, `UPLOAD_FAILED` (diğer kabul hataları): backoff ile yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `504`: `504 PROXY_ERROR`: backend zamanında yanıt vermedi. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` ### POST /invoices:convert-structured — Yapılandırılmış fatura verisini dönüştürün Sisteminizdeki fatura verilerini dönüştürün. `data_file` tek veri kaynağıdır; `pdf_file` yalnızca taşıyıcıdır (ZUGFeRD için içine gömülür, diğer durumlarda orijinal PDF olarak saklanır). - **Deterministik:** `StructuredInvoiceData` formatındaki tek bir JSON `data_file`, tutarlı kanonik JSON parçaları veya tek bir UBL 2.1 Invoice / CII D16B XML dosyası yapay zekâ olmadan eşlenir ([şema](https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json), [örnek](https://www.invoice-converter.com/developer-api/v1/invoice-data.example.json)). - **Yorumlanan:** CSV, XLSX, TXT, diğer XML, özel JSON ve karma formatlı parçalar yapay zekâ ile eşlenir; eksik alanlar boş bırakılır. - Bölünmüş dışa aktarımlar: `data_file` alanını tekrarlayın; tüm parçalarda aynı fatura numarası bulunmalıdır. `Invoice Number`, `Rechnungsnr`, `invoiceNumber` ve `Invoice_Number__c` gibi sütunlar tanınır; kanonik JSON `ID` kullanır. - Kanonik JSON: Bilinmeyen alanlar `details.unknown_paths` ile `400 INVALID_UPLOAD` döndürür; çelişen paket değerleri `details.reason=canonical_bundle_conflict` ve `details.path` döndürür. Satırlar her parçada benzersiz ve açık `InvoiceLine[].ID` değerlerine ihtiyaç duyar. - Limitler: `pdf_file` ≤ 20 MB, `data_file` parçaları toplamda ≤ 2 MB, multipart gövdenin tamamı ≤ 23 MB. Hız limiti: API anahtarı başına 30/dk ve 500/saat. - `format` ve `profile` kuralları `POST /invoices:convert` ile aynıdır. **Parametreler** | Ad | Konum | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | --- | | `Idempotency-Key` | header | string | evet | Her iki POST uç noktasında zorunludur. Her yeniden denemede aynı anahtarı aynı istek içeriğiyle yeniden kullanın; bir tekrar, ikinci bir ücretlendirme olmadan orijinal `202` yanıtını döndürür. Kapsam: kiracı + uç nokta, 24 saat saklanır. Eksik → `400 IDEMPOTENCY_KEY_REQUIRED`; hatalı biçim → `400 INVALID_IDEMPOTENCY_KEY`; aynı anahtar başka bir istek içeriğiyle → `409 IDEMPOTENCY_CONFLICT`. | | `X-Correlation-ID` | header | string (uuid) | | İzleme için isteğe bağlı UUID. Eksik veya UUID olmayan bir değer, sunucunun oluşturduğu bir UUID ile değiştirilir. `X-Correlation-ID` yanıt başlığında döndürülür; destek ekibine bu değeri belirtin. | **İstek gövdesi** (`multipart/form-data`) | Ad | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | | `pdf_file` | string (binary) | evet | Taşıyıcı PDF. `ZUGFERD` için doğrulanmış XML bu PDF’e gömülür; XML formatlarında PDF orijinal PDF olarak saklanır. Hiçbir zaman fatura verisi sağlamaz. | | `data_file` | oneOf(string (binary), array of string (binary)) | evet | Fatura verileri: `.json`, `.csv`, `.xml`, `.xlsx` veya `.txt` (toplam ≤ 2 MB). Kanonik JSON (en üst düzeyde veya `invoice_data` içine sarılmış), tutarlı kanonik JSON parçaları ve tek bir UBL 2.1 Invoice / CII D16B XML dosyası yapay zekâ olmadan eşlenir; diğer formatlar yapay zekâ ile eşlenir. Bilinmeyen kanonik alanlar ve çelişen paket verileri `400 INVALID_UPLOAD` döndürür. Birden fazla dosyaya bölünmüş tek bir fatura için parçayı tekrarlayın; tüm parçalarda aynı fatura numarası bulunmalı ve kanonik satırların benzersiz, açık ID değerleri olmalıdır. Şema: https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json. `data_files` ve `data_files[]` alan adları takma ad olarak kabul edilir. | | `format` | string: `XRECHNUNG`, `ZUGFERD`, `EN16931`, `UBL`, `CII` | evet | Hedef çıktı formatı. Zorunludur; varsayılan değer yoktur. Büyük/küçük harfe duyarsız eşleştirilir. Eksik → `400 FORMAT_REQUIRED`; bilinmeyen → `422 INVALID_FORMAT`. | | `profile` | string: `XRECHNUNG`, `PEPPOL`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | | Çıktı dosyasının doğrulandığı kural seti. İsteğe bağlı: her `format` için bir varsayılan vardır (bkz. işlem tablosu). Büyük/küçük harfe duyarsız eşleştirilir. Takma adlar: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Bu format için kabul edilmeyen profil → `422 OUTPUT_PROFILE_CONFLICT`; bilinmeyen ad → `422 INVALID_PROFILE`. | | `jurisdiction` | string | | İşlemin ISO 3166-1 alpha-2 ülke kodu, örneğin `DE`. İsteğe bağlı bağlam bilgisi. Geçersiz → `422 UPLOAD_FAILED`. | | `transaction_scope` | string: `B2B`, `B2G`, `B2C` | | İsteğe bağlı bağlam bilgisi. Geçersiz → `422 UPLOAD_FAILED`. | | `delivery_channel` | string: `PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN` | | İsteğe bağlı bağlam bilgisi: hibrit PDF teslimi için `EMAIL_PDF`, doğrudan XML entegrasyonu için `DIRECT_XML`, ağ üzerinden teslim için `PEPPOL`. Geçersiz → `422 UPLOAD_FAILED`. | | `client_reference` | string | | Fatura veya iş referansınız. 202 yanıtında ve görev durumunda aynen geri döndürülür. Kontrol karakteri içeremez. `external_invoice_id` takma ad olarak kabul edilir; ikisi birlikte gönderilirse eşleşmeleri gerekir, aksi takdirde `400 CLIENT_REFERENCE_CONFLICT`. | | `source_system` | string | | Çağıran ERP veya faturalama sisteminin etiketi. 202 yanıtında ve görev durumunda aynen geri döndürülür. | | `use_seller_master_data` | boolean | | Satıcı ana verilerini uygular. Gönderilmezse: hesabın varsayılanı uygulanır. `false`: bu istek için kayıtlı satıcı verilerini yok sayar. `true`: kayıtlı verileri ve `seller_master_data` değerini uygular. | | `seller_master_data` | string | | JSON nesnesi dizesi (şema: `SellerMasterData`). Yalnızca `use_seller_master_data=true` olduğunda uygulanır. Gönderilen her değer, çıkarılan satıcı veya ödeme değerinin yerine geçer; gönderilmeyen anahtarlar faturayı değiştirmez. Geçersiz → `400 INVALID_SELLER_MASTER_DATA`. | ```json { "$ref": "#/components/schemas/ConvertStructuredInvoiceRequest" } ``` **Yanıtlar** - `202`: Kabul edildi. `status_url` adresini sorgulayın. Aynı Idempotency-Key ve aynı istek içeriğiyle yapılan bir yeniden deneme, zaten kabul edilmiş olan görevi döndürür: aynı task_id ve aynı 202 gövdesi, Idempotency-Replayed: true başlığıyla. Bu, ilk yanıt kaybolduğunda veya görev kabul edildikten sonra bir 5xx olduğunda ve görev başarısız olduktan sonra da geçerlidir. Hiçbir zaman ikinci bir görev başlatmaz ve hiçbir zaman ikinci bir birim ayırmaz veya ücretlendirmez. `application/json` ```json { "$ref": "#/components/schemas/ConvertAcceptedResponse" } ``` - `400`: Geçersiz istek. Yeniden denenemez: isteği düzeltin. Tüm 400 kodları için bkz. `ErrorEnvelope.code`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `401`: Kimlik doğrulama başarısız oldu. Yeniden denenemez. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `402`: `402 INSUFFICIENT_API_CREDITS`. Yeniden denenemez: ön ödemeli bir kredi paketi satın alın veya bir sonraki aylık kotayı bekleyin. İki `details` yapısı vardır; mevcut olan anahtarları okuyun. `application/json` ```json { "oneOf": [ { "$ref": "#/components/schemas/InsufficientApiCreditsPrepaidError" }, { "$ref": "#/components/schemas/InsufficientApiCreditsAllowanceError" } ] } ``` - `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Yeniden denenemez: destek ekibiyle iletişime geçin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `405`: `405 METHOD_NOT_ALLOWED`: dönüştürme yolları POST kabul eder; OPTIONS 204 döndürür. Desteklenmeyen yöntemler için backend `correlation_id` içeren bir JSON hatası döndürür. HEAD gövde döndürmez. `application/json` ```json { "$ref": "#/components/schemas/EdgeError" } ``` - `409`: Idempotency çakışması. `IDEMPOTENCY_IN_PROGRESS`: kısa bir süre sonra aynı anahtarla yeniden deneyin (takılı kalan bir talep 15 dk sonra serbest bırakılır). `IDEMPOTENCY_CONFLICT` ve `IDEMPOTENCY_REPLAY_EXPIRED`: yeni bir anahtar kullanın. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `410`: 410 ACCOUNT_DELETED. API anahtarı hâlâ kimlik doğrulamasından geçer, ancak hesabı silinmiştir. Silme kalıcıdır; bu nedenle bunu bildiren her yolda yanıt 410 Gone olur. Yeniden denenemez. İptal edilmiş bir anahtar bunun yerine 401 INVALID_API_KEY döndürür. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `413`: İstek çok büyük. Tekrarlanamaz: daha küçük bir istek gönderin. Yüklemeler doğrudan backend’e yönlenir. Dosya ve multipart gövde limitleri `details.limit_bytes` içeren JSON `413 PAYLOAD_TOO_LARGE` döndürür. Varsayılan limitler: kaynak veya taşıyıcı dosya 20 MB, yapılandırılmış veri parçaları toplamda 2 MB; multipart gövdenin tamamı belge yüklemeleri için 21 MB veya yapılandırılmış yüklemeler için 23 MB (1 MB ek alan dahil). `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` `text/plain` ```json { "type": "string" } ``` - `415`: `415 INVALID_UPLOAD`: `multipart/form-data` gönderin. Yeniden denenemez. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `422`: Yükleme veya istek seçeneği doğrulaması başarısız oldu. Yeniden denenemez: isteği düzeltin. Kodlar: `INVALID_FORMAT`, `INVALID_PROFILE`, `OUTPUT_PROFILE_CONFLICT`, `OUTPUT_PROFILE_REQUIRED`, `UPLOAD_FAILED` (geçersiz bağlam değeri), `ZUGFERD_SOURCE_PDF_REQUIRED`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `429`: `429 RATE_LIMITED`. Yeniden denenebilir: `Retry-After` saniye bekleyin ve aynı Idempotency-Key ile yeniden deneyin. Limitler API anahtarı ve uç nokta başına, sabit takvim dakikası ve takvim saati pencerelerinde uygulanır. Reddedilen istekler sayılmaz. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `500`: Sunucu tarafı hata. Bir 500 varsayılan olarak yeniden denenemez. `TASK_FAILED`: `details.code` değerini okuyun; yalnızca `details.retryable: true` yeniden denemeye izin verir ve yalnızca yeni bir Idempotency-Key ile YENİ bir dönüşüm olarak. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: destek ekibine iletin. Yüklemede `UPLOAD_FAILED`: aynı anahtarla yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `502`: `502 PROXY_ERROR`: edge katmanı backend’e ulaşamadı. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `503`: Geçici olarak kullanılamıyor. Aynı Idempotency-Key ile yeniden deneyin. `SERVER_BUSY`: işleme kuyruğu dolu; `Retry-After` saniye bekleyin. `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `API_CREDIT_SERVICE_UNAVAILABLE`, `UPLOAD_FAILED` (diğer kabul hataları): backoff ile yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `504`: `504 PROXY_ERROR`: backend zamanında yanıt vermedi. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` ### GET /tasks/{task_id} — Görev durumunu alın Görev durumunu döndürür. `status` değeri `completed` veya `failed` olana kadar sorgulayın. - Backoff: ilk çağrı `202` yanıtından yaklaşık 20 sn sonra, ardından 20, 30, 45, 60 sn sonra, sonra her 60 sn’de bir. Yaklaşık 16 dk sonra durun. - `completed`: `primary_result_url` adresinden indirin. `failed`: türü belirli hata için `/result` çağrısını yapın. - Bilinmeyen görev veya tamamlanmadan bu yana 24 saatten fazla süre geçmiş: `404 TASK_NOT_FOUND`. - Hız limiti: API anahtarı başına 60/dk ve 1.500/saat. **Parametreler** | Ad | Konum | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | --- | | `task_id` | path | string (uuid) | evet | `202` yanıtındaki `task_id`. UUID değilse → `400 BAD_REQUEST`. | | `include_validation_report_html` | query | string: `true`, `false` | | `true`, temizlenmiş doğrulama raporu HTML’ini `validation_report_html` olarak ekler. `true`/`false` dışındaki değerler → `400 INVALID_QUERY_PARAMETER`. | | `X-Correlation-ID` | header | string (uuid) | | İzleme için isteğe bağlı UUID. Eksik veya UUID olmayan bir değer, sunucunun oluşturduğu bir UUID ile değiştirilir. `X-Correlation-ID` yanıt başlığında döndürülür; destek ekibine bu değeri belirtin. | **Yanıtlar** - `200`: Güncel görev durumu. `application/json` ```json { "$ref": "#/components/schemas/TaskStatusResponse" } ``` - `400`: Geçersiz istek. Yeniden denenemez: isteği düzeltin. Tüm 400 kodları için bkz. `ErrorEnvelope.code`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `401`: Kimlik doğrulama başarısız oldu. Yeniden denenemez. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Yeniden denenemez: destek ekibiyle iletişime geçin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `404`: `404 TASK_NOT_FOUND`: bilinmeyen görev, başka bir kiracının görevi veya tamamlandıktan 24 saat sonra silinmiş görev. Yeniden denenemez. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `405`: `405 METHOD_NOT_ALLOWED`: görev yolları yalnızca GET kabul eder. Edge proxy tarafından gönderilir; bu nedenle gövdede `correlation_id` yoktur. `application/json` ```json { "$ref": "#/components/schemas/EdgeError" } ``` - `410`: 410 ACCOUNT_DELETED. API anahtarı hâlâ kimlik doğrulamasından geçer, ancak hesabı silinmiştir. Silme kalıcıdır; bu nedenle bunu bildiren her yolda yanıt 410 Gone olur. Yeniden denenemez. İptal edilmiş bir anahtar bunun yerine 401 INVALID_API_KEY döndürür. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `429`: `429 RATE_LIMITED`. Yeniden denenebilir: `Retry-After` saniye bekleyin ve aynı Idempotency-Key ile yeniden deneyin. Limitler API anahtarı ve uç nokta başına, sabit takvim dakikası ve takvim saati pencerelerinde uygulanır. Reddedilen istekler sayılmaz. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `500`: Sunucu tarafı hata. Bir 500 varsayılan olarak yeniden denenemez. `TASK_FAILED`: `details.code` değerini okuyun; yalnızca `details.retryable: true` yeniden denemeye izin verir ve yalnızca yeni bir Idempotency-Key ile YENİ bir dönüşüm olarak. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: destek ekibine iletin. Yüklemede `UPLOAD_FAILED`: aynı anahtarla yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `502`: `502 PROXY_ERROR`: edge katmanı backend’e ulaşamadı. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `503`: Geçici olarak kullanılamıyor. Backoff ile yeniden deneyin: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `AUTHORITATIVE_VALIDATION_UNAVAILABLE`. Bunun yerine YENİ bir dönüşüm başlatın: `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `504`: `504 PROXY_ERROR`: backend zamanında yanıt vermedi. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` ### GET /tasks/{task_id}/result — Sonucu indirin Doğrulanmış çıktı dosyasını indirir. Yalnızca veri alır: bu çağrıda hiçbir şey oluşturulmaz, onarılmaz veya doğrulanmaz. - `download=xml`: UBL (`XRECHNUNG`, `EN16931`, `UBL`) veya CII (`CII`, `ZUGFERD`). XML formatlarında her zaman birincil çıktı dosyasıdır. - `download=pdf`: `ZUGFERD` için hibrit ZUGFeRD/Factur-X PDF; diğer formatlar için en iyi çaba ile oluşturulan bir görselleştirme. - İşlem sürerken: `202 TASK_NOT_READY`. Başarısız görev: türü belirli hatası (`422 VALIDATION_FAILED`, `500 TASK_FAILED`, `503 ...`). - Hız limiti: API anahtarı başına 60/dk ve 1.000/saat. **Parametreler** | Ad | Konum | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | --- | | `task_id` | path | string (uuid) | evet | `202` yanıtındaki `task_id`. UUID değilse → `400 BAD_REQUEST`. | | `download` | query | string: `xml`, `pdf` | evet | İndirilecek çıktı dosyası (büyük/küçük harfe duyarsız). Eksik → `400 DOWNLOAD_FORMAT_REQUIRED`; diğer değerler → `400 INVALID_DOWNLOAD_FORMAT`. | | `X-Correlation-ID` | header | string (uuid) | | İzleme için isteğe bağlı UUID. Eksik veya UUID olmayan bir değer, sunucunun oluşturduğu bir UUID ile değiştirilir. `X-Correlation-ID` yanıt başlığında döndürülür; destek ekibine bu değeri belirtin. | **Yanıtlar** - `200`: Çıktı dosyasının baytları. `X-*` başlıkları teslim edilen baytları tanımlar; bunları arşiviniz için kaydedin. `application/xml` ```json { "type": "string" } ``` `application/pdf` ```json { "type": "string", "format": "binary" } ``` - `202`: `202 TASK_NOT_READY`: işlem sürüyor. Gövde bir dosya değil, bir hata zarfıdır. Görev durumunu sorgulamaya devam edin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `400`: Geçersiz istek. Yeniden denenemez: isteği düzeltin. Tüm 400 kodları için bkz. `ErrorEnvelope.code`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `401`: Kimlik doğrulama başarısız oldu. Yeniden denenemez. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Yeniden denenemez: destek ekibiyle iletişime geçin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `404`: `404 TASK_NOT_FOUND`: bilinmeyen görev, başka bir kiracının görevi veya tamamlandıktan 24 saat sonra silinmiş görev. `404 TASK_RESULT_FAILED`: görev mevcut ancak sonuç verileri kullanılamıyor; korelasyon kimliğiyle destek ekibine iletin. Yeniden denenemez. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `405`: `405 METHOD_NOT_ALLOWED`: görev yolları yalnızca GET kabul eder. Edge proxy tarafından gönderilir; bu nedenle gövdede `correlation_id` yoktur. `application/json` ```json { "$ref": "#/components/schemas/EdgeError" } ``` - `410`: 410 ACCOUNT_DELETED. API anahtarı hâlâ kimlik doğrulamasından geçer, ancak hesabı silinmiştir. Silme kalıcıdır; bu nedenle bunu bildiren her yolda yanıt 410 Gone olur. Yeniden denenemez. İptal edilmiş bir anahtar bunun yerine 401 INVALID_API_KEY döndürür. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `422`: Fatura düzenlenemez. Yeniden denenemez: verileri düzeltin ve yeni bir dönüşüm başlatın. Kodlar: `VALIDATION_FAILED` (`details.items`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `429`: `429 RATE_LIMITED`. Yeniden denenebilir: `Retry-After` saniye bekleyin ve aynı Idempotency-Key ile yeniden deneyin. Limitler API anahtarı ve uç nokta başına, sabit takvim dakikası ve takvim saati pencerelerinde uygulanır. Reddedilen istekler sayılmaz. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `500`: Sunucu tarafı hata. Bir 500 varsayılan olarak yeniden denenemez. `TASK_FAILED`: `details.code` değerini okuyun; yalnızca `details.retryable: true` yeniden denemeye izin verir ve yalnızca yeni bir Idempotency-Key ile YENİ bir dönüşüm olarak. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: destek ekibine iletin. Yüklemede `UPLOAD_FAILED`: aynı anahtarla yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `502`: `502 PROXY_ERROR`: edge katmanı backend’e ulaşamadı. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `503`: Geçici olarak kullanılamıyor. Backoff ile yeniden deneyin: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `AUTHORITATIVE_VALIDATION_UNAVAILABLE`. Bunun yerine YENİ bir dönüşüm başlatın: `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `504`: `504 PROXY_ERROR`: backend zamanında yanıt vermedi. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` ### GET /tasks/{task_id}/validation-report — Doğrulama raporunu indirin Teslim edilen çıktı dosyasına bağlı doğrulama raporunu indirir. - İnsanlar için `download=html`; KoSIT raporu veya Factur-X `validation-evidence` XML’i (`source="facturx_php"`, KoSIT formatında değil) için `download=xml`. - `X-Artifact-*` başlıkları rapor baytlarını değil, doğrulanmış sonuç dosyasını tanımlar. - Factur-X kanıtı yalnızca saklanan XML’in doğrulamasını kanıtlar; kaynağa sadakati veya PDF/A uyumluluğunu kanıtlamaz. - Hız limiti: API anahtarı başına 30/dk ve 500/saat. **Parametreler** | Ad | Konum | Tür | Zorunlu | Açıklama | | --- | --- | --- | --- | --- | | `task_id` | path | string (uuid) | evet | `202` yanıtındaki `task_id`. UUID değilse → `400 BAD_REQUEST`. | | `download` | query | string: `html`, `xml` | evet | Okunabilir bir rapor için `html`, makine tarafından okunabilir rapor için `xml`. Eksik → `400 DOWNLOAD_FORMAT_REQUIRED`; diğer değerler → `400 INVALID_DOWNLOAD_FORMAT`. | | `X-Correlation-ID` | header | string (uuid) | | İzleme için isteğe bağlı UUID. Eksik veya UUID olmayan bir değer, sunucunun oluşturduğu bir UUID ile değiştirilir. `X-Correlation-ID` yanıt başlığında döndürülür; destek ekibine bu değeri belirtin. | **Yanıtlar** - `200`: Rapor. `text/html` ```json { "type": "string" } ``` `application/xml` ```json { "type": "string" } ``` - `202`: `202 TASK_NOT_READY`: işlem sürüyor. Gövde bir dosya değil, bir hata zarfıdır. Görev durumunu sorgulamaya devam edin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `400`: Geçersiz istek. Yeniden denenemez: isteği düzeltin. Tüm 400 kodları için bkz. `ErrorEnvelope.code`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `401`: Kimlik doğrulama başarısız oldu. Yeniden denenemez. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Yeniden denenemez: destek ekibiyle iletişime geçin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `404`: `404 TASK_NOT_FOUND` (bilinmeyen veya süresi dolmuş görev) veya `404 VALIDATION_REPORT_NOT_FOUND` (güncel çıktı dosyasına bağlı rapor yok; `details.reason`). Yeniden denenemez. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `405`: `405 METHOD_NOT_ALLOWED`: görev yolları yalnızca GET kabul eder. Edge proxy tarafından gönderilir; bu nedenle gövdede `correlation_id` yoktur. `application/json` ```json { "$ref": "#/components/schemas/EdgeError" } ``` - `410`: 410 ACCOUNT_DELETED. API anahtarı hâlâ kimlik doğrulamasından geçer, ancak hesabı silinmiştir. Silme kalıcıdır; bu nedenle bunu bildiren her yolda yanıt 410 Gone olur. Yeniden denenemez. İptal edilmiş bir anahtar bunun yerine 401 INVALID_API_KEY döndürür. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `422`: Fatura düzenlenemez. Yeniden denenemez: verileri düzeltin ve yeni bir dönüşüm başlatın. Kodlar: `VALIDATION_FAILED` (`details.items`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `429`: `429 RATE_LIMITED`. Yeniden denenebilir: `Retry-After` saniye bekleyin ve aynı Idempotency-Key ile yeniden deneyin. Limitler API anahtarı ve uç nokta başına, sabit takvim dakikası ve takvim saati pencerelerinde uygulanır. Reddedilen istekler sayılmaz. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `500`: Sunucu tarafı hata. Bir 500 varsayılan olarak yeniden denenemez. `TASK_FAILED`: `details.code` değerini okuyun; yalnızca `details.retryable: true` yeniden denemeye izin verir ve yalnızca yeni bir Idempotency-Key ile YENİ bir dönüşüm olarak. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: destek ekibine iletin. Yüklemede `UPLOAD_FAILED`: aynı anahtarla yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `502`: `502 PROXY_ERROR`: edge katmanı backend’e ulaşamadı. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `503`: Geçici olarak kullanılamıyor. Backoff ile yeniden deneyin: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `AUTHORITATIVE_VALIDATION_UNAVAILABLE`. Bunun yerine YENİ bir dönüşüm başlatın: `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `504`: `504 PROXY_ERROR`: backend zamanında yanıt vermedi. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` ## Şemalar ### `ConvertInvoiceRequest` ```json { "type": "object", "required": [ "file", "format" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Fatura belgesi: `.pdf`, `.docx` veya `.txt`, dosya başına bir fatura. `.doc`, `.rtf` ve görseller reddedilir (`400 INVALID_UPLOAD`). `format=ZUGFERD` bir PDF gerektirir (`422 ZUGFERD_SOURCE_PDF_REQUIRED`)." }, "format": { "type": "string", "enum": [ "XRECHNUNG", "ZUGFERD", "EN16931", "UBL", "CII" ], "description": "Hedef çıktı formatı. Zorunludur; varsayılan değer yoktur. Büyük/küçük harfe duyarsız eşleştirilir. Eksik → `400 FORMAT_REQUIRED`; bilinmeyen → `422 INVALID_FORMAT`.", "examples": [ "XRECHNUNG" ] }, "profile": { "type": "string", "enum": [ "XRECHNUNG", "PEPPOL", "EN16931", "ZUGFERD_EN16931", "ZUGFERD_FACTURX_EXTENDED", "ZUGFERD_XRECHNUNG" ], "description": "Çıktı dosyasının doğrulandığı kural seti. İsteğe bağlı: her `format` için bir varsayılan vardır (bkz. işlem tablosu). Büyük/küçük harfe duyarsız eşleştirilir. Takma adlar: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Bu format için kabul edilmeyen profil → `422 OUTPUT_PROFILE_CONFLICT`; bilinmeyen ad → `422 INVALID_PROFILE`.", "examples": [ "XRECHNUNG" ] }, "jurisdiction": { "type": "string", "description": "İşlemin ISO 3166-1 alpha-2 ülke kodu, örneğin `DE`. İsteğe bağlı bağlam bilgisi. Geçersiz → `422 UPLOAD_FAILED`.", "examples": [ "DE" ] }, "transaction_scope": { "type": "string", "enum": [ "B2B", "B2G", "B2C" ], "description": "İsteğe bağlı bağlam bilgisi. Geçersiz → `422 UPLOAD_FAILED`." }, "delivery_channel": { "type": "string", "enum": [ "PEPPOL", "DIRECT_XML", "PORTAL", "EMAIL_PDF", "UNKNOWN" ], "description": "İsteğe bağlı bağlam bilgisi: hibrit PDF teslimi için `EMAIL_PDF`, doğrudan XML entegrasyonu için `DIRECT_XML`, ağ üzerinden teslim için `PEPPOL`. Geçersiz → `422 UPLOAD_FAILED`." }, "client_reference": { "type": "string", "maxLength": 200, "description": "Fatura veya iş referansınız. 202 yanıtında ve görev durumunda aynen geri döndürülür. Kontrol karakteri içeremez. `external_invoice_id` takma ad olarak kabul edilir; ikisi birlikte gönderilirse eşleşmeleri gerekir, aksi takdirde `400 CLIENT_REFERENCE_CONFLICT`.", "examples": [ "ERP-2026-0001" ] }, "source_system": { "type": "string", "maxLength": 100, "description": "Çağıran ERP veya faturalama sisteminin etiketi. 202 yanıtında ve görev durumunda aynen geri döndürülür.", "examples": [ "salesforce" ] }, "use_embedded_xml": { "type": "boolean", "default": false, "description": "PDF’e gömülü Factur-X/ZUGFeRD/XRechnung XML’ini veri çıkarımı kaynağı olarak kullanır. Varsayılan `false`: gömülü XML yok sayılır ve görünür belge okunur." }, "email_input": { "type": "string", "maxLength": 10000, "description": "Veri çıkarımı için herhangi bir dilde serbest metin talimatlar (yalnızca PDF kaynağı). `use_embedded_xml=true` ile birlikte kullanılamaz. Idempotency kimliğinin bir parçasıdır. Geçersiz → `400 INVALID_EMAIL_INPUT`.", "examples": [ "Use purchase order number PO-42." ] }, "use_seller_master_data": { "type": "boolean", "description": "Satıcı ana verilerini uygular. Gönderilmezse: hesabın varsayılanı uygulanır. `false`: bu istek için kayıtlı satıcı verilerini yok sayar. `true`: kayıtlı verileri ve `seller_master_data` değerini uygular." }, "seller_master_data": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/SellerMasterData" }, "description": "JSON nesnesi dizesi (şema: `SellerMasterData`). Yalnızca `use_seller_master_data=true` olduğunda uygulanır. Gönderilen her değer, çıkarılan satıcı veya ödeme değerinin yerine geçer; gönderilmeyen anahtarlar faturayı değiştirmez. Geçersiz → `400 INVALID_SELLER_MASTER_DATA`.", "examples": [ "{\"business_name\":\"Seller GmbH\",\"vat_id\":\"DE123456789\",\"city\":\"Berlin\",\"country\":\"DE\"}" ] } }, "additionalProperties": false } ``` ### `ConvertStructuredInvoiceRequest` ```json { "type": "object", "required": [ "pdf_file", "data_file", "format" ], "properties": { "pdf_file": { "type": "string", "format": "binary", "description": "Taşıyıcı PDF. `ZUGFERD` için doğrulanmış XML bu PDF’e gömülür; XML formatlarında PDF orijinal PDF olarak saklanır. Hiçbir zaman fatura verisi sağlamaz." }, "data_file": { "oneOf": [ { "type": "string", "format": "binary" }, { "type": "array", "minItems": 1, "items": { "type": "string", "format": "binary" } } ], "description": "Fatura verileri: `.json`, `.csv`, `.xml`, `.xlsx` veya `.txt` (toplam ≤ 2 MB). Kanonik JSON (en üst düzeyde veya `invoice_data` içine sarılmış), tutarlı kanonik JSON parçaları ve tek bir UBL 2.1 Invoice / CII D16B XML dosyası yapay zekâ olmadan eşlenir; diğer formatlar yapay zekâ ile eşlenir. Bilinmeyen kanonik alanlar ve çelişen paket verileri `400 INVALID_UPLOAD` döndürür. Birden fazla dosyaya bölünmüş tek bir fatura için parçayı tekrarlayın; tüm parçalarda aynı fatura numarası bulunmalı ve kanonik satırların benzersiz, açık ID değerleri olmalıdır. Şema: https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json. `data_files` ve `data_files[]` alan adları takma ad olarak kabul edilir." }, "format": { "type": "string", "enum": [ "XRECHNUNG", "ZUGFERD", "EN16931", "UBL", "CII" ], "description": "Hedef çıktı formatı. Zorunludur; varsayılan değer yoktur. Büyük/küçük harfe duyarsız eşleştirilir. Eksik → `400 FORMAT_REQUIRED`; bilinmeyen → `422 INVALID_FORMAT`.", "examples": [ "XRECHNUNG" ] }, "profile": { "type": "string", "enum": [ "XRECHNUNG", "PEPPOL", "EN16931", "ZUGFERD_EN16931", "ZUGFERD_FACTURX_EXTENDED", "ZUGFERD_XRECHNUNG" ], "description": "Çıktı dosyasının doğrulandığı kural seti. İsteğe bağlı: her `format` için bir varsayılan vardır (bkz. işlem tablosu). Büyük/küçük harfe duyarsız eşleştirilir. Takma adlar: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Bu format için kabul edilmeyen profil → `422 OUTPUT_PROFILE_CONFLICT`; bilinmeyen ad → `422 INVALID_PROFILE`.", "examples": [ "XRECHNUNG" ] }, "jurisdiction": { "type": "string", "description": "İşlemin ISO 3166-1 alpha-2 ülke kodu, örneğin `DE`. İsteğe bağlı bağlam bilgisi. Geçersiz → `422 UPLOAD_FAILED`.", "examples": [ "DE" ] }, "transaction_scope": { "type": "string", "enum": [ "B2B", "B2G", "B2C" ], "description": "İsteğe bağlı bağlam bilgisi. Geçersiz → `422 UPLOAD_FAILED`." }, "delivery_channel": { "type": "string", "enum": [ "PEPPOL", "DIRECT_XML", "PORTAL", "EMAIL_PDF", "UNKNOWN" ], "description": "İsteğe bağlı bağlam bilgisi: hibrit PDF teslimi için `EMAIL_PDF`, doğrudan XML entegrasyonu için `DIRECT_XML`, ağ üzerinden teslim için `PEPPOL`. Geçersiz → `422 UPLOAD_FAILED`." }, "client_reference": { "type": "string", "maxLength": 200, "description": "Fatura veya iş referansınız. 202 yanıtında ve görev durumunda aynen geri döndürülür. Kontrol karakteri içeremez. `external_invoice_id` takma ad olarak kabul edilir; ikisi birlikte gönderilirse eşleşmeleri gerekir, aksi takdirde `400 CLIENT_REFERENCE_CONFLICT`.", "examples": [ "ERP-2026-0001" ] }, "source_system": { "type": "string", "maxLength": 100, "description": "Çağıran ERP veya faturalama sisteminin etiketi. 202 yanıtında ve görev durumunda aynen geri döndürülür.", "examples": [ "salesforce" ] }, "use_seller_master_data": { "type": "boolean", "description": "Satıcı ana verilerini uygular. Gönderilmezse: hesabın varsayılanı uygulanır. `false`: bu istek için kayıtlı satıcı verilerini yok sayar. `true`: kayıtlı verileri ve `seller_master_data` değerini uygular." }, "seller_master_data": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/SellerMasterData" }, "description": "JSON nesnesi dizesi (şema: `SellerMasterData`). Yalnızca `use_seller_master_data=true` olduğunda uygulanır. Gönderilen her değer, çıkarılan satıcı veya ödeme değerinin yerine geçer; gönderilmeyen anahtarlar faturayı değiştirmez. Geçersiz → `400 INVALID_SELLER_MASTER_DATA`.", "examples": [ "{\"business_name\":\"Seller GmbH\",\"vat_id\":\"DE123456789\",\"city\":\"Berlin\",\"country\":\"DE\"}" ] } }, "additionalProperties": false } ``` ### `StructuredInvoiceData` ```json { "additionalProperties": false, "properties": { "CustomizationID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Customizationid" }, "ProfileID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Profileid" }, "ID": { "title": "Id", "type": "string" }, "IssueDate": { "title": "Issuedate", "type": "string" }, "DueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Duedate" }, "TaxCurrencyCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxcurrencycode" }, "TaxPointDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxpointdate" }, "InvoicePeriod": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_InvoicePeriod" }, { "type": "null" } ], "default": null }, "InvoiceTypeCode": { "title": "Invoicetypecode", "type": "string" }, "DocumentCurrencyCode": { "title": "Documentcurrencycode", "type": "string" }, "OrderReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_OrderReference" }, { "type": "null" } ], "default": null }, "SalesOrderReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_SalesOrderReference" }, { "type": "null" } ], "default": null }, "ContractDocumentReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_ContractDocumentReference" }, { "type": "null" } ], "default": null }, "ProjectReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_ProjectReference" }, { "type": "null" } ], "default": null }, "TenderOrLotReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_TenderOrLotReference" }, { "type": "null" } ], "default": null }, "DespatchDocumentReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DespatchDocumentReference" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_DespatchDocumentReference" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Despatchdocumentreference" }, "PrecedingInvoiceReference": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_PrecedingInvoiceReference" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Precedinginvoicereference" }, "AdditionalDocumentReference": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_AdditionalDocumentReference" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Additionaldocumentreference" }, "AllowanceCharge": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowancecharge" }, "AccountingSupplierParty": { "$ref": "#/components/schemas/StructuredInvoice_AccountingSupplierParty" }, "AccountingCustomerParty": { "$ref": "#/components/schemas/StructuredInvoice_AccountingCustomerParty" }, "PayeeParty": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PayeeParty" }, { "type": "null" } ], "default": null }, "TaxRepresentativeParty": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_TaxRepresentativeParty" }, { "type": "null" } ], "default": null }, "Delivery": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Delivery" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_Delivery" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Delivery" }, "DeliveryTerms": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DeliveryTerms" }, { "type": "null" } ], "default": null }, "PaymentMeans": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PaymentMeans" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_PaymentMeans" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Paymentmeans" }, "PaymentTerms": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PaymentTerms" }, { "type": "null" } ], "default": null }, "TaxTotal": { "$ref": "#/components/schemas/StructuredInvoice_TaxTotal" }, "LegalMonetaryTotal": { "$ref": "#/components/schemas/StructuredInvoice_LegalMonetaryTotal" }, "InvoiceLine": { "items": { "$ref": "#/components/schemas/StructuredInvoice_InvoiceLine" }, "title": "Invoiceline", "type": "array" }, "Note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "BuyerReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Buyerreference" }, "BuyerAccountingReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Buyeraccountingreference" } }, "required": [ "ID", "IssueDate", "InvoiceTypeCode", "DocumentCurrencyCode", "AccountingSupplierParty", "AccountingCustomerParty", "TaxTotal", "LegalMonetaryTotal", "InvoiceLine" ], "title": "Invoice Converter structured invoice JSON", "type": "object", "description": "POST /api/v1/invoices:convert-structured için kanonik fatura JSON’u. Öğe adları UBL 2.1 / EN 16931’e uyar. Bir faturayı tek bir JSON data_file olarak, en üst düzeyde veya bir 'invoice_data' nesnesi içine sarılmış şekilde gönderin; bu format yapay zekâ yorumu olmadan eşlenir. Algılama için ID, IssueDate, InvoiceTypeCode, DocumentCurrencyCode, AccountingSupplierParty, AccountingCustomerParty, TaxTotal, LegalMonetaryTotal, InvoiceLine üst düzey anahtarlarından en az 3’ü gerekir; bunlardan biri ID, InvoiceLine veya LegalMonetaryTotal olmalıdır. İndirilebilir: https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json", "examples": [ { "ID": "RE-2026-00123", "IssueDate": "2026-09-30", "DueDate": "2026-10-30", "InvoiceTypeCode": "380", "DocumentCurrencyCode": "EUR", "BuyerReference": "04011000-1234512345-06", "OrderReference": { "ID": "PO-4711" }, "InvoicePeriod": { "StartDate": "2026-09-01", "EndDate": "2026-09-30" }, "Note": "Monthly subscription September 2026", "AccountingSupplierParty": { "Party": { "EndpointID": { "#text": "billing@seller.example", "@schemeID": "EM" }, "PartyName": { "Name": "Seller GmbH" }, "PostalAddress": { "StreetName": "Hauptstraße 1", "CityName": "Berlin", "PostalZone": "10115", "Country": { "IdentificationCode": "DE" } }, "PartyTaxScheme": { "CompanyID": "DE123456789", "TaxScheme": { "ID": "VAT" } }, "PartyLegalEntity": { "RegistrationName": "Seller GmbH", "CompanyID": "HRB 12345" }, "Contact": { "Name": "Erika Muster", "Telephone": "+49 30 123456", "ElectronicMail": "erika@seller.example" } } }, "AccountingCustomerParty": { "Party": { "EndpointID": { "#text": "04011000-1234512345-06", "@schemeID": "0204" }, "PartyName": { "Name": "Buyer AG" }, "PostalAddress": { "StreetName": "Marktplatz 5", "CityName": "München", "PostalZone": "80331", "Country": { "IdentificationCode": "DE" } }, "PartyTaxScheme": { "CompanyID": "DE987654321", "TaxScheme": { "ID": "VAT" } }, "PartyLegalEntity": { "RegistrationName": "Buyer AG" } } }, "Delivery": { "ActualDeliveryDate": "2026-09-30", "DeliveryLocation": { "Address": { "StreetName": "Marktplatz 5", "CityName": "München", "PostalZone": "80331", "Country": { "IdentificationCode": "DE" } } } }, "PaymentMeans": { "PaymentMeansCode": "58", "PaymentID": "RE-2026-00123", "PayeeFinancialAccount": { "ID": "DE02120300000000202051", "Name": "Seller GmbH", "FinancialInstitutionBranch": { "ID": "BYLADEM1001" } } }, "PaymentTerms": { "Note": "Zahlbar innerhalb von 30 Tagen ohne Abzug", "NetDays": 30 }, "TaxTotal": { "TaxAmount": "285.00", "TaxSubtotal": [ { "TaxableAmount": "1500.00", "TaxAmount": "285.00", "TaxCategory": { "ID": "S", "Percent": 19, "TaxScheme": { "ID": "VAT" } } } ] }, "LegalMonetaryTotal": { "LineExtensionAmount": "1500.00", "TaxExclusiveAmount": "1500.00", "TaxInclusiveAmount": "1785.00", "PayableAmount": "1785.00" }, "InvoiceLine": [ { "ID": "1", "InvoicedQuantity": 10, "unitCode": "HUR", "LineExtensionAmount": "1200.00", "Item": { "Name": "Consulting", "SellersItemIdentification": { "ID": "SRV-01" }, "ClassifiedTaxCategory": { "ID": "S", "Percent": 19, "TaxScheme": { "ID": "VAT" } } }, "Price": { "PriceAmount": "120.00" } }, { "ID": "2", "InvoicedQuantity": 2, "unitCode": "C62", "LineExtensionAmount": "300.00", "Item": { "Name": "Software licence", "ClassifiedTaxCategory": { "ID": "S", "Percent": 19, "TaxScheme": { "ID": "VAT" } } }, "Price": { "PriceAmount": "150.00" } } ] } ] } ``` ### `SellerMasterData` ```json { "type": "object", "description": "`seller_master_data` JSON dize form alanı olarak gönderilen satıcı varsayılanları. Her anahtar isteğe bağlıdır. `electronic_address` ve `electronic_address_scheme` bir çifttir: ikisini birlikte gönderin veya hiçbirini göndermeyin.", "properties": { "business_name": { "type": "string", "maxLength": 240, "description": "Yasal ad (BT-27)." }, "trading_name": { "type": "string", "maxLength": 240, "description": "Ticari ad (BT-28)." }, "street": { "type": "string", "description": "Sokak ve numara (BT-35)." }, "additional_address": { "type": "string", "description": "Ek adres satırı (BT-36)." }, "postal_code": { "type": "string", "description": "Posta kodu (BT-38)." }, "city": { "type": "string", "description": "Şehir (BT-37)." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 ülke kodu (BT-40).", "examples": [ "DE" ] }, "vat_id": { "type": "string", "description": "KDV kimlik numarası (BT-31).", "examples": [ "DE123456789" ] }, "tax_number": { "type": "string", "description": "Vergi numarası (BT-32)." }, "electronic_address": { "type": "string", "description": "Elektronik adres (BT-34). `electronic_address_scheme` gerektirir." }, "electronic_address_scheme": { "type": "string", "description": "Elektronik adresin EAS şeması, örneğin `EM` veya `0204`." }, "contact_name": { "type": "string", "description": "İrtibat kişisi (BT-41)." }, "contact_email": { "type": "string", "description": "İrtibat e-postası (BT-43)." }, "contact_phone": { "type": "string", "description": "İrtibat telefonu (BT-42)." }, "payment_means_code": { "type": "string", "enum": [ "30", "42", "58" ], "description": "Kredi transferi için ödeme yöntemi kodu (BT-81): 30 kredi transferi, 42 banka hesabına ödeme, 58 SEPA kredi transferi." }, "payment_iban": { "type": "string", "description": "Alacaklı hesabının IBAN’ı (BT-84)." }, "payment_bic": { "type": "string", "description": "Alacaklı bankasının BIC’i (BT-86)." }, "payment_account_name": { "type": "string", "description": "Alacaklı hesabının adı (BT-85)." }, "payment_terms_note": { "type": "string", "description": "Ödeme koşulları metni (BT-20)." } }, "additionalProperties": false, "examples": [ { "business_name": "Seller GmbH", "street": "Hauptstraße 1", "postal_code": "10115", "city": "Berlin", "country": "DE", "vat_id": "DE123456789", "electronic_address": "billing@seller.example", "electronic_address_scheme": "EM", "contact_name": "Erika Muster", "contact_email": "erika@seller.example", "contact_phone": "+49 30 123456", "payment_means_code": "58", "payment_iban": "DE02120300000000202051" } ] } ``` ### `ConvertAcceptedResponse` ```json { "type": "object", "required": [ "task_id", "status", "correlation_id" ], "properties": { "task_id": { "type": "string", "format": "uuid", "description": "Tüm görev çağrılarında bunu kullanın." }, "status": { "type": "string", "enum": [ "pending", "processing" ], "description": "`pending`: kuyrukta. `processing`: başladı." }, "message": { "type": "string", "description": "İnsanlar için okunabilir onay. Mantığınızı buna göre kurmayın." }, "filename": { "type": [ "string", "null" ], "description": "Yüklenen belgenin (veya taşıyıcı PDF’in) dosya adı." }, "pdf_filename": { "type": [ "string", "null" ], "description": "Taşıyıcı PDF’in dosya adı (yapılandırılmış uç nokta)." }, "data_filename": { "type": [ "string", "null" ], "description": "İlk veri dosyasının adı (yapılandırılmış uç nokta)." }, "data_filenames": { "type": "array", "items": { "type": "string" }, "description": "Tüm veri dosyalarının adları (yapılandırılmış uç nokta)." }, "data_file_count": { "type": "integer", "minimum": 1, "description": "Veri dosyalarının sayısı (yapılandırılmış uç nokta)." }, "file_size": { "type": "integer", "minimum": 0, "description": "Kabul edilen toplam bayt." }, "pdf_file_size": { "type": "integer", "minimum": 0, "description": "Taşıyıcı PDF’in baytları (yapılandırılmış uç nokta)." }, "data_file_size": { "type": "integer", "minimum": 0, "description": "Veri dosyalarının toplam baytı (yapılandırılmış uç nokta)." }, "correlation_id": { "type": "string", "format": "uuid" }, "status_url": { "type": "string", "description": "Sorgulanacak göreli URL." }, "primary_result_format": { "type": "string", "enum": [ "xml", "pdf" ], "description": "İstenen format için olağan indirme: ZUGFERD için `pdf`, diğerleri için `xml`." }, "primary_result_url": { "type": "string", "description": "`download=` içeren göreli sonuç URL’si." }, "client_reference": { "type": "string", "description": "`client_reference` değerinin aynen geri dönüşü." }, "source_system": { "type": "string", "description": "`source_system` değerinin aynen geri dönüşü." } }, "additionalProperties": false } ``` ### `TaskStatusResponse` ```json { "type": "object", "required": [ "task_id", "status", "correlation_id" ], "properties": { "task_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "`pending`: kuyrukta. `processing`: çalışıyor. `completed`: doğrulanmış bir çıktı dosyası var. `failed`: son durum, çıktı dosyası yok." }, "progress": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100, "description": "Yüzde olarak yaklaşık ilerleme. Zamanlama için kullanmayın." }, "created_at": { "type": "string", "format": "date-time", "description": "Görevin kabul edildiği zaman (UTC)." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Görevin `completed` veya `failed` durumuna ulaştığı zaman (UTC)." }, "filename": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "object", "null" ], "additionalProperties": true, "description": "`status=failed` olduğunda hata özeti: bir mesaj veya `code`, `message`, `retryable` içeren bir nesne. Bilgi amaçlıdır; türü belirli hata zarfını `/result` döndürür." }, "correlation_id": { "type": "string", "format": "uuid", "description": "Bu durum çağrısının izleme kimliği." }, "client_reference": { "type": [ "string", "null" ], "description": "`client_reference` değerinin aynen geri dönüşü." }, "source_system": { "type": [ "string", "null" ], "description": "`source_system` değerinin aynen geri dönüşü." }, "primary_result_format": { "type": "string", "enum": [ "xml", "pdf" ], "description": "İstenen format için olağan indirme." }, "primary_result_url": { "type": "string", "description": "Göreli sonuç URL’si." }, "result_artifacts": { "$ref": "#/components/schemas/ResultArtifacts" }, "validation_report_html": { "$ref": "#/components/schemas/ValidationReportHtmlStatus" } }, "additionalProperties": false } ``` ### `ResultArtifacts` ```json { "type": "object", "description": "Çıktı dosyası başına indirmeye hazır olma durumu.", "properties": { "xml": { "$ref": "#/components/schemas/ResultArtifactStatus" }, "pdf": { "$ref": "#/components/schemas/ResultArtifactStatus" } }, "additionalProperties": false } ``` ### `ResultArtifactStatus` ```json { "type": "object", "required": [ "state", "download_url" ], "properties": { "state": { "type": "string", "enum": [ "cached", "not_ready", "validation_failed", "dependency_failed", "artifact_generation_rerun_required", "artifact_invariant_failed" ], "description": "`cached`: indirilebilir. `not_ready`: henüz oluşturulmadı. `validation_failed`: engelleyici veri veya kaynak PDF sorunu. `dependency_failed`: doğrulayıcı/depolama kesintisi. `artifact_generation_rerun_required`: yeni bir dönüşüm başlatın. `artifact_invariant_failed`: korelasyon kimliğiyle destek ekibine iletin." }, "download_url": { "type": "string", "description": "Göreli indirme URL’si." }, "content_type": { "type": "string" }, "filename": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0 }, "artifact_state": { "type": "string", "enum": [ "compliant", "warning_only", "cannot_guarantee", "blocked" ], "description": "Uyumluluk durumu. Teslim edilen her API çıktı dosyasında `compliant`." }, "validation_state": { "type": "string", "enum": [ "passed", "failed_overridable", "failed_blocking", "not_validated" ], "description": "Doğrulama sonucu. Teslim edilen her API çıktı dosyasında `passed`." } }, "additionalProperties": false } ``` ### `ValidationReportHtmlStatus` ```json { "type": "object", "description": "Yalnızca `include_validation_report_html=true` ile mevcuttur.", "required": [ "available" ], "properties": { "available": { "type": "boolean" }, "content_type": { "type": "string", "enum": [ "text/html; charset=utf-8" ] }, "html": { "type": "string", "description": "Temizlenmiş rapor HTML’i; sunucu yolları gizlenmiştir." }, "source": { "type": "string", "description": "Örneğin `artifact`, `embedded_xml` veya `source_xml`." }, "source_result_format": { "type": "string", "enum": [ "xml", "pdf" ] }, "reason": { "type": "string", "description": "Neden rapor bulunmadığı, örneğin `task_not_completed`, `proof_not_found`, `artifact_not_current`." } }, "additionalProperties": false } ``` ### `ErrorEnvelope` ```json { "type": "object", "description": "Her JSON hatası. Mantığınızı `code` değerine göre kurun; `500 TASK_FAILED` için ayrıca `details.code` ve `details.retryable` değerlerine göre. Bir yazma isteğini yalnızca aynı Idempotency-Key ile yeniden deneyin.", "required": [ "code", "message", "correlation_id" ], "properties": { "code": { "type": "string", "enum": [ "AUTHENTICATION_REQUIRED", "INVALID_API_KEY", "API_NOT_ENABLED_FOR_TENANT", "ACCOUNT_DELETED", "INSUFFICIENT_API_CREDITS", "AUTH_SERVICE_UNAVAILABLE", "PLAN_TIER_CHECK_FAILED", "RATE_LIMIT_SERVICE_UNAVAILABLE", "API_CREDIT_SERVICE_UNAVAILABLE", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_CONFLICT", "IDEMPOTENCY_REPLAY_EXPIRED", "FORMAT_REQUIRED", "INVALID_FORMAT", "INVALID_PROFILE", "OUTPUT_PROFILE_CONFLICT", "OUTPUT_PROFILE_REQUIRED", "CLIENT_REFERENCE_CONFLICT", "INVALID_CLIENT_METADATA", "INVALID_SELLER_MASTER_DATA", "INVALID_EMBEDDED_XML_POLICY", "INVALID_EMAIL_INPUT", "INVALID_UPLOAD", "PAYLOAD_TOO_LARGE", "UPLOAD_FAILED", "SERVER_BUSY", "ZUGFERD_SOURCE_PDF_REQUIRED", "METHOD_NOT_ALLOWED", "NOT_FOUND", "BAD_REQUEST", "INVALID_QUERY_PARAMETER", "DOWNLOAD_FORMAT_REQUIRED", "INVALID_DOWNLOAD_FORMAT", "TASK_NOT_READY", "TASK_NOT_FOUND", "TASK_STATUS_FAILED", "TASK_RESULT_FAILED", "TASK_FAILED", "VALIDATION_FAILED", "PROFILE_MISMATCH", "ZUGFERD_SOURCE_PDF_INCOMPATIBLE", "ZUGFERD_CII_CONVERSION_FAILED", "ZUGFERD_PDF_GENERATION_FAILED", "XML_GENERATION_FAILED", "PDF_GENERATION_FAILED", "AUTHORITATIVE_VALIDATION_UNAVAILABLE", "ARTIFACT_GENERATION_RERUN_REQUIRED", "EXTRACTION_INCOMPLETE_GROUP_FAILURE", "INTERNAL_ARTIFACT_INVARIANT_FAILED", "VALIDATION_REPORT_NOT_FOUND", "VALIDATION_REPORT_FAILED", "PROXY_ERROR" ], "x-enumDescriptions": { "AUTHENTICATION_REQUIRED": "401 · hayır · `Authorization: Bearer ` gönderin.", "INVALID_API_KEY": "401 · hayır · Anahtar bilinmiyor, iptal edilmiş veya hatalı biçimde. Düzeltin veya yenileyin.", "API_NOT_ENABLED_FOR_TENANT": "403 · hayır · Anahtar geçerli, ancak hesabın Harici API erişimi yok. Destek ekibiyle iletişime geçin.", "ACCOUNT_DELETED": "410 · hayır · Bu API anahtarının hesabı silindi. Silme kalıcıdır. İptal edilmiş bir anahtar `INVALID_API_KEY` döndürür.", "INSUFFICIENT_API_CREDITS": "402 · hayır · Aylık kota ve ön ödemeli krediler tükendi. Bir kredi paketi satın alın veya bir sonraki ayı bekleyin. İki `details` yapısı vardır.", "AUTH_SERVICE_UNAVAILABLE": "503 · evet · Kimlik doğrulama geçici olarak kullanılamıyor. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin.", "PLAN_TIER_CHECK_FAILED": "503 · evet · Plan/API erişimi doğrulanamadı. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin.", "RATE_LIMIT_SERVICE_UNAVAILABLE": "503 · evet · Hız limiti hizmeti kullanılamıyor. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin.", "API_CREDIT_SERVICE_UNAVAILABLE": "503 · evet · Kredi/kota doğrulaması kullanılamıyor. Yüklemeyi aynı Idempotency-Key ile yeniden deneyin.", "RATE_LIMITED": "429 · evet · `Retry-After` saniye bekleyin, ardından aynı Idempotency-Key ile yeniden deneyin.", "IDEMPOTENCY_KEY_REQUIRED": "400 · hayır · Her iki POST uç noktasında bir `Idempotency-Key` başlığı gönderin.", "INVALID_IDEMPOTENCY_KEY": "400 · hayır · `^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$` ile eşleşen 1–200 karakter kullanın.", "IDEMPOTENCY_IN_PROGRESS": "409 · evet · Bu anahtarla yapılan ilk istek hâlâ çalışıyor. Kısa bir süre sonra aynı anahtarla yeniden deneyin.", "IDEMPOTENCY_CONFLICT": "409 · hayır · Anahtar farklı bir istek içeriğiyle kullanıldı. Yeni bir istek içeriği için yeni bir anahtar kullanın.", "IDEMPOTENCY_REPLAY_EXPIRED": "409 · hayır · Orijinal görevin 24 saatlik saklama süresi doldu. Yeni bir anahtarla yeni bir dönüşüm başlatın.", "FORMAT_REQUIRED": "400 · hayır · Her dönüşüm isteğinde `format` gönderin.", "INVALID_FORMAT": "422 · hayır · XRECHNUNG, ZUGFERD, EN16931, UBL, CII değerlerinden birini gönderin.", "INVALID_PROFILE": "422 · hayır · Bilinmeyen profil adı. `details.allowed_profiles` kabul edilen değerleri listeler.", "OUTPUT_PROFILE_CONFLICT": "422 · hayır · Profil bu `format` için kabul edilmiyor. Uyumlu bir profil gönderin veya profili göndermeyin.", "OUTPUT_PROFILE_REQUIRED": "422 · hayır · Savunma amaçlıdır; V1 her format için varsayılan bir profil atadığından beklenmez.", "CLIENT_REFERENCE_CONFLICT": "400 · hayır · `client_reference` ve `external_invoice_id` farklı. Birini veya ikisinde de aynı değeri gönderin.", "INVALID_CLIENT_METADATA": "400 · hayır · `client_reference`/`external_invoice_id` değerini ≤ 200 ve `source_system` değerini ≤ 100 karakterde, kontrol karakteri olmadan tutun.", "INVALID_SELLER_MASTER_DATA": "400 · hayır · `seller_master_data` değerini desteklenen anahtarlara sahip bir JSON nesnesi dizesi olarak gönderin; `electronic_address` ve `electronic_address_scheme` alanlarını birlikte gönderin.", "INVALID_EMBEDDED_XML_POLICY": "400 · hayır · `use_embedded_xml` değerini `true` veya `false` olarak gönderin ya da hiç göndermeyin.", "INVALID_EMAIL_INPUT": "400 · hayır · `email_input` değerini bir kez, ≤ 10.000 karakter, yalnızca PDF kaynağında, `use_embedded_xml=true` olmadan gönderin; convert-structured’da asla göndermeyin.", "INVALID_UPLOAD": "400/415 · hayır · Yüklemeyi düzeltin: multipart/form-data, desteklenen dosya türü, ≤ 20 dosya parçası ve 50 alan, tüm `data_file` parçalarında tek bir fatura numarası (`details.reason`).", "PAYLOAD_TOO_LARGE": "413 · hayır · Bir dosya, `data_file` toplamı veya multipart gövde kendi backend limitini aşıyor. `details.limit_bytes` değerini inceleyin; daha küçük bir istek gönderin.", "UPLOAD_FAILED": "422 · hayır: geçersiz `jurisdiction`/`transaction_scope`/`delivery_channel` değeri. 500/503 · evet: yükleme kabul edilmedi veya kabul edildi ancak ilk yanıtı yeniden oluşturulamadı. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin; yeniden deneme kabul edilen görevi döndürür.", "SERVER_BUSY": "503 · evet · İşleme kuyruğu dolu. `Retry-After` saniye (15) bekleyin, ardından aynı Idempotency-Key ile yeniden deneyin.", "ZUGFERD_SOURCE_PDF_REQUIRED": "422 · hayır · `format=ZUGFERD` bir PDF kaynağı gerektirir. Bir PDF yükleyin veya bir XML formatı seçin.", "METHOD_NOT_ALLOWED": "405 · hayır · Dönüşüm yollarında POST, görev yollarında GET kullanın (bkz. `Allow`).", "NOT_FOUND": "404 · hayır · /api/v1 altında bilinmeyen yol.", "BAD_REQUEST": "400 · hayır · `task_id` bir UUID olmalıdır.", "INVALID_QUERY_PARAMETER": "400 · hayır · `include_validation_report_html` değerini `true` veya `false` olarak gönderin.", "DOWNLOAD_FORMAT_REQUIRED": "400 · hayır · Zorunlu `download` sorgu parametresini gönderin.", "INVALID_DOWNLOAD_FORMAT": "400 · hayır · /result üzerinde `download=xml|pdf`, /validation-report üzerinde `download=html|xml` kullanın.", "TASK_NOT_READY": "202 · sorgulayın · Görev hâlâ çalışıyor. Görev durumunu backoff ile sorgulamaya devam edin.", "TASK_NOT_FOUND": "404 · hayır · Bilinmeyen görev, başka bir kiracının görevi veya tamamlandıktan 24 saat sonra silinmiş görev. Tüm görev uç noktaları.", "TASK_STATUS_FAILED": "5xx · evet · Durum okunamadı. Sorgulamayı backoff ile yeniden deneyin.", "TASK_RESULT_FAILED": "404/5xx · yalnızca 5xx · Sonuç okunamadı (örneğin eksik görev meta verisi). 5xx yanıtlarını backoff ile yeniden deneyin; bir 404’ü korelasyon kimliğiyle destek ekibine iletin.", "TASK_FAILED": "500 · yalnızca `details.retryable` true ise · `details.code` değerini okuyun. Yeniden denenebilir hatalar, yeni bir Idempotency-Key ile YENİ bir dönüşüm gerektirir.", "VALIDATION_FAILED": "422 · hayır · Engelleyici doğrulama hataları. Verileri düzeltin (`details.items`) ve yeni bir dönüşüm başlatın.", "PROFILE_MISMATCH": "422 · hayır · Saklanan belge başka bir profil bildiriyor. Doğru profille yeni bir dönüşüm başlatın.", "ZUGFERD_SOURCE_PDF_INCOMPATIBLE": "422 · hayır · Kaynak PDF katı bir PDF/A-3 hibrit taşıyamaz. PDF’i normalleştirin veya `download=xml` kullanın.", "ZUGFERD_CII_CONVERSION_FAILED": "422/500 · hayır · Hibrit CII dönüşümü başarısız oldu. Korelasyon kimliğiyle destek ekibine iletin.", "ZUGFERD_PDF_GENERATION_FAILED": "500 · hayır · Hibrit PDF oluşturma başarısız oldu. Korelasyon kimliğiyle destek ekibine iletin.", "XML_GENERATION_FAILED": "500 · evet, backoff ile · Eski isteğe bağlı oluşturma yolu; katı API görevlerinde beklenmez.", "PDF_GENERATION_FAILED": "500 · evet, backoff ile · Eski isteğe bağlı oluşturma yolu; katı API görevlerinde beklenmez.", "AUTHORITATIVE_VALIDATION_UNAVAILABLE": "503 · evet · Doğrulayıcı geçici olarak kullanılamıyor. Aynı indirmeyi daha sonra yeniden deneyin.", "ARTIFACT_GENERATION_RERUN_REQUIRED": "503 · yeni görev · Çıktı dosyası oluşturma, sunucu tarafı yeniden denemelerden sonra başarısız oldu. Yeni bir dönüşüm başlatın.", "EXTRACTION_INCOMPLETE_GROUP_FAILURE": "503 · yeni görev · Veri çıkarımı grupları başarısız oldu (`details.failed_groups`). Yeni bir dönüşüm başlatın.", "INTERNAL_ARTIFACT_INVARIANT_FAILED": "500 · hayır · Güvenli şekilde saklanmış bir çıktı dosyası olmadan tamamlanmış görev. Korelasyon kimliğiyle destek ekibine iletin.", "VALIDATION_REPORT_NOT_FOUND": "404 · hayır · Güncel çıktı dosyasına bağlı rapor yok (`details.reason`).", "VALIDATION_REPORT_FAILED": "4xx/5xx · yalnızca 5xx · Rapor alınamadı. Geçici 5xx yanıtlarını backoff ile yeniden deneyin.", "PROXY_ERROR": "502/504 · evet · Edge ile backend arasında iletim hatası. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin." }, "description": "Makine tarafından okunabilir hata kodu. Her açıklamanın biçimi: HTTP durumu · yeniden deneme? · yapılacak işlem." }, "message": { "type": "string", "description": "İnsanlar için okunabilir metin. Ayrıştırmayın." }, "correlation_id": { "type": "string", "format": "uuid", "description": "Destek ekibine bu değeri belirtin." }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "additionalProperties": false } ``` ### `EdgeError` ```json { "type": "object", "description": "İstek API’ye ulaşmadan önce edge proxy tarafından gönderilen hata (`404 NOT_FOUND`, `405 METHOD_NOT_ALLOWED`). `correlation_id` içermez.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND", "METHOD_NOT_ALLOWED" ] }, "message": { "type": "string" } } } ``` ### `ErrorDetails` ```json { "type": "object", "description": "Yapılandırılmış bağlam. Anahtarlar koda bağlıdır; bilinmeyen anahtarlar görünebilir. `type` genellikle mevcuttur, ancak her zaman değil (örneğin `{\"field\": \"download\"}`, `INVALID_UPLOAD`, `413`); bu nedenle mantığınızı zarftaki `code` değerine göre kurun.", "properties": { "type": { "type": "string", "description": "Ayrıntı ailesi, örneğin `validation`, `rate_limit`, `idempotency_conflict`, `idempotency_in_progress`, `profile_mismatch`, `context`, `dependency`, `artifact_generation`, `validation_report`, `message`." }, "code": { "type": "string", "description": "Temeldeki hata kodu. `500 TASK_FAILED` durumunda bu, nedendir; bkz. `x-enumDescriptions`.", "examples": [ "MULTIPLE_INVOICES_IN_DOCUMENT", "NO_INVOICE_DETECTED", "INSUFFICIENT_INVOICE_SIGNAL", "SOURCE_TEXT_UNAVAILABLE", "SCHEMA_PARSE_FAILED", "ARTIFACT_PARITY_FAILED", "PROVIDER_ERROR" ], "x-enumDescriptions": { "MULTIPLE_INVOICES_IN_DOCUMENT": "Kalıcı. Belge birden fazla fatura içeriyor. Belgeyi bölün ve her faturayı ayrı ayrı dönüştürün.", "NO_INVOICE_DETECTED": "Kalıcı. Belge bir fatura değil. Belgeyi bir kişiye yönlendirin.", "INSUFFICIENT_INVOICE_SIGNAL": "Kalıcı. Fatura verisi çok az. Daha iyi bir kaynak gönderin veya convert-structured kullanın.", "SOURCE_TEXT_UNAVAILABLE": "Bkz. `retryable`. false: okunabilir metin yok (metin içeren bir PDF veya daha net bir tarama yükleyin). true: OCR geçici olarak kullanılamıyordu; yeni bir dönüşüm başlatın.", "SCHEMA_PARSE_FAILED": "Bu deneme için kalıcı. Yeni bir dönüşüm başlatın; tekrarlanırsa destek ekibine iletin.", "ARTIFACT_PARITY_FAILED": "Kalıcı. Çıktı dosyası nihai fatura verileriyle eşleşmedi. Korelasyon kimliğiyle destek ekibine iletin.", "PROVIDER_ERROR": "Bkz. `retryable`. true: bir süre bekledikten sonra yeni bir dönüşüm başlatın. `classification=provider_context_too_large`: daha küçük bir belge gönderin." } }, "retryable": { "type": "boolean", "description": "Mevcut olduğunda belirleyicidir. `TASK_FAILED` üzerinde `true`: yeni bir Idempotency-Key ile YENİ bir dönüşüm başlatın." }, "can_review": { "type": "boolean" }, "classification": { "type": "string", "description": "Örneğin `multiple_invoices`, `not_invoice`, `provider_context_too_large`." }, "category": { "type": "string" }, "recovery_hint": { "type": "string", "description": "İnsanlar için okunabilir sonraki adım." }, "same_task_retryable": { "type": "boolean", "description": "`false`: aynı görev kurtarılamaz; yeni bir dönüşüm başlatın." }, "recovery": { "type": "string", "description": "Örneğin `start_new_conversion`." }, "dependency": { "type": "string" }, "stage": { "type": "string" }, "failed_groups": { "type": "array", "items": { "type": "string" }, "description": "`EXTRACTION_INCOMPLETE_GROUP_FAILURE` durumunda başarısız olan veri çıkarımı grupları." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationDetail" }, "description": "`VALIDATION_FAILED` durumunda engelleyici sorunlar." }, "field": { "type": "string", "description": "Soruna neden olan istek alanı, örneğin `download` veya `file`." }, "reason": { "type": "string", "description": "Alt neden, örneğin `bundle_invoice_id_missing`, `bundle_invoice_id_mismatch`, `different_payload_for_same_key`." }, "profile": { "type": "string" }, "format": { "type": "string" }, "allowed_profiles": { "type": "array", "items": { "type": "string" }, "description": "Profil hatalarında kabul edilen profiller." }, "minute_count": { "type": "integer" }, "hour_count": { "type": "integer" }, "limit_minute": { "type": "integer" }, "limit_hour": { "type": "integer" }, "limit_bytes": { "type": "integer", "description": "`413 PAYLOAD_TOO_LARGE` durumundaki boyut limiti." }, "declared_size": { "type": "integer" }, "received_bytes": { "type": "integer" }, "remaining": { "type": "integer" }, "included_remaining": { "type": "integer" }, "credit_remaining": { "type": [ "integer", "null" ] }, "shortfall": { "type": "integer" }, "minimum_purchase": { "type": "integer" }, "bridge_status": { "type": "integer" } }, "additionalProperties": true } ``` ### `ValidationDetail` ```json { "type": "object", "description": "Engelleyici bir doğrulama sorunu.", "properties": { "field": { "type": [ "string", "null" ], "description": "Fatura alanı yolu, örneğin `BuyerReference`." }, "rule_id": { "type": [ "string", "null" ], "description": "Kural kimliği, örneğin `BR-DE-15`." }, "severity": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "suggestion": { "type": [ "string", "null" ], "description": "Neyin düzeltileceği." }, "message": { "type": [ "string", "null" ] } }, "additionalProperties": true } ``` ### `InsufficientApiCreditsPrepaidError` ```json { "type": "object", "description": "Yalnızca ön ödemeli hesaplar için 402 yapısı.", "required": [ "code", "message", "correlation_id", "details" ], "properties": { "code": { "type": "string", "const": "INSUFFICIENT_API_CREDITS" }, "message": { "type": "string" }, "correlation_id": { "type": "string", "format": "uuid" }, "details": { "type": "object", "required": [ "type", "remaining", "minimum_purchase" ], "properties": { "type": { "type": "string", "const": "context" }, "remaining": { "type": "integer", "description": "Kalan ön ödemeli kredi." }, "minimum_purchase": { "type": "integer", "description": "En küçük kredi paketi (100)." } }, "additionalProperties": true } }, "additionalProperties": false } ``` ### `InsufficientApiCreditsAllowanceError` ```json { "type": "object", "description": "Zorunlu aylık kotası olan hesaplar için 402 yapısı.", "required": [ "code", "message", "correlation_id", "details" ], "properties": { "code": { "type": "string", "const": "INSUFFICIENT_API_CREDITS" }, "message": { "type": "string" }, "correlation_id": { "type": "string", "format": "uuid" }, "details": { "type": "object", "required": [ "type", "included_remaining", "credit_remaining", "shortfall", "minimum_purchase" ], "properties": { "type": { "type": "string", "const": "context" }, "included_remaining": { "type": "integer", "description": "Bu ay kalan kota." }, "credit_remaining": { "type": [ "integer", "null" ], "description": "Kalan ön ödemeli kredi veya null." }, "shortfall": { "type": "integer", "description": "Karşılanmayan birimler." }, "minimum_purchase": { "type": "integer", "description": "En küçük kredi paketi (100)." } }, "additionalProperties": true } }, "additionalProperties": false } ``` ### `StructuredInvoice_AccountingCustomerParty` ```json { "additionalProperties": false, "properties": { "Party": { "$ref": "#/components/schemas/StructuredInvoice_Party" } }, "required": [ "Party" ], "title": "AccountingCustomerParty", "type": "object" } ``` ### `StructuredInvoice_AccountingSupplierParty` ```json { "additionalProperties": false, "properties": { "Party": { "$ref": "#/components/schemas/StructuredInvoice_Party" } }, "required": [ "Party" ], "title": "AccountingSupplierParty", "type": "object" } ``` ### `StructuredInvoice_AdditionalDocumentReference` ```json { "additionalProperties": false, "properties": { "ID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "DocumentTypeCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Documenttypecode" }, "DocumentDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Documentdescription" }, "Attachment": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Attachment" }, { "type": "null" } ], "default": null } }, "title": "AdditionalDocumentReference", "type": "object" } ``` ### `StructuredInvoice_AllowanceCharge` ```json { "additionalProperties": false, "description": "Belge düzeyinde indirim veya ek ücret (BG-20/BG-21)", "properties": { "ChargeIndicator": { "title": "Chargeindicator", "type": "boolean" }, "AllowanceChargeReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowancechargereasoncode" }, "AllowanceChargeReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowancechargereason" }, "MultiplierFactorNumeric": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "description": "Kaynaktaki yüzde puanları, tam olarak yazıldığı gibi. %30 değeri 30’dur, asla 0.3 değildir; %0,3 değeri 0.3 olarak kalır. Yüzde puanlarını asla ondalık çarpanlara dönüştürmeyin.", "title": "Multiplierfactornumeric" }, "BaseAmount": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Baseamount" }, "Amount": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "TaxCategory": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_AllowanceChargeTaxCategory" }, { "type": "null" } ], "default": null } }, "required": [ "ChargeIndicator", "Amount" ], "title": "AllowanceCharge", "type": "object" } ``` ### `StructuredInvoice_AllowanceChargeTaxCategory` ```json { "additionalProperties": false, "description": "Belge düzeyinde indirim/ek ücret için vergi kategorisi (BG-21)", "properties": { "ID": { "title": "Id", "type": "string" }, "Percent": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "ID", "TaxScheme" ], "title": "AllowanceChargeTaxCategory", "type": "object" } ``` ### `StructuredInvoice_Attachment` ```json { "additionalProperties": false, "properties": { "EmbeddedDocumentBinaryObject": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_EmbeddedDocumentBinaryObject" }, { "type": "null" } ], "default": null } }, "title": "Attachment", "type": "object" } ``` ### `StructuredInvoice_BuyersItemIdentification` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "BuyersItemIdentification", "type": "object" } ``` ### `StructuredInvoice_CardAccount` ```json { "additionalProperties": false, "properties": { "PrimaryAccountNumberID": { "title": "Primaryaccountnumberid", "type": "string" }, "NetworkID": { "title": "Networkid", "type": "string" }, "HolderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Holdername" } }, "required": [ "PrimaryAccountNumberID", "NetworkID" ], "title": "CardAccount", "type": "object" } ``` ### `StructuredInvoice_ClassifiedTaxCategory` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "Percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent" }, "TaxExemptionReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreasoncode" }, "TaxExemptionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreason" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "ID", "TaxScheme" ], "title": "ClassifiedTaxCategory", "type": "object" } ``` ### `StructuredInvoice_CommodityClassification` ```json { "additionalProperties": false, "properties": { "ItemClassificationCode": { "$ref": "#/components/schemas/StructuredInvoice_ItemClassificationCode" } }, "required": [ "ItemClassificationCode" ], "title": "CommodityClassification", "type": "object" } ``` ### `StructuredInvoice_Contact` ```json { "additionalProperties": false, "properties": { "Name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "Telephone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Telephone" }, "ElectronicMail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Electronicmail" } }, "title": "Contact", "type": "object" } ``` ### `StructuredInvoice_ContractDocumentReference` ```json { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "ContractDocumentReference", "type": "object" } ``` ### `StructuredInvoice_Country` ```json { "additionalProperties": false, "properties": { "IdentificationCode": { "title": "Identificationcode", "type": "string" } }, "required": [ "IdentificationCode" ], "title": "Country", "type": "object" } ``` ### `StructuredInvoice_Delivery` ```json { "additionalProperties": false, "properties": { "ActualDeliveryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Actualdeliverydate" }, "DeliveryLocation": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DeliveryLocation" }, { "type": "null" } ], "default": null }, "DeliveryParty": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Party" }, { "type": "null" } ], "default": null } }, "title": "Delivery", "type": "object" } ``` ### `StructuredInvoice_DeliveryAddress` ```json { "additionalProperties": false, "properties": { "StreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Streetname" }, "AdditionalStreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Additionalstreetname" }, "CityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cityname" }, "PostalZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Postalzone" }, "CountrySubentity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Countrysubentity" }, "Country": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Country" }, { "type": "null" } ], "default": null } }, "title": "DeliveryAddress", "type": "object" } ``` ### `StructuredInvoice_DeliveryLocation` ```json { "additionalProperties": false, "properties": { "ID": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Id" }, "schemeID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Schemeid" }, "Address": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DeliveryAddress" }, { "type": "null" } ], "default": null } }, "title": "DeliveryLocation", "type": "object" } ``` ### `StructuredInvoice_DeliveryTerms` ```json { "additionalProperties": false, "properties": { "ID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "SpecialTerms": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Specialterms" } }, "title": "DeliveryTerms", "type": "object" } ``` ### `StructuredInvoice_DespatchDocumentReference` ```json { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "DespatchDocumentReference", "type": "object" } ``` ### `StructuredInvoice_EmbeddedDocumentBinaryObject` ```json { "additionalProperties": false, "properties": { "#text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "#Text" }, "mimeCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mimecode" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" } }, "title": "EmbeddedDocumentBinaryObject", "type": "object" } ``` ### `StructuredInvoice_EndpointID` ```json { "additionalProperties": false, "properties": { "#text": { "title": "#Text", "type": "string" }, "@schemeID": { "title": "@Schemeid", "type": "string" } }, "required": [ "#text", "@schemeID" ], "title": "EndpointID", "type": "object" } ``` ### `StructuredInvoice_FinancialInstitutionBranch` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "FinancialInstitutionBranch", "type": "object" } ``` ### `StructuredInvoice_InvoiceLine` ```json { "additionalProperties": false, "properties": { "ID": { "description": "Satır tanımlayıcısı - orijinal faturadaki pozisyon numarasını aynen kullanın (örneğin '1.1.30', '10', '001'). Yalnızca açık tanımlayıcılar yoksa sıralı '1', '2', '3' kullanın. Ürün adı DEĞİLDİR.", "title": "Id", "type": "string" }, "Note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "InvoicedQuantity": { "title": "Invoicedquantity", "type": "number" }, "unitCode": { "title": "Unitcode", "type": "string" }, "LineExtensionAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Lineextensionamount" }, "PeriodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Periodstart" }, "PeriodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Periodend" }, "InvoicePeriod": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_InvoicePeriod" }, { "type": "null" } ], "default": null }, "OrderLineReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Orderlinereference" }, "Item": { "$ref": "#/components/schemas/StructuredInvoice_Item" }, "Price": { "$ref": "#/components/schemas/StructuredInvoice_Price" }, "AllowanceCharge": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowancecharge" } }, "required": [ "ID", "InvoicedQuantity", "unitCode", "LineExtensionAmount", "Item", "Price" ], "title": "InvoiceLine", "type": "object" } ``` ### `StructuredInvoice_InvoicePeriod` ```json { "additionalProperties": false, "properties": { "StartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Startdate" }, "EndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Enddate" }, "DescriptionCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Descriptioncode" } }, "title": "InvoicePeriod", "type": "object" } ``` ### `StructuredInvoice_Item` ```json { "additionalProperties": false, "properties": { "Description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "Name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "BuyersItemIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_BuyersItemIdentification" }, { "type": "null" } ], "default": null }, "SellersItemIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_SellersItemIdentification" }, { "type": "null" } ], "default": null }, "StandardItemIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_StandardItemIdentification" }, { "type": "null" } ], "default": null }, "OriginCountry": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_OriginCountry" }, { "type": "null" } ], "default": null }, "CommodityClassification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_CommodityClassification" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_CommodityClassification" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Commodityclassification" }, "ClassifiedTaxCategory": { "$ref": "#/components/schemas/StructuredInvoice_ClassifiedTaxCategory" } }, "required": [ "ClassifiedTaxCategory" ], "title": "Item", "type": "object" } ``` ### `StructuredInvoice_ItemClassificationCode` ```json { "additionalProperties": false, "properties": { "#text": { "title": "#Text", "type": "string" }, "listID": { "title": "Listid", "type": "string" }, "listVersionID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Listversionid" } }, "required": [ "#text", "listID" ], "title": "ItemClassificationCode", "type": "object" } ``` ### `StructuredInvoice_LegalMonetaryTotal` ```json { "additionalProperties": false, "properties": { "LineExtensionAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Lineextensionamount" }, "AllowanceTotalAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowancetotalamount" }, "ChargeTotalAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Chargetotalamount" }, "TaxExclusiveAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxexclusiveamount" }, "TaxInclusiveAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxinclusiveamount" }, "PrepaidAmount": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prepaidamount" }, "PayableRoundingAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Payableroundingamount" }, "PayableAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Payableamount" } }, "required": [ "LineExtensionAmount", "TaxExclusiveAmount", "TaxInclusiveAmount", "PayableAmount" ], "title": "LegalMonetaryTotal", "type": "object" } ``` ### `StructuredInvoice_OrderReference` ```json { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" }, "IssueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Issuedate" } }, "required": [ "ID" ], "title": "OrderReference", "type": "object" } ``` ### `StructuredInvoice_OriginCountry` ```json { "additionalProperties": false, "properties": { "IdentificationCode": { "title": "Identificationcode", "type": "string" } }, "required": [ "IdentificationCode" ], "title": "OriginCountry", "type": "object" } ``` ### `StructuredInvoice_Party` ```json { "additionalProperties": false, "properties": { "EndpointID": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_EndpointID" }, { "type": "null" } ], "default": null }, "PartyIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PartyIdentification" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_PartyIdentification" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Partyidentification" }, "PartyName": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Partyname" }, "PostalAddress": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PostalAddress" }, { "type": "null" } ], "default": null }, "PartyTaxScheme": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Partytaxscheme" }, "PartyLegalEntity": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PartyLegalEntity" }, { "type": "null" } ], "default": null }, "Contact": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Contact" }, { "type": "null" } ], "default": null } }, "title": "Party", "type": "object" } ``` ### `StructuredInvoice_PartyIdentification` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "schemeID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Schemeid" } }, "required": [ "ID" ], "title": "PartyIdentification", "type": "object" } ``` ### `StructuredInvoice_PartyLegalEntity` ```json { "additionalProperties": false, "properties": { "RegistrationName": { "title": "Registrationname", "type": "string" }, "CompanyID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Companyid" }, "CompanyLegalForm": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Companylegalform" } }, "required": [ "RegistrationName" ], "title": "PartyLegalEntity", "type": "object" } ``` ### `StructuredInvoice_PartyTaxScheme` ```json { "additionalProperties": false, "properties": { "CompanyID": { "title": "Companyid", "type": "string" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "CompanyID", "TaxScheme" ], "title": "PartyTaxScheme", "type": "object" } ``` ### `StructuredInvoice_PayeeFinancialAccount` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "Name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "FinancialInstitutionBranch": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_FinancialInstitutionBranch" }, { "type": "null" } ], "default": null } }, "required": [ "ID" ], "title": "PayeeFinancialAccount", "type": "object" } ``` ### `StructuredInvoice_PayeeParty` ```json { "additionalProperties": false, "properties": { "Party": { "$ref": "#/components/schemas/StructuredInvoice_Party" } }, "required": [ "Party" ], "title": "PayeeParty", "type": "object" } ``` ### `StructuredInvoice_PaymentMandate` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "PayerFinancialAccount": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PayeeFinancialAccount" }, { "type": "null" } ], "default": null } }, "required": [ "ID" ], "title": "PaymentMandate", "type": "object" } ``` ### `StructuredInvoice_PaymentMeans` ```json { "additionalProperties": false, "properties": { "PaymentMeansCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paymentmeanscode" }, "PaymentID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paymentid" }, "PaymentChannelCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paymentchannelcode" }, "InstructionID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructionid" }, "InstructionNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructionnote" }, "PayeeFinancialAccount": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PayeeFinancialAccount" }, { "type": "null" } ], "default": null }, "CardAccount": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_CardAccount" }, { "type": "null" } ], "default": null }, "PaymentMandate": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PaymentMandate" }, { "type": "null" } ], "default": null } }, "title": "PaymentMeans", "type": "object" } ``` ### `StructuredInvoice_PaymentTerms` ```json { "additionalProperties": false, "properties": { "Note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "PenaltySurchargePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Penaltysurchargepercent" }, "Amount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Amount" }, "NetDays": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Netdays" }, "DiscountDays": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Discountdays" }, "DiscountPercent": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Discountpercent" }, "DiscountBaseAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Discountbaseamount" }, "ExplicitDueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Explicitduedate" } }, "title": "PaymentTerms", "type": "object" } ``` ### `StructuredInvoice_PostalAddress` ```json { "additionalProperties": false, "properties": { "StreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Streetname" }, "CityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cityname" }, "PostalZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Postalzone" }, "Country": { "$ref": "#/components/schemas/StructuredInvoice_Country" }, "AdditionalStreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Additionalstreetname" }, "CountrySubentity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Countrysubentity" } }, "required": [ "Country" ], "title": "PostalAddress", "type": "object" } ``` ### `StructuredInvoice_PrecedingInvoiceReference` ```json { "additionalProperties": false, "description": "BG-3: Önceki bir faturaya referans (örneğin Abschlagsrechnungen’e referans veren bir Schlussrechnung için)", "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" }, "IssueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Issuedate" } }, "required": [ "ID" ], "title": "PrecedingInvoiceReference", "type": "object" } ``` ### `StructuredInvoice_Price` ```json { "additionalProperties": false, "properties": { "PriceAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Priceamount" }, "BaseQuantity": { "anyOf": [ { "type": "number" }, { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Basequantity" }, "AllowanceCharge": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowancecharge" } }, "required": [ "PriceAmount" ], "title": "Price", "type": "object" } ``` ### `StructuredInvoice_ProjectReference` ```json { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "ProjectReference", "type": "object" } ``` ### `StructuredInvoice_SalesOrderReference` ```json { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "SalesOrderReference", "type": "object" } ``` ### `StructuredInvoice_SellersItemIdentification` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "SellersItemIdentification", "type": "object" } ``` ### `StructuredInvoice_StandardItemIdentification` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "schemeID": { "default": "0160", "title": "Schemeid", "type": "string" } }, "required": [ "ID" ], "title": "StandardItemIdentification", "type": "object" } ``` ### `StructuredInvoice_TaxCategory` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "Percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent" }, "TaxExemptionReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreasoncode" }, "TaxExemptionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreason" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "ID", "TaxScheme" ], "title": "TaxCategory", "type": "object" } ``` ### `StructuredInvoice_TaxRepresentativeParty` ```json { "additionalProperties": false, "description": "BG-11: Satıcının vergi temsilcisi\nS, Z, E, AE, K, G, L, M vergi kodları kullanıldığında\nve ne BT-31 ne de BT-32 verildiğinde zorunludur (BR-DE-16)", "properties": { "PartyName": { "minLength": 1, "title": "Partyname", "type": "string" }, "PostalAddress": { "$ref": "#/components/schemas/StructuredInvoice_TaxRepresentativePostalAddress" }, "PartyTaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme" } }, "required": [ "PartyName", "PostalAddress", "PartyTaxScheme" ], "title": "TaxRepresentativeParty", "type": "object" } ``` ### `StructuredInvoice_TaxRepresentativePostalAddress` ```json { "additionalProperties": false, "description": "BG-12: Satıcının vergi temsilcisinin posta adresi", "properties": { "StreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Streetname" }, "AdditionalStreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Additionalstreetname" }, "CityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cityname" }, "PostalZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Postalzone" }, "CountrySubentity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Countrysubentity" }, "Country": { "$ref": "#/components/schemas/StructuredInvoice_Country" } }, "required": [ "Country" ], "title": "TaxRepresentativePostalAddress", "type": "object" } ``` ### `StructuredInvoice_TaxScheme` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "TaxScheme", "type": "object" } ``` ### `StructuredInvoice_TaxSubtotal` ```json { "additionalProperties": false, "properties": { "TaxableAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxableamount" }, "TaxAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxamount" }, "TaxCategory": { "$ref": "#/components/schemas/StructuredInvoice_TaxCategory" } }, "required": [ "TaxableAmount", "TaxAmount", "TaxCategory" ], "title": "TaxSubtotal", "type": "object" } ``` ### `StructuredInvoice_TaxTotal` ```json { "additionalProperties": false, "properties": { "TaxAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxamount" }, "TaxSubtotal": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_TaxSubtotal" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_TaxSubtotal" }, "type": "array" } ], "title": "Taxsubtotal" } }, "required": [ "TaxAmount", "TaxSubtotal" ], "title": "TaxTotal", "type": "object" } ``` ### `StructuredInvoice_TenderOrLotReference` ```json { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "TenderOrLotReference", "type": "object" } ``` ## Hata kodları | Kod | Açıklama | | --- | --- | | `AUTHENTICATION_REQUIRED` | 401 · hayır · `Authorization: Bearer ` gönderin. | | `INVALID_API_KEY` | 401 · hayır · Anahtar bilinmiyor, iptal edilmiş veya hatalı biçimde. Düzeltin veya yenileyin. | | `API_NOT_ENABLED_FOR_TENANT` | 403 · hayır · Anahtar geçerli, ancak hesabın Harici API erişimi yok. Destek ekibiyle iletişime geçin. | | `ACCOUNT_DELETED` | 410 · hayır · Bu API anahtarının hesabı silindi. Silme kalıcıdır. İptal edilmiş bir anahtar `INVALID_API_KEY` döndürür. | | `INSUFFICIENT_API_CREDITS` | 402 · hayır · Aylık kota ve ön ödemeli krediler tükendi. Bir kredi paketi satın alın veya bir sonraki ayı bekleyin. İki `details` yapısı vardır. | | `AUTH_SERVICE_UNAVAILABLE` | 503 · evet · Kimlik doğrulama geçici olarak kullanılamıyor. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. | | `PLAN_TIER_CHECK_FAILED` | 503 · evet · Plan/API erişimi doğrulanamadı. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. | | `RATE_LIMIT_SERVICE_UNAVAILABLE` | 503 · evet · Hız limiti hizmeti kullanılamıyor. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. | | `API_CREDIT_SERVICE_UNAVAILABLE` | 503 · evet · Kredi/kota doğrulaması kullanılamıyor. Yüklemeyi aynı Idempotency-Key ile yeniden deneyin. | | `RATE_LIMITED` | 429 · evet · `Retry-After` saniye bekleyin, ardından aynı Idempotency-Key ile yeniden deneyin. | | `IDEMPOTENCY_KEY_REQUIRED` | 400 · hayır · Her iki POST uç noktasında bir `Idempotency-Key` başlığı gönderin. | | `INVALID_IDEMPOTENCY_KEY` | 400 · hayır · `^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$` ile eşleşen 1–200 karakter kullanın. | | `IDEMPOTENCY_IN_PROGRESS` | 409 · evet · Bu anahtarla yapılan ilk istek hâlâ çalışıyor. Kısa bir süre sonra aynı anahtarla yeniden deneyin. | | `IDEMPOTENCY_CONFLICT` | 409 · hayır · Anahtar farklı bir istek içeriğiyle kullanıldı. Yeni bir istek içeriği için yeni bir anahtar kullanın. | | `IDEMPOTENCY_REPLAY_EXPIRED` | 409 · hayır · Orijinal görevin 24 saatlik saklama süresi doldu. Yeni bir anahtarla yeni bir dönüşüm başlatın. | | `FORMAT_REQUIRED` | 400 · hayır · Her dönüşüm isteğinde `format` gönderin. | | `INVALID_FORMAT` | 422 · hayır · XRECHNUNG, ZUGFERD, EN16931, UBL, CII değerlerinden birini gönderin. | | `INVALID_PROFILE` | 422 · hayır · Bilinmeyen profil adı. `details.allowed_profiles` kabul edilen değerleri listeler. | | `OUTPUT_PROFILE_CONFLICT` | 422 · hayır · Profil bu `format` için kabul edilmiyor. Uyumlu bir profil gönderin veya profili göndermeyin. | | `OUTPUT_PROFILE_REQUIRED` | 422 · hayır · Savunma amaçlıdır; V1 her format için varsayılan bir profil atadığından beklenmez. | | `CLIENT_REFERENCE_CONFLICT` | 400 · hayır · `client_reference` ve `external_invoice_id` farklı. Birini veya ikisinde de aynı değeri gönderin. | | `INVALID_CLIENT_METADATA` | 400 · hayır · `client_reference`/`external_invoice_id` değerini ≤ 200 ve `source_system` değerini ≤ 100 karakterde, kontrol karakteri olmadan tutun. | | `INVALID_SELLER_MASTER_DATA` | 400 · hayır · `seller_master_data` değerini desteklenen anahtarlara sahip bir JSON nesnesi dizesi olarak gönderin; `electronic_address` ve `electronic_address_scheme` alanlarını birlikte gönderin. | | `INVALID_EMBEDDED_XML_POLICY` | 400 · hayır · `use_embedded_xml` değerini `true` veya `false` olarak gönderin ya da hiç göndermeyin. | | `INVALID_EMAIL_INPUT` | 400 · hayır · `email_input` değerini bir kez, ≤ 10.000 karakter, yalnızca PDF kaynağında, `use_embedded_xml=true` olmadan gönderin; convert-structured’da asla göndermeyin. | | `INVALID_UPLOAD` | 400/415 · hayır · Yüklemeyi düzeltin: multipart/form-data, desteklenen dosya türü, ≤ 20 dosya parçası ve 50 alan, tüm `data_file` parçalarında tek bir fatura numarası (`details.reason`). | | `PAYLOAD_TOO_LARGE` | 413 · hayır · Bir dosya, `data_file` toplamı veya multipart gövde kendi backend limitini aşıyor. `details.limit_bytes` değerini inceleyin; daha küçük bir istek gönderin. | | `UPLOAD_FAILED` | 422 · hayır: geçersiz `jurisdiction`/`transaction_scope`/`delivery_channel` değeri. 500/503 · evet: yükleme kabul edilmedi veya kabul edildi ancak ilk yanıtı yeniden oluşturulamadı. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin; yeniden deneme kabul edilen görevi döndürür. | | `SERVER_BUSY` | 503 · evet · İşleme kuyruğu dolu. `Retry-After` saniye (15) bekleyin, ardından aynı Idempotency-Key ile yeniden deneyin. | | `ZUGFERD_SOURCE_PDF_REQUIRED` | 422 · hayır · `format=ZUGFERD` bir PDF kaynağı gerektirir. Bir PDF yükleyin veya bir XML formatı seçin. | | `METHOD_NOT_ALLOWED` | 405 · hayır · Dönüşüm yollarında POST, görev yollarında GET kullanın (bkz. `Allow`). | | `NOT_FOUND` | 404 · hayır · /api/v1 altında bilinmeyen yol. | | `BAD_REQUEST` | 400 · hayır · `task_id` bir UUID olmalıdır. | | `INVALID_QUERY_PARAMETER` | 400 · hayır · `include_validation_report_html` değerini `true` veya `false` olarak gönderin. | | `DOWNLOAD_FORMAT_REQUIRED` | 400 · hayır · Zorunlu `download` sorgu parametresini gönderin. | | `INVALID_DOWNLOAD_FORMAT` | 400 · hayır · /result üzerinde `download=xml\|pdf`, /validation-report üzerinde `download=html\|xml` kullanın. | | `TASK_NOT_READY` | 202 · sorgulayın · Görev hâlâ çalışıyor. Görev durumunu backoff ile sorgulamaya devam edin. | | `TASK_NOT_FOUND` | 404 · hayır · Bilinmeyen görev, başka bir kiracının görevi veya tamamlandıktan 24 saat sonra silinmiş görev. Tüm görev uç noktaları. | | `TASK_STATUS_FAILED` | 5xx · evet · Durum okunamadı. Sorgulamayı backoff ile yeniden deneyin. | | `TASK_RESULT_FAILED` | 404/5xx · yalnızca 5xx · Sonuç okunamadı (örneğin eksik görev meta verisi). 5xx yanıtlarını backoff ile yeniden deneyin; bir 404’ü korelasyon kimliğiyle destek ekibine iletin. | | `TASK_FAILED` | 500 · yalnızca `details.retryable` true ise · `details.code` değerini okuyun. Yeniden denenebilir hatalar, yeni bir Idempotency-Key ile YENİ bir dönüşüm gerektirir. | | `VALIDATION_FAILED` | 422 · hayır · Engelleyici doğrulama hataları. Verileri düzeltin (`details.items`) ve yeni bir dönüşüm başlatın. | | `PROFILE_MISMATCH` | 422 · hayır · Saklanan belge başka bir profil bildiriyor. Doğru profille yeni bir dönüşüm başlatın. | | `ZUGFERD_SOURCE_PDF_INCOMPATIBLE` | 422 · hayır · Kaynak PDF katı bir PDF/A-3 hibrit taşıyamaz. PDF’i normalleştirin veya `download=xml` kullanın. | | `ZUGFERD_CII_CONVERSION_FAILED` | 422/500 · hayır · Hibrit CII dönüşümü başarısız oldu. Korelasyon kimliğiyle destek ekibine iletin. | | `ZUGFERD_PDF_GENERATION_FAILED` | 500 · hayır · Hibrit PDF oluşturma başarısız oldu. Korelasyon kimliğiyle destek ekibine iletin. | | `XML_GENERATION_FAILED` | 500 · evet, backoff ile · Eski isteğe bağlı oluşturma yolu; katı API görevlerinde beklenmez. | | `PDF_GENERATION_FAILED` | 500 · evet, backoff ile · Eski isteğe bağlı oluşturma yolu; katı API görevlerinde beklenmez. | | `AUTHORITATIVE_VALIDATION_UNAVAILABLE` | 503 · evet · Doğrulayıcı geçici olarak kullanılamıyor. Aynı indirmeyi daha sonra yeniden deneyin. | | `ARTIFACT_GENERATION_RERUN_REQUIRED` | 503 · yeni görev · Çıktı dosyası oluşturma, sunucu tarafı yeniden denemelerden sonra başarısız oldu. Yeni bir dönüşüm başlatın. | | `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 503 · yeni görev · Veri çıkarımı grupları başarısız oldu (`details.failed_groups`). Yeni bir dönüşüm başlatın. | | `INTERNAL_ARTIFACT_INVARIANT_FAILED` | 500 · hayır · Güvenli şekilde saklanmış bir çıktı dosyası olmadan tamamlanmış görev. Korelasyon kimliğiyle destek ekibine iletin. | | `VALIDATION_REPORT_NOT_FOUND` | 404 · hayır · Güncel çıktı dosyasına bağlı rapor yok (`details.reason`). | | `VALIDATION_REPORT_FAILED` | 4xx/5xx · yalnızca 5xx · Rapor alınamadı. Geçici 5xx yanıtlarını backoff ile yeniden deneyin. | | `PROXY_ERROR` | 502/504 · evet · Edge ile backend arasında iletim hatası. Backoff ile ve aynı Idempotency-Key ile yeniden deneyin. |