Yönetim Kurulu Raporları API
| HTTP yöntemi | Yol | İşlev |
|---|---|---|
GET | /api/v1/board-reports | Organizasyonun raporlarını listeler |
GET | /api/v1/board-reports/:id | Tek raporun detayını döndürür |
Bu yollar mevcut raporları okur; rapor üretimi başlatmaz. Liste createdAt
azalan sıralanır. Liste ve detay sorguları sunucuda çözülen organizasyon
kimliğiyle sınırlandırılır; başka organizasyonun raporu detayda 404 döner.
Kimlik Doğrulama ve Yetki
| Kimlik doğrulama | Kural |
|---|---|
| API anahtarı | x-api-key; reports:read izni gerekir. Bu izin anahtar oluşturma veya izin güncelleme sırasında yalnız ENTERPRISE planına verilir |
| JWT | Authorization: Bearer <JWT>; yalnız ADMIN veya EDITOR rolü kabul edilir |
| Plan ve kota | Anahtar çağrısında publicApi özelliği ve planın hız sınırı; hem JWT hem anahtar çağrısında genel API kullanım kotası denetlenir |
JWT yolunda ayrıca bir ENTERPRISE plan kontrolü tanımlı değildir. API
anahtarı için izin verme politikası, JWT rol kontrolüyle aynı kural değildir.
Geçerli abonelik ve kullanılabilir kota gerekir.
Sorgu ve Yol Parametreleri
Liste sorgusunun bütün alanları isteğe bağlıdır:
| Parametre | Tip ve doğrulama | Varsayılan |
|---|---|---|
page | Tam sayı, en az 1 | 1 |
limit | Tam sayı, 1–50 | 20 |
Detay yolundaki id mevcut raporun metin kimliğidir; controller UUID
biçimi zorunlu tutmaz. Tanımlanmamış liste sorgusu alanları 400 döner.
Yanıt
Her iki işlem başarıda 200 döner. Liste zarfı:
{
"success": true,
"data": {
"items": [],
"page": 1,
"limit": 20,
"total": 0,
"totalPages": 1
}
}Detayda data tek rapor nesnesidir. Liste satırı ve detay aynı alanları taşır:
| Alan | Tip / anlam |
|---|---|
id, title | Metin |
periodStart, periodEnd, createdAt | ISO 8601 tarih-saat |
periodType | MONTHLY, QUARTERLY, YEARLY, CUSTOM |
sections | Metin dizisi |
format | PDF veya EXCEL |
status | GENERATING, COMPLETED, FAILED |
fileKey | Depolama anahtarı veya null; doğrudan indirme URL’si değildir |
downloadUrl | İmzalı dosya URL’si veya null |
lowQualityCount, highQualityCount | Sayısal kayıt sayıları |
lowQualityAppendix | { regulationId, title, sourceType, impactLevel, qualityScore } dizisi |
readinessSummary | Hazırlık özeti nesnesi veya null |
verificationAppendix | Doğrulama eki nesnesi veya null |
createdBy | { id, name, email } veya null |
downloadUrl yalnız status=COMPLETED ve dosya anahtarı dolu olduğunda
üretilir; imzalama başarısızsa yine null olur. İmzalı bağlantı için
3600 saniyelik geçerlilik istenir. Dosya format alanına göre PDF veya
Excel olabilir; her bağlantı PDF değildir.
readinessSummary; generatedAt, regulationChangeSummary,
openEvidenceGaps, overdueActions, unsignedMandatoryReads,
trustRiskSummary, missingEvidenceCount, articleImpactLinks alanlarını
taşır. verificationAppendix; generatedAt, runs, results, exports
alanlarını taşır. Bu alanların varlığı dış denetim veya sertifika onayı değildir.
Boş listede totalPages=1; diğer durumlarda ceil(total / limit) olur.
Hata Kodları
| HTTP durumu | Anlam |
|---|---|
400 | Geçersiz liste sorgusu veya sayfalama |
401 | JWT/API anahtarı eksik veya geçersiz |
402 | Genel API kotası çözülürken abonelik bağlamı bulunamıyor |
403 | JWT rolü, anahtar/IP izni, plan özelliği veya kullanım kotası yetersiz |
404 | Detay raporu bulunamadı veya organizasyon kapsamında değil |
429 | İstek hızı aşıldı; mevcutsa Retry-After süresine uyulur |
503 | API anahtarının hız sınırı denetimi kullanılamıyor |
Hatalar application/problem+json türünde döner. Ortak alanlar
Ortak API Kuralları sayfasındadır.
Örnekler
curl --fail-with-body 'https://api.mevzuatradar.com/api/v1/board-reports?limit=10' \
-H "x-api-key: $MEVZUATRADAR_API_KEY"Listedeki id değeriyle detay okunur:
curl --fail-with-body "https://api.mevzuatradar.com/api/v1/board-reports/$REPORT_ID" \
-H "Authorization: Bearer $MEVZUATRADAR_JWT"Kişisel alan izni
API anahtarıyla createdBy kişi bilgisini (id, ad ve e-posta) almak için
people:read izni gerekir. İzin yoksa createdBy alanı yanıtta hiç bulunmaz;
null yer tutucu dönmez. JWT yanıtı değişmez. Yeni anahtarlarda bu izin açıkça seçilir.