Talep açma

Bu sayfa v1/integration/tickets ile kendi sisteminizden FlowDesk’e talep açmanın tüm ayrıntılarını anlatır. Bir API token’ınız yoksa önce Kimlik doğrulama sayfasına bakın; token olmadan bu endpoint’lerin hiçbiri çalışmaz.

İki endpoint, tek öneri

Endpoint	Yanıt	Kullanım
POST /v1/integration/tickets	202 + trackingKey	Önerilen. Havuz varsayımı, atama ve karşılama e-postası isteğinizin dışında (arka planda) çalışır.
POST /v1/integration/tickets/sync	201 + tam talep gövdesi	Önerilmez. Aynı işler isteğiniz üzerinde çalışır: yanıt süresi belirgin şekilde daha yüksektir ve yavaş bir bağımlılık (ör. e-posta sağlayıcısı) sizin timeout’unuz olur. Yanıtı Deprecation: true ve Link: </v1/integration/tickets>; rel="successor-version" başlıklarıyla işaretler. Idempotency-Key desteklemez: tekrarlanan bir çağrı ikinci bir talep açar. Yalnızca gerçekten polling yapamayan entegrasyonlar için vardır.

Aşağıdaki örneklerin tamamı async (/tickets) endpoint’e göredir; alan sözleşmesi ikisinde de aynıdır.

Zorunlu ve isteğe bağlı alanlar

curl -s -X POST https://api.ornek.com/v1/integration/tickets \
  -H "Authorization: Bearer fd_ab12cd34ef...9f" \
  -H "Content-Type: application/json" \
  -d '{
        "subject": "Kart işlemi hesapta görünmüyor",
        "description": "Son işlem hesabımda görünmüyor, iki gündür bekliyorum.",
        "priority": "High",
        "requesterFullName": "Ayşe Yılmaz",
        "requesterEmailAddress": "ayse@ornek.com",
        "requesterPhoneNumber": "+905551234567",
        "poolId": 7
      }'

Alan	Zorunlu mu	Not
subject	Koşullu	subject ve description’dan en az biri zorunludur; ikisi de boşsa 422. Azami 512 karakter.
description	Koşullu	Yukarıdaki koşula tabi. Azami 8000 karakter.
priority	Hayır	Aşağıya bakın: yalnızca iki değer geçerli. Boş bırakılırsa deployment’ın varsayılanı (Medium) uygulanır.
requesterFullName	Hayır	Azami 256 karakter.
requesterEmailAddress	Hayır	Geçerli bir e-posta biçimi olmalı. Verilirse takip linkini içeren karşılama e-postası bu adrese gönderilir.
requesterPhoneNumber	Hayır	Azami 256 karakter; biçim doğrulaması yapılmaz.
poolId	Koşullu	Aşağıdaki “Havuz seçimi” bölümüne bakın.

priority yalnızca iki değer kabul eder: Medium ve High (büyük/küçük harf duyarsız). FlowDesk’in talep önceliği modeli Low/Normal/Critical gibi ek kademeler taşımaz: bu ikisi dışında bir değer ("Normal" dahil) doğrulamadan geçmez ve 422 döner. Alan boş bırakılırsa deployment’ın varsayılan önceliği (Medium) kullanılır.

Talep kaynağı (ticketSourceId) hiçbir zaman request body’de gönderilmez. Token’ınızdan çözülür; raporlamada her entegrasyon kendi kanalı olarak görünsün diye böyledir.

Havuz seçimi: poolId

poolId, token’ınızın izinli olduğu havuz kümesi içinden seçim yapar. O kümeyi asla genişletemez:

Token’ın kapsamı	poolId	Boş bırakılırsa	Kapsam dışı bir değer verilirse
Tek havuz	İsteğe bağlı	O tek havuz varsayılır	403
Birden çok havuz	Zorunlu	422: hedef belirsiz	403
Tüm havuzlar (allPools)	Zorunlu	422: hedef belirsiz	403

Müşteri eşleştirme yoktur: yalnızca talep sahibi alanları

FlowDesk, requesterFullName / requesterEmailAddress / requesterPhoneNumber alanlarını e-posta veya telefona göre eşleştirip tekilleştiren bir müşteri/kişi kaydı tutmaz. Her talep, kendi talep-sahibi bilgisini kendi üzerinde taşıyan bağımsız bir kayıttır; aynı e-postayla daha önce açılmış başka talepler arasında otomatik bir bağlantı kurulmaz. requesterEmailAddress’in tek işlevsel etkisi: verilmişse, takip linkini içeren karşılama e-postasının o adrese gönderilmesidir.

Kendi sisteminizde bir müşteri/talep eşleşmesi kurmanız gerekiyorsa (ör. “bu talep hangi siparişe ait”) bunu kendi tarafınızda, trackingKey’i kendi kaydınızla ilişkilendirerek yapmanız gerekir; aşağıya bakın.

Ek dosya yükleme desteklenmiyor

v1/integration/tickets (async veya sync) dosya eki kabul etmez. Request body’de böyle bir alan yoktur ve bu sürümde eklenmesi planlanmıyor. Talebe ek dosya iliştirmeniz gerekiyorsa bunu talep açıldıktan sonra panel üzerinden (bir ajan/yönetici olarak) yapmanız gerekir; entegrasyon token’ınız bu işlem için kullanılamaz.

Güvenli tekrar deneme: Idempotency-Key

Ağ zaman aşımı gibi durumlarda “isteğim gitti mi gitmedi mi” belirsizliğini çözmek için async endpoint’e bir Idempotency-Key başlığı gönderin:

curl -s -X POST https://api.ornek.com/v1/integration/tickets \
  -H "Authorization: Bearer fd_ab12cd34ef...9f" \
  -H "Idempotency-Key: siparis-42-deneme-1" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "...", "description": "..." }'

Durum	Davranış
Aynı anahtar + aynı gövde	Orijinal 202 yanıtı tekrar döner. Yeni talep açılmaz.
Aynı anahtar + farklı gövde	409. Anahtarı farklı bir talep için tekrar kullandınız. İstemci mantığınızda bir hata var.
Aynı anahtarla eşzamanlı iki istek	Anahtar iddiası atomiktir; tam olarak bir talep açılır.
Anahtarın geçerlilik penceresi	24 saat. Bu sürenin ardından aynı anahtar yeni bir istek gibi işlenir.

Anahtarlar token başına ayrılır: iki farklı entegrasyonun aynı anahtarı seçmesi çakışmaz.

Response body ve talep anahtarının saklanması

Async endpoint, talep kuyruğa alındığında hemen 202 döner:

{ "success": true, "data": { "trackingKey": "K7xQm9Zp...eF5A", "status": "queued" } }

trackingKey, talebin oluştuğu anlamına gelmez: kuyruğa girdiği anlamına gelir. Gerçek talep kaydı, isteğinizin dışında (arka planda) birazdan oluşturulur. trackingKey, rastgele üretilmiş, URL güvenli, ~64 karakterlik opak bir dizedir: FD- gibi bir önek ya da okunabilir bir yapı taşımaz; içeriğinden bir anlam çıkarmaya çalışmayın, yalnızca saklayıp geri sorgulamak için kullanın.

Bu değeri kendi sisteminizde saklayın: kendi talep/sipariş/kayıt kimliğinizle ilişkilendirerek. Bu, hem talebin sonucunu daha sonra sorgulamanızı (aşağıya bakın) hem de son kullanıcının kendi talebini takip edebilmesini sağlayan tek bağlantı noktasıdır. FlowDesk tarafında sizin kendi kaydınıza geri dönük bir referans tutulmaz.

Talebi geri okuma

202 aldıktan kısa bir süre sonra, artan aralıklarla (ör. 1s, 2s, 4s) aşağıdaki endpoint’e sorun:

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

Talep henüz oluşmadıysa 404: bu bir hata değildir, beklenen ilk durumdur; artan aralıklarla tekrar deneyin. Oluştuğunda aynı endpoint 200 ve talebin tam gövdesini döner. Bu endpoint kasıtlı olarak cache’lenmez, aksi hâlde kabul edilmiş bir istek cache penceresi boyunca “kayıp” görünürdü.

Talebi id ile de okuyabilirsiniz (GET /v1/integration/tickets/{id}); bu yanıt bir ETag taşır; tekrar sorguda If-None-Match gönderirseniz talep değişmemişse gövdesiz bir 304 alırsınız. Bu endpoint, listelemenin aksine, her yazımda geçersiz kılınır: yani hiçbir zaman değişiklikten daha bayat değildir.

Response body, entegrasyon yüzeyine özgü, kasıtlı olarak dar bir kesittir: id, trackingKey, subject, description, priority, ticketStatusId, ticketStatusName, ticketSubStatusId, requesterFullName, requesterEmailAddress, requesterPhoneNumber, createdAt, completedAt, etag. Atanan ajan, departman, SLA bayrakları gibi iç yönlendirme bilgisi bu yanıtta hiç yer almaz. Entegratörün işi değildir.

Listeleme ve filtreleme

curl -s "https://api.ornek.com/v1/integration/tickets?perPage=50&requesterEmail=ayse@ornek.com&createdAtGte=2026-08-01" \
  -H "Authorization: Bearer fd_ab12cd34ef...9f"

Çalışan filtreler: statusIds, requesterEmail, requesterPhone, trackingKey, createdAtGte, createdAtLte (tarih-yalnız, YYYY-MM-DD). Sayfalama/sıralama: page, perPage, field, order.

• perPage 100’de tavanlanır. Daha yüksek bir değer hataya değil, sessizce 100’e indirilir.
• API referansında updatedAtGte / updatedAtLte parametreleri de görünür, ancak bu listeleme hiçbir filtreye bağlamaz. Gönderseniz de sonucu değiştirmez. Tarihe göre daraltmak için createdAtGte / createdAtLte kullanın.
• field= yalnızca şunları kabul eder: id, trackingKey, description, priority, ticketStatusId, ticketSubStatusId, requesterFullName, requesterEmailAddress, requesterPhoneNumber, createdAt, completedAt. Yanıtta görünen subject, ticketStatusName ve etag alanları bile bununla sıralanamaz (400). Bu alanlar iç veri modelinde farklı bir adla saklanır ya da yalnızca yanıt için hesaplanır.

Liste yanıtı yalnızca süreyle cache’lenir (varsayılan 45 saniye) ve yazımda geçersiz kılınmaz. Az önce açtığınız veya durumunu değiştirdiğiniz bir talep bu süre boyunca listede görünmeyebilir veya eski hâliyle görünebilir. Bir talebin o anki durumunu öğrenmek için her zaman tekil talep okuma ya da by-tracking-key kullanın; liste endpoint’i toplu tarama ve raporlama içindir, an be an doğruluk için değil.

Hata sözleşmesi

Durum	Kod	Anlamı
401	FD:0004	Credential eksik, geçersiz, süresi dolmuş veya iptal edilmiş. Tekrar denemeyin; kimlik doğrulama sayfasındaki kontrol listesine bakın.
403	FD:0001	Geçerli bir credential, ama yetersiz kapsam veya talebi izinli olmadığınız bir poolId ile açmaya çalışma: ikisi de aynı kodu taşır; ayrımı yanıt mesajından okuyun.
404	FD:0002	Talep yok, izinli olmadığınız bir havuza ait, veya async talep henüz oluşmadı. Son durumda artan aralıklarla tekrar deneyin.
409		Aynı Idempotency-Key, farklı gövde. İstemci mantığınızda bir hata; tekrar denemeyin.
422		Gövde doğrulaması başarısız (error.details alan bazlı liste taşır), poolId belirsiz kaldı, ya da hedef havuz entegrasyon talebi almak için tam yapılandırılmamış. Düzeltmeden tekrar denemeyin.
429		Rate limit aşıldı. Retry-After süresi kadar bekleyip tekrar deneyin.
503	FD:0011	Deployment’ın lisans durumu isteği geçici olarak reddediyor. Sizin isteğinizle ilgili değil; geri çekilip tekrar deneyin.

Rate limit: her token’ın kendi bütçesi vardır (varsayılan dakikada 120 istek, token id’sine göre bölütlenir). Başarılı bir yanıt rate limit başlığı taşımaz; kalan kotanızı önceden göremezsiniz; yalnızca 429 aldığınızda Retry-After ile öğrenirsiniz.

Sırada ne var

• Son kullanıcının, sizin oluşturduğunuz trackingKey ile kimlik doğrulamadan talebini takip etmesi: Talep takibi
• Talep durumu değiştiğinde nasıl haberdar olursunuz (webhook yok, polling var): Webhook ve otomasyon
• Tam endpoint sözleşmesi: POST /v1/integration/tickets · GET /v1/integration/tickets · GET /v1/integration/tickets/{id} · GET .../by-tracking-key/{trackingKey} · POST /v1/integration/tickets/sync