---
title: ikas SDK Kullanımı
description: ikas, uygulamanızın mağaza verilerine erişmesi için güçlü bir GraphQL API sağlar. Bu rehberde GraphQL Playground kullanımından production-ready kod yazımına kadar tüm süreçleri ele alacağız.
---

## GraphQL Playground

ikas GraphQL Playground, API'yi keşfetmek ve sorguları test etmek için interaktif bir araçtır.

### Playground'a Erişim

GraphQL Playground'a [https://api.myikas.com/api/v2/admin/graphql](https://api.myikas.com/api/v2/admin/graphql) adresinden erişebilirsiniz.

<Callout type="warning" title="Token Gerekli">
Playground'u kullanmak için geçerli bir access token'a ihtiyacınız vardır. Token'ı Authorization header'ında `Bearer YOUR_TOKEN` formatında göndermelisiniz.
</Callout>

### İlk Query'nizi Yazma

Playground arayüzü aşağıdaki gibi görünecektir:


Playground'da sol panele aşağıdaki örnek query'yi yapıştırın:

```graphql
query ListProducts($pagination: PaginationInput) {
  listProduct(pagination: $pagination) {
    count
    data {
      id
      name
      description
      totalStock
      type
      brand {
        name
      }
      variants {
        id
        barcodeList
      }
    }
  }
}
```

### Variables Kullanımı

Query'nizde değişkenler kullanmak için alt paneldeki "Query Variables" bölümüne şunu ekleyin:

```json
{
  "pagination": {
    "limit": 10,
    "page": 1
  }
}
```

### Headers Ayarlama

"HTTP Headers" bölümüne access token'ınızı ekleyin:

```json
{
  "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
```

<Callout type="info" title="Schema Explorer">
Sağ paneldeki "Schema" sekmesinde tüm mevcut query'ler, mutation'lar ve type'ları keşfedebilirsiniz. Bu, API'nin ne sunduğunu anlamanın en iyi yoludur.
</Callout>

## GraphQL Code Generation

### GraphQL Codegen Nedir?

GraphQL Code Generation, GraphQL şemanızdan otomatik olarak TypeScript tipleri ve client kodu üretir. Bu sayede:

- **Type Safety**: Compile-time'da type kontrolü
- **IntelliSense**: IDE'nizde otomatik tamamlama
- **Hata Azaltma**: Runtime hatalarının önlenmesi
- **Geliştirici Deneyimi**: Daha hızlı ve güvenli kodlama

### Codegen Kurulumu

ikas starter projesinde codegen zaten kurulu gelir. Konfigürasyon dosyası `codegen.ts`:

```typescript title="src/lib/ikas-client/codegen.ts"
import type { CodegenConfig } from '@graphql-codegen/cli';
import { preset } from '@ikas/admin-api-client';

const config: CodegenConfig = {
  schema: {
    'https://api.myikas.com/api/v2/admin/graphql': {
      headers: {
        'Content-Type': 'application/json',
      },
    },
  },
  documents: ['src/lib/ikas-client/**/*.ts'],
  generates: {
    'src/lib/ikas-client/generated/graphql.ts': {
      preset,
      plugins: [],
      presetConfig: {
        gqlTagName: 'gql',
      },
    },
  },
};

export default config;
```

### GraphQL Requests Dosyası

Tüm GraphQL dokümanlarınızı `src/lib/ikas-client/graphql-requests.ts` dosyasında tanımlayın:

```typescript title="File: src/lib/ikas-client/graphql-requests.ts"
import { gql } from 'graphql-request';

export const LIST_PRODUCTS = gql`
  query ListProducts($pagination: PaginationInput) {
    listProduct(pagination: $pagination) {
      count
      data {
        id
        name
        description
        totalStock
        type
        brand {
          name
        }
        variants {
          id
          barcodeNumber
        }
        categories {
          id
          name
        }
      }
    }
  }
`;

export const GET_PRODUCT = gql`
  query GetProduct($id: ID!) {
    getProduct(id: $id) {
      id
      name
      description
      totalStock
      type
      brand {
        name
      }
      variants {
        id
        barcodeList
      }
    }
  }
`;

export const CREATE_PRODUCT = gql`
  mutation CreateProduct($input: CreateProductInput!) {
    createProduct(input: $input) {
      id
      name
      type
      totalStock
    }
  }
`;
```

### Kod Üretimi

GraphQL dokümanlarınızı ekledikten sonra kod üretmek için:

```bash
pnpm codegen
```

Bu komut `src/lib/ikas-client/generated/graphql.ts` dosyasında `ikasAdminGraphQLAPIClient` sınıfı ve type-safe methodları üretir.

<Callout type="info" title="Otomatik Üretim">
Her `graphql-requests.ts` değişikliğinde `pnpm codegen` komutunu çalıştırmanız gerekir. Bu süreci otomatikleştirmek için file watcher kullanabilirsiniz.
</Callout>

## ikas API Client Kullanımı

### getIkas Helper Fonksiyonu

API çağrıları için `getIkas` helper fonksiyonunu kullanın:

```typescript title="File: src/helpers/api-helpers.ts"
import { OAuthAPI } from '@ikas/admin-api-client';
import moment from 'moment';
import { AuthToken } from '../models/auth-token';
import { AuthTokenManager } from '../models/auth-token/manager';
import { ikasAdminGraphQLAPIClient } from '../lib/ikas-client/generated/graphql';
import { config } from '../globals/config';

export function getIkas(token: AuthToken): ikasAdminGraphQLAPIClient<AuthToken> {
  return new ikasAdminGraphQLAPIClient<AuthToken>({
    graphApiUrl: config.graphApiUrl!,
    accessToken: token.accessToken,
    tokenData: token,
    onCheckToken: () => onCheckToken(token),
  });
}

export async function onCheckToken(token?: AuthToken): Promise<{ accessToken: string | undefined; tokenData?: AuthToken }> {
  try {
    if (!token) {
      return { accessToken: undefined };
    }

    const now = new Date();
    const expireDate = new Date(token.expireDate);

    if (now.getTime() >= expireDate.getTime()) {
      const response = await OAuthAPI.refreshToken(
        {
          refresh_token: token.refreshToken,
          client_id: process.env.NEXT_PUBLIC_CLIENT_ID!,
          client_secret: process.env.CLIENT_SECRET!,
        },
        {
          storeName: 'api',
          storeDomain: '.myikas.dev',
        },
      );

      if (response.data) {
        const newExpireDate = moment().add(response.data.expires_in, 'seconds').toDate().toISOString();

        token.accessToken = response.data.access_token;
        token.refreshToken = response.data.refresh_token;
        token.tokenType = response.data.token_type;
        token.expiresIn = response.data.expires_in;
        token.expireDate = newExpireDate;

        await AuthTokenManager.put(token);

        return { accessToken: token.accessToken, tokenData: token };
      }
    }

    return { accessToken: undefined };
  } catch (error) {
    console.error('Failed to check or refresh token:', error);
    return { accessToken: undefined };
  }
}
```

### Auth Helper Fonksiyonları

Request'ten kullanıcı bilgisi almak için `src/lib/auth-helpers.ts` dosyası:

```typescript title="File: src/lib/auth-helpers.ts"
import { NextRequest } from 'next/server';
import { JwtHelpers } from '../helpers/jwt-helpers';
import { AuthToken } from '../models/auth-token';
import { AuthTokenManager } from '../models/auth-token/manager';

export function getUserFromRequest(request: NextRequest) {
  try {
    const authHeader = request.headers.get('authorization');
    
    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      return null;
    }
    
    const jwtToken = authHeader.substring(7);
    const payload = JwtHelpers.verifyToken(jwtToken);
    
    if (!payload || !payload.sub || !payload.aud) {
      return null;
    }
    
    return {
      merchantId: payload.sub,
      authorizedAppId: payload.aud
    };
  } catch (error) {
    return null;
  }
}

export async function getTokenFromUser(merchantId: string, authorizedAppId: string): Promise<AuthToken | null> {
  return await AuthTokenManager.get(authorizedAppId);
}
```

### Generated Client Kullanımı

Codegen ile üretilen client'ı kullanarak type-safe sorgular çalıştırın:

```typescript title="File: src/app/api/products/route.ts"
import { NextRequest, NextResponse } from 'next/server';
import { getIkas } from '@/helpers/api-helpers';
import { getUserFromRequest } from '@/lib/auth-helpers';
import { AuthTokenManager } from '@/models/auth-token/manager';

export async function GET(request: NextRequest) {
  try {
    const user = getUserFromRequest(request);
    if (!user) {
      return NextResponse.json(
        { error: 'Authentication required' },
        { status: 401 }
      );
    }
    
    const token = await AuthTokenManager.get(user.authorizedAppId);
    if (!token) {
      return NextResponse.json(
        { error: 'Token not found' },
        { status: 401 }
      );
    }
    
    const ikasClient = getIkas(token);
    
    // Generated client ile sorgu
    const result = await ikasClient.query({
      query: `
        query ListProducts($pagination: PaginationInput) {
          listProduct(pagination: $pagination) {
            count
            data {
              id
              name
              description
              totalStock
              type
              brand {
                name
              }
            }
          }
        }
      `,
      variables: {
        pagination: {
          limit: 20,
          page: 1
        }
      }
    });

    return NextResponse.json({
      products: result.data.listProduct.data,
      total: result.data.listProduct.count
    });
  } catch (error) {
    return NextResponse.json(
      { error: 'Ürünler yüklenirken hata oluştu' },
      { status: 500 }
    );
  }
}
```


### Mutation Örneği

```typescript title="File: src/app/api/create-product/route.ts"
import { NextRequest, NextResponse } from 'next/server';
import { getIkas } from '@/helpers/api-helpers';
import { getUserFromRequest } from '@/lib/auth-helpers';
import { AuthTokenManager } from '@/models/auth-token/manager';

export async function POST(request: NextRequest) {
  try {
    const user = getUserFromRequest(request);
    if (!user) {
      return NextResponse.json(
        { error: 'Authentication required' },
        { status: 401 }
      );
    }
    
    const token = await AuthTokenManager.get(user.authorizedAppId);
    if (!token) {
      return NextResponse.json(
        { error: 'Token not found' },
        { status: 401 }
      );
    }
    
    const ikasClient = getIkas(token);
    const productData = await request.json();

    const result = await ikasClient.mutation({
      query: `
        mutation CreateProduct($input: CreateProductInput!) {
          createProduct(input: $input) {
            id
            name
            type
            totalStock
          }
        }
      `,
      variables: {
        input: {
          name: productData.name,
          type: productData.type || "SIMPLE"
        }
      }
    });

    return NextResponse.json(result.data);
  } catch (error) {
    return NextResponse.json(
      { error: 'Ürün oluşturma hatası' },
      { status: 500 }
    );
  }
}
```

## Sonraki Adımlar

ikas SDK'nın temellerini öğrendikten sonra, aşağıdaki konulara göz atabilirsiniz:

<Callout type="info" title="İleri Seviye Konular">
**SDK'yı daha etkili kullanmak için:**

- [Pratik Örnekler](/docs/app-development/ikas-sdk-kullanimi/pratik-ornekler) - Test edilmiş query örnekleri ve kullanım şekilleri
- [Webhook Entegrasyonu](/docs/app-development/ikas-sdk-kullanimi/webhook-entegrasyonu) - Real-time event handling ve webhook sistemleri
</Callout>