İçeriğe geç
Başlangıç

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:

BilgiAçıklama
Client IDUygulamanız için atanmış rastgele üretilmiş string. Bu bilgi açıktır.
Client SecretUygulamanız için özel üretilmiş string. Bu bilgi gizli tutulmalıdır.
Redirect URLKullanı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
GET https://magaza-adiniz.myideasoft.com/panel/auth
ParametreAçıklama
client_idYukarıda tanımlanan Client ID değeri
response_typeDoğ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_uriYukarı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
GET https://magaza-adiniz.myideasoft.com/panel/auth ?client_id=7_7d67dc7597f034d63775c1d9ae5d9ac7f5750197f &response_type=code &state=2b33fdd45jbevd6nam &redirect_uri=https://client.example-app.com/auth

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.

ParametreAçıklama
code4. adımda token almak için kullanılacak kimlik doğrulama kodu. Geçerlilik süresi 30 saniyedir.
state1. adımda verilen kod. MITM tipi saldırılardan korunmak için doğruluğunu kontrol etmeniz gerekir.
errorHata kodu (yalnızca hata durumunda gönderilir)
error_descriptionHata açıklaması (yalnızca hata durumunda gönderilir)

Başarılı dönüş örneği:

Code
GET https://client.example-app.com/auth ?state=2b33fdd45jbevd6nam &code=Q0ODMI2OGYjMjBkN2mJmYzNkOTE4gzMGRhZDZTcykyOGQ3M2M2YTU2ZGVlMzE2MzB2MYkc5NWzE0ZWNiYjI2MA

Hata durumunda dönebilecek değerler:

errorAçıklama
invalid_grantKullanılan yetkilendirme yöntemi geçersiz
access_deniedKullanıcı uygulamanıza yetki vermemeyi seçti

Başarısız dönüş örneği:

Code
GET https://client.example-app.com/auth ?error=access_denied &error_description=The%20user%20denied%20access%20to%20your%20application &state=2b33fdd45jbevd6nam

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
POST https://magaza-adiniz.myideasoft.com/oauth/v2/token Content-Type: application/x-www-form-urlencoded
ParametreAçıklama
grant_typeDoğrulama yöntemi. Geçerli değer: authorization_code
client_idClient ID değeri
client_secretClient Secret değeri
code3. adımda elde edilen kimlik doğrulama kodu
redirect_uriRedirect URL değeri

Örnek istek (form gövdesi olarak gönderin; aynı parametreler query string olarak da kabul edilir):

Code
POST https://magaza-adiniz.myideasoft.com/oauth/v2/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &client_id=7_7d67dc7597f034d63775c1d9ae5d9ac7f5750197f &client_secret=1sowg0oogc4wg4w4o4gh4va57gggwskkgo08m44ksog8kmu88o &code=Q0ODMI2OGYjMjBkN2mJmYzNkOTE4gzMGRhZDZTcykyOGQ3M2M2YTU2ZGVlMzE2MzB2MYkc5NWzE0ZWNiYjI2MA &redirect_uri=https%3A//client.example-app.com%2Fauth%2F

Başarılı istek HTTP 200 ile şuna benzer bir JSON döner:

JSONCode
{ "access_token": "OGE3MzkxNDlhOGY0M2RjZWM1MWI2MWIxZjRmNDJhZThiOGJkOWZlMWIwNzVkYWFlOWFiMDAxYzkwMDlmMDhlMw", "expires_in": 86400, "token_type": "bearer", "scope": "Sahip olduğunuz izinler burada görüntülenecektir.", "refresh_token": "NjczY2E2NzZiNDJjZWI5NTE2YjZhNTlhYTJmOTQ5MjljN2MwNmUxM2MzODc5YTE4OGVjMDdlYTBiMzY1MWI1Mw" }

Başarısız istek HTTP 400 ile error ve error_description alanları içeren bir JSON döner. Olası hatalar:

errorerror_descriptionAçıklama
invalid_requestInvalid grant_type parameter or parameter missinggrant_type değeri eksik veya geçersiz
invalid_requestMissing parameter. "code" is requiredcode değeri eksik
invalid_requestThe redirect URI parameter is requiredredirect_uri değeri eksik
unauthorized_clientThe grant type is unauthorized for this client_idKullanılan grant_type uygulamanız için geçersiz
invalid_clientThe client credentials are invalidVerilen client_id veya client_secret doğru değil
invalid_grantCode doesn't exist or is invalid for the clientVerilen code değeri doğru değil
redirect_uri_mismatchThe redirect URI is missing or do not matchredirect_uri değeri doğru değil
invalid_grantThe authorization code has expiredVerilen 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
POST https://magaza-adiniz.myideasoft.com/oauth/v2/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token &client_id=7_7d67dc7597f034d63775c1d9ae5d9ac7f5750197f &client_secret=1sowg0oogc4wg4w4o4gh4va57gggwskkgo08m44ksog8kmu88o &refresh_token=NjczY2E2NzZiNDJjZWI5NTE2YjZhNTlhYTJmOTQ5MjljN2MwNmUxM2MzODc5YTE4OGVjMDdlYTBiMzY1MWI1Mw

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
Authorization: Bearer <access_token>

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:

  1. İstekte Authorization sekmesinden OAuth 2.0 seçilir.
  2. Grant type olarak Authorization Code (authorization_code) ve Callback URL olarak https://www.getpostman.com/oauth2/callback girilir. Callback URL, admin panelindeki Redirect URL değeriyle aynı tanımlanmalıdır.
  3. Auth URL: https://magaza-adiniz.myideasoft.com/panel/auth, Access Token URL: https://magaza-adiniz.myideasoft.com/oauth/v2/token olarak doldurulur.
  4. Client ID ve Client Secret değerleri, admin panelinde tanımladığınız API bilgilerinden alınır.
  5. 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.

Son güncelleme: