Ortak API Kuralları

Bu sayfa MevzuatRadar herkese açık API, webhook yönetim API’si ve SDK istemcileri için ortak entegrasyon sözleşmesini toplar. Endpoint özelinde farklılık varsa ilgili API referansı sayfası ve OpenAPI çıktısı önceliklidir.

Temel URL

Ortam	Temel URL
Canlı API	`https://api.mevzuatradar.com`
Test ortamı	Entegrasyon Testi sayfasındaki base URL ayarı

Canlı domain örnekleri canlı ortam kullanım hedefini gösterir. Bir dağıtım kanıtı veya müşteri sözleşmesi yerine geçmez.

Kimlik Doğrulama

Endpoint ailesi	Üst bilgi	Not
Herkese açık arşiv	Yok	`/api/v1/public/*` uçları herkese açık okuma sözleşmesidir.
Müşteri API’si	`x-api-key`	API anahtarı müşteri uygulamasında `/settings/api` üzerinden yönetilir.
Webhook yönetimi	`Authorization: Bearer <JWT>`	Admin session JWT, rol ve `settings:*` permission ister.

Gizli değerler tek seferlik gösterimden sonra gizli değer yöneticisine taşınır. Repo, destek kaydı, ekran görüntüsü veya log içine canlı ortam gizli değeri yazılmaz.

Yanıt Zarfı

Uygulama API endpointleri genel olarak envelope ile döner:


{ "success": true, "data": {} }

Liste endpointlerinde data.items, data.total, data.page, data.limit ve data.totalPages alanları veya endpoint özelindeki eşdeğer meta alanları kullanılır. İstemci tarafı yeni alanlara toleranslı, eksik opsiyonel alanlara null-safe davranmalıdır.

Sağlık kontrol endpointleri bu kuralın istisnasıdır. /health, /health/live ve /health/ready yanıtları yük dengeleyici ve erişilebilirlik izleme uyumluluğu için yanıt zarfı içine sarılmaz.

Sayfalama

Parametre	Anlam
`page`	1 tabanlı sayfa numarası
`limit`	Sayfa başı kayıt sayısı; endpoint özelinde üst sınır uygulanabilir
`sort` / `order`	Sadece ilgili endpointte belgelenmişse kullanılır

İstemci entegrasyonları sayfalama bitişini items.length, totalPages veya endpoint özelindeki meta alanıyla doğrulamalıdır; sadece boş sayfa dönmesini başarı ölçütü kabul etmemelidir.

Tarih ve Kod Alanları

Tarih alanları ISO-8601 string olarak döner.
API sözleşmesindeki saatler UTC kabul edilir; kullanıcı arayüzü yerel saat gösterimini kendi tarafında yapar.
sourceCode, sourceType, sourceCategory, sourceSubcategory ve legalDocumentClass teknik filtre alanlarıdır. Kullanıcıya gösterilecek metin için kendi label katmanınızı kullanın; ham enum değerlerini ekrana doğrudan basmayın.

Hata Formatı

Hata yanıtları RFC 9457 Problem Details uyumlu alanlarla dönebilir ve geriye uyumluluk için legacy alanlar taşıyabilir:


{
  "type": "https://api.mevzuatradar.com/problems/validation-error",
  "title": "Doğrulama başarısız",
  "status": 400,
  "detail": "Geçersiz sorgu parametresi.",
  "requestId": "req_01",
  "errorId": "err_01",
  "success": false,
  "error": "Geçersiz sorgu parametresi.",
  "statusCode": 400
}

HTTP durumu	Entegrasyon davranışı
`400`	İstek gövdesi veya sorgu düzeltildikten sonra tekrar denenir.
`401`	API anahtarı/JWT eksik veya geçersizdir; gizli değer rotasyonu ve oturum yenileme kontrol edilir.
`403`	İzin, rol veya paket hakkı kapsamı yoktur.
`404`	Kayıt yoktur veya tenant sınırı dışındadır.
`429`	`Retry-After` varsa ona uyulur; yoksa katlanarak artan bekleme kullanılır.
`5xx`	Sadece tekil okuma istekleri yeniden denenir; değişiklik isteği tekrarları tekillik ile korunur.

İstek Korelasyonu

MevzuatRadar yanıt üst bilgilerinde x-request-id ve hata durumunda x-error-id dönebilir. Destek kaydı açarken bu iki değer, endpoint, saat ve HTTP durumu paylaşılır. API anahtarı, JWT, webhook gizli değeri veya ham kişisel veri gövdesi paylaşılmaz.