Karayolu e-Bileti

Karayolu Senaryoları

Karayolu biletinde oluşturma, numara üretme, gider gösterme, yabancı yolcu ve iptal senaryoları.

Genel Bakış

Karayolu e-Bileti request'i; bilet kimliği, yolcu, sefer, hizmet, ödeme ve tutar bilgilerini birlikte taşır. Senaryo seçimi ayrı bir profil alanıyla değil, yolcu uyruğu, gider gösterme tercihi, bilet numarasının kim tarafından üretileceği ve iptal durumu gibi alanlarla yapılır.

Senaryo Kararları

Karar	Gönderilecek alanlar	Ek kural
Bilet numarasını kaynak sistem üretiyor	`TicketNumber`, `TicketModDate`	Numara 16 karakter olmalı, yıl bölümü düzenlenme yılıyla eşleşmeli ve Türkçe karakter içermemelidir.
Bilet numarasını platform üretecek	`LocationCode`; `TicketNumber` boş bırakılır	Response'taki bilet numarası ERP kaydına geri yazılır.
Yolcu Türkiye Cumhuriyeti vatandaşı	`PassangerIsTR=true`, `PassangerTaxOrId`, `PassangerNameSurname`	Kimlik numarası 11 haneli ve yalnız rakam olmalıdır.
Yolcu yabancı	`PassangerIsTR=false`, `PassangerPasaportNo`, `PassangerNameSurname`	Türkiye kimlik alanı yerine pasaport bilgisi kullanılır.
Bilet gider gösterilecek	`IsCustomer=true`, `CustomerTaxOrId`, `CustomerTaxOffice`, müşteri adı	VKN/TCKN 10 veya 11 haneli, yalnız rakam olmalıdır.
Bilet iptal edilecek	Oluşturma request'i yerine mevcut biletin `TicketExternalNumber` değeri	İptal endpoint'i tekrar çağrıldığında iptal edilmiş bilet başarılı/iptal sonucu döndürebilir.

Senaryo Grupları

Grup	Ne zaman kullanılır?	Ayırt edici alan
Normal seyahat	Standart yolcu taşıma bileti	`ServiceType=SEYAHAT`
Ek hizmet	Bagaj, yemek, koltuk seçimi veya diğer hizmetler	`ServiceType`
Gider gösteren	Bilet bir kişi veya firma adına giderleştirilecek	`IsCustomer=true`
Yabancı yolcu	Yolcu T.C. kimlik numarası yerine pasaport kullanıyor	`PassangerIsTR=false`
İptal	Daha önce oluşturulmuş karayolu bileti iptal edilecek	`TicketExternalNumber`

Hizmet ve Ödeme Seçimi

ServiceType boş bırakılamaz. Desteklenen hizmet ve ödeme değerlerinin tam listesi Teknik Referans sayfasındadır. Rapor çıktısında hizmet ve ödeme bilgileri bilet kaydından alınır; kaynak sistem bu alanları kendi serbest metniyle genişletmemelidir.

DIGER kullanımı: Hizmetin standart değerlerden biriyle ifade edilebildiği durumda DIGER seçmeyin. Açıklama ve GİB rapor eşleşmesi Karayolu Alan Kuralları üzerinden kontrol edilmelidir.

İptal Senaryosu

Karayolu iptali yeni bir negatif bilet oluşturarak yapılmaz. Mevcut bilet, kaynak sistemde saklanan TicketExternalNumber değeriyle iptal endpoint'ine gönderilir. Bilet bulunamazsa veya iptal edilemezse response içindeki durum açıklaması işlenir. İptal başarılı olduğunda aynı bilet numarası ve teknik kimlik korunur.

Sınır Durumları

Durum	Beklenen davranış
Aynı `TicketExternalNumber` yeniden gönderildi	Yeni dış referans üretmeden mevcut kayıt bilgisi ve hata listesini işleyin.
Request timeout oldu	Yeni bilet oluşturmadan önce dış numara veya bilet numarasıyla sorgulayın.
Bilet oluşturuldu fakat PDF hazır değil	Belgeyi başarısız saymayın; durum endpoint'ini kontrollü aralıklarla sorgulayın.
Bilet iptal çağrısı daha önce tamamlanmış	İptal sonucunu idempotent kabul edin ve kaynak sistem durumunu eşitleyin.
Bilet `Raporlandı` görünüyor	Bu değeri GİB paket kabulü olarak yorumlamayın; rapor sonucu ayrı süreçtir.