Upload

Belge yuklemenin iki yolu vardir: tek dosya icin POST /v1/documents kisayolu, birden fazla dosya icin POST /v1/batches. Her iki yol da ayni alttaki Batch/Document kayitlarini olusturur; POST /v1/documents arka planda tek elemanli bir batch acar. id degerleri her zaman aninda doner -- istemci parse islemi bitmesini beklemeden document.id'yi (ve batch.id'yi) alir, sonraki adim GET /v1/jobs/{id} polling ya da webhook'tur (bkz. Polling, Webhook).

Auth ve entitlement

Tum upload istekleri Authorization: Bearer <api_key> gerektirir (dip_live_... ya da dip_test_..., bkz. Baslangic ve Auth). Upload, extract modulunu tetikler -- key'in entitlements listesinde extract yoksa istek dosya hic okunmadan 403 service_not_enabled ile reddedilir. Bu kontrol test key'ler icin de gecerlidir: TEST-KEY-EXEMPTION yalnizca faturalamayi ve rate-limit'i kapsar, erisimi degil.

POST /v1/documents (tekli yukleme)

multipart/form-data govdesi.

Cevap (201 Created), GET /v1/jobs/{id} ile ayni semaya sahip tek bir document objesidir, status: "queued" ile: id opak d_ on ekli, batch_id (otomatik olusan tek-elemanli batch'in id'si) opak b_ on ekli. result ve error henuz null, page_count de henuz bilinmez (split adimi sonrasinda dolar). Tam alan listesi icin bkz. Polling.

curl ornegi ve tam cevap govdesi sag panelde.

POST /v1/batches (coklu yukleme)

multipart/form-data govdesi ile bir ya da birden fazla dosya tek istekte yuklenir.

metadata govdesi:

{
  "external_batch_ref": "PO-2026-001",
  "callback_url": "https://tenant.example.com/webhooks/docsfra",
  "items": [
    { "key": "item_0", "external_item_ref": "INV-001" },
    { "key": "item_1", "external_item_ref": "INV-002" }
  ]
}

• external_batch_ref, callback_url -- opsiyonel (bkz. yukarisi).
• items[] -- her biri key (karsilik gelen dosya parcasinin adi) ve opsiyonel external_item_ref icerir. Her items[].key icin ayni isimde bir dosya parcasi (item_0, item_1, ...) istekte gonderilmelidir -- eslesen dosya bulunamazsa 400 invalid_request.

Cevap (201 Created) bir batch objesidir: id (b_ on ekli), external_batch_ref, status (documents[]'ten turetilir: hepsi completed/failed ise completed/failed, aksi halde processing, hicbiri islenmediyse queued), created_at, documents[] -- her biri kisa bir temsil (id, external_item_ref, status). Detayli durum icin GET /v1/batches/{id} kullanin (bkz. Polling).

curl ornegi ve tam cevap govdesi sag panelde.

Desteklenen formatlar ve limitler

Upload aninda hem Content-Type hem de dosyanin ilk baytlarindaki (magic-number) imza dogrulanir -- yalnizca uzantiya/header'a guvenmek spoof edilebilir oldugu icin ikisi birden kontrol edilir.

• Office/metin formatlari (yukaridaki PDF/gorsel/e-posta/ses disinda kalan hepsi) parse'tan once kendi altyapimizda (LibreOffice, ucuncu-taraf bulut YOK) PDF'e cevrilir, sonra ayni sayfa-render zincirinden gecer -- sonuc, esdeger bir PDF yuklemesiyle birebir aynidir.
• Eski/alternatif Content-Type degerleri (or. bir istemci gercek .docx dosyasini eski application/msword header'iyla gonderirse) dosyanin gercek imzasi hem beyan edilen header'a hem uzantiya karsi kontrol edilerek otomatik cozulur -- hangisi uyuyorsa o kazanir.
• Content-Type bos ya da application/octet-stream gelirse dosya uzantisindan tahmin edilir; yine de magic-number kontrolunden gecmesi gerekir -- ad/uzanti tek basina yeterli degildir.
• Bir istekteki dosyalardan biri bile whitelist'e uymuyorsa ya da magic-number beyan edilen formatla uyusmuyorsa tum istek reddedilir (422 unprocessable_file) -- kismi kabul yoktur; gecerli dosyalari ayiklayip yeniden gondermeniz gerekir.
• Dosya boyutu sunucu tarafi ust siniri asarsa (varsayilan 1 GB, yapilandirilabilir) 413 payload_too_large doner.
• E-posta (.eml, message/rfc822) yuklemeleri deterministik olarak kanonik markdown'a donusturulur: konu ve basliklar (Kimden/Kime/Cc/Tarih), govde ve ek listesi (ad · tip · boyut) -- eklerin kendisi v1'de ayrica islenmez.
• Ses (mp3/wav/m4a/ogg/webm/opus/amr — WhatsApp sesli mesajlar dahil) yuklemeleri otomatik olarak [MM:SS] zaman damgali satirlarla markdown'a transkript edilir. Ses destegi platformda yapilandirilmis olmalidir (AUDIO_TRANSCRIBE_API_URL) -- yapilandirilmamissa ses yuklemeleri 400 unsupported_media ile reddedilir. Video (mp4/mov/avi/mkv/webm) ayni hattan gecer: ses izi cikarilip transkribe edilir — kare/gorsel analiz v1'de yoktur.

Yukleme sonrasi ne olur

201 cevabi is bittigi anlamina gelmez -- yalnizca dokumanin kuyruga alindigini gosterir. Asagidaki adimlarin tamami sunucuda otomatik ilerler, sizin ayrica bir cagri yapmaniza gerek yoktur:

1. queued -> processing -- dosya sayfa gorsellerine bolunur (sayfa-basi dayanikli pipeline).
2. parsing -- her sayfa ayri ayri parse edilir. Bir sayfa tum bulut motorlarinda kalici olarak tukenirse o sayfa atlanir ama pipeline durmaz; diger sayfalar kaybolmaz.
3. indexing -- sayfalar page_no sirasiyla birlestirilip kanonik markdown + JSON uretilir; ayrica en-iyi-caba bir yapilandirma (structuring) denenir.
4. completed -- result.markdown_url / result.json_url (ve uretilebildiyse result.structured_url) hazir olur. partial: true ise en az bir sayfa adim 2'de kaybedilmis demektir; dokuman yine de completed sayilir, geri kalan sayfalar kaybolmaz. Bu noktada kredi dusumu olur: extract modulu (sayfa basi) her zaman, structure modulu (sayfa basi) ise yalnizca yapilandirma basariliysa ayrica dusulur.
5. AI-indeksleme (completed'tan bagimsiz, arka planda ilerler) -- dokuman chunk'lara ayrilir, embed edilir ve vektor indekse yazilir (embed ve index modulleri, ayrica faturalandirilir). Tamamlaninca dokuman Semantik Arama ve Soru-Cevap uzerinden sorgulanabilir olur.

Ilerlemeyi GET /v1/jobs/{id} ile polling yaparak ya da webhook dinleyerek takip edin (bkz. Polling, Webhook) -- ikisi de ayni son duruma yakinsar.

Test key ile yukleme

dip_test_ on ekli bir key ile yapilan yuklemeler ayni pipeline'dan gecer -- parse, yapilandirma, AI-indeksleme hepsi normal calisir. Fark yalnizca faturalamadadir:

• Upload oncesi bakiye on-kontrolu (BILL-PRECHECK) atlanir -- test key'lerle 402 insufficient_credit alinmaz.
• extract/structure/embed/index icin kullanim yine olculur (audit izi olarak UsageEvent yazilir) ama tenant bakiyesinden dusulmez.
• Test key'ler tenant_upload throttle'undan muaf, bunun yerine sabit ve comert bir hard-cap'e tabidir (varsayilan 1000/gun, tenant degil key basina).

Entitlement kontrolu (403 service_not_enabled) test key'ler icin de gecerlidir -- muafiyet yalnizca faturalama ve rate-limit icindir.

Hatalar