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

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

---

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

---

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

---

## Aksiyonların Göründüğü Yerler

- **Ü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 Query Parametreleri

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

<Callout type="info" title="Parametreler Hakkında">
- Base URL her zaman `action.redirectUrl` olur.
- `idList` virgülle ayrılır.
- `quantityMap` JSON string'dir; URL içinde encode edilmesi tavsiye edilir.
</Callout>

---

## Aksiyon 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.

---

## Güvenlik

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

---

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

---

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

---

## Örnek Proje

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.

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)

---

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

| Hata | Neden | Çözüm |
|------|-------|-------|
| `401 Invalid signature` (API) | Secret yanlış veya `data` UTF-8 ile imzalanmıyor | Secret'ı doğrula, algoritmanın `sha256` olduğunu kontrol et |
| `Unauthorized` (iframe) | App Bridge'den token gelmiyor veya backend JWT doğrulaması yanlış | Token akışını ve backend doğrulamasını kontrol et |
| GraphQL hatası | Şema/izinler yanlış veya sorgu değişti | İzinleri kontrol et, gerekirse codegen'i yeniden çalıştır |
| Toplu işlemde performans yavaşlığı | İstekler sıralı işleniyor | Backend'de istekleri paralelleştir, retry stratejisi uygula |
| iframe veri gelmiyor | App Bridge token'ı backend'e iletilmiyor | Token akışını ve backend JWT doğrulamasını kontrol et |