PDF, DOCX, TXT, CSV ve XLSX belgelerini ayrıştırın, sayfa başına KKV tespit edin ve redakte edilmiş bir kopya indirin.

Bir belgeden metin çıkarın — taranmış sayfalar için OCR ile — KKV ve güvenlik sorunları açısından tarayın ve daha sonra indirebileceğiniz redakte edilmiş bir kopya üretin.

Warning

Her /document-analysis yolu yalnızca JWT koruyucusuyla korunur. Bir ağ geçidi API anahtarı (cid_key_…) bu uç noktaları çağıramaz.

Uç noktalar

Metot	Yol	Gövde
POST	`/document-analysis/analyze`	base64 taşıyan JSON
POST	`/document-analysis/analyze-file`	Çok parçalı, alan adı `file`
POST	`/document-analysis/redact-jobs`	Çok parçalı `file`; asenkron redaksiyon işi başlatır
GET	`/document-analysis/redact-jobs/:jobId`	Bir redaksiyon işini sorgular
GET	`/document-analysis/supported-types`	Ayrıştırılabilir türler ve OCR desteği
GET	`/document-analysis/status`	Belge ayrıştırıcısına erişilebilirlik
GET	`/document-analysis/:id/download`	Redakte edilmiş belgeyi akış hâlinde gönderir

Bir belgeyi analiz etme (JSON)

POST /document-analysis/analyze

Parametre	Tür	Gerekli	Açıklama
`documentBase64`	string	Evet	Base64 kodlanmış belge
`documentType`	string	Evet	`pdf`, `docx`, `txt`, `csv` veya `xlsx`
`sessionId`	string	Hayır	Tespitleri bu oturuma kaydeder
`redact`	boolean	Hayır	Redakte edilmiş bir kopya üretir. Varsayılan `true`
`parseOptions`	object	Hayır	`ocrScannedPages` (varsayılan `true`), `ocrLanguage` (varsayılan `en`), `ocrEngine`, `extractTextBlocks` (varsayılan `true`), `includeMetadata` (varsayılan `true`), `filename`
`processingMode`	string	Hayır	`text` (varsayılan) veya `visual`
`renderDpi`	number	Hayır	72–300, varsayılan `150`. `visual` modda geçerlidir

curl -X POST https://<appliance-fqdn>/document-analysis/analyze \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "documentBase64": "JVBERi0xLjQK...",
    "documentType": "pdf",
    "redact": true
  }'

Bir belgeyi analiz etme (çok parçalı)

POST /document-analysis/analyze-file

Çok parçalı yol, base64 yerine ham bir yükleme alır; bu da base64'ün getirdiği yaklaşık üçte birlik şişmeyi ortadan kaldırır. Dosya alanının adı file'dır. Belge türü dosya uzantısından türetilir, dolayısıyla documentType gönderilmez.

Form alanı	Gerekli	Açıklama
`file`	Evet	Belge. En fazla 20 MB
`redact`	Hayır	`false` dizesi redaksiyonu kapatır; başka her değer açık bırakır
`sessionId`	Hayır	Tespitleri bu oturuma kaydeder

curl -X POST https://<appliance-fqdn>/document-analysis/analyze-file \
  -H "Authorization: Bearer <jwt>" \
  -F "file=@statement.xlsx" \
  -F "redact=true"

Uzantılar

Uzantı	Şu tür olarak ayrıştırılır
`.pdf`	`pdf`
`.docx`	`docx`
`.txt`	`txt`
`.csv`, `.tsv`	`csv`
`.xlsx`	`xlsx`

Danger

.xls, .xlsm, .xlsb, .xlt ve .xltm 415 ile reddedilir. Eski ikili ve makro etkin çalışma kitapları doğrulanabilir biçimde redakte edilemez — bir makro, boyanarak kaldırılan veriyi yeniden oluşturabilir — bu yüzden ağ geçidi, güvence veremeyeceği bir kopya döndürmek yerine bunları engeller. Dosyayı makrosuz .xlsx olarak kaydedip yeniden yükleyin.

Tanınmayan bir uzantı da 415 döndürür ve desteklenenleri listeler. Dosya parçası olmayan bir istek 400 ve No file uploaded (expected multipart field "file") döndürür.

Yanıt

Her iki analiz yolu da aynı yapıyı döndürür.

{
  "success": true,
  "analysisId": "a1b2c3d4-0000-0000-0000-000000000000",
  "documentType": "pdf",
  "pageCount": 4,
  "totalWordCount": 1280,
  "action": "mask",
  "detections": [
    { "type": "EMAIL", "value": "[EMAIL]", "action": "mask", "confidence": 0.95, "pageNumber": 1 }
  ],
  "pageResults": [
    { "pageNumber": 1, "wordCount": 320, "isScanned": false, "detectionCount": 3 }
  ],
  "wasRedacted": true,
  "ocrPages": 0,
  "processingTimeMs": 2540
}

Alan	Tür	Açıklama
`success`	boolean	Analizin tamamlanıp tamamlanmadığı
`analysisId`	string	Bunu `/document-analysis/:id/download` uç noktasına verirsiniz
`documentType`, `pageCount`, `totalWordCount`	—	Neyin ayrıştırıldığı
`action`, `actionReason`	string	Kararlaştırılan eylem ve gerekçesi
`detections`	array	`{type, value, confidence, action, pageNumber?, filterName?, placeholder?}`
`pageResults`	array	Sayfa başına kelime sayısı, tarandı bayrağı ve tespit sayıları
`redactedDocumentBase64`	string	Üretildiğinde redakte edilmiş kopya
`wasRedacted`	boolean	Redaksiyonun çalışıp çalışmadığı
`ocrPages`	number	Kaç sayfanın OCR gerektirdiği
`extractedText`, `redactedText`	string	Öncesi ve sonrası düz metin
`processingMode`	string	Uygulandığı hâliyle `text` veya `visual`
`redactionVerified`	boolean	Redakte edilmiş kopyanın, tespit edilen değerleri artık içermediğinin denetlenip denetlenmediği
`renderedPages`, `tablePreview`	—	Görsel mod ve hesap tabloları için bulunur
`error`	string	Analiz başarısız olduğunda bulunur

Metin yolunda olduğu gibi value, eşleşen metni değil yer tutucuyu taşır.

Ağ geçidinin okuyamadığı bir belgenin kararı

Karar bir etiket değil, bir kapıdır: panel Send to AI düğmesini yalnızca analizin gerçekten okuduğu ve reddetmediği bir belge için gösterir. Bu nedenle iki durum asla allow olarak dönmez.

Durum	`action`	`actionReason`
Belge ayrıştırılamadı — eski ya da şifreli `.xls`, makro içeren çalışma kitabı, bozuk kapsayıcı veya ayrıştırıcı servisine ulaşılamaması	`reject`	`Not inspected: the document could not be parsed: …`
Ayrıştırma başarılı oldu ama hiç metin üretmedi	`flag`	`Not inspected: no text could be extracted from this document`

Bu değişiklikten önce ayrıştırma hatası flag, boş çıkarım ise allow olarak dönüyordu; playground bunları "Flagged" ve "Safe" olarak gösteriyor ve gönderme düğmesi açık kalıyordu. Kural artık tarayıcı denetimi yolundaki davranışla aynı: ayrıştırması başarısız olan bir çalışma kitabı okunmadan geçirilmez, engellenir.

Hesap tablolarında ayrıca her çıkarılan sayfanın başına sentetik bir Columns: a;b;c satırı eklenir; böylece bir .xlsx ile aynı tablonun .csv hâli aynı biçimde tanınır. Veri hücreleri değişmez.

Desteklenen türler

GET /document-analysis/supported-types

Belge ayrıştırıcısının bildirdiği türleri, her birinin uzantıları, MIME türleri ve OCR desteğiyle birlikte döndürür. Ayrıştırıcı hizmetine erişilemediğinde ağ geçidi 503 döndürür; bu yüzden bu uç nokta aynı zamanda o hizmet için bir sağlık yoklaması işlevi görür.

Redakte edilmiş bir belgeyi indirme

GET /document-analysis/:id/download

Daha önceki bir analizin ürettiği redakte edilmiş belgeyi, analysisId ile adresleyerek akış hâlinde gönderir.

curl -X GET https://<appliance-fqdn>/document-analysis/a1b2c3d4-0000-0000-0000-000000000000/download \
  -H "Authorization: Bearer <jwt>" \
  -o redacted.pdf

İlgili sayfalar

Görüntü analizi — aynı hattın görüntüler üzerinde, OCR ile çalışması.
KKV tespiti — çıkarılan metnin hangi varlık türleri için tarandığı.
İçerik tespiti — bu yanıtların paylaştığı tespit sözleşmesi.

Belge analizi