Hızlı başlangıç

Bu sayfa, çalışan bir FlowDesk kurulumunuz olduğunu varsayar. Kendi kurulumunuzu henüz yapmadıysanız önce Kurulum → Gereksinimler bölümüne bakın.

Aşağıdaki örneklerde API adresi olarak https://api.ornek.com kullanılıyor; kendi kurulumunuzun API adresiyle değiştirin. Bu adresi ve ilk kullanıcı bilgilerinizi FlowDesk panel yöneticinizden (kurulumu yapan ekipten) alırsınız.

Talep açmak için bir API token gerekir; panel girişiyle aldığınız JWT bu iş için geçerli değildir. Token’ı panelden alacağınız için önce panele giriş yapın. Bu iki credential’ın neden ayrı olduğunu Kimlik doğrulama sayfası anlatır.

1. Panele giriş yapın

Bu adım kurulumunuzun kimlik doğrulama sağlayıcısına göre değişir; hangisinin etkin olduğunu Yapılandırma → Kimlik doğrulama sayfasından ya da kurulumu yapan ekipten öğrenebilirsiniz.

EmailPassword etkinse (aşağıdaki gibi çalışır): taze bir kurulumda API, ilk açılışta admin@shft.co kullanıcısını seed’lenmiş bir parolayla otomatik oluşturur. Bu parola burada yayınlanmaz; kurulumunuzu yapan ekipten alın. İlk girişten hemen sonra bu parolayı değiştirin.

curl -s -X POST https://api.ornek.com/v1/dashboard/auth/login \
  -H "Content-Type: application/json" \
  -d '{
        "email": "admin@shft.co",
        "password": "<kurulumu-yapan-ekipten-alacağınız-seed-parola>"
      }'

Yalnızca Keycloak etkinse yukarıdaki uç işe yaramaz: API, parola tabanlı girişten önce EmailPassword sağlayıcısının etkin olduğunu doğrular, değilse isteği reddeder. Bunun yerine panelden, e-postası bir FlowDesk kullanıcısıyla birebir eşleşen bir Keycloak realm kullanıcısıyla oturum açın; ayrıntı için Yapılandırma → Kimlik doğrulama sayfasına bakın.

Beklenen yanıt (200):

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "accessTokenExpiresAt": "2026-08-13T10:15:00Z",
    "refreshToken": "8f2c1a...",
    "refreshTokenExpiresAt": "2026-08-20T10:00:00Z"
  },
  "error": null
}

accessToken alanını bir sonraki adımda kullanacaksınız: sadece panel endpoint’leri için, entegrasyon endpoint’leri için değil.

2. Bir API token oluşturun

Bu adım panelde bir yönetici tarafından yapılır (api-tokens:api-token-create:save izni gerekir). Token, bir veya daha çok havuza (pool) ya da tüm havuzlara (allPools: true) bağlanır: bu kapsam, o token ile hangi havuzlarda talep açılabileceğini belirler. Kendi kurulumunuzdaki havuz id’lerini panelden (Havuzlar sayfası) doğrulayın; aşağıdaki 1 yalnızca bir örnektir.

curl -s -X POST https://api.ornek.com/v1/dashboard/api-tokens \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
        "name": "İlk entegrasyon",
        "scopes": ["tickets:read", "tickets:write"],
        "poolIds": [1],
        "allPools": false
      }'

Beklenen yanıt (201):

{
  "success": true,
  "data": { "id": 1, "token": "fd_ab12cd34ef...9f", "tokenPrefix": "fd_ab12c" },
  "error": null
}

token alanı yalnızca bu yanıtta görünür. Sunucu bundan sonra yalnızca hash’ini saklar; kaybederseniz yapacağınız tek şey yeni bir token oluşturmaktır. Değeri şimdi bir kasaya (secret manager) kaydedin.

3. İlk talebi açın

Artık v1/integration/tickets’ı API token ile çağırabilirsiniz:

curl -s -X POST https://api.ornek.com/v1/integration/tickets \
  -H "Authorization: Bearer fd_ab12cd34ef...9f" \
  -H "Content-Type: application/json" \
  -d '{
        "subject": "Test talebi",
        "description": "Hızlı başlangıç rehberinden açılan ilk talep.",
        "priority": "High",
        "requesterFullName": "Ayşe Yılmaz",
        "requesterEmailAddress": "ayse@ornek.com"
      }'

Yukarıdaki örnekte priority için High kullanıldı. Bu alanın kabul ettiği tüm değerler ve doğrulama kuralları için Talep açma sayfasına bakın.

Beklenen yanıt (202 Accepted):

{
  "success": true,
  "data": { "trackingKey": "TI1LL2-s20EICNKMwYbzr_jzpr_kzZN5bRjz8gdGYS8yZUsm6w6EScY9FKSjTxJV", "status": "queued" },
  "error": null
}

trackingKey insan tarafından okunabilir bir biçim değildir: 64 karakterlik, URL güvenli bir rastgele dizedir (FD-… gibi bir önek ya da öngörülebilir bir kalıp taşımaz). Kendiniz oluşturamaz veya tahmin edemezsiniz; yalnızca sunucunun döndürdüğü değeri kullanın.

Bu endpoint hemen 202 döner; havuz ataması ve karşılama e-postası isteğinizin dışında (arka planda) çalışır. Yukarıdaki örnekte poolId gönderilmedi, çünkü 2. adımda oluşturduğunuz token tek bir havuza bağlı: bu durumda o tek havuz otomatik varsayılır. Havuz seçiminin tam kuralları için Talep açma sayfasındaki “Havuz seçimi” bölümüne bakın.

Ağ zaman aşımı gibi durumlarda güvenle tekrar deneyebilmek için Idempotency-Key başlığı gönderin: aynı anahtar + aynı gövde ikinci bir talep açmaz, orijinal yanıtı tekrar döner.

4. Talebin gerçekten oluştuğunu doğrulayın

trackingKey’i almanız, talebin oluştuğu anlamına gelmez: kuyruğa girdiği anlamına gelir. Kısa bir gecikmeyle (ör. 1s, 2s, 4s geri çekilme) aşağıdaki endpoint’e sorun:

curl -s https://api.ornek.com/v1/integration/tickets/by-tracking-key/TI1LL2-s20EICNKMwYbzr_jzpr_kzZN5bRjz8gdGYS8yZUsm6w6EScY9FKSjTxJV \
  -H "Authorization: Bearer fd_ab12cd34ef...9f"

Talep henüz oluşmadıysa bu endpoint 404 döner: bu bir hata değil, beklenen ilk durumdur. Talep oluştuğunda aynı endpoint 200 ve talebin tam gövdesini döner.

Sırada ne var

Tüm entegrasyon endpoint’lerinin (listeleme, filtreleme, rate limit, hata kodları) tam referansı için: API Referansı
Gelen e-postadan otomatik talep açmak için: E-posta ayarları
Kendi kurulumunuzu sıfırdan yapacaksanız: Kurulum