Arama ve Mevzuat Kataloğu API
Katalog uçları, kurumunuzun planında ve kaynak erişiminde bulunan mevzuatı entegrasyonunuza açar. Aynı kurum ve aynı sorgu için uygulamadaki okuyucuyla aynı görünürlük uygulanır. Kurum kimliği istek parametresinden alınmaz.
| Yöntem ve yol | API anahtarı izni | Sonuç |
|---|---|---|
GET /api/v1/catalog/search | search:read | Sıralı arama sonuçları ve sayfalama |
GET /api/v1/catalog/regulations/{id} | regulations:read | Mevzuatın okunabilir ayrıntıları |
GET /api/v1/catalog/sector-taxonomy/active | regulations:read | Etkin taksonomi sürümü |
GET /api/v1/catalog/sector-taxonomy/nodes | regulations:read | Taksonominin kök veya alt düğümleri |
Anahtarı x-api-key başlığında gönderin. Planınızın Public API erişimini
desteklemesi, anahtar izninin planla uyumlu olması ve kotanın yeterli olması
gerekir. JWT ile de çağrılabilir; arama için search:read, mevzuat detayı
için feed:read uygulama sayfa izni korunur. Taksonomi yolları normal
taksonomi okuyucusuyla aynı oturum erişimini kullanır.
Arama
q en fazla 120 karakterdir. page en az 1, limit 1–100 arasında tam
sayıdır; varsayılanlar 1 ve 20’dir. Kaynak, tarih, etki ve sektör filtreleri
uygulama aramasıyla aynı anlama gelir. sourceCode, dateFrom, dateTo,
impactLevels, sectorKeys ve includeCrossSector kullanılabilir.
semantic=true isteği 400 ile reddedilir. Bu uç tam metin arama içindir.
Sonuçta items, titleBand, total, page, limit, totalPages, mode,
effectiveMode ve degradedModeReason alanları bulunur. totalIsCapped
varsa toplamın bir alt sınır olduğunu belirtir.
curl 'https://api.mevzuatradar.com/api/v1/catalog/search?q=sermaye&limit=20' \
-H 'x-api-key: <API_KEY>'Detay ve taksonomi
Mevzuat detayı için contentSource=auto|text|pdf kullanılabilir;
varsayılan auto olur. Metin kalite koşullarını henüz karşılamıyorsa
okuyucudaki aynı içerik durumu ve işlem mesajı döner.
Taksonomi nodes yolunda parentKey verilmezse kök düğümler, verilirse
o düğümün etkin alt düğümleri gelir. active yanıtı scheme, version,
officialVersionId, title, effectiveFrom, effectiveTo içerir.
nodes yanıtı taxonomyVersion, parentSelectionKey, items içerir.
Yanıt zarfı { "success": true, "data": ... } biçimindedir. Katalog,
tenant notlarını, annotation ve yorumları, isRead/isBookmarked
durumlarını veya kullanıcı e-postalarını döndürmez. Bu uçların veri modeli
kişi alanı içermez; people:read verilmesi yeni kişi alanı eklemez.
Hatalar ve sınırlar
| HTTP durumu | Anlam |
|---|---|
400 | Geçersiz sorgu, semantic=true veya limit sınırının aşılması |
401 | Anahtar yok, bozuk, süresi dolmuş veya iptal edilmiş |
403 | Anahtar izni, plan özelliği veya uygulama sayfa izni yeterli değil |
404 | Mevzuat görünür değil/bulunamadı veya yol desteklenmiyor |
429 | Hız sınırı aşıldı; Retry-After başlığına uyun |
503 | Anahtarlı istekte hız sınırı altyapısı kullanılamıyor |
Başka kuruma ait özel bir mevzuatın yanıtı, bulunmayan kimliğin yanıtıyla aynıdır. Anahtarlı istekler genel API kotasını anahtarın kurumu adına tüketir. Planın dakikalık sınırı ile 600/dakika genel anahtar tavanından düşük olanı uygulanır; JWT okuma katmanında kalır.
Katalog altında saved/history/suggest/facets, arama dışındaki taksonomi
araçları ve kurum kapsamlı node-counts/bucket-counts yolları sunulmaz;
bu yollar 404 döner. Ortak API kuralları
ve hız sınırları da geçerlidir.
Vergi metadata alanları
Katalog araması (items ve titleBand) ve mevzuat detayı effectiveDate ile
taxTags alanlarını içerir. Eksik yürürlük tarihi null, konu eşleşmesi olmayan
veya henüz doldurulmamış etiketler [] olarak sunulur. Kontrollü sözlük:
KDV, VUK, GV, KV, SGK, E_BELGE, OTV, DAMGA, HARC.
Yürürlük yalnız resmi kaynağın tek, açık tarihinden alınır. Yayım ve ödeme son
süreleri yürürlük tarihi yerine kullanılmaz. Vergi etiketleri sektör ataması ve
kullanıcı rolünü değiştirmez. Metadata, mevcut kurum/plan/kaynak görünürlüğü
uygulandıktan sonra PostgreSQL’den okunur; tam metin arama dizinine eklenmez.
Belge Bağlantıları
app_url, /regulation/<id> uygulama detayını açan kanonik URL’dir. Sorgu,
fragment, oturum, token, kullanıcı veya kurum kimliği taşımaz. Oturum yoksa
mevcut OTP giriş akışı aynı belgeye dönüş adresini korur; tek tıkla giriş
bağlantısı değildir. Belge erişimi ve kurum notlarının görünürlüğü mevcut
yetki kontrollerinden geçer.
public_url, yalnız kamu arşivine uygun belgede yapılandırılmış kamu kökü ve
kanonik /mevzuat/... yolunu içerir. Özel, kuruma ait, arşivlenmiş, henüz
yayımlanmamış veya desteklenmeyen kaynak belgelerinde null olur. Kamu kökü
yapılandırılmamışsa da null döner. Alanlar additive olup eski alanları korur.