Başlangıç
Ön koşullar, panelden bağlantı oluşturma, bağlantı bilgileri, yönetim işlemleri, test modu ve webhook adresi kuralları.
Son güncelleme:
Ön koşullar
- Şirketinizin paketinde API Erişimi lisans modülü bulunmalıdır. Modül yoksa panelden bağlantı oluşturulamaz ve API çağrıları
402 MODULE_NOT_IN_PLANdöner. - Panelde bağlantıyı görmek için API Erişimi görüntüleme yetkisi, oluşturmak veya değiştirmek için API Erişimi yönetme yetkisi gerekir. Bu yetkiler şirket sahibine paketten gelir; diğer kullanıcılara Yetki Matrisi'ndeki API Erişimi satırından verilir.
- ETK kararlarınızın İYS'ye iletilmesini istiyorsanız şirketinizin İYS bağlantısı hazır olmalıdır. Hazır değilse kararlar yine kaydedilir ancak İYS'ye gönderilmez; KVKK kararları etkilenmez. Panel, bu durumda bağlantı üzerinde bir uyarı gösterir.
- Webhook almak istiyorsanız herkese açık, geçerli sertifikalı bir
httpsadresi (yalnızca 443 portu) yayınlamalısınız.
Panelden bağlantı oluşturma
Bağlantıyı müşteri olarak kendiniz, panelde Hesabım → Şirket Ayarları → API Erişimi sekmesinden oluşturursunuz; Rıza AL ekibinin işlem yapmasına gerek yoktur. Şirket başına tek bağlantı açılabilir; zaten aktif bir bağlantınız varken ikincisi oluşturulamaz.
Adım 1: API Erişimi sekmesini açın
Rıza AL paneline giriş yapıp Hesabım → Şirket Ayarları → API Erişimi sekmesine gidin.
Adım 2: Bağlantıyı oluşturun
İsterseniz webhook adresinizi ekleyin; ilk denemeleriniz için test modunu açık tutabilirsiniz (aşağıya bakın). Webhook adresini ve test modunu sonradan da değiştirebilirsiniz.
Adım 3: Bilgileri güvenli saklayın
Oluşturma sonunda API anahtarı ve webhook secret'ı yalnızca bir kez gösterilir; pencereyi kapatmadan önce ikisini de güvenli bir yere kaydedin. Kaybederseniz yenisi üretilir (aşağıya bakın).
Adım 4: Müşteri kimliğinizi not edin
Panelde gösterilen `externalCustomerId` şirketinizin kimliğidir; isteklerinizde
customer.externalCustomerIdolarak bu değeri göndermelisiniz.Adım 5: Test isteği gönderin
Kimlik doğrulama bölümündeki örneklerle ilk imzalı isteğinizi gönderin.
Bağlantı bilgileriniz
| Değer | Ne için kullanılır? |
|---|---|
clientKey | İstek adresinin içinde yer alır. Panelden oluşturduğunuz bağlantılarda değeri her zaman direct'tir. |
externalCustomerId | Şirketinizin kimliği; panelde gösterilir. İstek gövdesinde customer.externalCustomerId olarak gönderilir; bağlantıdakiyle aynı olmazsa 422 CUSTOMER_MISMATCH döner. |
| API anahtarı | Authorization: Bearer veya X-Rizaal-Api-Key başlığında gönderilir; bağlantınızı tanıtır. Yalnızca bir kez gösterilir. |
| Webhook secret'ı | İstek imzasını hesaplamak ve Rıza AL'ın gönderdiği webhook imzasını doğrulamak için kullanılır. Aynı secret iki yönde de geçerlidir. Yalnızca bir kez gösterilir. |
| Webhook adresi | İzin değişikliği olaylarının gönderileceği https adresi (isteğe bağlı). |
Bağlantıyı yönetme
Aşağıdaki işlemlerin tümü Hesabım → Şirket Ayarları → API Erişimi sekmesinden yapılır ve API Erişimi yönetme yetkisi gerektirir.
| İşlem | Ne olur? |
|---|---|
| Webhook adresini veya test modunu değiştirme | Adres boşaltılarak webhook kapatılabilir. Webhook adresi değişirse webhook secret'ı yeniden üretilir; yeni secret yalnızca bir kez gösterilir. |
| API anahtarını yenileme | Yeni anahtar yalnızca bir kez gösterilir. Eski anahtar, seçtiğiniz geçiş süresi boyunca geçerli kalır (1–30 gün, varsayılan 7 gün); sistemlerinizi bu sürede yeni anahtara geçirin. |
| Webhook secret'ını yenileme | Yeni secret yalnızca bir kez gösterilir. Geçiş süresi (1–30 gün, varsayılan 7 gün) boyunca Rıza AL webhook'ları iki secret ile imzalar ve gelen isteklerde de iki secret'ı kabul eder. |
| Test webhook'u gönderme | Adresinize bir ping olayı gönderilir; sonucu (başarılı mı, hangi HTTP durumu ya da hata kodu) panelde görürsünüz. |
| Bağlantıyı iptal etme | Bağlantı hemen pasifleşir; sonraki istekler 401 döner. Geçiş süresindeki eski anahtar ve secret değerleri de geçerliliğini yitirir. |
| Bağlantıyı yeniden açma | İptal ettiğiniz bağlantıyı yeniden oluşturduğunuzda yeni bir API anahtarı ve webhook secret'ı üretilir; iptal edilmiş anahtarlar geri gelmez. |
| Webhook gönderim kayıtları | Gönderilen webhook'ların durumunu ve ayrıntısını panelden izlersiniz. Başarısız olup denemeleri tükenen (DEAD) kayıtlar panelden yeniden gönderilebilir; yalnızca DEAD kayıtlar yeniden gönderilir. |
Webhook adresi kuralları
- Adres
httpsolmalı ve yalnızca 443 portunu kullanmalıdır. - Adreste kullanıcı adı/parola bulunamaz.
- Özel veya iç ağ IP'sine çözülen alan adları reddedilir.
- Yönlendirme (redirect) izlenmez; adres doğrudan 2xx yanıt vermelidir.
Test modu
Bağlantıyı test modunda açabilir veya sonradan test modunu açıp kapatabilirsiniz. Test modunda kararlar normal şekilde kaydedilir ve kanıt zincirine yazılır; ancak ETK kararları İYS'ye gönderilmez. KVKK kararları zaten İYS'ye gitmez.
API anahtarınızı ve bağlantınızı yönetmek için panelde Hesabım → Şirket Ayarları → API Erişimi sekmesini kullanın. Hesabım sayfasını aç (giriş yapmanız gerekir).
