API Temelleri
API Temelleri
Kimlik doğrulama, ortak header, response, belge kimliği ve çağrı sözleşmeleri.
Başlangıç noktası: Bu sözleşmeler karayolu, e-Yolcu Listesi, etkinlik ve havayolu REST endpointleri için ortaktır. İşleme özgü request alanları ilgili belge ailesinin API ve örnek sayfalarında açıklanır.
Kimlik Doğrulama
Önce hesap bilgileriyle token alın. Dönen token'ı sonraki korumalı çağrılarda VbtAuthorization header'ına yazın.
POST/api/Account/Token
API oturumu için yetkilendirme token'ı üretir.
| Request | TokenRequestModel — Email, Password |
| Response | TokenResponseModel — token bilgisi |
Token JSON örneğini görüntüle
{
"Email": "entegrasyon@firma.com",
"Password": "GUCLU_PAROLANIZ"
}Ortak Header Sözleşmesi
| Header | Değer | Kullanım |
|---|---|---|
Content-Type | application/json | JSON request gövdesi taşıyan çağrılarda kullanılır. |
VbtAuthorization | Token endpointinden dönen değer | Token çağrısı dışındaki korumalı REST endpointlerinde gönderilir. |
Body ve URI Parametreleri
Bütün POST endpointleri JSON gövdesi kullanmaz. Oluşturma ve tarih aralığı sorguları body taşırken bilet/liste durum ve iptal işlemlerinin bir bölümü değeri URI üzerinden alır.
| İşlem türü | Girdi biçimi | Örnek |
|---|---|---|
| Belge oluşturma | JSON body | HwTicketSave, EventTicketSave, AirwayTicketSave |
| Yolcu listesi oluşturma | JSON body | HwPassengerListSave |
| Durum sorgulama | URI parametresi | ticketNumber veya passengerListExternalNumber |
| İptal | URI parametresi | Karayolunda ticketExternalNumber, etkinlikte ticketNumber |
| Etkinlik tarih aralığı | JSON body | GetEventTicketDateRangeRequestModel |
Response ve Hata Sözleşmesi
REST sonuçları işlem verisini ortak response zarfının Data alanında taşır. Belge oluşturma sonucu bilet numarası ve UUId döndürür; bu sonuç PDF'in veya GİB raporunun tamamlandığı anlamına gelmez.
| Kontrol | Entegratör davranışı |
|---|---|
| HTTP sonucu | Yalnız HTTP koduna göre belgeyi başarılı kapatmayın; response gövdesini ve hata listesini okuyun. |
HasError ve Errors[] | Alan veya iş kuralı hatasını düzelttikten sonra aynı iş kimliğiyle kontrollü yeniden deneyin. |
| Oluşturma sonucu | TicketNumber ve UUId değerlerini kalıcı olarak saklayın. |
| Asenkron PDF | Durum sorgusunda imzalı PDF'in hazır olduğunu görmeden belge bağlantısını nihai çıktı kabul etmeyin. |
| Timeout veya bağlantı kopması | Yeni dış referansla tekrar oluşturmadan önce mevcut bilet/listeyi sorgulayın. |
Belge Kimlikleri
| Kimlik | Kullanım | Tekrar güvenliği |
|---|---|---|
UUId | PDF, portal ve arşiv korelasyonu | Response'tan dönen değeri değiştirmeden saklayın. |
TicketNumber | Bilet durum sorgusu ve görünen belge numarası | Numara üretilmişse response değerini kaynak sisteme geri yazın. |
TicketExternalNumber | Kaynak sistem bilet referansı | Aynı iş belgesi için tekil ve değişmez tutun. |
YolcuListesiExternalId | Yolcu listesi durum sorgusu ve tekillik | Aynı sefer/listenin tekrar gönderiminde yeni değer üretmeyin. |
API Yüzeyleri ve Sonraki Adım
| İhtiyaç | Kaynak |
|---|---|
| Karayolu bileti oluşturma, iptal ve durum | Karayolu Entegratör API |
| e-Yolcu Listesi oluşturma ve durum | e-Yolcu Listesi Entegratör API |
| Etkinlik bileti oluşturma, iptal ve sorgu | Etkinlik Entegratör API |
| Havayolu bileti oluşturma ve durum | Havayolu Entegratör API |
| Timeout, mükerrerlik ve güvenli tekrar | Hata ve Güvenli Tekrar |
| Eski SOAP entegrasyonu | Legacy SOAP Servisi |