Baslangic ve Auth

Docsfra API, dokumanlarinizi cikarimdan AI-hazir aranabilir/sorgulanabilir hale getiren, modul modul calisan bir M2M (makine-to-makine) arayuzdur. Bu bolum entegrasyona baslamadan once bilmeniz gereken temel kavramlari anlatir: API key, Bearer auth, entitlement (modul yetkisi), metering (kredi) ve hata/rate-limit davranisi.

Docsfra nedir

Bir dokuman yukledikten sonra sunucu tarafinda modul modul islenir:

cikarim (extract) -> yapilandirma (structure) -> embedding (embed) -> indeksleme (index)

Bu boru hatti arka planda otomatik ilerler — asamalari ayri ayri tetiklemeniz gerekmez. Dokuman indekslendikten sonra iki sorgu modulu devreye girer: semantik arama (search) ve soru-cevap/RAG (ask). Her modul ayri ayri faturalandirilir (bkz. Metering ve kredi) ve ayri ayri yetkilendirilir (bkz. Entitlement).

Uctan uca akis

Tipik bir entegrasyon su sirayla ilerler:

Key olustur — dashboard'da (app.docsfra.com) bir API key uretin, hangi modullere yetkili olacagini secin.
Belge yukle — POST /v1/documents (ya da coklu dosya icin POST /v1/batches); id degeri aninda doner, isleme arka planda devam eder.
Isi yokla — GET /v1/jobs/{id} ile durumu kontrol edin (queued -> processing -> parsing -> indexing -> completed/failed).
Opsiyonel: webhook alin — polling yerine (ya da onunla birlikte) document.completed / document.failed bildirimi alin.
Semantik arama yapin — GET /v1/search ile indekslenmis dokumanlarda chunk-seviyeli hibrit arama yapin.
Soru sorun — POST /v1/ask ile retrieval ve sentezi tek cagrida birlestiren RAG uc noktasini kullanin.

Bu adimlarin her biri kendi sayfasinda detaylandirilir: Upload, Polling, Webhook, Semantik Arama, Soru-Cevap.

API key

Her istek bir API key ile kimliklendirilir. Key iki tipte gelir:

dip_live_... — gercek tenant verisi; entitlement, metering ve rate limit'e tam tabidir.
dip_test_... — staging/entegrasyon testleri icin; billing ve tenant-bazli rate limit'ten muaftir, bunun yerine sabit ve comert bir hard-cap'e tabidir (varsayilan 1000 istek/gun, key basina). Test key entitlement kontrolunden muaf degildir — yetkisiz bir modulu cagirirsa yine 403 service_not_enabled alir.

Key'ler yalnizca dashboard'dan (app.docsfra.com, oturum tabanli auth ile) olusturulur ve iptal edilir — API'nin kendisi key CRUD islemi sunmaz. Key olustururken hangi modullere yetkili olacagini da secersiniz (bkz. Entitlement). Yeni bir key olusturuldugunda ham deger yalnizca o cevapta gorunur, sonrasinda tekrar gosterilmez — guvenli bir yerde saklayin.

Bearer ile kimliklendirme

Tum istekler Authorization basligina Bearer seklinde key icermelidir:

Authorization: Bearer dip_live_a1b2c3d4e5f6...

Eksik/gecersiz key -> 401 unauthorized
Iptal edilmis (revoke) key -> yine 401 unauthorized, mesaj invalid_or_revoked_key
Key dogrulandiktan sonra tum sorgular otomatik olarak o key'in tenant'ina scope edilir. Baska bir tenant'a ait bir kaynagi id ile sorgulasaniz bile 404 donulur (kaynagin varligini sizdirmamak icin 403 degil).

Entitlement: modul bazli erisim

Her API key, yalnizca kendisine tanimlanmis modullere erisebilir. Modul kodlari: extract | structure | embed | index | search | ask | media-cdn | md-cdn. Bir key'in yetkili oldugu modul listesi dashboard'da key olusturulurken/duzenlenirken secilir ve her zaman tenant'in plan kapsamiyla sinirlidir — bir key, tenant'in sahip olmadigi bir module yetkilendirilemez.

Bir istek, key'in yetkili olmadigi bir modulu cagirirsa 403 service_not_enabled doner:

{
  "error": {
    "code": "service_not_enabled",
    "message": "Bu API anahtari 'ask' modulune yetkili degil",
    "request_id": "req_9f8a7b6c"
  }
}

Bu kontrol kredi bakiyesinden bagimsizdir — bakiyeniz yeterli olsa bile yetkisiz bir modulu cagiramazsiniz.

Metering ve kredi

Basarili her modul cagrisi tenant kredi bakiyesinden dusulur. Yeni kaydolan her tenant 250 kredi welcome bonusu ile baslar. Bakiye, cagrilan islemin maliyetini karsilamiyorsa istek on-kontrolde reddedilir: 402 insufficient_credit.

dip_test_ key'ler icin cagrilar yine olculur (usage kaydi olusur) ama bakiyeden dusulmez.

Varsayilan (global) katalog oranlari:

Modul	Aciklama	Birim	Varsayilan oran
`extract`	Cikarim	sayfa	1.00
`structure`	Yapilandirma (reasoning)	sayfa	0.50
`embed`	Embedding	1K token	0.02
`index`	Vektor indeksleme	1K chunk-ay	0.10
`search`	Hibrit arama	sorgu	0.02
`ask`	RAG soru-cevap	sorgu	0.20
`memory`	Belge Kimlik Karti (Document Memory)	belge	0.10
`entities`	Varlik Grafi (Entity Graph)	belge	0.15
`reasoning`	Mantik Grafi (Reasoning Graph)	belge	0.15
`layout`	Yerlesim/bbox (Layout Model)	sayfa	0.05
`media-cdn`	Media CDN	GB-ay	0.05
`md-cdn`	Markdown CDN	GB-ay	0.02

Bu oranlar tenant basina override edilebilir; gecerli oranlarinizi her zaman dashboard'daki usage/fiyat ekraninda gorebilirsiniz — buradaki tablo yalnizca varsayilan referans degerleridir.

Not: extract/structure/embed/index/search/ask'in aksine (her cagrida ucretlendirilir), memory/entities/reasoning/layout belge basina bir kez (layout icin sayfa basina bir kez) o artifact uretildigi anda ucretlendirilir — sonrasinda uc noktasindan okumak ucretsizdir (bkz. Veri Cikarimi ve Artifact'ler → Fiyatlandirma).

Hata formati

Tum hatalar ayni zarfla doner:

{ "error": { "code": "...", "message": "...", "request_id": "..." } }

En sik karsilasilan kodlar:

HTTP	code	Anlami
400	`invalid_request`	Eksik/hatali alan
401	`unauthorized`	Eksik, gecersiz veya revoke edilmis key
402	`insufficient_credit`	Bakiye, islemin maliyetini karsilamiyor
403	`service_not_enabled`	Key, cagrilan module yetkili degil
404	`not_found`	Kaynak yok ya da baska tenant'a ait
413	`payload_too_large`	Dosya boyutu limiti asildi
422	`unprocessable_file`	Desteklenmeyen format ya da bozuk dosya
429	`rate_limited`	Throttle limiti asildi (`Retry-After` ile)
500	`internal_error`	Beklenmeyen sunucu hatasi
503	`service_unavailable`	Alt sistem gecici olarak musait degil

Rate limit

Rate limit tenant bazinda anahtarlanir (IP bazinda degil); dip_test_ key'ler ise kendi key'lerine ozel sabit bir hard-cap'e tabidir:

Scope	Kapsam	Limit
`tenant_upload`	`POST /v1/documents`, `/v1/batches`	60 / dakika
`tenant_status`	`GET /v1/jobs/{id}`, `/v1/batches/{id}`	600 / dakika
`tenant_search`	`GET /v1/search`	300 / dakika
`tenant_ask`	`POST /v1/ask`	60 / dakika
`test_key_hard_cap`	`dip_test_` key, tum uc noktalar	1000 / gun (key basina)

Limit asildiginda 429 rate_limited doner ve cevapta Retry-After basligi bulunur — bu, tekrar denemeden once beklenmesi gereken saniye sayisidir:

HTTP/1.1 429 Too Many Requests
Retry-After: 42

Retry-After degerine uyup istemci tarafinda exponential backoff uygulamaniz onerilir.

Model seçimi & BYOK

Tamamen isteğe bağlı — hiçbir şey yapılandırmazsan Docsfra varsayılanları geçerlidir ve hiçbir şey değişmez. Her işlem hattı için (structuring, contextual, memory, entity, reasoning, rag) OpenRouter kataloğundaki dilediğin modeli seçebilir, istersen kendi sağlayıcı API anahtarını getirebilirsin. Yapılandırma Console'daki Modeller sayfasındadır.

Mod	Anahtar	Model	Faturalama
Varsayılan	Docsfra	Docsfra varsayılanları	sabit artifact tarifesi (değişmez)
Özel model	Docsfra	senin seçimin	sabit tarife + `model-usage`: listelenen model fiyatı üzerinden token başına krediye çevrilir
BYOK	senin	senin seçimin	yalnız sabit artifact tarifesi — model maliyeti kendi sağlayıcı faturana

Dilediğin lane'i kendi OpenAI-uyumlu uç noktana da yönlendirebilirsin (Azure OpenAI, vLLM, Ollama, LiteLLM…): uç nokta URL'ini gir (base URL girersen /chat/completions otomatik eklenir) ve model adını serbest metin yaz; self-host motorlarda API anahtarı opsiyoneldir. Özel uç noktalar genel internetten erişilebilir olmalıdır.

Anahtar güvenliği: BYOK anahtarları şifreli saklanır, asla loglanmaz ve API tarafından asla geri döndürülmez (yalnız son-4 haneli key_hint). Anahtarın sağlayıcı tarafından reddedilirse çekirdek endpoint'ler (/v1/ask) net bir hata döner — Docsfra hiçbir zaman sessizce platform anahtarına düşmez. Her işlem adımı kullanılan modeli belgenin provenance zincirine kaydeder; model seçimi tamamen denetlenebilirdir.