İçeriğe geç

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_PLAN dö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 https adresi (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.

  1. 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.

  2. 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.

  3. 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).

  4. Adım 4: Müşteri kimliğinizi not edin

    Panelde gösterilen `externalCustomerId` şirketinizin kimliğidir; isteklerinizde customer.externalCustomerId olarak bu değeri göndermelisiniz.

  5. 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

Bağlantıyla birlikte edindiğiniz değerler
DeğerNe 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.

Yönetim işlemleri
İşlemNe olur?
Webhook adresini veya test modunu değiştirmeAdres 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ı yenilemeYeni 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ı yenilemeYeni 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öndermeAdresinize 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 etmeBağ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 https olmalı 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).