Kimlik Doğrulama
Ideasoft API, kimlik doğrulama için OAuth2 standardını kullanır. OAuth2; kullanıcı adı ve parola paylaşılmadan, gerekli parametreler gönderilerek hesap bilgilerine sınırlı erişim sağlayan bir yetkilendirme sistemidir.
- authorizationUrl:
https://magaza-adiniz.myideasoft.com/panel/auth - tokenUrl:
https://magaza-adiniz.myideasoft.com/oauth/v2/token - akış:
authorization_code
Mağaza alan adınızı ayarlayın
Her istek kendi mağazanızın alan adına gider: https://<mağaza>.myideasoft.com ya da mağazanıza bağlı kendi alan adınız. Referanstaki örnekler magaza-adiniz.myideasoft.com yer tutucusunu gösterir; bir isteği denemek için Test düğmesine tıklayıp açılan penceredeki URL alanına kendi alan adınızı yazın — tarayıcınızda saklanır ve tüm isteklerde kullanılır. Endpoint URL'sinin yanındaki ayar simgesi de ("Edit server variables") aynı işi yapar.
Gerekli Bilgiler
Uygulamanızın yetkilendirilmesi için üç bilgiye ihtiyacınız vardır:
| Bilgi | Açıklama |
|---|---|
| Client ID | Uygulamanız için atanmış rastgele üretilmiş string. Bu bilgi açıktır. |
| Client Secret | Uygulamanız için özel üretilmiş string. Bu bilgi gizli tutulmalıdır. |
| Redirect URL | Kullanıcının uygulamanıza yetki verdikten sonra geri dönmesi gereken adres. |
Kayıt
Bu üç bilginin de önceden sistemde kayıtlı olması gerekir. Admin panelinden Entegrasyonlar → API → Ekle yolu izlendiğinde "Redirect URL" kullanıcının tercihine göre girilir; "Client ID" ve "Client Secret" ise sistem tarafından otomatik üretilir.
Yetkilendirme İşlemleri
authorization_code yönteminde kullanıcı özel bir sayfaya yönlendirilir ve uygulamaya izin vermesi istenir; kullanıcı adı ve parola gerekmez. İşlem dört aşamada gerçekleştirilir. Bu aşamalar her uygulama için yalnızca bir kez izlenir ve uygulamaya gerekli izinleri verme yetkisi yalnızca mağaza yöneticisindedir.
1. Yetki sayfasına geliş
Kullanıcıyı, uygulamanızı tanımlayan bilgilerle birlikte yetki sayfasına yönlendirin:
Code
| Parametre | Açıklama |
|---|---|
client_id | Yukarıda tanımlanan Client ID değeri |
response_type | Doğrulama için kullanılacak yöntem. Geçerli değer: code |
state | İstek için rastgele üretilmiş kod (3. adımda kontrol edilmelidir) |
redirect_uri | Yukarıda tanımlanan Redirect URL değeri; onay sonrası kullanıcı bu adrese yönlendirilir |
İzinler (scope) istek başına istenmez; mağaza panelinde (Entegrasyonlar → API) oluşturulan API tanımıyla sabittir.
Örnek istek:
Code
2. Yetki izni sayfası
Kullanıcı Ideasoft admin panelindeki yetki izin ekranına gelir. Burada uygulamanızın adı ve izinleri görülür; kullanıcı uygulamaya yetki verebilir veya reddedebilir.
3. Uygulama sayfasına geri dönüş
Kullanıcı, redirect_uri adresine yönlendirilir. Duruma göre GET parametrelerinde aşağıdaki değerler bulunur; uygulamanız bu değerleri dikkate alarak token alma veya hata işleme adımlarını gerçekleştirmelidir.
| Parametre | Açıklama |
|---|---|
code | 4. adımda token almak için kullanılacak kimlik doğrulama kodu. Geçerlilik süresi 30 saniyedir. |
state | 1. adımda verilen kod. MITM tipi saldırılardan korunmak için doğruluğunu kontrol etmeniz gerekir. |
error | Hata kodu (yalnızca hata durumunda gönderilir) |
error_description | Hata açıklaması (yalnızca hata durumunda gönderilir) |
Başarılı dönüş örneği:
Code
Hata durumunda dönebilecek değerler:
| error | Açıklama |
|---|---|
invalid_grant | Kullanılan yetkilendirme yöntemi geçersiz |
access_denied | Kullanıcı uygulamanıza yetki vermemeyi seçti |
Başarısız dönüş örneği:
Code
4. Token isteği
Bu adımda uygulama, kullanıcıdan bağımsız olarak sunucuya doğrudan istek göndererek Access Token ve Refresh Token alır.
Code
| Parametre | Açıklama |
|---|---|
grant_type | Doğrulama yöntemi. Geçerli değer: authorization_code |
client_id | Client ID değeri |
client_secret | Client Secret değeri |
code | 3. adımda elde edilen kimlik doğrulama kodu |
redirect_uri | Redirect URL değeri |
Örnek istek (form gövdesi olarak gönderin; aynı parametreler query string olarak da kabul edilir):
Code
Başarılı istek HTTP 200 ile şuna benzer bir JSON döner:
Code
Başarısız istek HTTP 400 ile error ve error_description alanları içeren bir JSON döner. Olası hatalar:
| error | error_description | Açıklama |
|---|---|---|
invalid_request | Invalid grant_type parameter or parameter missing | grant_type değeri eksik veya geçersiz |
invalid_request | Missing parameter. "code" is required | code değeri eksik |
invalid_request | The redirect URI parameter is required | redirect_uri değeri eksik |
unauthorized_client | The grant type is unauthorized for this client_id | Kullanılan grant_type uygulamanız için geçersiz |
invalid_client | The client credentials are invalid | Verilen client_id veya client_secret doğru değil |
invalid_grant | Code doesn't exist or is invalid for the client | Verilen code değeri doğru değil |
redirect_uri_mismatch | The redirect URI is missing or do not match | redirect_uri değeri doğru değil |
invalid_grant | The authorization code has expired | Verilen code değerinin kullanım süresi dolmuş |
Token Geçerliliği
Alınan Access Token sonraki tüm API çağrılarında kullanılır; geçerlilik süresi 24 saat'tir.
Access Token'ın süresi dolduğunda Refresh Token ile yeni bir Access Token alınabilir:
Code
Refresh Token ile yapılan her Access Token talebinde Refresh Token da yenilenir (rotate edilir). Doğru bir kurguyla iki token düzenli yenilenirse yeniden yetkilendirme gerekmez. Refresh Token geçerlilik süresi 2 ay'dır; bu süreden sonra kullanıcının yeniden yetki vermesi gerekir.
API Çağrısı
Access token'ı her istekte Authorization başlığı ile gönderin:
Code
Access token'ın yetkileri, mağaza panelindeki API tanımıyla belirlenir (istek başına scope gönderilmez); tüm scope listesi için Admin API spec'indeki güvenlik tanımına bakın. Endpoint ve alan detayları için OAuth referansına bakın.
Postman ile örnek yetkilendirme
Postman'de yetkilendirme adımları şöyledir:
- İstekte Authorization sekmesinden OAuth 2.0 seçilir.
- Grant type olarak Authorization Code (
authorization_code) ve Callback URL olarakhttps://www.getpostman.com/oauth2/callbackgirilir. Callback URL, admin panelindeki Redirect URL değeriyle aynı tanımlanmalıdır. - Auth URL:
https://magaza-adiniz.myideasoft.com/panel/auth, Access Token URL:https://magaza-adiniz.myideasoft.com/oauth/v2/tokenolarak doldurulur. - Client ID ve Client Secret değerleri, admin panelinde tanımladığınız API bilgilerinden alınır.
- Get New Access Token butonu ile yetki sayfasına yönlendirilip, gerekli izinleri tanımladığınız kullanıcı ile giriş yapılır. İzinler kabul edildikten sonra Access Token Postman'de kullanılabilir hale gelir.
Eski yetkilendirme
v8.0 öncesinde /admin/user/auth adresinde bulunan eski yetkilendirme endpoint'i kaldırılmıştır; yalnızca /panel/auth kullanılmalıdır.