Kurum bağlantısı ve izin ekranı
Kapalı beta bağlantısı app.mevzuatradar.com/baglan üzerinde açılır. Uygulama
kimliği, kayıtlı yönlendirme adresi, state, scope, code_challenge ve
code_challenge_method=S256 gerekir. Adres kayıtlı URI ile tam eşleşmelidir.
Sandbox ortamında yalnız kayıtlı localhost port jokeri desteklenir.
Oturumu olmayan kullanıcı mevcut giriş ekranına gider. Kayıt bağlantısı ve
posta doğrulaması aynı /baglan dönüş yolunu korur. Kurumun etkin yöneticisi,
uygulamanın firma bilgilerini ve aydınlatma sürümünü inceleyerek istenen
izinlerin alt kümesini seçer. Ekranda görülen aydınlatma sürümü onaydan önce
veya kanonik metnin baytları değişirse işlem 409 ile durur; kullanıcı yeni metni görmeden grant oluşmaz. Ret halinde uygulamaya error=access_denied
ve aynı state döner; bağlantı kaydedilmez.
Veriler yalnız Türkiye’de işlenir. people:read isteği, aktif veri işleme eki
ve bağlantı aydınlatma sürümünün hukuk doğrulaması olmadan kabul edilmez.
Model A canlı bağlantısında kurumun ürün erişimi açık ve planı genel API
özelliğini içermelidir; ayrıntı Ödeme modelleri sayfasındadır.
Yürürlük tarihi gelmemiş aydınlatma sürümü bağlantı izni için kullanılamaz.
Onaydan dönen kod 60 saniye geçerlidir ve yalnız bir kez kullanılabilir.
Sunucunuz POST /api/v1/integration/token çağrısında client_id,
client_secret, code, redirect_uri, state ve code_verifier gönderir.
Yanıt yalnız grant_id, organization_id ve scopes taşır; erişim token’ı
üretilmez. Uygulama sırrını tarayıcıya koymayın. Başarılı takastan sonra kodun
tekrar kullanılması bağlantıyı sistem tarafından iptal eder.
Akış sırası
Uygulama sunucusu Tarayıcı / kurum yöneticisi MevzuatRadar
| code_verifier üretir, S256 code_challenge hesaplar |
|------ /baglan?client_id&redirect_uri&state&scope&... ----->|
| | giriş + kurum ve izin seçimi
| |-- onay ------------------->|
|<----- redirect_uri?code&state (veya error=access_denied) --|
| state değerini kendi kaydıyla karşılaştırır |
|------ POST /api/v1/integration/token (sunucudan) --------->|
|<----- grant_id, organization_id, scopes ------------------|
|------ X-API-Key + X-MR-Organization-Id ile API istekleri ->|Hata kodları
| Adım | HTTP | Gövde / durum | Anlamı |
|---|---|---|---|
| İzin ekranı | 400 | Geçersiz bağlantı isteği | state boş ya da 512 karakterden uzun, yöntem S256 değil veya code_challenge 43 karakterlik base64url değil |
| İzin ekranı | 400 | Geçersiz yönlendirme adresi | Adres kayıtlı URI ile tam eşleşmiyor |
| İzin ekranı | 400 | Geçersiz izin kapsamı / İzin seçimi istenen kapsamı aşamaz | Kapsam uygulamanın onaylı kapsamında değil |
| İzin ekranı | 403 | INTEGRATION_APP_SUSPENDED, INTEGRATION_APP_TERMINATED | Uygulama bağlantıya kapalı |
| İzin ekranı | 403 | INTEGRATION_ENVIRONMENT_MISMATCH | Sır, kurum ve izin ortamı (test/canlı) uyuşmuyor |
| İzin ekranı | 402 | CUSTOMER_PLAN_REQUIRED | Canlı kurumun ödeme/plan koşulu karşılanmıyor |
| İzin ekranı | 409 | Aydınlatma metni değişti; ekranı yenileyin | Onaylanan metin sürümü güncel değil |
| İzin ekranı | 409 | Sertifikasız uygulama bağlantı tavanına ulaşıldı | Canlıya geçmemiş uygulamanın kurum tavanı doldu |
| Ret | yönlendirme | error=access_denied + state | Yönetici izni reddetti; kayıt oluşmadı |
| Kod takası | 400 | invalid_grant | Sır, client_id, kod, redirect_uri, state veya code_verifier hatalı ya da kodun süresi dolmuş |
| Her adım | 503 | INTEGRATION_DISABLED | Entegrasyonlar geçici olarak kapalı |
Kod takası hata nedenini bilerek ayırmaz; tüm reddedilen takaslar aynı
invalid_grant gövdesini alır. API isteklerindeki hata kodları
Kimlik Doğrulama sayfasındadır.
Uygulama sırrı ve rotasyon
Test ortamı mr_app_test_, canlı ortam mr_app_live_ önekli sır kullanır.
Sır yalnız üretim veya yenileme yanıtında bir kez gösterilir; platform
yalnız özetini saklar. Firma yöneticisi şu uçları kullanır (environment:
SANDBOX veya LIVE, confirmed: true):
| İşlem | API yolu | Etki |
|---|---|---|
| Rotasyon | POST /api/v1/integration-apps/{id}/secrets/rotate | Yeni sır döner; eski sır 24 saat daha geçerlidir (previousSecretExpiresAt) |
| Acil iptal | POST /api/v1/integration-apps/{id}/secrets/emergency-revoke | Yeni sır döner; eski sır bir sonraki istekte geçersizdir |
Örtüşme süresi dolmadan ikinci olağan rotasyon 409 alır. Askıdaki
uygulamada yalnız acil iptal yapılabilir. Canlı sır yalnız production
ortamında üretilir. Rotasyonda yeni sırrı önce sunucunuza dağıtın, sonra eski
sırrın kullanımını bırakın.
Bağlı uygulamalar ekranı
Kurum kullanıcıları Ayarlar › Entegrasyon uygulamaları sayfasındaki Bağlı uygulamalar listesinde her bağlantı için uygulamayı, geliştirici firmayı, izin verilen kapsamları, izni veren kişiyi, izin tarihini, son kullanımı, teslim sayısını ve son teslim durumunu görür. Teslimlerin gövdesi bu ekranda gösterilmez. İptal edilen bağlantı son 90 gün boyunca durum etiketiyle listede kalır. Yalnız kurum yöneticisi bağlantıyı kesebilir; diğer roller listeyi yalnız görüntüler. Aynı sayfadaki destek formunda Hangi uygulama üzerinden? alanından yalnız kurumunuzun bağlı uygulamaları seçilebilir.
Bağlantının iptali
İptal geri alınmaz; yeniden bağlanmak için kurum yöneticisinin yeni izin vermesi gerekir ve eski kayıt iptal edilmiş olarak kalır. Üç yol vardır:
- Kurum: etkin kurum yöneticisi bağlı uygulamalar ekranından onay
penceresiyle bağlantıyı keser (
REVOKED,CUSTOMER). Düzenleyici ve görüntüleyici rolleri iptal edemez. - Geliştirici firma: sunucunuz uygulama sırrıyla
DELETE /api/v1/integration/grants/{id}çağırır (REVOKED,VENDOR).X-MR-Organization-Idbaşlığı gerekmez; izin yalnız uygulamanıza aitse bulunur. Başka uygulamanın veya var olmayan izin aynı403gövdesini alır. Ortak sır, uygulama durumu, genel durdurma, IP listesi ve uygulama toplam hız sınırı aynen uygulanır. - Platform: tek izin, uygulamanın tamamı (sonlandırma) veya genel durdurma.
Genel durdurma iptal değildir; izinler korunur, istekler
503alır.
İptalden sonraki ilk istek 403 INTEGRATION_CONSENT_REVOKED alır. Kuyruktaki
teslimler teslim anında iptal edilir ve yeniden denenmez. Uygulama ucunuza
integration.grant_revoked olayı gider; ayrıntılar Webhook Akışı
sayfasındadır.