İçeriğe geç

10. User story: Tek link, çok kanal

Bir tenant olarak, bir yolcuya aynı anketi e-posta, push bildirimi ve mobil uygulama üzerinden göndermek istiyorum; böylece yolcu hangi kanaldan doldurursa doldursun tek yanıt sayılsın, yanıtın hangi kanaldan geldiğini göreyim ve mobil uygulamada hangi anketlerin doldurulduğunu toplu olarak sorgulayabileyim.

  • Aynı yolcu (ör. PNR + soyad + tarih) için tekrar istenen link, ilk üretilen linkin aynısıdır.
  • Link üç kanaldan gönderilir; yolcu ilk hangi kanaldan gönderirse o yanıt kaydedilir, diğer kanallarda link “daha önce kullanıldı” der.
  • Yanıtta, linkin hangi kanaldan doldurulduğu (email, push, mobile-app) görünür.
  • Tek istekte en fazla 100 linkin durumu (answered, pending, …) sorulabilir.
  • API anahtarı yalnızca tenant sunucusunda durur; mobil uygulama durumu tenant sunucusu üzerinden sorar.
KimNe yaparNerede
Anket yöneticisiGizli kanal sorusunu ekler, URL ön doldurmayı açar, API entegrasyonunu oluştururPanel
Tenant sunucusuYolcu başına link üretir, kanallara dağıtır, durum sorarlink-sharings, link-statuses
Tenant kanalları (e-posta, push, uygulama)Aynı linkin sonuna kendi channel değerini ekleyip gönderirKendi sistemleri
YolcuLinki açar ve anketi doldururAnket formu
Mobil uygulamaHangi anketlerin doldurulduğunu tenant sunucusuna sorarTenant backend

Ankete yolcuya görünmeyen bir “Kanal” sorusu eklenir ve URL ile ön doldurma açılır. Kanal kaydı istenmiyorsa bu adım atlanabilir; link tekilleştirme ve durum sorgusu bu adım olmadan da çalışır.

  1. Anketler menüsünden anketi aç, Düzenle sekmesine geç.
  2. Soldaki soru tiplerinden Açık Metin’e tıkla. Başlığı “Kanal” yaz.
  3. Sorunun sağ üstündeki ⋯ (Diğer işlemler) menüsünden Soruyu Gizle’yi seç. Soruda “Gizli” rozeti görünür.
  4. Sorunun ⚙ (Soru ayarları) penceresini aç:
    • Entegrasyon Anahtarı alanına channel yaz.
    • Zorunlu anahtarını kapat. Gizli soru zorunlu olursa kanal değeri gelmeyen yanıtlar engellenir.
    • Kişisel Verileri Gizle kapalı kalsın; açık bir soruya URL’den değer yazılamaz.
  5. Pencereyi kapat ve sağ üstten Kaydet’e bas.
  6. Dağıtım → Public Link sekmesinde Mobil push URL ile ön doldurma anahtarını aç ve tekrar Kaydet’e bas. Bu kapalıyken linke eklenen ?responses= parametresi yok sayılır.
  1. Anketin Dağıtım → API Entegrasyonları sekmesinde Yeni Entegrasyon’a tıkla.
  2. Teslimat Modu: Sadece link dön. “E-posta ile gönder” modunda external_key kabul edilmez.
  3. Entegrasyon Adı: tenantı tanıtan bir ad (ör. “Tenant Yolcu Anketi”).
  4. Link Geçerlilik Süresi (gün): tenantın durum sorgulamaya devam edeceği süreden uzun olmalı (1–365). Süresi dolan linkler gece silinir ve sorguda not_found döner.
  5. Tek Kullanımlık: aç. Kapalı kalırsa aynı link birden fazla yanıt alır.
  6. Oluştur’a bas. Açılan pencerede:
    • API Anahtarı (tkc_…) yalnız bir kez gösterilir; tenant sunucusunun gizli ayarlarına kaydet.
    • Endpoint satırındaki link-campaigns/<kampanya-id>/ kısmı kampanya kimliğidir.

Anahtar kaybolursa entegrasyon satırından yenilenir; yenileme eski anahtarı hemen geçersiz kılar.

Tenant sunucusu her yolcu için bir kez link-sharings isteği atar. Aynı external_key ile tekrar istek gelirse yeni link üretilmez, ilk link döner.

POST/api/v1/external/surveys/link-campaigns/{campaignId}/link-sharings

POST /api/v1/external/surveys/link-campaigns/{campaignId}/link-sharings
Authorization: Bearer <kampanya anahtarı>
Content-Type: application/json
{
"external_key": "ABC123|YILMAZ|2026-12-01",
"built_in_responses": { "PNR": "ABC123", "Soyad": "YILMAZ", "Tarih": "2026-12-01" },
"options": { "single_use": true }
}
AlanZorunluAçıklama
external_keyHayırYolcunun kendi değerleri (ör. PNR, soyad, tarih), en fazla 128 karakter. Her kanalda birebir aynı yazılmalı.
built_in_responsesHayırAnkette gizli soruların Entegrasyon Anahtarı ile eşleşen değerler. Eşleşmeyen anahtar 422 döner.
options.single_useHayırtrue olmalı; yoksa kampanyanın varsayılanı kullanılır.
options.expires_atHayırLinkin bitiş zamanı (ISO 8601); verilmezse kampanya süresi.

Yanıt (201):

{
"url": "https://s.air.tk/p/0aH0bmVMEyOVADliG8vyGH",
"token": "0aH0bmVMEyOVADliG8vyGH",
"expires_at": "2026-12-08T09:00:00.000Z",
"campaign_id": "…",
"created": true,
"status": "pending"
}
  • created: false = bu external_key için daha önce üretilmiş link döndü; ilk isteğin içeriği geçerlidir.
  • status = dönen linkin durumu. Tekrar gelen istekte revoked veya expired ise bu link artık kullanılamaz.
  • token ve url saklanmalı; durum sorgusu token ya da external_key ile yapılır.
  • channel değeri bu istekte gönderilmez: link oluşturulurken verilen değer URL’deki değerden önceliklidir ve her kanalda aynı görünür.

Aynı url üç kanala gönderilir; her kanal sonuna kendi ?responses= parametresini ekler. Parametre, [{"question":"channel","answer":"<kanal>"}] JSON’unun base64 halidir.

KanalJSON?responses= değeri
E-posta[{"question":"channel","answer":"email"}]W3sicXVlc3Rpb24iOiJjaGFubmVsIiwiYW5zd2VyIjoiZW1haWwifV0=
Push[{"question":"channel","answer":"push"}]W3sicXVlc3Rpb24iOiJjaGFubmVsIiwiYW5zd2VyIjoicHVzaCJ9XQ==
Mobil uygulama[{"question":"channel","answer":"mobile-app"}]W3sicXVlc3Rpb24iOiJjaGFubmVsIiwiYW5zd2VyIjoibW9iaWxlLWFwcCJ9XQ==

Örnek push linki:

https://s.air.tk/p/0aH0bmVMEyOVADliG8vyGH?responses=W3sicXVlc3Rpb24iOiJjaGFubmVsIiwiYW5zd2VyIjoicHVzaCJ9XQ==
  • Mobil uygulama linki WebView’da açar; ayrı bir SDK gerekmez.
  • Yolcu ilk hangi kanaldan gönderirse o kanalın değeri kaydedilir. Aynı link diğer kanallardan açılınca “Bu link daha önce kullanıldı” görür.
  • sig (imza) parametresi zorunlu değildir. İmza anahtarı tanımlıysa ve linkte sig varsa doğrulanır; doğrulanamazsa gönderim reddedilir.

Mobil uygulama “hangi anketler dolduruldu?” sorusunu tenant sunucusuna sorar; tenant sunucusu link-statuses ile sorar. Tek istekte en fazla 100 link sorulur; ya tokens ya external_keys gönderilir, ikisi birlikte gönderilmez.

POST/api/v1/external/surveys/link-campaigns/{campaignId}/link-statuses

POST /api/v1/external/surveys/link-campaigns/{campaignId}/link-statuses
Authorization: Bearer <kampanya anahtarı>
Content-Type: application/json
{ "external_keys": ["ABC123|YILMAZ|2026-12-01", "XYZ789|KAYA|2026-12-02"] }

Yanıt (200), istekteki sırayla:

{
"results": [
{ "token": "0aH0bmVMEyOVADliG8vyGH", "external_key": "ABC123|YILMAZ|2026-12-01", "status": "answered", "answered_at": "2026-12-02T09:14:00.000Z" },
{ "token": "6tnI8ZbRdmcljlOdx9fU0O", "external_key": "XYZ789|KAYA|2026-12-02", "status": "pending", "answered_at": null }
]
}
statusAnlamı
answeredDolduruldu; answered_at gönderim zamanı.
in_progressYarıda bırakıldı (taslak var) ya da gönderim sürüyor.
pendingHenüz doldurulmadı.
expiredLinkin süresi doldu.
revokedLink iptal edildi.
not_foundBöyle bir link yok, başka kampanyaya ait ya da süresi dolup silindi.

Kampanya duraklatılmışsa durum sorgusu yine çalışır; yeni link üretimi 401 campaign_paused ile reddedilir.

  1. Anketler → Geri Bildirimler: yanıtı aç. Üstte kaynak “API kampanyası · <entegrasyon adı>” yazar; soruların altında Kanal alanı (push, email, mobile-app) görünür.
  2. Anket → Dağıtım → API Entegrasyonları: entegrasyon satırındaki Üretilen Link sayısına tıkla. Liste her linkin oluşturulma, son kullanma, tıklama ve Yanıtlandı bilgisini gösterir.

Aynı yolcu için tekrar gelen istekler yeni link üretmediği için Üretilen Link sayısı yolcu sayısına eşit kalır.

  • Tek biçim seçin. Anahtar yazıldığı gibi karşılaştırılır. “YILMAZ” ile “Yılmaz”, ya da farklı tarih biçimleri ayrı link üretir. Tüm kanallar aynı kuralı kullanmalı (ör. büyük harf, YYYY-AA-GG).
  • Linki bir kez üretin, kanallara dağıtın. Link üretme sınırı kampanya başına dakikada 60 istek; aşılınca 5 dakika tüm kanallar engellenir.
  • Link süresini yeterince uzun tutun. Süresi dolan link gece silinir; aynı anahtarla yeni bir link üretilir ve durum sorgusu eskisi için not_found döner.
  • İptal edilen link bir süre aynı kalır. İptal edilen link süresi dolana kadar aynı anahtara dönmeye devam eder; yanıttaki status: revoked bunu bildirir.
  • in_progress kalıcı olabilir. Nadiren, gönderim yarıda kesilirse link bu durumda kalır.
KodUç noktaNe zamanNe yapılır
401 invalid_keyikisi deAnahtar yok ya da yanlışAnahtarı kontrol edin; gerekirse yenileyin
401 campaign_pausedlink-sharingsKampanya duraklatılmışPanelden kampanyayı aktifleştirin
404 campaign_not_foundikisi deURL’deki kampanya kimliği anahtarın kampanyası değilDoğru kampanya kimliğini kullanın
400link-statuses100’den fazla kayıt ya da tokens ile external_keys birlikteİsteği bölün ya da tek liste gönderin
422 external_key_not_supportedlink-sharingsE-posta modundaki kampanyaya external_key gönderildi“Sadece link dön” modunda entegrasyon kullanın
422 unknown_built_in_response_keylink-sharingsbuilt_in_responses anahtarı ankette yokGizli sorunun Entegrasyon Anahtarını kontrol edin
429link-sharingsDakikalık istek sınırı aşıldıRetry-After kadar bekleyin; istekleri azaltın
410 already_consumedanket formuTek kullanımlık link zaten doldurulduBeklenen davranış; yolcuya “daha önce kullanıldı” görünür