Polling

GET /v1/jobs/{id} tek uc noktadir — hem is durumunu, hem (tamamlaninca) sonucu ayni cevapta doner; ayri bir "sonucu al" uc noktasi yoktur. Webhook teslimi basarisiz olsa ya da hic gelmese dahi istemci her zaman bu uc noktaya guvenebilir: polling, webhook'un guvenilir fallback'idir.

Durum makinesi

queued -> processing -> parsing -> indexing -> completed / failed

result alani yalnizca status: "completed" iken doludur. error alani yalnizca status: "failed" iken doludur.

Bir dokuman completed olduktan sonra otomatik olarak AI-indekslemesine (chunk -> embed -> vektor) ve AI-temsil uretimine (memory, entities, reasoning, layout — bkz. Veri Cikarimi ve Artifact'ler) girer; bu arka planda, completed'tan bagimsiz ilerler. Indekslenen dokumanlar Semantik Arama ve Soru-Cevap uzerinden sorgulanabilir hale gelir.

Bu arka plan asamasinin ilerleyisi, ayni cevaptaki additive ai_status alaniyla disariya acilir (asagiya bkz.) — bir is status: "completed" okurken ai_status hala chunking ya da embedding olabilir.

GET /v1/jobs/{id} — durum ve sonuc ayni cevapta

{
  "id": "d_9c1a...",
  "batch_id": "b_5f2a...",
  "external_item_ref": "INV-001",
  "external_batch_ref": "PO-2026-001",
  "status": "completed",
  "page_count": 12,
  "partial": false,
  "file_size_bytes": 245678,
  "source": {
    "filename": "invoice-001.pdf",
    "content_type": "application/pdf",
    "size_bytes": 245678,
    "url": "https://media-cdn.../signed?exp=..."
  },
  "result": {
    "markdown_url": "https://markdown-cdn.../result.md?signed&exp=...",
    "json_url": "https://markdown-cdn.../result.json?signed&exp=...",
    "structured_url": "https://markdown-cdn.../result.structured.md?signed&exp=..."
  },
  "error": null,
  "created_at": "2026-07-01T09:00:00Z",
  "updated_at": "2026-07-01T09:02:15Z",
  "completed_at": "2026-07-01T09:02:15Z",
  "ai_status": "ready",
  "cost": "16.6893"
}

• ai_status — bu dokuman icin arka plan AI-temsil hattini izleyen additive bir alan, status'tan bagimsizdir. Su degerlerden biri: none (henuz baslamadi, ya da completed'tan hemen sonraki kisa sure), chunking, embedding, ready (istenen tum AI artifact'leri tamamlandi), partial (bazi artifact'ler uretilemedi — geri kalani yine de kullanilabilir) veya failed. Hangi artifact'lerin tam olarak hazir oldugunu gormek icin GET /v1/documents/{id}/artifactsi yoklayin (bkz. Veri Cikarimi ve Artifact'ler).
• source.url — orijinal yuklenen dosyanin indirme linki. Ham dosya retention suresi sonunda media-cdn'den silinirse url null doner (dosya artik yok, ama kayit ve result etkilenmez).
• result.markdown_url, result.json_url — sureli signed link'lerdir, her GET cagrisinda taze uretilir (lazy signing). Linki onbelleklemeyin, suresi dolar.
• result.structured_url — opsiyonel; ham markdown'in sabit sablona gore yeniden duzenlenmis (yapilandirilmis) hali. Yalnizca uretilebildiginde bulunur — bir en-iyi-caba zenginlestirmedir, cekirdek teslim degildir; uretilemezse alan cevapta hic yer almaz.

Hata: 404 not_found — id yok ya da baska bir tenant'a ait (kaynagin varligi asla 403 ile sizdirilmaz).

Sonuc icerigi: markdown, JSON ve sayfa atiflari

result alanindaki iki (opsiyonel ucuncu) link farkli govdeler indirir:

• markdown_url — tum sayfalarin birlestirildigi duz metin markdown.

• json_url — DIP kanonik, versiyonlu wrapper sema. Sayfa-basi atiflar (pages[]) bu govdenin icindedir — is durumu cevabinda degil:

  {
    "schema_version": "1.0",
    "source": { "engine": "vlm", "engine_version": "per-page", "backend": "vlm-page" },
    "document": {
      "page_count": 12,
      "pages": [
        { "page": 1, "markdown": "...", "blocks": [] },
        { "page": 2, "markdown": "...", "blocks": [] }
      ],
      "metadata": {}
    },
    "markdown": "...",
    "extracted_at": "2026-07-01T09:02:15Z"
  }
  

  Her pages[] elemani hangi sayfadan geldigini (page) ve o sayfanin markdown'ini tasir — sayfa-seviyeli atif/kaynak gosterimi icin bu govdeyi kullanin.

• structured_url (varsa) — ayni icerigin sabit bir sablona (Taraflar / Ana Tablo / Toplam / Diger) gore yeniden organize edilmis hali; ozetleme degildir, kaynaktaki hicbir veri atilmaz.

partial — kismi basari

Sayfa-basi dayanikli boru hattinda tek bir sayfanin gecici sorunu tum dokumani failed yapmaz: basarisiz sayfalar otomatik yeniden denenir, son care olarak alternatif bir motora dusulur. Buna ragmen bir sayfa tum motorlarda tukenirse:

• Dokuman yine de completed olur (diger sayfalar asla kaybolmaz).
• partial: true doner — sonucta en az bir sayfanin eksik/yer-tutucu oldugunu isaret eder (pages[] icinde o sayfanin markdown'i bostur).
• partial: false tam sonuc demektir.

Yuksek dogruluk gerektiren akislarda partial: true gelen sonuclari "eksik olabilir" olarak isleyip pages[] uzerinden hangi sayfanin etkilendigini kontrol edin.

Basarisiz is (failed)

• error doludur, result her zaman null'dur.
• Gecici hatalarda (ornegin depolamaya yazma basarisiz) is arka planda sinirli sayida otomatik olarak yeniden denenir; yalnizca deneme hakki tukenirse durum failed'e gecer.
• failed kalicidir — istemci tarafinda yeniden deneme, dokumani tekrar yuklemek anlamina gelir (POST /v1/documents).

GET /v1/batches/{id} — toplu durum

Bir batch'in ve icindeki tum document'lerin durumunu doner. Batch status'u turetilmis bir alandir: tum document'ler completed/failed ise batch completed/failed, en az biri islenmekte ise processing. Her document, GET /v1/jobs/{id} ile ayni kisa temsille (id, external_item_ref, status) listelenir; tam sonuc icin yine ilgili document.id ile GET /v1/jobs/{id} cagrilmalidir.

Onerilen polling stratejisi

• Baslangicta 2-3 saniyede bir kontrol edin, completed/failed gibi terminal bir duruma ulasana kadar tekrarlayin.
• 429 alirsaniz Retry-After header'ina uyup exponential backoff uygulayin (bkz. Baslangic ve Auth rate limit basliklari). Durum sorgulama uc noktasinin limiti yuklemeden cok daha cömerttir, ama yine de siki dongude polling yapmaktan kacinin.
• Webhook aliyorsaniz polling'i yalnizca dogrulama/fallback icin kullanin — her iki kanal da ayni son duruma yakinsayacaktir; webhook teslimi tukenirse (exhausted) istemci zaten bu uc noktaya dusmelidir.