Belge Setleri ve Sema Doldurma

Bugune kadar gordugunuz her uc nokta tek bir belgeye cevap verir: "bu belgede teslim sekli ne?" sorusunun muhatabi tek bir document_id'dir (bkz. Veri Cikarimi, Soru-Cevap). Ama gercek dunyada soru cogunlukla belge degil islem seviyesindedir: "bu SEVKIYATTA teslim sekli ne?" sorusunun cevabi ticari faturada olabilir, navlun faturasinda dogrulanabilir, ama hicbiri tek basina "bu islem" degildir — muhatap bir belge kumesidir (set).

Bu bolum iki primitifi anlatir: set (birden fazla belgeyi tek bir islem/sevkiyat olarak gruplayan hafif bir kaynak) ve sema doldurma (bir sema — alan listesi — verip o setteki belgelerden doldurulmus degerleri, celiskileri ve eksikleri geri almak). Tipik kullanim: bir gumruk beyannamesi sablonunu (30+ alanli) yapistirip "bu sevkiyatin belgelerinden bu semayi doldur" demek — bkz. asagida Kullanim vakasi.

Set nedir

Bir DocumentSet, tenant'iniza ait bir ya da daha fazla belgeyi gruplayan hafif bir kaynaktir — kendi islemesi/temsili yoktur, yalniz uye belgelere bir referans listesidir. Ayni belge birden fazla sette yer alabilir (bir set bir batch degildir, POST /v1/batches'teki gibi yukleme-zamanli bir gruplama degil — mevcut, zaten islenmis belgeleri sonradan istediginiz sekilde gruplarsiniz).

Set CRUD

Set olustur — POST /v1/sets

curl -X POST https://api.docsfra.com/v1/sets \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME GmbH - INV-2026-0001 sevkiyati",
    "document_ids": ["d_a1b2c3", "d_d4e5f6", "d_a7b8c9"]
  }'

201 Created:

{
  "id": "set_8f3a1b2c",
  "name": "ACME GmbH - INV-2026-0001 sevkiyati",
  "documents": [
    { "id": "d_a1b2c3", "status": "completed", "doc_type": "commercial_invoice" },
    { "id": "d_d4e5f6", "status": "completed", "doc_type": "packing_list" },
    { "id": "d_a7b8c9", "status": "completed", "doc_type": "bill_of_lading" }
  ],
  "created_at": "2026-08-05T09:00:00Z"
}

documents[].doc_type, belgenin memory katmani uretildiyse oradan (memory.doc_type) gelir — henuz uretilmediyse null'dur. Sema doldurma bu alani beklemez: memory olmasa da belgenin canonical markdown'i uzerinden aday toplama calisir (bkz. asagida Cozumleme motoru).

Varlik sizdirmama: document_ids icindeki bir id ya yok ya da baska bir tenant'a aitse istek 404 not_found doner — hangisi oldugu ayirt edilmez (bkz. Baslangic ve Auth → Bearer ile kimliklendirme, ayni desen).

Set getir — GET /v1/sets/{id}

curl https://api.docsfra.com/v1/sets/set_8f3a1b2c \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

Ayni govdeyi doner (yukaridaki POST cevabiyla birebir ayni sekil).

Sete belge ekle — POST /v1/sets/{id}/documents

curl -X POST https://api.docsfra.com/v1/sets/set_8f3a1b2c/documents \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["d_f1e2d3"]}'

200 OK, guncellenmis set govdesini doner. Idempotent: zaten uye olan bir document_id tekrar gonderilirse hata vermez, sadece hicbir sey degismez.

Setten belge cikar — DELETE /v1/sets/{id}/documents/{doc_id}

curl -X DELETE https://api.docsfra.com/v1/sets/set_8f3a1b2c/documents/d_f1e2d3 \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

204 No Content. Belgenin kendisi silinmez, yalniz bu setteki uyeligi kalkar — belge baska setlerde ya da tek basina (GET /v1/documents/{id}) erisilebilir kalmaya devam eder.

Setleri listele — GET /v1/sets

curl "https://api.docsfra.com/v1/sets?limit=20&offset=0" \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

{
  "results": [
    {
      "id": "set_8f3a1b2c",
      "name": "ACME GmbH - INV-2026-0001 sevkiyati",
      "documents": [
        { "id": "d_a1b2c3", "status": "completed", "doc_type": "commercial_invoice" }
      ],
      "created_at": "2026-08-05T09:00:00Z"
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 1
}

limit (varsayilan 20, ust siniri 100) ve offset (varsayilan 0) opsiyonel query parametreleridir. Sonuclar olusturulma tarihine gore en yeniden eskiye sirali doner.

Set CRUD hatalari

Set CRUD uc noktalari (/v1/sets, /v1/sets/{id}, /v1/sets/{id}/documents) herhangi bir modul entitlement'i gerektirmez — GET /v1/jobs/{id} ve /v1/batches ile ayni desen: gecerli bir API key yeterlidir (bkz. Polling). Entitlement kontrolu yalnizca asagidaki sema doldurma uc noktalarinda devreye girer.

Sema doldurma (asenkron)

Sema doldurma bir setteki tum belgelere karsi calisan, alan basina (potansiyel olarak) bir LLM mikro-cagrisi iceren bir islemdir — buyuk semalarda (30+ alan) ve coklu belgede toplam sure 120 saniyelik istek duvarini asabilir. Bu yuzden diger agir islerle (yukleme, cross-check) ayni desende arka plan isi olarak calisir: POST isi kuyruga alir ve hemen doner, sonucu bir GET ile yoklarsiniz.

1. Sema doldurmayi baslat — POST /v1/sets/{id}/extract

curl -X POST https://api.docsfra.com/v1/sets/set_8f3a1b2c/extract \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "fields": [
        {
          "key": "teslim_sekli",
          "label": "20. Teslim Sekli",
          "hint": "Incoterms (EXW, FOB, CIF vb.)",
          "primary_docs": ["commercial_invoice"],
          "verify_docs": ["freight_invoice", "insurance_certificate"],
          "type": "text"
        }
      ]
    },
    "language": "tr"
  }'

Dogrulama hatalari (bkz. asagida Hatalar) bu cagrida hemen doner. Aksi halde yanit 202 Accepted'tir:

{ "run_id": "sxr_4d9e2f1a" }

language opsiyoneldir (ISO 639-1 kodu) ve yalniz LLM'e verilen alan-doldurma talimatinin dilini etkiler — kaynak belgeden alinan degerler/alintilar her zaman belgenin kendi dilinde kalir, verilmezse tenant'in Console → Modeller varsayilanina duser (bkz. Veri Cikarimi → Cikti dili, ayni desen).

2. Sonucu yokla — GET /v1/sets/{id}/extract/{run_id}

status, queued → running → completed (ya da failed) sirasiyla ilerler. Bu uc noktayi (or. 2-3 saniyede bir) terminal bir duruma ulasana dek yoklayin — GET cagrilari asla ucretlendirilmez.

curl https://api.docsfra.com/v1/sets/set_8f3a1b2c/extract/sxr_4d9e2f1a \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

Islem surerken:

{ "status": "running", "result": null, "error": null }

completed oldugunda result doludur (bkz. asagida Sonuc formati):

{
  "status": "completed",
  "result": {
    "filled": { "teslim_sekli": { "value": "CIF", "confidence": 0.95, "sources": [] } },
    "conflicts": [],
    "missing": [],
    "stats": { "fields_total": 1, "filled": 1, "conflicts": 0, "missing": 0,
               "documents_used": 3, "llm_calls": 3, "duration_ms": 5200 }
  },
  "error": null
}

failed ise result null kalir, error doludur ({"code", "message"}) — bir sema alanindaki tekil bir sorun (or. tek bir belgenin LLM cagrisi zaman asimina ugramasi) tum kosuyu failed yapmaz; o belgeden gelecek adaylar yalniz o alan/belge icin eksik kalir, kosu completed olarak sonuclanmaya devam eder. failed, yalnizca kosu tumuyle baslatilamadiginda (or. tum belgeler icin LLM erisilemez oldu) olusur.

3. Gecmis kosulari listele — GET /v1/sets/{id}/extract

curl https://api.docsfra.com/v1/sets/set_8f3a1b2c/extract \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

{
  "results": [
    { "run_id": "sxr_4d9e2f1a", "status": "completed", "created_at": "2026-08-05T09:05:00Z" }
  ]
}

En yeniden eskiye sirali, kosu ozetlerinin listesi (tam result icin ilgili run_id ile yukaridaki GET .../extract/{run_id} cagrilmalidir).

Sema doldurma hatalari

Is basladiktan sonra olusan bir hata POST uzerinde HTTP hatasi uretmez — sonraki bir GET'te status: "failed" ve bir error objesi olarak yuzeye cikar (bkz. Soru-Cevap → Cross-check, ayni asenkron desen).

Sema formati

Sema iki bicimde kabul edilir: kanonik (dogrudan kullanilir) ve gumruk formati (girişte kanoniğe otomatik donusturulur, siz hicbir sey yapmadan). Ikisi de ayni schema alaninda gonderilir — hangi bicimde geldigi otomatik algilanir (govdede fields anahtari varsa kanonik, baslik_alanlari varsa gumruk formati sayilir).

Kanonik format

{
  "fields": [
    {
      "key": "teslim_sekli",
      "label": "20. Teslim Sekli",
      "hint": "Incoterms (EXW, FOB, CIF vb.)",
      "primary_docs": ["commercial_invoice"],
      "verify_docs": ["freight_invoice", "insurance_certificate"],
      "type": "text"
    }
  ]
}

primary_docs/verify_docs bos birakildiginda o alan setteki her belgeden aday toplayabilir (hicbir doc-type kisiti yok) — dogrudan karsilastirma icin bkz. asagida Cozumleme motoru.

Gumruk formati (otomatik donusturulur)

Gruplu, Turkce anahtarli gumruk beyanname sablonlari da dogrudan gonderilebilir — donusum sunucu tarafinda, sizin hicbir sey yapmaniza gerek kalmadan olur:

{
  "baslik_alanlari": {
    "teslim_odeme": {
      "alanlar": {
        "teslim_sekli": {
          "etiket": "20. Teslim Sekli",
          "aciklama": "Incoterms (EXW, FOB, CIF vb.)",
          "belge_birincil": ["commercial_invoice"],
          "belge_dogrulama": ["freight_invoice", "insurance_certificate"],
          "kaynak_tanimi": "belge"
        },
        "doviz_kuru": {
          "etiket": "23. Doviz Kuru",
          "aciklama": "Gumruk beyan tarihindeki resmi kur",
          "belge_birincil": [],
          "belge_dogrulama": [],
          "kaynak_tanimi": "operator girisi"
        }
      }
    }
  },
  "mikro_cagri": true
}

Yol: baslik_alanlari.<grup>.alanlar.<key>. Bu ornek, kanonige donusurken tek bir alan uretir:

{
  "fields": [
    {
      "key": "teslim_sekli",
      "label": "20. Teslim Sekli",
      "hint": "Incoterms (EXW, FOB, CIF vb.)",
      "primary_docs": ["commercial_invoice"],
      "verify_docs": ["freight_invoice", "insurance_certificate"],
      "type": "text"
    }
  ]
}

Eslesme: etiket → label, aciklama → hint, belge_birincil → primary_docs, belge_dogrulama → verify_docs. <grup> seviyesi sonuca yansimaz — sonuc govdesi her zaman duz bir key -> ... haritasi kullanir (bkz. asagida Sonuc formati); gruplama yalniz sizin sablon duzeninizin bir parcasidir.

doviz_kuru ise hic fields icine girmez — nedeni bir sonraki basliktaki kaynak_tanimi kurali.

Operator alanlari LLM'e hic gitmez

kaynak_tanimi degeri "operator" ya da "otomatik" kelimelerini iceren bir alan, belgeden cikarilamayacagi varsayilan (operator tarafindan elle girilecek ya da baska bir sistemden otomatik gelecek) bir alan sayilir. Bu alanlar:

• hicbir zaman LLM'e sorulmaz (ne aday toplama adiminda, ne baska bir yerde) — bosuna mikro-cagri harcanmaz,
• sonuc govdesinde dogrudan missing altinda {"key": "doviz_kuru", "reason": "operator_input"} olarak listelenir.

Bu, "belgede bulunamadi" (not_found) ile bilerek ayri bir nedendir — istemci tarafinizda ikisini farkli isleyebilirsiniz (biri "belgeleri tekrar kontrol et", digeri "operator bu alani dolduracak").

Bilinmeyen anahtarlar

Kanonik ya da gumruk formatinda taninmayan herhangi bir anahtar (yukaridaki ornekteki mikro_cagri gibi) sessizce yok sayilir — hata uretmez. Kendi sablon meta-verinizi (versiyon numarasi, ic notlar vb.) semanin icinde tasimak istiyorsaniz guvenle yapabilirsiniz.

Sonuc formati

{
  "filled": {
    "teslim_sekli": {
      "value": "CIF",
      "confidence": 0.95,
      "sources": [
        { "document_id": "d_a1b2c3", "doc_type": "commercial_invoice", "page": 1, "quote": "Teslim sekli: CIF Rotterdam" }
      ]
    }
  },
  "conflicts": [
    {
      "key": "kap_adedi",
      "values": [
        { "value": "12", "sources": [{ "document_id": "d_a1b2c3", "doc_type": "commercial_invoice", "page": 1, "quote": "12 kap" }] },
        { "value": "14", "sources": [{ "document_id": "d_d4e5f6", "doc_type": "packing_list", "page": 1, "quote": "14 kap" }] }
      ]
    }
  ],
  "missing": [
    { "key": "doviz_kuru", "reason": "operator_input" },
    { "key": "odeme_sekli", "reason": "not_found" }
  ],
  "stats": {
    "fields_total": 30,
    "filled": 21,
    "conflicts": 2,
    "missing": 7,
    "documents_used": 9,
    "llm_calls": 9,
    "duration_ms": 48000
  }
}

filled

key -> {value, confidence, sources[]} haritasi. Yalniz tek, tutarli bir deger bulunan alanlar buraya girer — bkz. asagida Guven skorlari ne anlama gelir, hangi durumun hangi skoru urettigi icin. sources[], degeri destekleyen her belge icin document_id, doc_type, page ve degerin GERCEKTEN gectigi quote'u tasir — quote, kaynak belgenin metninde dogrulanmis (UYDURULMAMIS) bir alintidir (bkz. asagida Uydurma kalkani).

conflicts

Ayni alan icin normalize edildikten sonra bile farkli iki ya da daha fazla deger bulunduysa alan filled'a GIRMEZ — bunun yerine conflicts altinda key ve o alan icin bulunan her farkli value'nun kendi sources[]'iyle birlikte listelenir. Bu bilincli bir tercihtir: sema-doldurma hangi degerin "dogru" olduguna asla kendi basina karar vermez, celiskiyi oldugu gibi yuzeye cikarir (bkz. yukaridaki ornekte kap_adedi: fatura 12, ceki listesi 14 diyor — ikisi de kalir, hicbiri sessizce secilmez).

missing

{key, reason} ciftlerinin listesi. reason iki degerden biridir:

stats

Guven skorlari ne anlama gelir

confidence, filled altindaki her deger icin, o degerin ne kadar capraz dogrulanmis oldugunu yansitan sabit bir olcektir — modelin kendi beyan ettigi bir "emin miyim" skoru degildir, sunucu tarafinda saf kod ile (LLM'siz) hesaplanan bir karardir:

Iki ya da daha fazla farkli deger bulunursa (normalize edildikten sonra bile es olmuyorsa) alan bir confidence degeri almaz — bunun yerine conflicts'e duser (yukariya bkz.). confidence yalniz kaynak sayisini/turunu olcer, degerin dogru oldugunu garanti etmez — dusuk guvenli (0.5) alanlari istemci tarafinizda "goz atilmasi onerilir" olarak isaretlemeniz onerilir.

Cozumleme motoru (deterministik-once)

Sema doldurma, mumkun oldugunca LLM'i minimumda tutan, kararlari saf kodla veren bir motordur — line-item cikariminda kanitlanmis desenin (bkz. Veri Cikarimi → Line items) ayni felsefesi.

Aday toplama — belge basina tek LLM cagrisi

Sema doldurma alan basina degil belge basina LLM'e gider: 9 belge x 30 alan = 270 cagri felaketi yerine, her belge icin tek bir cagri yapilir — belgenin canonical markdown'i (uzunluk sinirlariyla) ve o belgenin doc_type'ina gore ilgili alan alt kumesi (bu belge primary_docs/verify_docs listesinde geciyor, ya da alanin doc-type kisiti yok) modele birlikte verilir; model her ilgili alan icin {value, quote, page?} doner. Bu yuzden stats.llm_calls, alan sayisiyla degil documents_used ile olceklenir.

Uydurma kalkani

Modelin dondugu her aday, kabul edilmeden once kaynak belgenin normalize edilmis metninde ARANIR: aday quote o belgede gercekten gecmiyorsa aday dusurulur — hicbir deger, kaynak metinde dogrulanmadan filled/conflicts'e giremez. Sayfa numarasi da modelin beyanindan degil, quote'un gercekten bulundugu sayfadan deterministik olarak turetilir.

Normalizasyon

Karsilastirma normalize edilmis degerler uzerinden yapilir: bosluk/buyuk- kucuk harf duyarsiz karsilastirma; sayilar icin Avrupa (1.234,56) / US (1,234.56) format farki giderilir; tarihler ISO 8601'e cevrilir (cevrilemeyen tarih oldugu gibi karsilastirilir). v1'de ulke kodu/adi esleme yoktur ("TR" ile "Turkiye" farkli deger sayilir, tipki line-items'taki gibi) — ham karsilastirma.

Karar kurallari

Normalize edilmis adaylar toplandiktan sonra karar tamamen saf kodla verilir (LLM ikinci kez cagirilmaz):

1. primary_docs'tan bir deger + verify_docs'tan ayni (normalize) deger → filled, confidence: 0.95.
2. Yalniz primary_docs'tan deger → filled, confidence: 0.7.
3. Yalniz verify_docs/diger belgelerden deger → filled, confidence: 0.5.
4. Normalize edildikten sonra 2+ farkli deger → conflicts (alan filled'a girmez).
5. Hic aday yok → missing, reason: "not_found" (kaynak_tanimi operator/otomatik ise LLM'e hic gitmeden dogrudan reason: "operator_input").

LLM cagrilari resolve_lane(tenant, "structuring") uzerinden aynı model seçimi/BYOK altyapısını kullanır (bkz. Baslangic ve Auth → Model secimi & BYOK) — sema doldurma icin ayri bir model lane'i icat edilmez.

Auth ve entitlement

Set CRUD uc noktalari yalniz gecerli bir Authorization: Bearer <api_key> ister (yukariya bkz.). Sema doldurma uc noktalari (POST/GET /v1/sets/{id}/extract*) ek olarak extract modul entitlement'i ile korunur — extract icin yetkilendirilmemis bir key 403 service_not_enabled doner (bkz. Baslangic ve Auth → Entitlement).

Faturalama

Sema doldurma SET_EXTRACT_RATE ile ucretlendirilir, varsayilan 0.05 kredi x setteki belge sayisi:

Ornegin 9 belgeli bir sette bir kosu 9 x 0.05 = 0.45 kredi'dir — semadaki alan sayisindan bagimsizdir (30 alanlik bir sema ile 3 alanlik bir sema ayni belge sayisinda ayni ucrete tabidir). Bakiye kontrolu istek oncesi yapilir (POST uzerinde 402 insufficient_credit); ucret, kosu basariyla tamamlandiginda bir kez alinir — GET ile yoklama her zaman ucretsizdir ve kosu status: "failed" ile sonuclanirsa ucretlendirme HIC yapilmaz (/v1/ask ile ayni "basarisiz senteze ucret yok" deseni, bkz. Soru-Cevap → Kredi ve ucretlendirme). dip_test_... key'ler icin cagri yine olculur ama bakiyeden dusulmez.

Kullanim vakasi: Gumruk beyannamesi hazirligi

Senaryo: ACME GmbH'nin bir sevkiyati icin 6 belge (ticari fatura, ceki listesi, konsimento, navlun faturasi, sigorta poliçesi, mense sahadetnamesi) zaten yuklenmis ve islenmis. Amac: bu belgelerden gumruk beyanname sablonundaki alanlari doldurup insan operatorun gozden gecirecegi bir "beyana-hazir" cikti uretmek.

1. Sevkiyatin belgelerini bir set'te grupla:

curl -X POST https://api.docsfra.com/v1/sets \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME GmbH - INV-2026-0001",
    "document_ids": ["d_a1b2c3", "d_d4e5f6", "d_a7b8c9", "d_c3d4e5", "d_e5f6a7", "d_f6a7b8"]
  }'

→ set_8f3a1b2c.

2. Gumruk beyanname sablonunu (gruplu, kaynak_tanimi iceren gumruk formatinda, 32 alanli) oldugu gibi yapistirip sema doldurmayi baslat:

curl -X POST https://api.docsfra.com/v1/sets/set_8f3a1b2c/extract \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"schema": { "baslik_alanlari": { "...": "..." } }, "language": "tr"}'

→ 202 Accepted, {"run_id": "sxr_4d9e2f1a"}.

3. 2-3 saniyede bir yokla, completed olunca sonucu al:

curl https://api.docsfra.com/v1/sets/set_8f3a1b2c/extract/sxr_4d9e2f1a \
  -H "Authorization: Bearer dip_live_a1b2c3d4e5f6..."

4. Beyana-hazir cikti:

{
  "status": "completed",
  "result": {
    "filled": {
      "teslim_sekli": { "value": "CIF", "confidence": 0.95, "sources": ["..."] },
      "mense_ulke": { "value": "DE", "confidence": 0.7, "sources": ["..."] }
    },
    "conflicts": [
      {
        "key": "kap_adedi",
        "values": [
          { "value": "12", "sources": [{ "document_id": "d_a1b2c3", "doc_type": "commercial_invoice", "page": 1, "quote": "12 kap" }] },
          { "value": "14", "sources": [{ "document_id": "d_d4e5f6", "doc_type": "packing_list", "page": 1, "quote": "14 kap" }] }
        ]
      }
    ],
    "missing": [
      { "key": "doviz_kuru", "reason": "operator_input" },
      { "key": "gtip_ek_aciklama", "reason": "not_found" }
    ],
    "stats": { "fields_total": 32, "filled": 24, "conflicts": 2, "missing": 6,
               "documents_used": 6, "llm_calls": 6, "duration_ms": 34500 }
  }
}

Operatorun is akisi netlesir: 24 alan dogrudan beyanname formuna tasinabilir (guven skoruna gore hangisinin cift-kontrol gerektirdigi belli), kap_adedi celiskisi (fatura 12 / ceki listesi 14) insan gozden gecirmesine dusurulur, doviz_kuru zaten operator tarafindan girilecegi bilinen bir alan olarak isaretlenir (hicbir belgede aranmaz), gtip_ek_aciklama ise belgelerde gercekten bulunamadigi icin ayri bir kovadadir.

Notlar

Sema doldurma, mevcut cikarim katmanlarinin (memory, structured objects, entities, reasoning — bkz. Veri Cikarimi) uzerine kurulan bir kompozisyon katmanidir; kendi ayri bir belge temsili uretmez. Bir setteki belgelerden biri henuz completed olmadiysa ya da canonical markdown'i yoksa, o belge sadece o kosuda aday uretmez — kosunun tumunu basarisiz kilmaz.