---
title: Uygulama Aksiyonları
description: Yönetim Panelinde kendi uygulamanızın farklı ekranlarda açılmasını sağlayarak yeni fonksiyonlar ekleyin
---

<img 
  className="mx-auto my-6 rounded-lg border border-zinc-200 shadow-sm dark:border-zinc-800" 
  src="/media/ikas-partners-photo-quick-start/app-actions.png" 
  alt="ikas dashboard with localhost tunnel connection" 
/>

Uygulama aksiyonları sayesinde, uygulamanız aşağıdaki alanlara kendi aksiyonlarını ekleyebilir ve bu aksiyonlar sayesinde yeni özellikleri kullanıcılarınıza sunabilirsiniz.

### Partner Üzerinden Aksiyon Tanımlama

Uygulamanızın yönetim paneli içerisinde aksiyonları gösterebilmesi için ilk olarak Partners panelinden uygulama detaylarına gitmeniz gerekmekte.

<video controls width="1024">
  <source src="/media/app-development-media/ikas-cli-media/page-actions.mp4" type="video/mp4" />
  Uygulama aksiyonları videosu yüklenemedi.
</video>

Örnek kullanım senaryolarından birkaçı:
- Sipariş detaydaki aksiyon sayesinde, siparişe fatura oluşturma.
- Paket aksiyonu sayesinde, paketin içindeki ürünleri kargo entegrasyonuna gönderme.
- Ürün aksiyonu sayesinde, ürünü pazaryerine ya da harici sistemlere gönderme.

### Nerelerde görünür?
- **Ürün Düzenleme** sayfaları (`/product/edit/:id`)
  - Aksiyon: Ürün Genel Aksiyon
  - Konum: Üst sağ **(︙)** menüsü
- **Sipariş** sayfası (`/order/view/:id`)
  - Aksiyon: **Sipariş Genel Aksiyon**
    - Konum: Üst sağ **(︙)** menüsü
  - Aksiyon: **Sipariş Paket Aksiyonu**
    - Konum: Her paket kartının altındaki aksiyonlar listesinde
- **Sipariş Liste** sayfası (`/order`)
  - Aksiyon: **Sipariş Listesi Toplu Aksiyon**
  - Konum: Tablo üstünde “Actions”/“İşlemler” → Bulk Operations açılır menüsü

### Aksiyon eklenen query parametreler
- Ürün Detay: `idList=<productId>`
- Sipariş Detay: `idList=<orderId>`
- Sipariş Paketi: `orderId=<orderId> (+ orderPackageId, orderLineItemIds=a,b, quantityMap=<JSON string>)`
- Sipariş Listesi: `idList=<orderId1,orderId2,...>`

Not:
- Base URL her zaman `action.redirectUrl`.
- `idList` virgülle ayrılır.
- `quantityMap` JSON string’dir; URL içinde encode edilmesi tavsiye edilir.

## Aksiyon Tipleri

<Callout type="info" title="Hangi yöntemi seçmeliyim?">
iframe: Kullanıcı etkileşimi, çok adımlı akış, görsel/ara yüz gereksinimi.
API: Arka plan işlemi, toplu/otomasyon, anlık başarılı/başarısız yanıt.
</Callout>

- **iframe (embedded UI)**: ikas yönetim paneli içinde sayfanız iframe olarak açılır. `actionRunId`, `idList`, `userLocale` gibi parametreler URL’e eklenir.
- **API (server-to-server)**: ikas, uygulamanızın API endpoint’ine imzalı bir POST isteği gönderir; siz doğrulayıp işlersiniz.

## Başlangıç (CLI ile hızlı kurulum)

<Callout type="info" title="Dashboard Actions App şablonu">
ikas CLI ile yeni proje oluştururken "Dashboard Actions App" şablonunu seçtiğinizde, örnek iframe ve API aksiyonları ile gerekli aksiyon tanımlamaları otomatik gelir. Böylece ek bir konfigürasyon adımı gerekmeksizin doğrudan geliştirmeye başlayabilirsiniz.
</Callout>

## Güvenlik (Özet)

<Callout type="warning" title="API aksiyonlarında imza doğrulaması zorunludur">
```ts
import crypto from 'crypto';

function validateWebhookSignature(data: string, received: string, secret: string) {
  const expected = crypto.createHmac('sha256', secret).update(data, 'utf8').digest('hex');
  return expected === received;
}
```
</Callout>

<Callout type="warning" title="iframe aksiyonlarında JWT doğrulaması yapın">
```ts
// Frontend: App Bridge ile token alın
const token = await TokenHelpers.getTokenForiframeApp();

// Backend: İstekten kullanıcıyı doğrulayın
const user = getUserFromRequest(request);
if (!user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
```
</Callout>

<Callout type="info" title="Güvenlik en iyi uygulamalar">
- Token/secret değerlerini asla loglamayın
- API çağrılarını her zaman backend üzerinden yapın
- Oran sınırlama (rate limiting) uygulayın
</Callout>

## Hızlı Akışlar

**API Action**
1. ikas, imzalı `POST` isteği gönderir (`signature`, `data`).
2. Endpoint’inizde imzayı doğrulayın ve `data`yı parse edin.
3. Yetkili uygulama için OAuth/erişim bilgisini alın.
4. ikas GraphQL API ile veriyi çekin/işleyin.
5. Yapılandırılmış JSON yanıt döndürün.

**iframe Action**
1. ikas, `actionRunId`, `idList`, `userLocale` parametreleriyle sayfanızı iframe’de açar.
2. App Bridge ile JWT alın, backend API’nize gönderin.
3. Backend, JWT’yi doğrular; ikas GraphQL API çağrılarını yapar.
4. Frontend, dönen veriyi ekranda gösterir.

**Özet Akış (API)**

```
ikas Admin → POST request with signature → Your API Endpoint → Process → Return JSON response
```

**Özet Akış (iframe)**

```
ikas Admin → Opens iframe with your URL → Your page loads → Fetch data via backend API → Display UI
```

## CLI ve Örnek Proje

- **CLI**: ikas CLI ile yeni proje oluştururken “Dashboard Actions App” şablonunu seçerek hızla başlayabilirsiniz.
- **Örnek depo**: Tamamlanmış bir örnek için GitHub’daki `Dashboard Actions App` projesine göz atın: [dashboard-actions-app](https://github.com/ikascom/ikas-app-examples/tree/main/examples/dashboard-actions-app)

## Hızlı Test

**API Action (curl)**

```bash
SECRET="your-app-secret"
DATA='{"actionRunId":"test-123","idList":["order-id"],"userLocale":"en"}'
SIGNATURE=$(echo -n "$DATA" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl -X POST http://localhost:3000/api/ikas/actions/order-detail \
  -H "Content-Type: application/json" \
  -d "{\
    \"signature\": \"$SIGNATURE\",\
    \"authorizedAppId\": \"your-app-id\",\
    \"merchantId\": \"your-merchant-id\",\
    \"data\": \"$DATA\"\
  }"
```

**iframe Action (tarayıcı)**

```
http://localhost:3000/ikas/actions/order-detail?actionRunId=test-123&idList=order-id&userLocale=tr
```

## Lokalizasyon

Aksiyonlar `userLocale` parametresiyle çok dilli çalışabilir (`tr`, `en`). API yanıtları ve iframe arayüz metinleri için bu değeri kullanın.

## SSS (Sık Sorulan Sorular)

- **iframe sayfam yükleniyor ama veri gelmiyor, neden?**
  - App Bridge token’ı alınıp backend’e iletiliyor mu? Backend JWT doğrulaması yapıyor mu? Backend üzerinden ikas API çağrısı yapıyor musunuz?
- **API aksiyonunda 401 Invalid signature alıyorum.**
  - Uygulama secret’ınız doğru mu? `data` UTF-8 ile imzalanıyor mu? HMAC-SHA256 kullanıyor musunuz?
- **Toplu işlemde performans yavaş.**
  - Backend’de istekleri paralelleştirin ve yanıtları birleştirin; oran sınırlama ve retry stratejisi uygulayın.
- **Çok dilli metinleri nasıl yönetmeliyim?**
  - `userLocale` ile çeviri anahtarlarını seçin; TR/EN anahtarlarınızı tek bir yerden yönetin.

## Sık Karşılaşılan Sorunlar

- **401 Invalid signature (API)**: Secret doğru mu? `data` UTF-8 ile imzalanıyor mu? Algoritma `sha256` mı?
- **Unauthorized (iframe)**: App Bridge’den token geliyor mu? Backend JWT doğrulaması doğru mu?
- **GraphQL hata**: Şema/izinler doğru mu? Sorgu değiştiyse codegen çalıştırıldı mı?