Ana içeriğe geç
Mevzuat RadarDokümantasyon
Uygulamaya git ↗

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ımHTTPGövde / durumAnlamı
İzin ekranı400Geçersiz bağlantı isteğistate boş ya da 512 karakterden uzun, yöntem S256 değil veya code_challenge 43 karakterlik base64url değil
İzin ekranı400Geçersiz yönlendirme adresiAdres kayıtlı URI ile tam eşleşmiyor
İzin ekranı400Geçersiz izin kapsamı / İzin seçimi istenen kapsamı aşamazKapsam uygulamanın onaylı kapsamında değil
İzin ekranı403INTEGRATION_APP_SUSPENDED, INTEGRATION_APP_TERMINATEDUygulama bağlantıya kapalı
İzin ekranı403INTEGRATION_ENVIRONMENT_MISMATCHSır, kurum ve izin ortamı (test/canlı) uyuşmuyor
İzin ekranı402CUSTOMER_PLAN_REQUIREDCanlı kurumun ödeme/plan koşulu karşılanmıyor
İzin ekranı409Aydınlatma metni değişti; ekranı yenileyinOnaylanan metin sürümü güncel değil
İzin ekranı409Sertifikasız uygulama bağlantı tavanına ulaşıldıCanlıya geçmemiş uygulamanın kurum tavanı doldu
Retyönlendirmeerror=access_denied + stateYönetici izni reddetti; kayıt oluşmadı
Kod takası400invalid_grantSır, client_id, kod, redirect_uri, state veya code_verifier hatalı ya da kodun süresi dolmuş
Her adım503INTEGRATION_DISABLEDEntegrasyonlar 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):

İşlemAPI yoluEtki
RotasyonPOST /api/v1/integration-apps/{id}/secrets/rotateYeni sır döner; eski sır 24 saat daha geçerlidir (previousSecretExpiresAt)
Acil iptalPOST /api/v1/integration-apps/{id}/secrets/emergency-revokeYeni 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-Id başlığı gerekmez; izin yalnız uygulamanıza aitse bulunur. Başka uygulamanın veya var olmayan izin aynı 403 gö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 503 alı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.