# Gömülü Uygulamalar

Gömülü olarak tanımlanan uygulamalar, mağaza panelindeki uygulama sayfasında bir çerçeve (iframe) içinde açılır. Panel bu durumda yetkilendirme adresine değil, doğrudan Redirect URL'nize imzalı parametrelerle gider; uygulamanız mağazayı doğruladıktan sonra gerekirse kendi yetkilendirme isteğini başlatır.

<Steps>
  <Step from="merchant" to="panel" title="Uygulamalar sayfasında uygulama detayını açar" />
  <Step from="panel" to="app" title="Uygulamanızı çerçeve içinde açar">
    Redirect URL'nize `embedded`, `domain`, `date`, varsa `renew_date` ve `hmac` parametreleriyle.
  </Step>
  <Step from="app" title="hmac ve date değerini doğrular">
    `date` bugün veya dün değilse adresi reddedin.
  </Step>
  <Step from="app" to="panel" title="Oturum yoksa yetkilendirme ister">
    `/panel/auth` adresine kendi ürettiğiniz `state` ile.
  </Step>
  <Step from="panel" to="app" title="code ile geri döner">
    Uygulama kurulu olduğu için izin ekranı gösterilmez.
  </Step>
  <Step from="app" to="api" title="Yetki kodunu token ile değiştirir">
    `POST /oauth/v2/token`
  </Step>
  <Step from="app" to="merchant" title="Arayüzünü panel içinde gösterir" />
</Steps>

## Açılış adresi

```http
GET https://uygulamaniz.example.com/ideasoft/callback
    ?embedded=1
    &domain=magaza-adiniz.myideasoft.com
    &date=20260518
    &renew_date=20270401
    &hmac=8b4ac8621d8df8ee80a7af7a62c29671aae737a5e1ef1e199765126f3243ccff
```

| Parametre | Açıklama |
|---|---|
| `embedded` | Her zaman `1`. |
| `domain` | Mağazanın alan adı, **şema olmadan** (ör. `magaza-adiniz.myideasoft.com`). |
| `date` | Adresin üretildiği gün, `YYYYMMDD` (Türkiye saati). |
| `renew_date` | Yalnızca yıllık yenilemeli ürünlerde: yenileme tarihi, `YYYYMMDD`. |
| `hmac` | Yukarıdaki parametrelerin HMAC-SHA256 imzası. |

:::warning{title="Redirect URL sorgu dizesi içermemeli"}
Panel bu parametreleri Redirect URL'nizin sonuna `?` ile ekler. Kayıtlı adresiniz zaten `?` içeriyorsa açılış adresi bozulur.
:::

## hmac doğrulama

```
hmac = hex( HMAC-SHA256( JSON, client_secret ) )

JSON (renew_date yoksa):
{"embedded":"1","domain":"<domain>","date":"<date>"}

JSON (renew_date varsa):
{"embedded":"1","domain":"<domain>","date":"<date>","renew_date":"<renew_date>"}
```

- Metin, [state doğrulamadaki](/app-store/installation#state-doğrulama) gibi PHP `json_encode` çıktısıdır: anahtar sırası sabit, boşluk yok.
- `embedded` değeri sayı değil, `"1"` metnidir.
- `date` URL'de gelir; imzayı bu değerle hesaplayın, ardından tarihin **bugün veya dün** olduğunu kontrol edin. Daha eski adresleri reddedin.
- Karşılaştırmayı sabit zamanlı yapın.

<CodeTabs>

```php title="PHP"
<?php
function verifyEmbedded(array $query, string $clientSecret): bool
{
    $data = [
        'embedded' => (string)($query['embedded'] ?? ''),
        'domain' => $query['domain'] ?? '',
        'date' => $query['date'] ?? '',
    ];
    if (!empty($query['renew_date'])) {
        $data['renew_date'] = $query['renew_date'];
    }
    $expected = hash_hmac('sha256', json_encode($data), $clientSecret);
    if (!hash_equals($expected, (string)($query['hmac'] ?? ''))) {
        return false;
    }

    $today = new DateTimeImmutable('now', new DateTimeZone('Europe/Istanbul'));
    $allowed = [$today->format('Ymd'), $today->modify('-1 day')->format('Ymd')];
    return in_array($data['date'], $allowed, true);
}
```

```js title="Node.js"
// ideasoftHmac, safeEqual ve ymd yardımcıları: Kurulum ve Yetkilendirme sayfasındaki örnekle aynı
export function verifyEmbedded(query, clientSecret) {
  const data = {
    embedded: String(query.embedded ?? ""),
    domain: query.domain ?? "",
    date: query.date ?? "",
  };
  if (query.renew_date) data.renew_date = query.renew_date;
  const expected = ideasoftHmac(data, clientSecret);
  if (!safeEqual(expected, query.hmac ?? "")) return false;

  const now = Date.now();
  return [ymd(new Date(now)), ymd(new Date(now - 86_400_000))].includes(data.date);
}
```

```python title="Python"
# ideasoft_hmac yardımcısı: Kurulum ve Yetkilendirme sayfasındaki örnekle aynı
def verify_embedded(query, client_secret):
    data = {
        "embedded": str(query.get("embedded", "")),
        "domain": query.get("domain", ""),
        "date": query.get("date", ""),
    }
    if query.get("renew_date"):
        data["renew_date"] = query["renew_date"]
    expected = ideasoft_hmac(data, client_secret)
    if not hmac.compare_digest(expected, query.get("hmac", "")):
        return False

    now = datetime.now(ZoneInfo("Europe/Istanbul"))
    return data["date"] in (now.strftime("%Y%m%d"), (now - timedelta(days=1)).strftime("%Y%m%d"))
```

</CodeTabs>

**Test vektörü:** `client_secret=ornek-client-secret`, `domain=magaza-adiniz.myideasoft.com`, `date=20260518` (`renew_date` yok) için imzalanan metin `{"embedded":"1","domain":"magaza-adiniz.myideasoft.com","date":"20260518"}`, `hmac` değeri `8b4ac8621d8df8ee80a7af7a62c29671aae737a5e1ef1e199765126f3243ccff` olur.

:::caution{title="hmac oturum değildir"}
`hmac` yalnızca mağaza ve gün bilgisini imzalar; aynı gün içinde tekrar kullanılabilir. Bu yüzden onu kalıcı oturum veya API yetkisi olarak kullanmayın, log kayıtlarına yazmayın. Mağaza verisine erişmek için aşağıdaki yetkilendirmeyi tamamlayın.
:::

## Yetkilendirme

Bu mağaza için geçerli bir oturumunuz veya token'ınız yoksa, çerçeve içinden mağazanın yetkilendirme adresine kendi ürettiğiniz bir `state` ile yönlendirin:

```http
GET https://magaza-adiniz.myideasoft.com/panel/auth
    ?client_id=<client_id>
    &response_type=code
    &redirect_uri=<kayıtlı redirect_uri>
    &state=<sizin ürettiğiniz rastgele değer>
```

Uygulama mağazada zaten kurulu olduğu için onay ekranı gösterilmez; mağaza Redirect URL'nize `state`, `code`, `domain` ve `user_id` ile döner. Bu akışta `state` Ideasoft imzası değil, **sizin gönderdiğiniz değerdir**; sakladığınız değerle karşılaştırın. Ardından `code` ile [token alın](/app-store/installation#token-alma).

## Çerçeve içinde çalışma

- Uygulamanız mağaza panelinin içinde çerçevede açılır. Çerçevelenmeyi engelleyen başlıklar (`X-Frame-Options`, `frame-ancestors` içeren `Content-Security-Policy`) mağaza alan adlarının uygulamanızı göstermesine izin vermelidir.
- Tarayıcılar çerçeve içindeki üçüncü taraf çerezleri kısıtlayabilir. Oturumunuzu yalnızca çereze bağlamayın; her açılışta `hmac` doğrulaması ve yetkilendirme akışıyla yeniden kurulabilecek şekilde tasarlayın.
