İçeriğe geç
App Store

Kurulum ve Yetkilendirme

Mağaza yöneticisi uygulamanızı App Store'dan kurduğunda, App Store'da Uygulamaya Git butonuna bastığında veya mağaza panelindeki Uygulamalar listesinden açtığında aynı akış çalışır:

  1. 1.Mağaza yöneticisi→App Store

    Uygulamayı yükler veya satın alır

    Ücretli uygulamalarda önce ödeme alınır.

  2. 2.App Store→Mağaza paneli

    Mağazanın yetkilendirme sayfasına yönlendirir

    https://<mağaza>/panel/auth adresine client_id, redirect_uri ve Ideasoft'un imzaladığı state ile.

  3. 3.Mağaza paneli→Mağaza yöneticisi

    İzin ekranını gösterir

    Yalnızca ilk kurulumda. Uygulama daha önce onaylandıysa bu adım atlanır.

  4. 4.Mağaza yöneticisi→Mağaza paneli

    İzinleri onaylar

  5. 5.Mağaza paneli→Uygulamanız

    Redirect URL'nize yönlendirir

    state, code, domain, user_id ve varsa renew_date parametreleriyle.

  6. 6.Uygulamanız

    State imzasını doğrular

    Doğrulama başarısızsa akışı durdurun; token isteği yapmayın.

  7. 7.Uygulamanız→Mağaza API

    Yetki kodunu token ile değiştirir

    POST /oauth/v2/token, code alındıktan sonraki 30 saniye içinde.

  8. 8.Mağaza API→Uygulamanız

    Token'ları döner

    access_token 24 saat geçerlidir; süresi dolmadan refresh_token ile yenilenir.

  9. 9.Uygulamanız→Mağaza API

    Admin API'yi çağırır

    Authorization: Bearer <access_token> başlığıyla.

Sonraki açılışlarda aynı akış çalışır: izin ekranı atlanır ve her seferinde yeni bir code gelir.

Redirect URL'ye gelen parametreler

Code
GET https://uygulamaniz.example.com/ideasoft/callback ?state=ceae612ec90a5cdc06f4fede3dbdf2a1390acd9129812ea4c4ba77d6ff0ad835 &code=NTJlMDRkZWI5ZGFkMDBiOTZjODU1YzY4YjAyNWNmNTJj &domain=https%3A%2F%2Fmagaza-adiniz.myideasoft.com &user_id=1 &renew_date=20270401
ParametreAçıklama
state64 karakterlik onaltılık HMAC-SHA256 imzası. İsteğin Ideasoft'tan geldiğini doğrulamak için kullanılır (aşağıda).
codeToken almak için kullanılan tek kullanımlık yetki kodu. 30 saniye geçerlidir.
domainUygulamayı kuran veya açan mağazanın şemayla birlikte adresi, ör. https://magaza-adiniz.myideasoft.com. URL kodlu gelir.
user_idİşlemi yapan panel kullanıcısının kimliği. İmzaya dahil değildir.
renew_dateYalnızca yıllık yenilemeli ürünlerde: yenileme tarihi, YYYYMMDD (Yenileme tarihi).

Yönetici izin vermeyi reddederse yönlendirme code yerine hata parametreleriyle gelir:

Code
GET https://uygulamaniz.example.com/ideasoft/callback?error=access_denied&error_description=The+user+denied+access+to+your+application&state=…

State doğrulama

state, mağaza adresi ve tarihten oluşan bir JSON metninin Client Secret ile alınmış HMAC-SHA256 imzasıdır:

Code
state = hex( HMAC-SHA256( JSON, client_secret ) ) JSON (renew_date yoksa): {"domain":"<domain>","date":"<YYYYMMDD>"} JSON (renew_date varsa): {"domain":"<domain>","date":"<YYYYMMDD>","renew_date":"<YYYYMMDD>"}

İmzalanan metin PHP'nin json_encode çıktısıdır. Kendi dilinizde aynı metni üretirken şunlara dikkat edin:

  • Anahtar sırası sabittir: domain, date, renew_date.
  • Metinde boşluk yoktur.
  • / karakteri \/ olarak yazılır: "https:\/\/magaza-adiniz.myideasoft.com". JavaScript'in JSON.stringify ve Python'un json.dumps fonksiyonları bunu yapmaz; aşağıdaki örneklerdeki yardımcı fonksiyonu kullanın.
  • date, imzanın üretildiği gündür (Türkiye saati). URL'de gönderilmez; gece yarısı geçişleri için bugünü ve dünü deneyin.
  • renew_date yalnızca URL'de geldiyse metne eklenir.
  • Karşılaştırmayı sabit zamanlı yapın (hash_equals, timingSafeEqual, compare_digest).

state doğrulanmadan token isteği yapmayın.

<?php function ideasoftHmac(array $data, string $clientSecret): string { // json_encode varsayılan ayarlarıyla "/" karakterini "\/" olarak yazar return hash_hmac('sha256', json_encode($data), $clientSecret); } function verifyState(array $query, string $clientSecret): bool { $today = new DateTimeImmutable('now', new DateTimeZone('Europe/Istanbul')); foreach ([$today, $today->modify('-1 day')] as $day) { $data = ['domain' => $query['domain'] ?? '', 'date' => $day->format('Ymd')]; if (!empty($query['renew_date'])) { $data['renew_date'] = $query['renew_date']; } if (hash_equals(ideasoftHmac($data, $clientSecret), (string)($query['state'] ?? ''))) { return true; } } return false; } if (!verifyState($_GET, getenv('IDEASOFT_CLIENT_SECRET'))) { http_response_code(403); exit('invalid state'); }

Test vektörü

Kendi uygulamanızı aşağıdaki değerlerle sınayabilirsiniz:

GirdiDeğer
client_secretornek-client-secret
domainhttps://magaza-adiniz.myideasoft.com
date20260518
İmzalanan metin{"domain":"https:\/\/magaza-adiniz.myideasoft.com","date":"20260518"}
stateceae612ec90a5cdc06f4fede3dbdf2a1390acd9129812ea4c4ba77d6ff0ad835
renew_date=20270401 ile stateb575af08b8334a9434cbc3668b131036dc7f2590c396008c116b6ee83fb9583b

Token alma

state doğrulandıktan sonra code değerini 30 saniye içinde token ile değiştirin. İstek, domain parametresinde gelen mağazaya yapılır:

Code
POST https://magaza-adiniz.myideasoft.com/oauth/v2/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &client_id=<client_id> &client_secret=<client_secret> &code=<code> &redirect_uri=<redirect_uri>

Yanıtta gelen access_token 24 saat geçerlidir. Süresi dolmadan refresh_token ile yenileyin; her yenilemede refresh token da değişir. İstek ve yanıt ayrıntıları, hata kodları ve yenileme isteği için Kimlik Doğrulama sayfasına bakın.

client_secret değerini istek gövdesinde gönderin; URL'de taşımayın.

Mağazayı ve kullanıcıyı tanıma

  • Mağazayı domain parametresiyle tanıyın. domain, state imzasına dahil olduğu için doğrulama sonrasında güvenilirdir. Token'larınızı mağaza bazında saklayın.
  • user_id imzaya dahil değildir; tek başına kimlik veya yetki kanıtı olarak kullanmayın.
  • Her açılışta yeni bir code gelir. Mağaza için geçerli token'ınız varsa yeni token almak zorunda değilsiniz, ancak state doğrulamasını her açılışta yapın.

Yenileme tarihi (renew_date)

App Store'da yıllık yenilemeli olarak satılan ürünlerde yenileme tarihi Redirect URL'ye renew_date parametresiyle YYYYMMDD biçiminde eklenir (ör. renew_date=20270401). renew_date geldiğinde state imzasına da dahildir.

İlk kurulumda gelmeyebilir

Uygulama App Store üzerinden ilk kurulduğunda yenileme tarihi henüz oluşmamış olabilir; bu durumda renew_date gönderilmez. Tarih, kullanıcının uygulamaya sonraki girişlerinde gönderilir.

Son güncelleme: