Ana içeriğe geç

Değişiklik günlüğü

20 Kasım 2026 — Webhook sözleşmesi 2026-12​

Kırıcı değişiklik. Webhook gövdeleri yeni sözleşmeye geçer; bütün olaylar apiVersion: "2026-12" taşır. REST API değişmez. Ayrıntı ve örnekler: Webhook Entegrasyon Rehberi.

Ne değişti:

  • Tek sürüm, tam görüntü. Her gövdede eventId, eventType, apiVersion, occurredAt (ISO 8601 UTC), transferId, pnr ve her zaman tam data bulunur. Önceki 2026-03 / 2026-05 sürümleri ve alanları eksik (kısmi) data kalktı. transfer.created'in üst düzeyindeki pickUpTime, vehicleTypeId ve saat dilimi alanları kalktı; aynı bilgiler data'dadır.
  • Beş olay. transfer.created, transfer.updated, transfer.status_changed, transfer.driver_assigned, transfer.driver_unassigned. transfer.merged, transfer.merge_added, transfer.merge_removed, transfer.merge_updated ve transfer.unmerged kalktı; grup üyeliği transfer.updated ile (data.mergeStatus, kurumsal planda data.corporatePlan.groupId) gelir.
  • transfer.updated yeni biçimde. changes[].field artık data'daki alan adıdır (camelCase; iç içe nesnede nokta yolu, ör. corporatePlan.groupId). oldValue / newValue data ile aynı tip ve biçimdedir: sayılar sayı, tarihler ISO 8601. Eski PascalCase adlar (PickUpTime, TotalGrossAmount, PassengerCount, DriverId, VehicleId, ExtraAdded, Shared* …) ve kültüre bağlı metin değerleri kalktı. Olay, data size en son yayımlanan görüntüden farklı olduğunda üretilir; daha önce bildirim üretmeyen değişiklikler de (elle fiyat, ek hizmet onayı, yolcu adı, sürücü telefonu, plaka, firma ve araç tipi adı …) artık gelir. stateVersionUtc, corporatePlan.publishedVersion ve corporatePlan.rowVersion tek başına olay üretmez; diğer istisnalar rehberin "Olay Gelmeyen Durumlar" bölümündedir.
  • Sürücü olayları. transfer.driver_assigned sürücü atandığında ya da değiştiğinde gelir ve driverFullName, driverPhone, vehiclePlate taşır (driverId kalktı). transfer.driver_unassigned rezervasyonda sürücü kalmadığında gelir ve previousDriverFullName, previousDriverPhone, previousVehiclePlate taşır (reason, driverId, vehicleId, transferGroupId, reassignedToTransferId kalktı).
  • transfer.created rezervasyon size görünür olduğunda gelir: ödeme gerektirmeyen rezervasyonda oluşturulunca, kartla ödenen rezervasyonda ödeme tamamlanınca. Her rezervasyon için garanti değildir: sözleşme yayına girmeden ya da firmanız ilk webhook'unu tanımlamadan önce oluşturulmuş rezervasyonlar ilk değişikliklerinde doğrudan transfer.updated alır (o anda henüz görünür olmayan, ör. ödemesi bekleyen rezervasyon görünür olduğunda transfer.created alır). O anda tamamlanmış ya da iptal edilmiş rezervasyonun ilk değişikliği (ne zaman olursa olsun) ve açık rezervasyonun ilk dakikalardaki değişikliği boş changes ile gelir; data tam ve günceldir, bu olayla transfer.status_changed ve sürücü olayları gelmez (transfer.updated'ı her zaman dinleyin); webhook'unuz kapalıyken görünür olan, olay filtrenizin dışında kalan ya da teslimatı bütün denemelerini tüketen transfer.created sonradan gönderilmez. Tanımadığınız bir transferId ile gelen her olayda kaydı data'dan oluşturun.
  • Test bildirimi (eventType: "test") aynı ortak gövdeyi ve apiVersion: "2026-12"'yi taşır.
  • stateVersionUtc artık yayımlanan hâlin sürümüdür. Her yeni hâlde kesin artar (değişiklik yolcu, fiyat satırı, ödeme ya da sürücü kartında olsa da); aynı hâli taşıyan olaylarda aynıdır. Önceden rezervasyon satırının son kayıt zamanıydı ve bu tür değişikliklerde artmıyordu. Büyükse uygulayın, küçükse uygulamayın; zaman damgası olarak karşılaştırın.
  • Teslimat ve yönetim. Değişiklik, onu yapan kayıtla aynı veritabanı işleminde "bildirilecek" diye işaretlenir; olay bu işaretten yaklaşık bir dakika içinde üretilir ve gönderilir (işaret kaybolmaz). İstekler User-Agent: YolcuGo-Webhooks/1.0 taşır; bir deneme 30 saniyeyle sınırlıdır. Olay filtresi yalnız katalog adı, transfer.* ya da * kabul eder. Endpoint URL'si yalnız https ve 443 ya da 8443 portunu kabul eder (mevcut kayıtlar yeniden doğrulanmaz). 3 günü aşan bir hata döneminde bir teslimatın 10 denemesinin tamamı başarısız olursa webhook otomatik kapatılır; kapatılan ya da silinen webhook'un bekleyen teslimatları iptal edilir (o sırada gönderimi süren teslimat başarısız olursa o da). Webhook kapalıyken yapılan değişiklikler, yeniden açtıktan sonraki olayların changes'inde listelenmez; data her zaman günceldir.
  • Yeniden deneme takvimi uzadı. En çok 10 deneme değişmedi; başarısız denemelerden sonraki beklemeler artık sırasıyla en az 1, 5, 15, 30, 60, 180, 360, 720 ve 1440 dakikadır. İlk denemeden onuncuya en az 2811 dakika (1 gün 22 saat 51 dakika) geçer; önceki takvim iki saatten kısa sürede tükeniyordu. Onuncu deneme de başarısız olursa teslimat kendiliğinden yeniden gönderilmez.
  • Yeniden gönderim. OpsPortal teslimat geçmişinden yalnız sonuçlanmış bir teslimat (başarılı, iptal edilmiş ya da 10 denemesinin tamamı başarısız) aynı gövde ve aynı eventId ile yeniden gönderilebilir.
  • Değişmeyenler: secret (isteğe bağlı, sizin seçtiğiniz değer, rotasyonda geçiş yok), V1 ve V2 imza, başlık adları ve en çok 10 deneme.

Yapmanız gerekenler:

  1. Alıcınızı apiVersion: "2026-12" gövdelerini işleyecek şekilde güncelleyin; transfer.merge* ve transfer.unmerged işleyicilerini kaldırın.
  2. transfer.updated işleyicinizi yeni alan adlarına (camelCase, nokta yolu) ve tipli değerlere geçirin; ya da yalnız data'yı uygulayın.
  3. transfer.driver_unassigned için previous* alanlarını kullanın; reason'a bağlı mantığı kaldırın.
  4. Tekilleştirmeyi eventId (en az 90 gün saklayarak), sıra kontrolünü data.stateVersionUtc ile yapın (büyükse uygula). Kaydı data ile oluşturun ya da güncelleyin (upsert); transfer.created'in gelmiş olmasına güvenmeyin. Boş changes'li transfer.updated'da data'yı tam hâl olarak uygulayın.
  5. Olay filtrenizde kalkan olay adları ya da ? varsa güncelleyin (kayıt ve düzenleme sırasında reddedilir).

20 Kasım 2026 — Rezerve edilemeyecek fiyatlar ve taşma hataları​

  • Fiyatı bir rezervasyonun alabileceği en yüksek tutarı (99.999.999,99 TL) aşan teklifler müsaitlik aramasında artık listelenmez.
  • Bu tutarı aşan bir fiyatla rezervasyon (quick dahil) 400 BOOKING_PRICE_OUT_OF_RANGE döner; mesaj hesaplanan tutarı içerir. Sorun istekte değil fiyat tanımındadır: aynı isteği tekrar göndermeyin, operasyonla iletişime geçin. Önceden bu durumda 400 VALIDATION_ERROR ("Girilen sayısal değer izin verilen aralığın dışında.") dönüyordu.
  • Kaydedilemeyecek kadar büyük sayı ya da uzun metin içeren 400 VALIDATION_ERROR yanıtları artık hangi alanın taştığını söyler (mesajda ve errors içinde, örn. transferFee).

12 Kasım 2026 — Müsaitlik aramasında giriş sınırları ve havalimanı eşleşmesi​

  • Müsaitlik araması rezervasyonla aynı sınırları uygular: en fazla 2 ara durak (waypoints); konum ve ara durak adı (name) en fazla 1000, placeId en fazla 500, district en fazla 100 karakter. Ara durakta placeId yoksa latitude/longitude geçerli ve sıfırdan farklı olmalıdır. Aşan istek fiyatlanmadan 400 döner.
  • Havalimanı adı veya kodu (name, airportCode) ile yapılan eşleşme yalnız koordinat o havalimanına yakınsa (yaklaşık 5 km) geçerlidir; aksi hâlde konum bulunduğu bölgenin fiyatıyla fiyatlanır. isAirport: true koordinat eşleşmesini havalimanı çevresinde yaklaşık 11 km'ye kadar genişletmeye devam eder; daha uzak bir noktaya havalimanı fiyatı vermez. Yakında havalimanı olmayan bir konumda isAirport: true fiyatı değiştirmez. Havalimanı uçlarında terminalin koordinatını gönderin.

12 Kasım 2026 — Teklif tek kullanımlıktır​

  • Bir teklifle (itemId) rezervasyon oluşturulduktan sonra o teklif tüketilir. Aynı itemId ile farklı bir Idempotency-Key taşıyan ikinci rezervasyon isteği 410 RESOURCE_GONE (süresi dolmuş teklifle aynı yanıt) döner; yeni rezervasyon için yeniden arama yapın. Gidiş-dönüşte iki bacağın teklifi de tüketilir.
  • Aynı Idempotency-Key ile tekrar gönderilen istek teklif tükenmiş olsa da ilk rezervasyonu döndürür.
  • Başarısız olan (geri alınan) bir rezervasyon isteği teklifi tüketmez; aynı teklifle yeniden deneyebilirsiniz.

11 Kasım 2026 — Etkin teklif türleri ucu API referansından kaldırıldı​

  • GET /api/availability/capabilities artık Partner API referansında yer almıyor. Paylaşımlı teklifleri müsaitlik aramasının yanıtındaki data.sharedTransfers listesinden, kişi başı teklifleri passengerCount göndererek alın (Paylaşımlı transfer, kişi başı fiyatlandırma). Arama ve rezervasyon akışı değişmedi.
  • Bu ucu entegrasyonunuzda çağırıyorsanız çağrıyı kaldırın; uç YolcuGo'nun kendi arayüzleri içindir ve sözleşmesi partnerler için sürdürülmez.

11 Kasım 2026 — Tek İstekte Rezervasyonda birden çok tedarikçi​

  • Tek İstekte Rezervasyon artık hesabınızın "ana tedarikçisine" bağlı değildir. Aday tedarikçiler hesabınızın aktif çalıştığı tedarikçilerdir; cari gönderilse de hepsi aday kalır. Tedarikçi cari için özel fiyat tanımladıysa o fiyat, tanımlamadıysa hesabınızın fiyatı kullanılır. Teklif varsa en ucuzu seçilir. Teklif yoksa adresin bölgesinde tarifesi olan tedarikçilerin o bölgedeki en yüksek tarifelerinin en ucuzu satılır; bölge bilinmiyorsa bütün tedarikçilerin havalimanı yönündeki en yüksek tarifesi satılır.
  • QUICK_PRIMARY_SUPPLIER_REQUIRED kaldırıldı; yerine hiç uygun tedarikçi olmadığında 400 QUICK_SUPPLIER_NOT_FOUND döner. Bir tedarikçinin cari için iki aktif listesi olması artık isteği durdurmaz; QUICK_PRICE_LIST_AMBIGUOUS yalnız bütün aday tedarikçiler belirsizse döner.
  • Cariye özel fiyat güzergâh ve araç tipi başına uygulanır: tedarikçinin cari için fiyat tanımlamadığı güzergâhta hesabınızın fiyatı kullanılır (önce bu güzergâh quick'te kapanıyordu). Webhook data.quickBooking.priceScope artık rezervasyonun gerçekte kesildiği fiyatı gösterir: Account cariye özel fiyat, Customer hesabınızın fiyatı.
  • 429 (istek hızı sınırı) yanıtı aynı customerReference ile tekrar denenebilir.

Kasım 2026 — Üretim API'si güncellendi​

Önceki girdilerde "yalnız test ortamında" olarak duyurulan aşağıdaki özellikler üretim API'sinde de geçerlidir. Rehberlerdeki ortam etiketleri kaldırıldı; rehberler iki ortamda aynı davranışı anlatır.

  • Tek İstekte Rezervasyon (POST /api/booking/quick), webhook data.quickBooking ve isteğe bağlı flightNo.
  • Birleştirilmeyecek rezervasyon (noMerge), BOOKING_MERGE_PROHIBITED ve BOOKING_IDEMPOTENCY_CONFLICT.
  • Müşteri rezervasyon numarası (customerReference, returnLeg.customerReference, clearCustomerReference).
  • Tanımsız, pasif ya da başka hesaba ait cari kodunun hata vermemesi; rezervasyon yanıtındaki partnerSubAccountCode / partnerSubAccountName alanları ve kodsuz teklifin cari koduyla reddi (410).
  • Birleşik seferde PNR bazlı sürücü olayları.
  • Kişi başı fiyatlandırma, rezervasyonda 1–46 yolcu kaydı ve passengerCount 1–46.
  • Paylaşımlı transfer ve webhook data.stateVersionUtc.

Kurumsal planlama bu kapsamda değildir; hesabınız için ayrıca açılır (Kurumsal planlama).

11 Kasım 2026 — Transfer saati geçmiş rezervasyon iptal edilemez​

Yalnız test ortamında; üretim API'si transfer saatinden sonraki iptali henüz kabul eder.

  • Rezervasyon iptali (POST /api/booking/{id}/cancel) transfer saati geçmiş bir rezervasyon için artık 400 döner; rezervasyon iptal edilmez ve iade oluşmaz. Transfer gerçekleşmiş olabileceği için bu durumdaki iptal ve iade talepleri operasyon ekibi üzerinden yürütülür.
  • Transfer saatinden önceki iptallerde davranış ve dönen kesinti yüzdesi değişmedi.

10 Kasım 2026 — Tek İstekte Rezervasyonda cari kodu isteğe bağlı​

Yalnız test ortamında; üretim API'si tanımsız kodu henüz 400 QUICK_ACCOUNT_REQUIRED ile reddeder.

  • Tek İstekte Rezervasyon isteğinde partnerSubAccountCode artık zorunlu değildir. Kod gönderilmezse, tanımsızsa, pasifse ya da başka hesaba aitse istek reddedilmez: rezervasyon hesabınızın carisiz fiyatıyla ve carisiz oluşur. Adres çözülemezse hesabınızın o havalimanı yönündeki en yüksek tarifesi uygulanır.
  • Cari tanımlı ama ana tedarikçide fiyat listesi yoksa da hesabınızın carisiz fiyatı uygulanır; rezervasyon o cariye bağlı kalır.
  • Webhook data.quickBooking alanına priceScope eklendi: Account (carinin fiyat listesi) veya Customer (hesabınızın carisiz fiyatı). Aynı nesnedeki requestedAccountCode, istekte gönderdiğiniz cari kodunu taşır.
  • QUICK_ACCOUNT_REQUIRED ve QUICK_PRICE_LIST_REQUIRED hata kodları kalktı. Birden çok aktif fiyat listesi 400 QUICK_PRICE_LIST_AMBIGUOUS döndürmeye devam eder.
  • Gönderilmeyen, boş ve null cari kodu tekrar gönderim kontrolünde aynı istek sayılır.

6 Kasım 2026 — Tek İstekte Rezervasyonda uçuş numarası isteğe bağlı​

Yalnız test ortamında.

  • Tek İstekte Rezervasyon isteğinde flightNo artık zorunlu değildir; uçuş numarası olmayan transferde alanı göndermeyin. Gönderilirse en çok 20 karakterdir. Boş, null veya hiç gönderilmeyen alan tekrar gönderim kontrolünde aynı istek sayılır.

6 Kasım 2026 — Tanımsız cari kodu hata vermez​

Yalnız test ortamında; üretim API'si tanımsız kodu henüz 400 ile reddeder.

  • Müsaitlik ve rezervasyon isteğindeki partnerSubAccountCode hesabınızda tanımlı ve aktif bir cariye karşılık gelmiyorsa (tanımsız, pasif ya da başka hesaba ait) istek artık reddedilmez: arama carisiz fiyatla yapılır, rezervasyon carisiz oluşur ve cari bazlı birleştirmeye girmez. Ayrıntı Cari fiyatıyla arama bölümünde.
  • Cari fiyatıyla alınan teklifin farklı, çözülemeyen veya boş kodla rezervasyonu eskisi gibi 410 döner.
  • Tek İstekte Rezervasyon değişmedi: tanımsız veya pasif kod 400 QUICK_ACCOUNT_REQUIRED döner.
  • API referansındaki rezervasyon şemalarına customerReference, returnLeg.customerReference, clearCustomerReference ve noMerge alanları eklendi.

6 Kasım 2026 — Birleştirilmeyecek rezervasyon​

Yalnız test ortamında; üretim API'si bu alanı henüz tanımaz.

  • Rezervasyon oluşturma ve Tek İstekte Rezervasyon isteklerine isteğe bağlı noMerge alanı eklendi. true ise rezervasyon tüm birleştirme ve planlama yollarının dışında kalır; fiyat değişmez. Yalnız oluşturmada verilir, gidiş-dönüşte iki bacağa uygulanır. Ayrıntı için Çift yön, ara durak ve özel ihtiyaçlar rehberine bakın.
  • noMerge alanı rezervasyon sorgu yanıtlarında ve webhook data snapshot'ında döner.
  • BOOKING_MERGE_PROHIBITED (400) ve BOOKING_IDEMPOTENCY_CONFLICT (409) hata kodları hata rehberine eklendi.

Bu değişiklik ekleyicidir; mevcut alanlar ve davranışlar aynı kalır.

6 Kasım 2026 — Müşteri rezervasyon numarası​

Yalnız test ortamında; üretim API'si bu alanları henüz tanımaz.

  • Rezervasyon oluşturma isteğine isteğe bağlı customerReference (kendi rezervasyon numaranız, en çok 100 karakter) ve dönüş bacağı için returnLeg.customerReference eklendi. Ayrıntı ilk rezervasyon rehberinde.
  • Numara GET /api/booking/{id} yanıtında ve webhook data.customerReference alanında döner; transferi yapan tedarikçiye gösterilmez. Değişikliği transfer.updated olayında CustomerReference adıyla bildirilir.
  • PUT /api/booking/{id} ile değiştirilebilir; clearCustomerReference: true siler. Ayrıntı yaşam döngüsü rehberinde.
  • Tek İstekte Rezervasyon da aynı customerReference alanını kullanır; orada zorunludur ve tekrar gönderim anahtarıdır. Numara satır sonu veya başka kontrol karakteri içeremez.

5 Kasım 2026 — Birleşik seferde PNR bazlı sürücü​

Yalnız test ortamında; üretimde davranış henüz değişmedi.

Webhook davranışı değişti (şema değişmedi): Birleşik seferde (DataMerged) sürücü ve araç artık her PNR'ın kendi kaydına yazılır. Birleşik transferler için transfer.driver_assigned, transfer.updated ve transfer.status_changed olayları PNR başına gelir; ana transfer de dahildir (eskiden bastırılıyordu). transfer.driver_unassigned, birleşik seferden ayrılan transfer için gelir (reason: manual_unmerge, cancelled, anchor_failover, resource_revalidation_required, kurumsal planda left_trip). transfer.merge_updated anchor_reassigned olayında driverTransferred, "yeni ana transfer grubun sürücüsünü taşıyor" anlamına gelir. Olay hacmi birleşik seferdeki transfer sayısı kadar artabilir; bilinmeyen olaylara ve tekrarlara karşı istemcinizi tolerant tutun. GET /api/booking/{id} yanıtında driverUserId ve sürücü alanları birleşik seferin her PNR'ında doludur. Ayrıntı için Webhook'lar rehberine bakın.

5 Kasım 2026 — Tek istekte rezervasyon​

Yalnız test ortamında; üretim API'si bu uç ve alanı henüz tanımaz.

  • Yeni uç: POST /api/booking/quick. Cari kodu, havalimanı (IATA), yön ve adresle adres çözümleme, fiyat seçimi ve rezervasyon oluşturma tek istekte yapılır. Fiyat her zaman TRY'dir. Aynı customerReference ile tekrar gönderilen aynı istek aynı rezervasyonu döner. Ayrıntı, fiyat seçim sırası ve QUICK_* hata kodları için Tek İstekte Rezervasyon rehberine bakın.

  • Webhook data snapshot'ına quickBooking alanı eklendi (yalnız bu uçla oluşturulan rezervasyonlarda): fiyat kaynağı ve adresin çözülüp çözülmediği. Webhook alan tablosunda.

  • API referansına eklendi: istek şeması, örnekler ve 409/503 yanıtları.

  • Rezervasyon yanıtlarındaki paylaşımlı sefer ve grup bilgisine estimatedDropoffUtc, driverUpgradeRequired, driverNoticeCode ve driverNotice alanları eklendi (API referansında).

Bu değişiklikler ekleyicidir; mevcut availability ve booking uçları ve davranışları aynı kalır.

20 Ekim 2026 — Dil alanı ve ülke bilgisi​

  • Rezervasyon oluşturma ve güncelleme isteklerine isteğe bağlı language alanı eklendi (tr, en, de, ru, ar; büyük/küçük harf duyarsız). Başka bir değer 400 ve "Desteklenmeyen dil." mesajıyla reddedilir. Gönderilmezse bildirim dili yolcu uyruğundan, hesabın varsayılanından ve alış ülkesinden seçilir; güncellemede null mevcut değeri korur. Seçilen dil rezervasyon detayında (GET /api/booking/{id}) language olarak döner. Ayrıntı için Çift yön, ara durak ve özel ihtiyaçlar rehberine bakın.
  • Müsaitlik yanıtına pickUpCountryCode, dropOffCountryCode ve uetdsApplicable alanları eklendi. Yalnız ülke çözüldüğünde bulunurlar.
  • Müsaitlik notices listesine iki kod eklendi: SUPPLIER_VAT_MISSING (tedarikçinin KDV tanımı olmadığı için teklifleri çıkarıldı; supplierId dolu) ve CROSS_COUNTRY_FIXED_ROUTE_ONLY (alış ve bırakış farklı ülkelerde; yalnız sabit güzergâh fiyatları sunulur). Ayrıntı için Fiyatlandırma rehberine bakın.
  • Yolcu nationalityCode alanında KKTC için XN kodu belgelendi.
  • SUPPLIER_COUNTRY_MISMATCH ve NO_SUPPLIER_IN_COUNTRY hata kodları hata rehberine eklendi; bunlar OpsPortal'daki havuz ve atama işlemlerinde görülür, partner rezervasyon uçlarında dönmez.

Bu değişikliklerin hepsi ekleyicidir (yeni isteğe bağlı alan, yeni yanıt alanı, yeni uyarı kodu); mevcut alanlar ve davranışlar aynı kalır, eski istemciler bozulmaz. Üretim API'si bu sürüm yayımlanana kadar yeni alanları tanımaz ve döndürmez.

20 Ekim 2026 — Offset'siz tarih-saat değerleri​

API davranışı değişti: Z ya da offset taşımayan tarih-saat değerleri artık her istek alanında (JSON gövde ve sorgu parametreleri; yalnız alış saati değil) Europe/Istanbul duvar saati olarak okunur. Önceki üretim sürümü bu değerleri UTC okuyordu. Örnek: 2026-11-02T15:00:00 eskiden 15:00Z (Türkiye'de 18:00) anlamına geliyordu; şimdi Türkiye'de 15:00, yani 12:00Z anlamına gelir.

  • Yalnız tarih içeren değerler (2026-07-11) takvim günü olarak kalır; bu kural değişmedi.
  • Z ya da açık offset taşıyan değerler olduğu gibi bir an sayılır; onlar için değişen bir şey yok.
  • Offset'siz tarih-saat gönderen bir entegrasyonunuz varsa değerin anlamı bu sürümle üç saat kayar. Her zaman Z ya da açık offset (ör. 2026-11-02T12:00:00Z, 2026-11-02T15:00:00+03:00) göndermenizi öneririz.
  • Üretim API'si bu sürüm yayımlanana kadar offset'siz değerleri UTC okumaya devam eder. İki ortamda da aynı sonucu almak için offset'siz değer göndermeyin.

20 Ekim 2026 — Alış noktasının saat dilimi​

  • Offset'siz alış saati her yerde alış noktasının yerel saati sayılır; Türkiye'de Europe/Istanbul kullanılır. Açık bir an için Z ya da alış noktasının doğru offset'i önerilir; örneklerdeki +03:00 yalnız Türkiye için geçerlidir.
  • Müsaitlik isteğine isteğe bağlı pickUpLocalDateTime alanı eklendi (pickUpDateTime ile birlikte gönderilemez).
  • Rezervasyon yanıtları ve webhook snapshot'larına pickUpTimeZoneId, pickUpLocalDateTime, pickUpTimeZoneLabel; grup olaylarına anchorPickUp* karşılıkları eklendi. pickUpTime UTC olarak değişmedi.
  • Türkiye dışı alışlar için PICKUP_TIME_OFFSET_MISMATCH, PICKUP_TIME_AMBIGUOUS ve PICKUP_TIME_NONEXISTENT hata kodları belgelendi. Bu üç hatada yanıt ek details alanını taşır (iki aday, geçerli ilk saat ya da beklenen offset).
  • Müsaitlik tekliflerindeki pickUpTimeZoneId iç tekliflerde de dolu döner (Türkiye'de Europe/Istanbul).

Şema değişikliklerinin hepsi ek alandır; yeni alanlar eski istemcileri bozmaz. Türkiye'deki alışlar için dokümante edilen sözleşme değişmez, ancak çalışan üretim API'si (önceki sürüm) offset'siz değerleri UTC okuyordu; ayrıntı için yukarıdaki "Offset'siz tarih-saat değerleri" girdisine bakın.

20 Ekim 2026 — Yolcu sınırı, oturum hataları ve ortam etiketleri​

  • Test ortamında yolcu sınırı değişti (API davranışı): müsaitlik aramasındaki passengerCount üst sınırı 100'den 46'ya indi; 47–100 artık 400 doğrulama hatası döner. Rezervasyonda passengerCount 1–46, yolcu kaydı sınırı 20'den 46'ya çıktı. Üretim API'si bu sürüm yayımlanana kadar rezervasyonda en çok 20 kayıt ve passengerCount 1–100 kabul eder, aramada passengerCount alanını tanımaz. İki ortamda da çalışmak için kayıt sayısını 20 ile sınırlayın.
  • Login ve token yenileme referansına 401 eklendi. Login 401 yanıtında refresh denemeyin; geçersiz veya süresi dolmuş yenileme token'ı 400 döner.
  • Partner hesabıyla aramada alış zamanının en erken arama anından 6 saat sonrası olabileceği ilk rezervasyon ve ileri rezervasyon rehberlerine eklendi.
  • Üretimde henüz bulunmayan özellikler "yalnız test ortamında" olarak işaretlendi: rezervasyon yanıtındaki cari alanları, kodsuz teklifin cari koduyla reddi, stateVersionUtc, kişi başı webhook alanları ve paylaşımlı transfer.
  • Webhook rehberine transfer.updated alan adlarının tam listesi, secret'ın kayıtta kırpıldığı ve kişi başı yeniden fiyatlama örneği eklendi; JSON örnekleri tutarlı hale getirildi.
  • API referansındaki AvailabilityNotice.vehicleTypeId açıklaması düzeltildi. 410 ve oturum hatası örneklerinden, sunucunun bu yolda yazmadığı data alanı kaldırıldı; diğer hata yollarında data: null gelebilir.

Yolcu sınırı dışındaki maddeler dokümantasyon düzeltmesidir; API davranışını değiştirmez.

18 Ekim 2026 — Webhook sıralama alanı ve paylaşımlı transfer​

Durum: stateVersionUtc ve paylaşımlı transfer şu an yalnız test ortamında (https://test-api.yolcugo.com) kullanılabilir; üretim API'si bu alanları ve olayları henüz göndermez. Üretimde açıldığında bu günlükte ayrıca duyurulacaktır.

  • Transfer olaylarının data snapshot'ına stateVersionUtc eklendi: rezervasyonun son değişiklik zamanı (UTC). Sırası bozulmuş yeniden denemelerde eski yükün yenisinin üzerine yazılmasını önlemek için kullanın. Grup ana transferi değişimindeki kısmi snapshot'ta null, test bildiriminde yoktur.
  • Yeni Paylaşımlı transfer rehberi: sharedTransfer bloğu, paylaşımlı rezervasyon olayları ve yeni changedFields adları.
  • Paylaşımlı transfer rezervasyonunda vehicleTypeId / vehicleTypeName null, passengerCount satın alınan kişi sayısıdır.

Değişiklikler ektir: olay adları, imza ve apiVersion aynı kalır. Bilinmeyen alanlara tolerans gösteren alıcılar değişiklik gerektirmez; katı şema doğrulaması kullanıyorsanız yeni alanları tanımlayın. Alanlar ilgili API sürümü yayımlandığında gelmeye başlar; paylaşımlı olaylar yalnız hesabınızda paylaşımlı transfer etkinse gelir.

17 Ekim 2026 — Kişi başı fiyatlandırma​

Tedarikçinin hesabınıza veya carinize özel listede kişi başı tanımladığı fiyatlar için eklenen alanlar. Hepsi isteğe bağlıdır; araç başı teklif, rezervasyon ve webhook yanıtları değişmez. Ayrıntılar fiyat rehberindedir.

Durum: Kişi başı fiyatlandırma şu an yalnız test ortamında (https://test-api.yolcugo.com) kullanılabilir. Üretim ortamında açıldığında bu günlükte ayrıca duyurulacaktır. passengerCount alanını şimdiden göndermek güvenlidir: üretim API'si alanı henüz tanımıyorsa yok sayar.

  • Müsaitlik isteği: passengerCount (1–100). Kişi başı fiyatlı teklifler yalnız bu alan gönderildiğinde döner.
  • Müsaitlik yanıtı: kişi başı teklifte pricingBasis (PerPerson), perPersonPrice ve pricedPassengerCount; passengerCount gönderilmediği için gösterilmeyen teklifler için notices listesinde PASSENGER_COUNT_REQUIRED uyarısı (code, supplierId, vehicleTypeId). Kişi başı teklifte fixedPrice asgari tutardır, toplam değildir.
  • Rezervasyon oluşturma: kişi başı teklifte yolcu sayısı teklifin pricedPassengerCount değerine eşit olmalıdır; değilse 400 doğrulama hatası (VALIDATION_ERROR) döner. Hata gövdesi alan adı taşımaz; errors yalnız metindir.
  • Rezervasyon detayı (GET ve PUT /api/booking/{id} yanıtı): kişi başı rezervasyonda pricingBasis, perPersonPrice (TRY) ve pricedPassengerCount.
  • Webhook data görüntüsü: aynı üç alan. data.passengerCount yolcu listesindeki kayıt sayısı olarak kalır; kişi başı rezervasyonda fiyatın yolcu sayısı pricedPassengerCount alanındadır.
  • Yolcu sayısı değişen kişi başı rezervasyon yeniden fiyatlanır. Bu durumda transfer.updated olayı PassengerCount değişiminin yanında TotalGrossAmount değişimini (istek öncesi ve kaydedilen KDV dahil toplam, TRY) taşır. Partner PUT isteği kişi başı rezervasyonun yolcu sayısını değiştirdiğinde PassengerCount değişimi de artık bildirilir.

API referansındaki şema alanları, ilgili sürüm test ortamına yayımlandıktan sonra OpenAPI kaynağı yeniden alınarak güncellenir.

15 Ekim 2026 — Cari fiyatıyla arama​

Durum: Cari koduyla arama ve cari fiyatıyla alınan teklifin aynı kodla rezerve edilmesi üretimde de geçerlidir. Kodsuz alınan teklifin cari koduyla reddi (410) ve rezervasyon yanıtındaki partnerSubAccountCode / partnerSubAccountName alanları şu an yalnız test ortamında kullanılabilir.

  • Müsaitlik isteğinde partnerSubAccountCode ile cariye tanımlı fiyatın aranması ve fiyat seçim sırası anlatıldı.
  • Cari fiyatıyla alınan teklifin rezervasyonda aynı kodla kullanılması gerektiği ve rezervasyon yanıtındaki partnerSubAccountCode / partnerSubAccountName alanları eklendi.
  • Çift yönde carinin iki bacağa da uygulandığı netleştirildi.
  • Entegrasyon kullanıcısıyla kodsuz alınan teklifin cari koduyla rezerve edilemediği (410) eklendi.

API referansındaki şema alanları, ilgili sürüm test ortamına yayımlandıktan sonra OpenAPI kaynağı yeniden alınarak güncellenir.

7 Ekim 2026 — Birleştirilmiş webhook rehberi​

  • OpsPortal rehberi bu portaldaki webhook sayfasında birleştirildi; OpsPortal bağlantısı rehberi yeni sekmede açar.
  • OpsPortal üzerinden kurulum, test bildirimi, teslimat geçmişi ve API'den yetkili veri okuma adımları eklendi.
  • V1/V2 imza doğrulaması, tam JSON örnekleri, kısmi snapshot ve grup olayları açıklandı. Kalıcı kayıt ve mükerrer kontrolü yapan Node.js alıcısı indirilebilir.
  • HTTP timeout'u (30 saniye), dış teslimat sınırı (45 saniye), iki retry katmanı ve ayar değişikliklerinin bekleyen olaylara etkisi ayrıştırıldı.

Bu kayıt dokümantasyon paketini anlatır; mevcut webhook olay/payload/imza sözleşmesini değiştirmez ve müşteriye V2 geçişi zorunluluğu getirmez.

1 Ekim 2026 — Entegrasyon rehberleri ve deneme alanı​

  • Kendi sunucumuzda yayımlanabilen Docusaurus portalı ve Scalar API referansı.
  • Portal içinde API isteklerini hazırlamak için etkileşimli deneme alanı.
  • Şema alanlarının açıklamaları ve sentetik istek/yanıt örnekleri.
  • Çift yön, ara durak, dış tedarikçi ve güncelleme/iptal rehberleri.
  • Webhook olayları, imza doğrulama ve tekrar teslim yönetimi.
  • Dayanıklı istemci, canlıya geçiş ve destek bilgileri.

Tarayıcıdan gerçek çağrı için portal adresinin API CORS listesinde izinli olması gerekir. Örnek yanıtlar gerçek bir rezervasyon veya fiyat taahhüdü değildir.

30 Eylül 2026 — İlk dokümantasyon paketi​

  • Türkçe başlangıç, kimlik doğrulama ve ilk rezervasyon rehberleri.
  • 14 işlem için API referansı.
  • Token, rezervasyon oluşturma ve profil yanıtlarının açıklanması.
  • İptal yüzdesi, gösterim/tahsilat para birimi ve tekrar deneme rehberi.
  • Mevcut Swagger ekranına erişim.

Bu kayıt dokümantasyon paketini anlatır; yeni bir API sürümü veya canlı ortam yayını duyurusu değildir. Referans, test ortamından alınan OpenAPI belgesine dayanır; sunucu davranışında değişiklik yapılmamıştır.