Dayanıklı bir API istemcisi

İstek hızı

API, kullanıcı, şirket veya IP kapsamına göre istekleri sınırlayabilir. 429 yanıtında varsa Retry-After başlığına uyun. Başlık yoksa artan bekleme ve küçük rastgele gecikme kullanın. Paralel işçilerinizin toplam istek hızını birlikte sınırlayın; her işçiyi ayrı bir kota varmış gibi çalıştırmayın. Login çağrılarını döngüye almayın; aynı oturumdaki eşzamanlı işler tek token yenileme işleminin sonucunu beklesin.

Zaman aşımı ve tekrar

İstemcinizde bağlantı ve yanıt bekleme sürelerini yapılandırılabilir tutun. Arayüz, arka plan senkronizasyonu ve rezervasyon oluşturma farklı bekleme politikaları gerektirebilir. Zaman aşımı, sunucudaki işlemin durduğunu göstermez.

Sonuç	İstemci yaklaşımı
Okuma isteğinde bağlantı hatası / 5xx	Sınırlı sayıda, artan bekleme ve rastgele gecikmeyle tekrar.
400	Alanları düzeltmeden tekrar göndermeyin.
401	Uygunsa bir kez token yenileyin; başarısızsa giriş isteyin.
403 / 404	Hesap kapsamı ve kaynak kimliğini kontrol edin.
Teklifte 410	Yeni teklif alın; fiyat ve koşulları tekrar gösterin.
Oluşturma sırasında belirsiz sonuç	Aynı Idempotency-Key ve gövdeyle tekrar deneyin.
Güncelleme/iptalde belirsiz sonuç	Önce rezervasyon detayını sorgulayın.

Bu yaklaşımlar istemci tasarımı önerileridir.

Idempotency kapsamı

Her yeni rezervasyon niyeti için UUID gibi benzersiz bir anahtar üretin. Anahtarı isteği göndermeden önce kendi işlem kaydınızla saklayın. Aynı isteğin tekrarında aynı hesap, aynı gövde ve aynı anahtarı kullanın. Başka kullanıcı/şirket bağlamında önceki sonucun alınacağını varsaymayın.

Aynı anahtarla farklı gövdenin otomatik reddedileceğine güvenmeyin; bu bir güncelleme yöntemi değildir. Teklif geçerlilik süresi ile idempotency davranışı farklı kavramlardır.

Senkronizasyon

Webhook'lar etkinse olayları kalıcı kaydedip tekrarlanan teslimleri ayıklayın. Webhook alamıyorsanız rezervasyon detayını kontrollü aralıklarla sorgulayın. Gereksiz sıklıkta bütün kayıtları taramak yerine değişmesini beklediğiniz rezervasyonları izleyin.

Sözleşme değişiklikleri

Değişiklik günlüğünü ve OpenAPI belgesini entegrasyon sürüm kontrolünüze dahil edin. Tanımadığınız yanıt alanlarını tolere edin; yeni durum/enum değerleri için genel gösterim ve hata yolu bulundurun.

Swagger URL'sindeki v1 belge grubunun adıdır. Ürün sürümü karşılaştırmasında OpenAPI info.version, şema farkı ve duyurulan değişiklikleri birlikte değerlendirin.

Destek

support@yolcugo.com adresine ortam, işlem, UTC zaman, HTTP kodu ve varsa correlationId ile başvurun. Token, şifre, webhook secret'ı ve yolcu kişisel bilgilerini paylaşmayın.