10. User story: Tek link, çok kanal
User story
Bölüm başlığı “User story”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.
Kabul kriterleri
Bölüm başlığı “Kabul kriterleri”- 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.
| Kim | Ne yapar | Nerede |
|---|---|---|
| Anket yöneticisi | Gizli kanal sorusunu ekler, URL ön doldurmayı açar, API entegrasyonunu oluşturur | Panel |
| Tenant sunucusu | Yolcu başına link üretir, kanallara dağıtır, durum sorar | link-sharings, link-statuses |
| Tenant kanalları (e-posta, push, uygulama) | Aynı linkin sonuna kendi channel değerini ekleyip gönderir | Kendi sistemleri |
| Yolcu | Linki açar ve anketi doldurur | Anket formu |
| Mobil uygulama | Hangi anketlerin doldurulduğunu tenant sunucusuna sorar | Tenant backend |
Adım 1: Anketi hazırla (panel)
Bölüm başlığı “Adım 1: Anketi hazırla (panel)”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.
- Anketler menüsünden anketi aç, Düzenle sekmesine geç.
- Soldaki soru tiplerinden Açık Metin’e tıkla. Başlığı “Kanal” yaz.
- Sorunun sağ üstündeki ⋯ (Diğer işlemler) menüsünden Soruyu Gizle’yi seç. Soruda “Gizli” rozeti görünür.
- Sorunun ⚙ (Soru ayarları) penceresini aç:
- Entegrasyon Anahtarı alanına
channelyaz. - 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.
- Entegrasyon Anahtarı alanına
- Pencereyi kapat ve sağ üstten Kaydet’e bas.
- 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.
Adım 2: API entegrasyonunu oluştur (panel)
Bölüm başlığı “Adım 2: API entegrasyonunu oluştur (panel)”- Anketin Dağıtım → API Entegrasyonları sekmesinde Yeni Entegrasyon’a tıkla.
- Teslimat Modu: Sadece link dön. “E-posta ile gönder” modunda
external_keykabul edilmez. - Entegrasyon Adı: tenantı tanıtan bir ad (ör. “Tenant Yolcu Anketi”).
- 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_founddöner. - Tek Kullanımlık: aç. Kapalı kalırsa aynı link birden fazla yanıt alır.
- 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.
- API Anahtarı (
Anahtar kaybolursa entegrasyon satırından yenilenir; yenileme eski anahtarı hemen geçersiz kılar.
Adım 3: Linki üret (tenant sunucusu)
Bölüm başlığı “Adım 3: Linki üret (tenant sunucusu)”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-sharingsAuthorization: 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 }}| Alan | Zorunlu | Açıklama |
|---|---|---|
external_key | Hayır | Yolcunun kendi değerleri (ör. PNR, soyad, tarih), en fazla 128 karakter. Her kanalda birebir aynı yazılmalı. |
built_in_responses | Hayır | Ankette gizli soruların Entegrasyon Anahtarı ile eşleşen değerler. Eşleşmeyen anahtar 422 döner. |
options.single_use | Hayır | true olmalı; yoksa kampanyanın varsayılanı kullanılır. |
options.expires_at | Hayır | Linkin 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= buexternal_keyiçin daha önce üretilmiş link döndü; ilk isteğin içeriği geçerlidir.status= dönen linkin durumu. Tekrar gelen istekterevokedveyaexpiredise bu link artık kullanılamaz.tokenveurlsaklanmalı; durum sorgusu token ya daexternal_keyile yapılır.channeldeğeri bu istekte gönderilmez: link oluşturulurken verilen değer URL’deki değerden önceliklidir ve her kanalda aynı görünür.
Adım 4: Linki kanallara dağıt
Bölüm başlığı “Adım 4: Linki kanallara dağıt”Aynı url üç kanala gönderilir; her kanal sonuna kendi ?responses= parametresini ekler. Parametre, [{"question":"channel","answer":"<kanal>"}] JSON’unun base64 halidir.
| Kanal | JSON | ?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 linktesigvarsa doğrulanır; doğrulanamazsa gönderim reddedilir.
Adım 5: Durumu sorgula (tenant sunucusu)
Bölüm başlığı “Adım 5: Durumu sorgula (tenant sunucusu)”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-statusesAuthorization: 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 } ]}status | Anlamı |
|---|---|
answered | Dolduruldu; answered_at gönderim zamanı. |
in_progress | Yarıda bırakıldı (taslak var) ya da gönderim sürüyor. |
pending | Henüz doldurulmadı. |
expired | Linkin süresi doldu. |
revoked | Link iptal edildi. |
not_found | Bö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.
Adım 6: Sonuçları panelde gör
Bölüm başlığı “Adım 6: Sonuçları panelde gör”- 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. - 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.
Dikkat edilecekler
Bölüm başlığı “Dikkat edilecekler”- 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_founddö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: revokedbunu bildirir. in_progresskalıcı olabilir. Nadiren, gönderim yarıda kesilirse link bu durumda kalır.
Hata kodları
Bölüm başlığı “Hata kodları”| Kod | Uç nokta | Ne zaman | Ne yapılır |
|---|---|---|---|
401 invalid_key | ikisi de | Anahtar yok ya da yanlış | Anahtarı kontrol edin; gerekirse yenileyin |
401 campaign_paused | link-sharings | Kampanya duraklatılmış | Panelden kampanyayı aktifleştirin |
404 campaign_not_found | ikisi de | URL’deki kampanya kimliği anahtarın kampanyası değil | Doğru kampanya kimliğini kullanın |
400 | link-statuses | 100’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_supported | link-sharings | E-posta modundaki kampanyaya external_key gönderildi | “Sadece link dön” modunda entegrasyon kullanın |
422 unknown_built_in_response_key | link-sharings | built_in_responses anahtarı ankette yok | Gizli sorunun Entegrasyon Anahtarını kontrol edin |
429 | link-sharings | Dakikalık istek sınırı aşıldı | Retry-After kadar bekleyin; istekleri azaltın |
410 already_consumed | anket formu | Tek kullanımlık link zaten dolduruldu | Beklenen davranış; yolcuya “daha önce kullanıldı” görünür |