API Temelleri
Entegrasyon Sorumlulukları
Entegratör ve platform sorumlulukları; validasyon, kimlik, timeout, durum sorgulama ve güvenli yeniden deneme sınırları.
Entegratör Sorumlulukları
| Konu | Entegratörün yapacağı işlem | Başarı kanıtı |
|---|---|---|
| Kaynak veri | Belge ailesine uygun zorunlu ve koşullu alanları, mali toplamları ve iş tarihlerini doğru üretir. | Request validasyonu hatasız tamamlanır. |
| İş kimliği | Her ticari işlem için değişmez ve tekil harici numara kullanır; platformun döndürdüğü belge numarası ve UUId değerini ERP kaydıyla ilişkilendirir. | ERP ile platform kaydı aynı iş kimliği üzerinden bulunabilir. |
| Çağrı sırası | e-Yolcu Listesi satırlarının referans verdiği karayolu biletlerini önce oluşturur; iptal ve iade işlemlerinde mevcut belge kimliğini kullanır. | Bağımlı işlem kaynak belgeyle eşleşir. |
| Response kontrolü | HTTP durumuyla birlikte HasError, Errors[] ve işlem sonucunu okur. | Kaynak sistem yalnızca doğrulanmış sonucu işler. |
| Timeout ve tekrar | Sonucu alınamayan oluşturmada önce mevcut kaydı sorgular; kayıt yokluğu doğrulanmadan yeni kimlik üretmez. | Aynı ticari işlem için mükerrer belge oluşmaz. |
| Durum ve mutabakat | Belge/PDF durumu ile GİB rapor sonucunu ayrı izler; kendi kaynak kaydıyla düzenli mutabakat yapar. | Yerel durum, platform kaydı ve GİB paket sonucu ayrıştırılabilir. |
Platform Sorumlulukları
| Konu | Platformun sağladığı davranış | Entegratöre görünen sonuç |
|---|---|---|
| Sözleşme doğrulaması | Request modelini ve belge ailesine ait alan kurallarını doğrular. | Alan ve iş kuralı hataları response içinde döner. |
| Numara ve teknik kimlik | Desteklenen ailelerde LocationCode üzerinden numara üretir; teknik kimliği kayıtla ilişkilendirir. | Response veya durum sorgusunda belge numarası ve UUId alınır. |
| Belge çıktısı | Kabul edilen kayıt için imzalı PDF üretim sürecini yürütür. | Hazır olma durumu sorgulanır; çıktı desteklenen kanaldan alınır. |
| Raporlama | Public destek kapsamındaki belge ailelerini GİB rapor paketine alır ve paket sonucunu izler. | Belge durumu ile GİB paket sonucu ayrı olarak görüntülenir. |
| Operasyon görünürlüğü | Desteklenen listeleme, belge görüntüleme, durum ve hata bilgilerini API veya Portal üzerinden sunar. | Entegratör ve operasyon ekibi aynı belgeyi kimlikleriyle izleyebilir. |
Sınır: Platformun request'i kabul etmesi, imzalı PDF'in hazır olması ve GİB rapor paketinin kabul edilmesi birbirinden farklı sonuçlardır. Her aşama kendi durumuyla doğrulanmalıdır.
Hata Katmanları
| Katman | Gözlenen sinyal | Entegratör davranışı |
|---|---|---|
| HTTP/kimlik doğrulama | 2xx dışı HTTP veya token hatası | Kimlik/erişim sorununu giderin; belgeyi oluşmuş kabul etmeyin. |
| Request validasyonu | HasError=true, Errors[] | Alanları düzeltin; aynı iş kimliğiyle yeniden gönderin. |
| Mükerrer kayıt | Numara veya harici numara mevcut | Yeni kimlik üretmeden mevcut kaydı sorgulayın. |
| Asenkron işlem | PDF/durum henüz hazır değil | Bekleyip durum sorgulayın; oluşturmayı tekrarlamayın. |
| GİB rapor paketi | Paket hata durumu ve açıklaması | Hata nedenini giderip aynı rapor süreci üzerinden izleyin. |
Timeout Karar Ağacı
- HTTP cevabı yoksa çağrının başarısız olduğunu varsaymayın.
- Karayolunda
TicketExternalNumberile; diğer ailelerde bilet numarası/durum endpointiyle kaydı arayın. - Kayıt bulunduysa dönen kimlikleri yerel işlemle ilişkilendirin.
- Kayıt bulunmadığı doğrulandıktan sonra aynı iş kimliğiyle yeniden deneyin.
Kör tekrar yok: Yeni
TicketExternalNumber üretmek aynı ticari işlem için ikinci bilet oluşturabilir.Response Okuma
Yalnız HTTP 200'e bakmayın. HasError, Errors[], Data.IsSucceded ve Data.Messages[] alanlarını birlikte değerlendirin. Aynı hata kodu farklı kontrollerde paylaşılabildiği için hata mesajını ve ilgili request alanını da loglayın.