# 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:

<Steps>
  <Step from="merchant" to="appstore" title="Uygulamayı yükler veya satın alır">
    Ücretli uygulamalarda önce ödeme alınır.
  </Step>
  <Step from="appstore" to="panel" title="Mağazanın yetkilendirme sayfasına yönlendirir">
    `https://<mağaza>/panel/auth` adresine `client_id`, `redirect_uri` ve Ideasoft'un imzaladığı `state` ile.
  </Step>
  <Step from="panel" to="merchant" title="İzin ekranını gösterir">
    Yalnızca ilk kurulumda. Uygulama daha önce onaylandıysa bu adım atlanır.
  </Step>
  <Step from="merchant" to="panel" title="İzinleri onaylar" />
  <Step from="panel" to="app" title="Redirect URL'nize yönlendirir">
    `state`, `code`, `domain`, `user_id` ve varsa `renew_date` parametreleriyle.
  </Step>
  <Step from="app" title="State imzasını doğrular">
    Doğrulama başarısızsa akışı durdurun; token isteği yapmayın.
  </Step>
  <Step from="app" to="api" title="Yetki kodunu token ile değiştirir">
    `POST /oauth/v2/token`, `code` alındıktan sonraki 30 saniye içinde.
  </Step>
  <Step from="api" to="app" title="Token'ları döner">
    `access_token` 24 saat geçerlidir; süresi dolmadan `refresh_token` ile yenilenir.
  </Step>
  <Step from="app" to="api" title="Admin API'yi çağırır">
    `Authorization: Bearer <access_token>` başlığıyla.
  </Step>
</Steps>

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

## Redirect URL'ye gelen parametreler

```http
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
```

| Parametre | Açıklama |
|---|---|
| `state` | 64 karakterlik onaltılık HMAC-SHA256 imzası. İsteğin Ideasoft'tan geldiğini doğrulamak için kullanılır ([aşağıda](#state-doğrulama)). |
| `code` | Token almak için kullanılan tek kullanımlık yetki kodu. **30 saniye** geçerlidir. |
| `domain` | Uygulamayı 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_date` | Yalnızca yıllık yenilemeli ürünlerde: yenileme tarihi, `YYYYMMDD` ([Yenileme tarihi](#yenileme-tarihi-renew_date)). |

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

```http
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:

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

<CodeTabs>

```php title="PHP"
<?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');
}
```

```js title="Node.js"
import crypto from "node:crypto";

// PHP json_encode ile aynı çıktı: boşluksuz, "/" → "\/", ASCII dışı → \uXXXX
const phpJson = (obj) =>
  JSON.stringify(obj)
    .replace(/\//g, "\\/")
    .replace(/[\u007f-\uffff]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));

const ideasoftHmac = (data, clientSecret) =>
  crypto.createHmac("sha256", clientSecret).update(phpJson(data)).digest("hex");

const safeEqual = (a, b) => {
  const x = Buffer.from(a);
  const y = Buffer.from(String(b));
  return x.length === y.length && crypto.timingSafeEqual(x, y);
};

// Türkiye saatine göre YYYYMMDD
const ymd = (date) =>
  new Intl.DateTimeFormat("en-CA", { timeZone: "Europe/Istanbul" }).format(date).replaceAll("-", "");

export function verifyState(query, clientSecret) {
  const now = Date.now();
  return [now, now - 86_400_000].some((t) => {
    const data = { domain: query.domain ?? "", date: ymd(new Date(t)) };
    if (query.renew_date) data.renew_date = query.renew_date;
    return safeEqual(ideasoftHmac(data, clientSecret), query.state ?? "");
  });
}
```

```python title="Python"
import hashlib
import hmac
import json
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo


def php_json(obj):
    # PHP json_encode ile aynı çıktı: boşluksuz, "/" → "\/", ASCII dışı → \uXXXX
    return json.dumps(obj, separators=(",", ":"), ensure_ascii=True).replace("/", "\\/")


def ideasoft_hmac(data, client_secret):
    return hmac.new(client_secret.encode(), php_json(data).encode(), hashlib.sha256).hexdigest()


def verify_state(query, client_secret):
    now = datetime.now(ZoneInfo("Europe/Istanbul"))
    for day in (now, now - timedelta(days=1)):
        data = {"domain": query.get("domain", ""), "date": day.strftime("%Y%m%d")}
        if query.get("renew_date"):
            data["renew_date"] = query["renew_date"]
        if hmac.compare_digest(ideasoft_hmac(data, client_secret), query.get("state", "")):
            return True
    return False
```

</CodeTabs>

### Test vektörü

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

| Girdi | Değer |
|---|---|
| `client_secret` | `ornek-client-secret` |
| `domain` | `https://magaza-adiniz.myideasoft.com` |
| `date` | `20260518` |
| İmzalanan metin | `{"domain":"https:\/\/magaza-adiniz.myideasoft.com","date":"20260518"}` |
| `state` | `ceae612ec90a5cdc06f4fede3dbdf2a1390acd9129812ea4c4ba77d6ff0ad835` |
| `renew_date=20270401` ile `state` | `b575af08b8334a9434cbc3668b131036dc7f2590c396008c116b6ee83fb9583b` |

## 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:

```http
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](/getting-started/authentication) 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.

:::note{title="İ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.
:::
