Mevzuat Detayı

Regülasyonun tam AI çıktısını döner: özet, sınıflandırma, yükümlülükler, kurum/departman/konu etiketleri ve ham metadata. /documents/{id} ile karıştırmayın — /library/{id} yanıtı compliance iş akışları için zenginleştirilmiştir.

`/documents/

/documents/{id}:

• sourceName, sourceUrl, documentFormat, hasDownloadableFile alanları vardır.
• summary, classification, metadata ve obligations da döner; etiket listeleri yoktur.

/library/{id}:

• sourceUrl, documentFormat, hasDownloadableFile alanları da vardır; yalnızca sourceName yoktur — kaynak adı için GET /library/sources üzerinden bir id→ad haritası kurun.
• isSubscribed — bu API anahtarının kiracısı bu mevzuata abone mi. Kiracı mevzuatın herhangi bir nüshasına (bu belgeye, sahibine ya da ikizlerinden birine — aşağıda "İkiz nüshalar") abone ise true döner. Kiracıya özeldir ve önbelleklenen gövdenin dışında doldurulur.
• institutionTypes, departments, topics etiket listeleri (etiket değerleri InstitutionType/DepartmentType/TopicType enum okunabilir değerlerine dönüştürülmüştür).
• obligations yapılandırılmış dizi: {id, ordinal, title?, description, deadline?, penalty?, severity?, confidence?, sourceFile?}.
• canonicalDocumentId ve twins — ikiz nüsha bilgisi (aşağıda). /documents/{id} bu iki alanı taşımaz.
• isPackage, files[], packageNote, aiBasisFiles, filesOutsideAi — zip paketi bilgisi (aşağıda). /documents/{id} bu alanları taşımaz.
• processingNote — belgenin işlenmesine ilişkin Türkçe müşteri notu, her biçimde (aşağıda); not yoksa null.

Belgenin çıkarılmış tam metni bu yanıtta yer almaz; onun için ayrı bir uç nokta vardır: GET /library/{id}/text.

İkiz nüshalar: canonicalDocumentId ve twins

Aynı mevzuat birden çok kaynakta yayımlanabilir (örneğin hem Resmî Gazete'de hem mevzuat.gov.tr'de); kütüphaneye her nüsha ayrı bir belge olarak girer. Regvion böyle bir mevzuatı bir kez analiz eder: analizi gösterilen nüsha analizin sahibidir; aynı mevzuatın öbür nüshaları sahibin ikizi olarak işaretlenir ve ayrıca analiz edilmez.

Sahiplik değişebilir. Aynı mevzuatın belirgin biçimde daha eksiksiz bir nüshası sonradan gelirse analizin sahipliği o nüshaya geçer ve önceki sahip onun ikizi olur. Bu yüzden daha önce sahip olarak kaydettiğiniz bir id sonradan canonicalDocumentId döndürebilir: işaretçiyi bir kez okuyup saklamayın, her okumada izleyin.

• canonicalDocumentId — doluysa bu belge bir ikizdir ve değer sahibin id'sidir. Özet, sınıflandırma, yükümlülükler ve etiketler sahipte yer alır; ikizin kendi bu alanları boş (ya da eski bir analizden kalma) olabilir. Tam analiz için GET /library/{canonicalDocumentId} çağırın; dönen id her zaman işlenmesi tamamlanmış, kendisi ikiz olmayan bir belgedir. null iki anlama gelir ve bu ikisi yanıttan ayırt edilemez:
  • belge kendi analizinin sahibidir (ikizi olmayan sıradan belge de böyledir); ya da
  • belge bir ikizdir ama sahibi geçici olarak kullanılamıyordur — yeniden işleniyordur, işlenmesi başarısız olmuştur ya da silinmiştir. Bu durumda yanıt ikizin kendi kaydıdır (özet ve yükümlülükler boş olabilir). Sahip yeniden kullanılabilir olduğunda işaretçi kendiliğinden geri gelir; sahip kalıcı olarak yoksa analiz başka bir nüshaya geçer ya da belge kendi analizinin sahibi olur.
• twins — bu belgeye işaret eden ikiz nüshalar: [{ "id", "sourceShortCode", "sourceName", "sourceUrl" }]. sourceUrl ikizin yayım organındaki orijinal adresidir (örneğin mevzuat.gov.tr'deki metin). Yalnız işlenmesi tamamlanmış ikizler listelenir, yani her id GET /library/{id} ile açılabilir. İkizi olmayan belgede ve ikizin kendisinde boş dizi döner (null değil).

İkiz nüshalar kütüphane listelerinde ve aramada ayrı kart olarak görünmez. Elinizde bir ikiz id'si olabilir: ikizi daha önce kaydetmiş ya da ona abone olmuş olabilirsiniz, kaydettiğiniz bir sahip de sonradan ikiz olmuş olabilir. Her okumada canonicalDocumentId'yi izleyin. /library/{id}/obligations ikizde ikizin kendi listesini döner; sahibin yükümlülükleri için sahibin id'sini kullanın.

Paketler (zip): isPackage, files[] ve ilgili alanlar

Bazı kurumlar bir mevzuatı tek bir zip paketi olarak yayımlar (ör. TCMB talimatları: ana metin, ekler, form şablonları). Regvion paketi tek belge olarak tutar; içindeki dosyalar o belgenin files[] listesindedir. Paket olmayan belgede isPackage false, files[] ve aiBasisFiles boş dizi, packageNote null, filesOutsideAi 0'dır.

• isPackage — belge bir zip paketi mi (documentFormat = 5, Archive).
• files[] — paketteki dosyalar, gösterim sırasıyla (önce ana metin, sonra ekler, form şablonları ve yalnız indirilebilir dosyalar). Çöp dosyalar (Thumbs.db, ~$…, __MACOSX/) listelenmez. Her öğe:
  • id — dosya kimliği; Paket Dosyası İndir ve Paket Dosyasının Metni bunu alır. Dosyanın paket içindeki yoluna bağlıdır: paket yeniden işlendiğinde dosya aynı yolla pakette kaldıkça değişmez; paketten çıkan dosyanın kimliği geçersizleşir.
  • path — paket içindeki yol (/ ile ayrılmış); name — yolun son bölümü (dosya adı).
  • size — açılmış boyut (bayt); pageCount — PDF'lerde sayfa sayısı (bilinmiyorsa null).
  • kind, role, status — dosyanın türü, paketteki rolü ve işlenme durumu; değerler Enum Referansı'nda.
  • inAiAnalysis — dosyanın metni AI analizine (özet, yükümlülükler) girdi mi.
  • hasText — dosyanın çıkarılmış metni var mı (metni Paket Dosyasının Metni ucu verir).
  • note — sınır, şifre ya da okuma hatası açıklaması (Türkçe) veya null.
• packageNote — paket bir sınıra takıldıysa ya da içindeki bir dosya okunamadıysa müşteriye gösterilecek Türkçe not (ör. "Bu paket büyük olduğu için ilk 150 dosya işlendi; tamamı için paketi indirin."); aksi null.
• aiBasisFiles — AI özetinin dayandığı dosyaların adları (inAiAnalysis = true), gösterim sırasıyla.
• filesOutsideAi — metni olduğu hâlde AI analizine girmeyen dosya sayısı. AI paket başına en çok 200.000 karakter okur; bu dosyaların metni yine okunabilir ve anlamlı aramada bulunabilir.

Yükümlülüklerdeki sourceFile — { "id", "path", "name" } — yükümlülüğün alıntısının bulunduğu paket dosyasıdır; bulunamadıysa, dosya artık pakette değilse ya da belge paket değilse null.

İşlem notu: processingNote

processingNote, belgenin işlenmesine ilişkin müşteriye gösterilecek Türkçe nottur ve her biçimde dolabilir; not yoksa null'dır. Örnekler:

• Okunamayan bir Word belgesi (bozuk, parola ile şifrelenmiş, desteklenmeyen sürüm ya da boyut sınırını aşan): "Word dosyası okunamadı (dosya bozuk); dosyayı indirerek açabilirsiniz." Böyle bir belgenin metni ve AI özeti yoktur; dosyası Doküman İndir ile indirilebilir.
• Okunabilir ama metni olmayan (yalnız görsel içeren) Word belgesi.
• Kaynağın yayımladığı son dosya okunamadığı için önceki sürümün metni gösterilen belge: "Kaynağın yayımladığı son dosya okunamadı (…); gösterilen metin önceki sürümdendir. Dosyayı indirerek açabilirsiniz."
• Zip paketinde packageNote ile aynı metin.

30 dakikalık önbellek

Yanıt sunucu tarafında 30 dakika önbelleklenir. Yayın sonrası veya AI yeniden analizi sonrası 30 dakikaya kadar eski veri dönebilir. Bir paket yeniden işlendiğinde ya da belgenin processingNote'u değiştiğinde önbellek kaydı temizlenir. Yeni bir ikizin işlenmesi tamamlandığında sahibin önbellek kaydı temizlenir, ikiz twins listesine normalde hemen yansır; en geç 30 dakika.

isSubscribed bu önbelleğin dışındadır: her istekte, kiracınıza göre hesaplanır. canonicalDocumentId için iki durum vardır:

• Belgenin önbellek kaydında işaretçi varsa sunulan değer her istekte sahibin o andaki durumuna göre yeniden kararlaştırılır (sahip kullanılamıyorsa null döner, yeniden kullanılabilir olduğunda kendiliğinden geri gelir).
• Belge, kaydı önbelleğe yazıldıktan sonra ikiz olduysa canonicalDocumentId kayıt temizlenene dek null döner. Bağ kurulurken ikizin ve sahibin kayıtları temizlenir; işaretçi normalde hemen, en geç 30 dakika içinde görünür. Bu sürede belge kütüphane listelerinde zaten ayrı kart olarak görünmez; anahtar kelime aramasının (/search/keyword) önbelleğe alınmış bir sonucunda en çok 5 dakika daha görünebilir; yeni bağlanmış bir nüshanın null'ını kesin saymayın, sonraki okumada işaretçiyi yeniden izleyin.

Sadece yükümlülükler gerekiyorsa /library/{id}/obligations uç noktası daha az trafik yaratır.