Ana içeriğe geç

Webhook Entegrasyon Rehberi

YolcuGo, rezervasyonlarınızda partnere görünen bir bilgi değiştiğinde sizin HTTPS adresinize POST ile bir JSON olayı gönderir. Bu sayfa webhook entegrasyonunun tek kaynağıdır ve apiVersion: "2026-12" sözleşmesini anlatır. Önceki sözleşmeden (2026-03 / 2026-05) geçiyorsanız önce değişiklik günlüğündeki geçiş notunu okuyun.

Genel Bakış​

  • Her olay rezervasyonun tam güncel görüntüsünü (data) taşır. Olayı işlemek için ayrıca API'yi çağırmanız gerekmez; data ile kaydınızı güncelleyebilirsiniz.
  • Beş olay vardır: transfer.created, transfer.updated, transfer.status_changed, transfer.driver_assigned, transfer.driver_unassigned. OpsPortal'daki Test düğmesi ayrıca eventType: "test" gönderir.
  • transfer.updated, size en son yayımlanan data'ya göre değişen her alanı eski ve yeni değeriyle listeler (changes). Değerler data ile aynı tip ve biçimdedir: sayı sayı, tarih ISO 8601 metni.
  • transfer.created her rezervasyon için garanti değildir. Tanımadığınız bir transferId ile gelen her olayda kaydı data'dan oluşturun (Bilinmeyen Rezervasyon).
  • Tek bir sürüm vardır: bütün gövdelerde apiVersion "2026-12"'dir.
  • Teslimat en az bir kez yapılır ve sıra garanti edilmez. Tekrarları eventId ile ayıklayın, eski yükü data.stateVersionUtc ile tanıyın (Sıra).

Bağlantıyı Kurun​

Webhook'lar OpsPortal'da Ayarlar → Webhooks (/settings/webhooks) sayfasından yönetilir. Webhook, oturum açan kullanıcının firmasına bağlanır; olaylar o firmanın sahibi olduğu rezervasyonlar için gelir. Sayfayı görmek, webhook eklemek/düzenlemek ve teslimat geçmişini görmek ayrı yetkilerdir (Companies.Webhook.View, Companies.Webhook.Manage, Companies.Webhook.Delivery.View). API hesabı OpsPortal yetkisi vermez; sayfaya erişiminiz yoksa destek ekibinden kurulum isteyin.

Yeni Webhook formundaki alanlar:

AlanKural
AdZorunlu, en çok 100 karakter.
Endpoint URLZorunlu, en çok 500 karakter. Yalnız https; port yalnız 443 (varsayılan) ya da 8443. localhost, bulut metadata adresleri, özel, loopback, link-local ve ayrılmış IP aralıkları reddedilir. Gönderim anında adınız yeniden çözülür; iç ağa çözülen adrese bağlanılmaz.
Secretİsteğe bağlı, en çok 255 bayt (UTF-8; Türkçe karakter 2 bayt sayılır). Aşağıya bakın.
Olay filtresiİsteğe bağlı, en çok 256 karakter. Aşağıya bakın.
AktifKapalı webhook'a gerçek olay gönderilmez (yalnız Test gider).

Secret​

Secret'ı siz seçersiniz ve imza doğrulaması için alıcınızda aynı değeri kullanırsınız. Secret bir API parolası ya da Bearer token değildir. Örnek üretim komutu: node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))".

  • Secret kaydedilirken baştaki ve sondaki boşluklar kırpılır ve imza kırpılmış değerle hesaplanır. Alıcınızda da kırpılmış değeri kullanın.
  • Secret isteğe bağlıdır, ama boş bırakırsanız istekler imzasız gelir: imza başlıklarının hiçbiri gönderilmez. Canlı ortamda secret tanımlayın.
  • Düzenleme formunda secret alanını boş bırakmak mevcut secret'ı korur. Alana yalnız boşluk yazıp kaydetmek ise secret'ı kaldırır (kırpılınca boş kalır); sonraki istekler imzasız gelir. Secret saklanırken şifrelenir ve geri gösterilmez.
  • Secret değiştiğinde eski ve yeni secret bir arada geçerli olmaz: kaydettiğiniz andan sonraki her gönderim (bekleyen yeniden denemeler dahil) yeni secret ile imzalanır. Değişimi alıcınızla koordine edin; örneğin geçiş süresince alıcınızda iki secret'ı da kabul edin.

Olay Filtresi​

Filtre, virgülle ayrılmış belirteçlerden oluşur. Her belirteç şunlardan biri olmalıdır: katalogdaki bir olay adı, transfer.* ya da *. Boş filtre bütün olaylar demektir. Belirteçlerin çevresindeki boşluklar yok sayılır. Başka bir değer (?, transfer.driver_*, bilinmeyen ad, boş belirteç) kayıtta reddedilir.

Örnek: transfer.created,transfer.updated yalnız bu iki olayı gönderir.

Kontrol​

Kaydettikten sonra Test düğmesine basın ve Teslimat Geçmişi'nde başarılı sonucu görün (Test Bildirimi). "Kuyruğa alındı" bildirimi, adresinizin yanıt verdiği anlamına gelmez.

Alıcınızı Yazın​

Alıcının görevi kısadır: ham gövdeyi doğrula → kalıcı kaydet → hızlı 2xx dön. İş işlemini (veritabanınızı güncelleme, kullanıcıya bildirim) yanıttan sonra, kendi arka plan işleyicinizde yapın.

  1. İmzayı JSON'u ayrıştırmadan önce, isteğin ham baytları üzerinde doğrulayın (İmza Doğrulama).
  2. Gövdeyi kalıcı olarak kaydedin ve eventId ile tekilleştirin. Aynı eventId birden çok kez gelebilir (yeniden deneme, elle yeniden gönderim); iş etkisini bir kez uygulayın.
  3. Kayıt başarılıysa 2xx dönün. Bir deneme toplam 30 saniyeyle sınırlıdır (Teslimat); birkaç saniyede yanıt verin.
  4. Kaydınızı data ile oluşturun ya da güncelleyin (upsert): transferId sizde yoksa olayın adı ne olursa olsun kaydı data'dan oluşturun. data.stateVersionUtc elinizdekinden eskiyse yükü uygulamayın (Sıra). data'yı her zaman tam hâl olarak uygulayın; changes boş da gelebilir (Boş changes).
  5. Bilinmeyen alanları ve olay adlarını yok sayın; katı şema doğrulaması (ör. Java Jackson'ın FAIL_ON_UNKNOWN_PROPERTIES) kullanıyorsanız kapatın. Alan sırasına güvenmeyin.

Çalıştırılabilir Node.js Alıcısı​

receiver.mjs dosyasını indirin. Node.js 24+ ile ek paket gerekmez. Örnek ham gövdeyi doğrular, SQLite'a transaction içinde kaydeder, eventId ve teslimat kimliğini tekilleştirir ve ancak kayıt tamamlandıktan sonra 204 döner. Aynı eventId yeniden gelirse ilk kaydedilen gövde korunur ve yine 204 döner. Örnek, secret'ın baştaki ve sondaki boşluklarını YolcuGo gibi kırparak kullanır. Varsayılan V1'dir; SIGNATURE_VERSION=v2 ile V2 doğrular. V2 başarısızsa V1'e dönmez.

# receiver.mjs dosyasının bulunduğu dizinde. Secret'ı ekranda göstermeden okuyun:
read -rs WEBHOOK_SECRET
export WEBHOOK_SECRET
export INBOX_PATH="$PWD/webhook-inbox.sqlite"
export SIGNATURE_VERSION=v2
node receiver.mjs

Alıcı 127.0.0.1:3000/webhook üzerinde dinler. Önündeki HTTPS sunucusu ya da reverse proxy bu yola gövdeyi değiştirmeden iletmelidir. OpsPortal'a yerel adres değil, dışarıdan erişilen HTTPS adresiniz kaydedilir. PORT ile yerel portu değiştirebilirsiniz. Örnekteki 1 MiB gövde sınırı alıcının seçimidir, YolcuGo'nun bir taahhüdü değildir.

İşlemeyi tamamlayın: events tablosunda state='pending' olan kayıtları kendi işleyicinize alın. raw_body, doğrulanmış gövdenin baytlarıdır. İş işlemi başarılı olunca state='processed' yapın; başarısızsa kaydı bekletip yeniden deneyin. 204 ile kabul ettiğiniz olayın iş hatasını YolcuGo göremez.

SELECT event_id, event_type, raw_body
FROM events WHERE state = 'pending' ORDER BY received_at LIMIT 100;
-- İş işleminiz başarıyla tamamlandıktan sonra, parametreli sorguyla:
UPDATE events SET state = 'processed' WHERE event_id = ?;

İş etkisi ile işaretlemeyi mümkünse aynı veritabanı transaction'ında yapın. Harici bir sisteme yazıyorsanız eventId'yi onun tekillik anahtarı olarak kullanın. SQLite ve WAL dosyalarını yalnız uygulamanıza açık, kalıcı bir dizinde tutun; ham gövde yolcu bilgileri içerir. Örnek tek webhook bağlantısı ve tek alıcı süreci içindir; çok süreçte ortak, atomik tekillik sağlayan bir veritabanı ya da kuyruk kullanın. Secret'ı kaynak koda, URL'ye ya da loglara yazmayın.

İmza Doğrulama​

Her istekte şu başlıklar bulunur:

Başlıkİçerik
Content-Typeapplication/json; charset=utf-8
X-Webhook-EventOlay adı (ör. transfer.updated). İş kararında imzalı gövdedeki eventType'ı esas alın.
X-Webhook-Delivery-IdTeslimat kimliği (tam sayı). Aynı teslimatın yeniden denemelerinde aynıdır; elle yeniden gönderimde ve aynı olayın başka bir webhook'unuza gidişinde farklıdır.
X-Company-IdWebhook'un bağlı olduğu firma kimliği. Tek başına kimlik kanıtı değildir.
User-AgentYolcuGo-Webhooks/1.0. Günlük ve güvenlik duvarı kuralları için; kimlik kanıtı değildir.
X-Webhook-SignatureSecret tanımlıysa: ham gövdenin HMAC-SHA256 özeti, küçük harf hex (V1).
X-Webhook-TimestampSecret tanımlıysa: imzanın üretildiği an, Unix saniyesi.
X-Webhook-Signature-V2Secret tanımlıysa: t=TIMESTAMP,v1=HEX (V2).

Secret tanımlı değilse son üç başlık hiç gönderilmez.

  • V1: HMAC-SHA256(secret, gövde), küçük harf hex.
  • V2: HMAC-SHA256(secret, "TIMESTAMP.DELIVERY_ID.gövde"), küçük harf hex. TIMESTAMP, X-Webhook-Timestamp ile aynıdır; DELIVERY_ID, X-Webhook-Delivery-Id'dir. V2 zamanı ve teslimat kimliğini imzaya bağlar; alıcıda bir zaman penceresi (ör. ±300 saniye) uygulayarak eski isteklerin tekrar oynatılmasını engelleyebilirsiniz. Saatinizi senkron tutun. Her yeni denemede zaman damgası yenilenir.

İki imza her istekte birlikte gönderilir; birini seçin. Yeni entegrasyonda V2 önerilir.

Ham baytları kullanın. Gövdeyi ayrıştırıp yeniden serileştirmeyin: boşluklar, sayı yazımı ve kaçış dizileri (gövde Türkçe karakterleri ı gibi kaçışlı yazabilir) değişirse imza tutmaz. Karşılaştırmayı sabit zamanlı yapın. Doğrulama başarısızsa 401 dönün ve kaydetmeyin.

V2 (Önerilen)​

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhookV2({
rawBody, secret, signatureV2, timestamp, deliveryId,
maxAgeSeconds, nowSeconds = Math.floor(Date.now() / 1000)
}) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
if (!Number.isFinite(maxAgeSeconds) || maxAgeSeconds <= 0) return false;
if (!Number.isFinite(nowSeconds)) return false;
if (typeof signatureV2 !== 'string' || typeof timestamp !== 'string'
|| typeof deliveryId !== 'string') return false;

const match = /^t=([0-9]+),v1=([0-9a-fA-F]{64})$/.exec(signatureV2);
if (!match || match[1] !== timestamp || !/^[0-9]+$/.test(deliveryId)) return false;
const sentAt = Number(timestamp);
if (!Number.isSafeInteger(sentAt) || Math.abs(nowSeconds - sentAt) > maxAgeSeconds) return false;

const expected = createHmac('sha256', secret)
.update(`${timestamp}.${deliveryId}.`, 'utf8')
.update(rawBody)
.digest();
const received = Buffer.from(match[2], 'hex');
return received.length === expected.length && timingSafeEqual(received, expected);
}

V1 (Express)​

Bu route'u app.use(express.json()) satırından önce tanımlayın.

const express = require('express');
const crypto = require('crypto');
const app = express();
// YolcuGo secret'ı baştaki ve sondaki boşlukları kırpılmış hâliyle kullanır.
const SECRET = process.env.WEBHOOK_SECRET?.trim();
if (!SECRET) throw new Error('WEBHOOK_SECRET is required');

function verifySignature(body, secret, signature) {
if (!Buffer.isBuffer(body) || typeof signature !== 'string' ||
!/^[a-f0-9]{64}$/i.test(signature)) return false;
const computed = crypto.createHmac('sha256', secret).update(body).digest();
return crypto.timingSafeEqual(computed, Buffer.from(signature, 'hex'));
}

app.post('/webhook', express.raw({ type: 'application/json', limit: '1mb' }), (req, res) => {
if (!verifySignature(req.body, SECRET, req.headers['x-webhook-signature'])) {
return res.status(401).send('Invalid signature');
}
// İmzadan sonra JSON.parse(req.body.toString('utf8')) kullanabilirsiniz.
// Üretimde 2xx dönmeden önce kalıcı kaydedin ve eventId ile tekilleştirin.
res.status(200).send('OK');
});

C# / ASP.NET Core (V1)​

Gövde model binding ile okunmadan önce kullanın; secret yapılandırmanızdan gelir (baştaki ve sondaki boşlukları kırpılmış değer).

using var buffer = new MemoryStream();
await Request.Body.CopyToAsync(buffer);
var signature = Request.Headers["X-Webhook-Signature"].ToString();
if (signature.Length != 64) return Unauthorized();
byte[] supplied;
try { supplied = Convert.FromHexString(signature); }
catch (FormatException) { return Unauthorized(); }
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var computed = hmac.ComputeHash(buffer.ToArray());
if (!CryptographicOperations.FixedTimeEquals(computed, supplied))
return Unauthorized();
// İmzadan sonra kalıcı kaydedin, eventId ile tekilleştirin, sonra 2xx dönün.

Python (V1)​

import hmac, hashlib, re

def verify_signature(body: bytes, secret: str, signature: str) -> bool:
if not isinstance(signature, str) or not re.fullmatch(r"[a-fA-F0-9]{64}", signature):
return False
computed = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(computed, signature.lower())

# body: ayrıştırılmamış ham istek baytları; secret: baştaki ve sondaki boşlukları kırpılmış değer.

Olay Kataloğu​

YolcuGo, rezervasyonu ilgilendiren her kayıttan sonra rezervasyonun yeni görüntüsünü, sizin için en son yayımladığı görüntüyle karşılaştırır ve olayları buna göre üretir. Bu yüzden bir değişiklik hangi ekrandan ya da süreçten gelirse gelsin (operasyon düzenlemesi, fiyat düzeltmesi, ek hizmet onayı, sürücü kartındaki telefon değişikliği, firma ya da araç tipi adının değişmesi, plan yayımı) aynı kurala göre bildirilir. Kendi başına olay üretmeyen az sayıdaki değişiklik aşağıda listelenmiştir.

OlayNe zaman gelirEk alanlar
transfer.createdRezervasyon size ilk kez görünür olduğunda.—
transfer.updateddata, size en son yayımlanan görüntüden farklı olduğunda (durum ve sürücü dahil). İstisnalar: Olay Gelmeyen Durumlar.changedFields, changes
transfer.status_changedstatus değiştiğinde.oldStatus, oldStatusName, newStatus, newStatusName
transfer.driver_assignedSürücü atandığında ya da başka bir sürücüye geçtiğinde.driverFullName, driverPhone, vehiclePlate (yeni atama)
transfer.driver_unassignedSürücü ataması kaldırıldığında.previousDriverFullName, previousDriverPhone, previousVehiclePlate

transfer.created ne zaman gelir? Rezervasyon size görünür olduğunda:

  • Ödeme gerektirmeyen rezervasyonda (ör. cari hesaba, API ile) oluşturulduğu anda.
  • Kartla ödenen rezervasyonda ödeme tamamlandığında. Ödemesi bekleyen, başarısız olan ya da vazgeçilen rezervasyon için hiçbir olay gelmez. Kart çekimi alınıp rezervasyon kesinleşemediği için otomatik iade edilen rezervasyon da hiç görünür olmaz; ona da olay gelmez.

Bilinmeyen Rezervasyon​

transfer.created her rezervasyon için garanti değildir. Şu durumlarda hiç gelmez ve sonradan da gönderilmez; rezervasyonu ilk kez transfer.updated, transfer.status_changed ya da bir sürücü olayıyla görürsünüz:

  • Rezervasyon bu sözleşme yayına girmeden ya da firmanız ilk webhook'unu tanımlamadan önce oluşturulduysa. İlk değişikliğinde doğrudan transfer.updated gelir. O anda açık olan rezervasyonların önceki hâli kaydedilir ve changes değişen alanları listeler; önceki hâli kaydedilmemiş rezervasyonda changes boş gelir (Boş changes). İlk webhook'tan yaklaşık bir dakika öncesine kadar oluşturulan rezervasyon yeni sayılır ve transfer.created alır. O anda size henüz görünür olmayan rezervasyon (ör. kart ödemesi bekleyen) da görünür olduğunda transfer.created alır.
  • Rezervasyon size görünür olduğunda webhook'unuz kapalıysa.
  • Olay filtreniz transfer.created'i kapsamıyorsa.
  • transfer.created teslimatı bütün denemelerini başarısız tükettiyse (Teslimat).

Yapmanız gereken: transferId sizde kayıtlı değilse, olayın adı ne olursa olsun kaydı data'dan oluşturun. data her olayda rezervasyonun tam görüntüsüdür; transfer.created'i beklemeyin ve bilinmeyen rezervasyona gelen olayı hata saymayın.

Aynı Kayıtta Birden Çok Olay​

Bir değişiklik aynı anda durumu, sürücüyü ve başka alanları değiştirebilir. Olaylar bu sırayla üretilir: önce transfer.status_changed, sonra transfer.driver_assigned ya da transfer.driver_unassigned, en son transfer.updated. Hepsi aynı occurredAt, aynı data.stateVersionUtc ve aynı data'yı taşır; transfer.updated bütün farkları (durum ve sürücü dahil) listeler. Yalnız bir olayı işleyecekseniz transfer.updated yeterlidir. Üretim sırası teslim sırası garantisi değildir.

Olaylar değişiklikten yaklaşık bir dakika içinde üretilir. Bu süre içinde aynı rezervasyon birden çok kez değişirse ara hâller tek bir transfer.updated'da birleşebilir: changes size en son gönderilen hâlden güncel hâle olan farkı listeler, aradaki geçici değerleri değil.

Sürücü olayları rezervasyonun etkin sürücüsüne bakar. Birleşik bir seferdeki (grup) rezervasyonun kendi ataması hiç yoksa (ne sürücüsü ne aracı) seferin sürücüsü ve aracı geçerlidir; rezervasyonda sürücü ya da araçtan biri bile atanmışsa kendi ataması geçerlidir. driverFullName, driverPhone, vehiclePlate ve vehiclePhotos aynı etkin atamadan gelir. Yalnız araç değişirse transfer.driver_assigned gelmez; transfer.updated (vehiclePlate, vehiclePhotos) gelir.

Olay Gelmeyen Durumlar​

Şu değişiklikler kendi başına olay üretmez:

  • Sürüm sayaçları: yalnız stateVersionUtc, corporatePlan.publishedVersion ya da corporatePlan.rowVersion değiştiyse (aşağıda).
  • Tamamlanmış ya da iptal edilmiş rezervasyonun gösterdiği tanımlar: sürücü (ad, telefon), araç (plaka, fotoğraf), konum adı, firma adı, araç tipi adı, ek hizmet tanımının adı ya da tipi ve paylaşımlı seferin yayımı ya da kalkışı sonradan değişirse. Açık rezervasyonlarda bu düzenlemeler transfer.updated üretir.
  • Saat dilimi etiketi: pickUpTimeZoneLabel ülke tanımından okunur; yalnız bu tanım değiştiyse.
  • Silinmiş rezervasyon: silinen rezervasyon için olay gelmez.

İlk üç durumdaki değişiklik kaybolmaz: rezervasyonun bir sonraki olayında data günceldir; tanım ve etiket farkları o olayın changes'inde de listelenir (sayaçlar changes'te hiç yer almaz). Rezervasyonun kendi kaydındaki değişiklikler (durum, saat, fiyat, yolcu, ek hizmet, atama) rezervasyon tamamlanmış ya da iptal edilmiş olsa da olay üretir.

Üretilen bir olayın size ulaşması için webhook'unuzun o anda açık olması ve olay filtrenizin o olayı kapsaması gerekir; kapalıyken ya da filtre dışında kalan olaylar sonradan gönderilmez (Kapatma, Açma ve Silme).

Durum Kodları​

KodMetin
1Yeni Transfer
2Tedarikçi Ataması Bekliyor
3Konfirme Bekliyor
4Konfirme Edildi
5Not Konfirme
6Sürücü Ataması Bekliyor
7Seyahata Hazır
8Yola Çıktım
9Yolcuyu Aldım
10Yolcuyu Bıraktım
11İptal Edildi
12Tamamlandı

Her transfer bütün durumlardan geçmez. Test bildirimindeki 0 gerçek bir durum değildir.

Ortak Gövde ve data Alanları​

Her gövde (test dahil) şu alanları taşır. Gövde API yanıt zarfına (success, statusCode) sarılmaz.

AlanTipAçıklama
eventIdstring (GUID biçimi)Olayın kimliği. Yeniden denemede ve elle yeniden gönderimde aynıdır; tekilleştirme anahtarınız budur.
eventTypestringOlay adı.
apiVersionstringHer zaman "2026-12".
occurredAtstring (ISO 8601, UTC)Olayın üretildiği an (ör. 2026-11-20T09:30:00.0000000Z).
transferIdstring (GUID)Rezervasyon kimliği; API'deki transferReservationId.
pnrstringRezervasyon kodu.
dataobjectRezervasyonun tam görüntüsü. Her olayda her zaman tam gelir.

data Alanları​

Tarih alanları ISO 8601 UTC metnidir (Z ile biter). null olabilen alanlar her gövdede yazılır; "yalnız … gelir" denen alanlar koşul yoksa gövdede hiç bulunmaz. Para alanlarında birim açıkça yazılmıştır. Sayıları sayısal olarak karşılaştırın; ondalık basamak sayısına ya da metin biçimine güvenmeyin.

AlanTipAçıklama
transferIdstring (GUID)Rezervasyon kimliği.
pnrstringRezervasyon kodu.
statusnumberDurum kodu (Durum Kodları).
statusNamestringDurumun Türkçe adı.
companyIdnumber | nullRezervasyonun sahibi firma.
companyNamestring | nullFirma adı.
pickUpTimestring | nullAlış zamanı (UTC).
pickUpTimeZoneIdstring | nullAlış noktasının IANA saat dilimi (ör. Europe/Istanbul, Asia/Famagusta).
pickUpLocalDateTimestring | nullAlış noktasındaki yerel saat, offset'siz (yyyy-MM-ddTHH:mm:ss). Yolcuya bunu gösterin.
pickUpTimeZoneLabelstring | nullDilimin görünen adı (ör. Türkiye, KKTC).
dropOffTimestring | nullBırakış zamanı (UTC).
vehicleTypeIdnumber | nullAraç tipi kimliği (paylaşımlı transferde null).
vehicleTypeNamestring | nullAraç tipi adı.
pickUpLocationstring | nullAlış noktası.
dropOffLocationstring | nullBırakış noktası.
driverFullNamestring | nullEtkin sürücünün adı soyadı.
driverPhonestring | nullEtkin sürücünün telefonu.
vehiclePlatestring | nullEtkin aracın plakası.
vehiclePhotosarray | nullEtkin aracın fotoğrafları; vitrin fotoğrafı önce, sonra tanımlı sıra. Fotoğraf yoksa null.
passengerCountnumberYolcu satırı sayısı. Paylaşımlı transferde satın alınan kişi sayısı, kurumsal planlı rezervasyonda beyan edilen kişi sayısıdır.
passengersarray | nullYolcular; baş yolcu önce, diğerleri kayıt sırasıyla. Yolcu yoksa null.
flightNostring | nullUçuş numarası.
notestring | nullTransfer notu.
customerReferencestring | nullRezervasyonda gönderdiğiniz kendi rezervasyon numaranız.
totalNetAmountnumberToplam net tutar, KDV hariç, TRY.
totalVatAmountnumberToplam KDV, TRY.
totalGrossAmountnumberToplam brüt tutar (net + KDV), TRY.
supplierFeenumberTedarikçi ücreti, TRY.
currencystringMüşteri para birimi (TRY, EUR, USD, RUB…). Yalnız customerTotalNet'in birimidir; total* ve supplierFee her zaman TRY'dir.
customerTotalNetnumberMüşteri para biriminde (currency) KDV hariç toplam.
pricingBasisstringYalnız kişi başı fiyatlı transferde gelir; değeri PerPerson. Alan yoksa fiyat araç başıdır.
perPersonPricenumberYalnız kişi başı fiyatlı transferde gelir: fiyat kaydındaki kişi başı birim fiyat, TRY. Toplamın kişi başı payı değildir; toplam için totalNetAmount ve diğer total* alanlarını kullanın.
pricedPassengerCountnumberYalnız kişi başı fiyatlı transferde gelir: fiyatın hesaplandığı kişi sayısı.
extrasarray | nullYalnız onaylanmış ek hizmetler, id sırasıyla. Yoksa null.
linkedReservationIdstring (GUID) | nullGidiş-dönüşte bağlı diğer bacağın kimliği.
linkedPnrstring | nullBağlı bacağın PNR'ı. Bağlı bacak henüz size görünür değilken (ör. ödemesi bekleniyor) null.
legOrdernumber | nullGidiş-dönüş sırası: 1 gidiş, 2 dönüş; tek yönde null.
mergeStatusnumberBirleşik sefer üyeliği: 0 bağımsız, 1 birleştirildi, 2 ayrıştırıldı.
noMergebooleanRezervasyon noMerge: true ile oluşturulduysa true.
isNoShowbooleanTransfer no-show (yolcu gelmedi) olarak kapatıldıysa true.
noShowFeenumber | nullNo-show bedeli, KDV hariç, TRY. No-show değilse ya da bedel girilmediyse null.
stateVersionUtcstring | nullBu data'nın sürümü (UTC zaman damgası): size yayımlanan her yeni hâlde kesin artar; aynı hâli taşıyan olaylarda aynıdır. Sıra kontrolü için; Sıra. Test bildiriminde null.
quickBookingobjectYalnız tek istekte rezervasyon ile oluşturulan rezervasyonda gelir.
sharedTransferobjectYalnız paylaşımlı transfer rezervasyonunda gelir.
corporatePlanobjectYalnız kurumsal planlı rezervasyonda gelir.

İç İçe Alanlar​

AlanTipAçıklama
passengers[].firstNamestringAd.
passengers[].lastNamestringSoyad.
passengers[].emailstring | nullE-posta.
passengers[].isLeadbooleanBaş yolcu. (İstekteki alan adı isLeadPassenger'dır.)
vehiclePhotos[].urlstringFotoğraf adresi.
vehiclePhotos[].isShowcasebooleanVitrin fotoğrafı.
extras[].idnumberEk hizmet kaydının kimliği.
extras[].typenumber0 Karşılama, 1 Oto Koltuğu, 2 Paralı Yol, 3 Ara Durak, 4 Diğer. Tedarikçinin ek hizmet kataloğuna bağlı olmayan, elle eklenmiş hizmet 4 (Diğer) gelir.
extras[].typeNamestringTipin Türkçe adı.
extras[].namestringHizmet adı.
extras[].descriptionstring | nullAçıklama.
extras[].netAmountnumberNet tutar, KDV hariç, TRY.
extras[].vatRatenumberKDV oranı (ör. 20).
extras[].approvalStatusnumberHer zaman 1 (yalnız onaylılar gönderilir).
extras[].approvalStatusNamestring"Onaylandi" (Approved değil).
corporatePlan.planIdstring (GUID)Planın kimliği.
corporatePlan.publishedVersionnumberYayımlanan plan sürümü (sayaç).
corporatePlan.rowVersionnumberPlanın güncel değişiklik sürümü (sayaç).
corporatePlan.groupIdstring (GUID) | nullRezervasyonun bağlı olduğu sefer (grup); sefere alınmadıysa null.
corporatePlan.pickUpTimeOriginstringpickUpTime'ın kaynağı: Customer talep edilen, Provisional geçici, Planned yayımlanan plan saati.
corporatePlan.requestedPickUpTimestring | nullMüşterinin talep ettiği alış saati (UTC).
corporatePlan.flightScheduledAtUtcstring | nullUçuşun planlanan saati (UTC).
corporatePlan.flightTimeZoneIdstring | nullUçuş saatinin dilimi.
corporatePlan.isInternationalFlightboolean | nullDış hat uçuşu.
sharedTransfer.isPublishedbooleanTedarikçi seferi yayımladı mı.
sharedTransfer.plannedDepartureUtcstring | nullYayımlanmış seferin kalkışı (UTC); sefer yayımlanmadıysa null.
sharedTransfer.departureIsPlannedbooleanYalnız yayımlanmış bir havalimanı geliş seferinde, rezervasyon hazır işaretlenene kadar true. Sefer yayımlanmadıysa, havalimanına gidiş yönünde ve hazır işaretlendikten sonra false.
sharedTransfer.reservedPassengerCountnumberSatın alınan kişi sayısı.
sharedTransfer.presentPassengerCountnumber | nullKaydedilen gelen yolcu sayısı.
quickBooking.pricingSourcestringAvailability, RegionMaximum ya da AirportMaximum.
quickBooking.fallbackReasonstring | nullYedek fiyata düşülme nedeni.
quickBooking.addressstringOluşturmada gönderilen adres.
quickBooking.addressResolvedbooleanAdres oluşturma anında çözüldü mü.
quickBooking.priceScopestringAccount (cariye özel fiyat) ya da Customer (hesabınızın fiyatı).
quickBooking.requestedAccountCodestring | nullİstekte gönderdiğiniz partnerSubAccountCode.

transfer.updated ve changes​

transfer.updated, size en son gönderilen data ile yeni data arasındaki farkı taşır:

  • changes[].field, data'daki alan adıdır (camelCase): pickUpTime, totalNetAmount, driverPhone…
  • İç içe nesnelerde (corporatePlan, sharedTransfer, quickBooking) her alt alan nokta yoluyla ayrı bildirilir: corporatePlan.groupId, sharedTransfer.plannedDepartureUtc. Nesne bir tarafta yoksa diğer taraftaki değeri dolu her alt alan null'a karşı listelenir (null değerli alt alan, nesnenin olmamasıyla aynı sayıldığı için listelenmez).
  • Diziler (passengers, extras, vehiclePhotos) bütün olarak tek alandır; oldValue ve newValue dizinin tamamıdır. Dizilerin sırası kararlıdır (yolcular: baş yolcu, sonra kayıt sırası; ek hizmetler: id; fotoğraflar: vitrin, tanımlı sıra, sonra kayıt sırası); içerik ya da bu sıra değişmedikçe dizi değişmiş sayılmaz.
  • oldValue ve newValue, data'daki JSON değerinin aynısıdır: sayılar sayı, tarihler ISO 8601 metni, diziler dizi. Kültüre bağlı metin yoktur.
  • Değeri null olan ya da gövdede hiç bulunmayan alan aynı sayılır. Bir alan boşaldığında ya da kaybolduğunda newValue: null, ilk kez dolduğunda oldValue: null gelir.
  • changes alan adına göre sıralıdır; changedFields aynı adları aynı sırayla verir.

Sürüm sayaçları bildirilmez: stateVersionUtc, corporatePlan.publishedVersion ve corporatePlan.rowVersion data'da güncel değerleriyle bulunur, ama karşılaştırmaya girmez: changes'te hiç yer almaz ve yalnız bunlar değiştiğinde olay gelmez (ör. plan yayımı, değişmeyen rezervasyona olay göndermez).

changes, size en son yayımlanan görüntüye göre farktır; o görüntünün size ulaşmış olması şart değildir. Webhook'unuz kapalıyken yapılan, olay filtrenizin dışında kalan ya da teslimatı bütün denemelerini tüketen bir değişiklik sonraki olayın changes'inde yeniden listelenmez. Bu yüzden güncel değeri her zaman data'dan okuyun; changes'i neyin değiştiğini göstermek (ör. yolcuya "alış saatiniz değişti" bildirimi) için kullanın.

Boş changes​

transfer.updated normalde en az bir değişiklik listeler. İstisna: YolcuGo rezervasyonun size yayımlanan önceki hâlini bilmiyorsa fark çıkaramaz ve değişikliği boş changedFields ve boş changes ile, güncel data'yla gönderir. Önceki hâli bilinmeyen rezervasyon, sözleşme yayına girmeden (ya da firmanız ilk webhook'unu tanımlamadan) önce oluşturulmuş olandır:

  • O anda tamamlanmış ya da iptal edilmiş rezervasyonların önceki hâli kaydedilmez. Böyle bir rezervasyon sonradan değişirse (ör. fiyat düzeltmesi, no-show bedeli) ilk değişikliği, ne zaman olursa olsun, boş changes ile gelir.
  • O anda açık olan rezervasyonların önceki hâli ilk birkaç dakikada kaydedilir; bu sürede değişen rezervasyon boş changes ile gelir.
  • YolcuGo'nun kaydettiği önceki hâl okunamazsa (iç veri hatası) da aynısı olur.

Bu olayla birlikte transfer.status_changed ve sürücü olayları gelmez (önceki durum ve sürücü bilinmez); durum ve sürücü değişikliği data'dadır. Olay filtrenizde transfer.updated yoksa bu değişikliği hiç almazsınız: transfer.updated'ı her zaman dinleyin.

Böyle bir olayda data'yı tam hâl olarak uygulayın; neyin değiştiğini kendi kaydınızla data'yı karşılaştırarak bulabilirsiniz. Aynı rezervasyonun sonraki değişiklikleri yine alan alan listelenir.

Böyle bir transfer.updated gövdesinin farkı (ortak gövde alanları kısaltıldı):

{
"changedFields": [],
"changes": [],
"data": { "...": "rezervasyonun tam güncel görüntüsü" }
}

Örnekler​

Örneklerin tamamını JSON olarak indirin. Örnekler elle yazılmaz; YolcuGo'nun gerçek yayımlama kodu çalıştırılarak üretilir (kimlikler ve saatler sabitlenmiştir). Koşullu alanlardan kişi başı alanlar ve sharedTransfer bu örneklerde görünmez; quickBooking tek istekte rezervasyon örneklerinde vardır. İmza, örneği yeniden biçimlendirdiğiniz için bu dosyalarda tutmaz; gerçek isteğin baytlarını doğrulayın.

İlk altı örnek aynı rezervasyonun (YG7K2M) akışıdır.

transfer.created — rezervasyon oluşturuldu
{
"eventId": "6f3b3751-a802-3ad3-53cb-f622bfb08104",
"apiVersion": "2026-12",
"occurredAt": "2026-11-20T09:30:40.0000000Z",
"transferId": "3f2b8c1e-7a4d-4e6b-9c1a-2d5e8f7a9b10",
"pnr": "YG7K2M",
"eventType": "transfer.created",
"data": {
"transferId": "3f2b8c1e-7a4d-4e6b-9c1a-2d5e8f7a9b10",
"pnr": "YG7K2M",
"status": 6,
"statusName": "Sürücü Ataması Bekliyor",
"companyId": 501,
"companyName": "Örnek Turizm",
"pickUpTime": "2026-12-01T07:00:00Z",
"dropOffTime": null,
"vehicleTypeId": 9,
"vehicleTypeName": "Vito",
"pickUpLocation": "İstanbul Havalimanı (IST)",
"dropOffLocation": "Taksim Meydanı, Beyoğlu, İstanbul",
"driverFullName": null,
"driverPhone": null,
"vehiclePlate": null,
"passengerCount": 2,
"flightNo": "TK2121",
"note": null,
"totalNetAmount": 2000,
"supplierFee": 1500,
"currency": "TRY",
"totalVatAmount": 400,
"totalGrossAmount": 2400,
"linkedReservationId": null,
"linkedPnr": null,
"legOrder": null,
"passengers": [
{
"firstName": "Ayşe",
"lastName": "Yılmaz",
"email": "ayse.yilmaz@example.com",
"isLead": true
},
{
"firstName": "Can",
"lastName": "Yılmaz",
"email": null,
"isLead": false
}
],
"vehiclePhotos": null,
"extras": [
{
"id": 8801,
"type": 4,
"typeName": "Diğer",
"name": "VIP Karşılama",
"description": "VIP Karşılama",
"netAmount": 500,
"vatRate": 20,
"approvalStatus": 1,
"approvalStatusName": "Onaylandi"
}
],
"mergeStatus": 0,
"stateVersionUtc": "2026-11-20T09:30:40Z",
"pickUpTimeZoneId": "Europe/Istanbul",
"customerReference": "ACME-48213",
"pickUpLocalDateTime": "2026-12-01T10:00:00",
"pickUpTimeZoneLabel": "Türkiye",
"noMerge": false,
"isNoShow": false,
"noShowFee": null,
"customerTotalNet": 2000
}
}
transfer.updated — alış saati ve fiyat değişti

Operasyon alış saatini 30 dakika ileri aldı ve fiyat yeniden hesaplandı. Değişen her para alanı eski ve yeni sayısal değeriyle gelir; yerel alış saati de ayrıca listelenir.

{
"eventId": "27908388-402a-1b69-b4e1-7f45d77106f4",
"apiVersion": "2026-12",
"occurredAt": "2026-11-20T11:15:40.0000000Z",
"transferId": "3f2b8c1e-7a4d-4e6b-9c1a-2d5e8f7a9b10",
"pnr": "YG7K2M",
"changedFields": [
"customerTotalNet",
"pickUpLocalDateTime",
"pickUpTime",
"supplierFee",
"totalGrossAmount",
"totalNetAmount",
"totalVatAmount"
],
"changes": [
{
"field": "customerTotalNet",
"oldValue": 2000,
"newValue": 2200
},
{
"field": "pickUpLocalDateTime",
"oldValue": "2026-12-01T10:00:00",
"newValue": "2026-12-01T10:30:00"
},
{
"field": "pickUpTime",
"oldValue": "2026-12-01T07:00:00Z",
"newValue": "2026-12-01T07:30:00Z"
},
{
"field": "supplierFee",
"oldValue": 1500,
"newValue": 1700
},
{
"field": "totalGrossAmount",
"oldValue": 2400,
"newValue": 2640
},
{
"field": "totalNetAmount",
"oldValue": 2000,
"newValue": 2200
},
{
"field": "totalVatAmount",
"oldValue": 400,
"newValue": 440
}
],
"eventType": "transfer.updated",
"data": {
"transferId": "3f2b8c1e-7a4d-4e6b-9c1a-2d5e8f7a9b10",
"pnr": "YG7K2M",
"status": 6,
"statusName": "Sürücü Ataması Bekliyor",
"companyId": 501,
"companyName": "Örnek Turizm",
"pickUpTime": "2026-12-01T07:30:00Z",
"dropOffTime": null,
"vehicleTypeId": 9,
"vehicleTypeName": "Vito",
"pickUpLocation": "İstanbul Havalimanı (IST)",
"dropOffLocation": "Taksim Meydanı, Beyoğlu, İstanbul",
"driverFullName": null,
"driverPhone": null,
"vehiclePlate": null,
"passengerCount": 2,
"flightNo": "TK2121",
"note": null,
"totalNetAmount": 2200,
"supplierFee": 1700,
"currency": "TRY",
"totalVatAmount": 440,
"totalGrossAmount": 2640,
"linkedReservationId": null,
"linkedPnr": null,
"legOrder": null,
"passengers": [
{
"firstName": "Ayşe",
"lastName": "Yılmaz",
"email": "ayse.yilmaz@example.com",
"isLead": true
},
{
"firstName": "Can",
"lastName": "Yılmaz",
"email": null,
"isLead": false
}
],
"vehiclePhotos": null,
"extras": [
{
"id": 8801,
"type": 4,
"typeName": "Diğer",
"name": "VIP Karşılama",
"description": "VIP Karşılama",
"netAmount": 500,
"vatRate": 20,
"approvalStatus": 1,
"approvalStatusName": "Onaylandi"
}
],
"mergeStatus": 0,
"stateVersionUtc": "2026-11-20T11:15:40Z",
"pickUpTimeZoneId": "Europe/Istanbul",
"customerReference": "ACME-48213",
"pickUpLocalDateTime": "2026-12-01T10:30:00",
"pickUpTimeZoneLabel": "Türkiye",
"noMerge": false,
"isNoShow": false,
"noShowFee": null,
"customerTotalNet": 2200
}
}
transfer.status_changed — sürücü atanınca (1/3)

Sürücü ve araç atandı, durum "Seyahata Hazır" oldu. Bu tek kayıt üç olay üretti; bu birincisi.

{
"eventId": "8f01b756-656f-9c08-8dff-541f7768d93b",
"apiVersion": "2026-12",
"occurredAt": "2026-11-28T16:40:40.0000000Z",
"transferId": "3f2b8c1e-7a4d-4e6b-9c1a-2d5e8f7a9b10",
"pnr": "YG7K2M",
"oldStatus": 6,
"oldStatusName": "Sürücü Ataması Bekliyor",
"newStatus": 7,
"newStatusName": "Seyahata Hazır",
"eventType": "transfer.status_changed",
"data": {
"transferId": "3f2b8c1e-7a4d-4e6b-9c1a-2d5e8f7a9b10",
"pnr": "YG7K2M",
"status": 7,
"statusName": "Seyahata Hazır",
"companyId": 501,
"companyName": "Örnek Turizm",
"pickUpTime": "2026-12-01T07:30:00Z",
"dropOffTime": null,
"vehicleTypeId": 9,
"vehicleTypeName": "Vito",
"pickUpLocation": "İstanbul Havalimanı (IST)",
"dropOffLocation": "Taksim Meydanı, Beyoğlu, İstanbul",
"driverFullName": "Mehmet Kaya",
"driverPhone": "+905551112233",
"vehiclePlate": "34 YG 1907",
"passengerCount": 2,
"flightNo": "TK2121",
"note": null,
"totalNetAmount": 2200,
"supplierFee": 1700,
"currency": "TRY",
"totalVatAmount": 440,
"totalGrossAmount": 2640,
"linkedReservationId": null,
"linkedPnr": null,
"legOrder": null,
"passengers": [
{
"firstName": "Ayşe",
"lastName": "Yılmaz",
"email": "ayse.yilmaz@example.com",
"isLead": true
},
{
"firstName": "Can",
"lastName": "Yılmaz",
"email": null,
"isLead": false
}
],
"vehiclePhotos": [
{
"url": "https://cdn.example.com/vehicles/7701/front-800.jpg",
"isShowcase": true
}
],
"extras": [
{
"id": 8801,
"type": 4,
"typeName": "Diğer",
"name": "VIP Karşılama",
"description": "VIP Karşılama",
"netAmount": 500,
"vatRate": 20,
"approvalStatus": 1,
"approvalStatusName": "Onaylandi"
}
],
"mergeStatus": 0,
"stateVersionUtc": "2026-11-28T16:40:40Z",
"pickUpTimeZoneId": "Europe/Istanbul",
"customerReference": "ACME-48213",
"pickUpLocalDateTime": "2026-12-01T10:30:00",
"pickUpTimeZoneLabel": "Türkiye",
"noMerge": false,
"isNoShow": false,
"noShowFee": null,
"customerTotalNet": 2200
}
}
transfer.driver_assigned — sürücü atanınca (2/3)
{
"eventId": "8610b02a-af30-9fb8-c1f9-d976fbb13275",
"apiVersion": "2026-12",
"occurredAt": "2026-11-28T16:40:40.0000000Z",
"transferId": "3f2b8c1e-7a4d-4e6b-9c1a-2d5e8f7a9b10",
"pnr": "YG7K2M",
"driverFullName": "Mehmet Kaya",
"driverPhone": "+905551112233",
"vehiclePlate": "34 YG 1907",
"eventType": "transfer.driver_assigned",
"data": {
"transferId": "3f2b8c1e-7a4d-4e6b-9c1a-2d5e8f7a9b10",
"pnr": "YG7K2M",
"status": 7,
"statusName": "Seyahata Hazır",
"companyId": 501,
"companyName": "Örnek Turizm",
"pickUpTime": "2026-12-01T07:30:00Z",
"dropOffTime": null,
"vehicleTypeId": 9,
"vehicleTypeName": "Vito",
"pickUpLocation": "İstanbul Havalimanı (IST)",
"dropOffLocation": "Taksim Meydanı, Beyoğlu, İstanbul",
"driverFullName": "Mehmet Kaya",
"driverPhone": "+905551112233",
"vehiclePlate": "34 YG 1907",
"passengerCount": 2,
"flightNo": "TK2121",
"note": null,
"totalNetAmount": 2200,
"supplierFee": 1700,
"currency": "TRY",
"totalVatAmount": 440,
"totalGrossAmount": 2640,
"linkedReservationId": null,
"linkedPnr": null,
"legOrder": null,
"passengers": [
{
"firstName": "Ayşe",
"lastName": "Yılmaz",
"email": "ayse.yilmaz@example.com",
"isLead": true
},
{
"firstName": "Can",
"lastName": "Yılmaz",
"email": null,
"isLead": false
}
],
"vehiclePhotos": [
{
"url": "https://cdn.example.com/vehicles/7701/front-800.jpg",
"isShowcase": true
}
],
"extras": [
{
"id": 8801,
"type": 4,
"typeName": "Diğer",
"name": "VIP Karşılama",
"description": "VIP Karşılama",
"netAmount": 500,
"vatRate": 20,
"approvalStatus": 1,
"approvalStatusName": "Onaylandi"
}
],
"mergeStatus": 0,
"stateVersionUtc": "2026-11-28T16:40:40Z",
"pickUpTimeZoneId": "Europe/Istanbul",
"customerReference": "ACME-48213",
"pickUpLocalDateTime": "2026-12-01T10:30:00",
"pickUpTimeZoneLabel": "Türkiye",
"noMerge": false,
"isNoShow": false,
"noShowFee": null,
"customerTotalNet": 2200
}
}
transfer.updated — sürücü atanınca (3/3)

Durum ve sürücü değişiklikleri de changes'te listelenir; vehiclePhotos dizisi bütün olarak gelir.

{
"eventId": "5815d445-f6a2-0d58-3a56-b64ece2d2720",
"apiVersion": "2026-12",
"occurredAt": "2026-11-28T16:40:40.0000000Z",
"transferId": "3f2b8c1e-7a4d-4e6b-9c1a-2d5e8f7a9b10",
"pnr": "YG7K2M",
"changedFields": [
"driverFullName",
"driverPhone",
"status",
"statusName",
"vehiclePhotos",
"vehiclePlate"
],
"changes": [
{
"field": "driverFullName",
"oldValue": null,
"newValue": "Mehmet Kaya"
},
{
"field": "driverPhone",
"oldValue": null,
"newValue": "+905551112233"
},
{
"field": "status",
"oldValue": 6,
"newValue": 7
},
{
"field": "statusName",
"oldValue": "Sürücü Ataması Bekliyor",
"newValue": "Seyahata Hazır"
},
{
"field": "vehiclePhotos",
"oldValue": null,
"newValue": [
{
"url": "https://cdn.example.com/vehicles/7701/front-800.jpg",
"isShowcase": true
}
]
},
{
"field": "vehiclePlate",
"oldValue": null,
"newValue": "34 YG 1907"
}
],
"eventType": "transfer.updated",
"data": {
"transferId": "3f2b8c1e-7a4d-4e6b-9c1a-2d5e8f7a9b10",
"pnr": "YG7K2M",
"status": 7,
"statusName": "Seyahata Hazır",
"companyId": 501,
"companyName": "Örnek Turizm",
"pickUpTime": "2026-12-01T07:30:00Z",
"dropOffTime": null,
"vehicleTypeId": 9,
"vehicleTypeName": "Vito",
"pickUpLocation": "İstanbul Havalimanı (IST)",
"dropOffLocation": "Taksim Meydanı, Beyoğlu, İstanbul",
"driverFullName": "Mehmet Kaya",
"driverPhone": "+905551112233",
"vehiclePlate": "34 YG 1907",
"passengerCount": 2,
"flightNo": "TK2121",
"note": null,
"totalNetAmount": 2200,
"supplierFee": 1700,
"currency": "TRY",
"totalVatAmount": 440,
"totalGrossAmount": 2640,
"linkedReservationId": null,
"linkedPnr": null,
"legOrder": null,
"passengers": [
{
"firstName": "Ayşe",
"lastName": "Yılmaz",
"email": "ayse.yilmaz@example.com",
"isLead": true
},
{
"firstName": "Can",
"lastName": "Yılmaz",
"email": null,
"isLead": false
}
],
"vehiclePhotos": [
{
"url": "https://cdn.example.com/vehicles/7701/front-800.jpg",
"isShowcase": true
}
],
"extras": [
{
"id": 8801,
"type": 4,
"typeName": "Diğer",
"name": "VIP Karşılama",
"description": "VIP Karşılama",
"netAmount": 500,
"vatRate": 20,
"approvalStatus": 1,
"approvalStatusName": "Onaylandi"
}
],
"mergeStatus": 0,
"stateVersionUtc": "2026-11-28T16:40:40Z",
"pickUpTimeZoneId": "Europe/Istanbul",
"customerReference": "ACME-48213",
"pickUpLocalDateTime": "2026-12-01T10:30:00",
"pickUpTimeZoneLabel": "Türkiye",
"noMerge": false,
"isNoShow": false,
"noShowFee": null,
"customerTotalNet": 2200
}
}
transfer.driver_unassigned — sürücü ataması kaldırıldı

previous* alanları kaldırılan atamanındır; data'da sürücü alanları artık null'dır. Aynı kayıt ayrıca transfer.status_changed ve transfer.updated üretti (burada gösterilmedi).

{
"eventId": "d8978d04-5dd2-5aa9-9d25-e6d29e1cbc76",
"apiVersion": "2026-12",
"occurredAt": "2026-11-29T08:05:40.0000000Z",
"transferId": "3f2b8c1e-7a4d-4e6b-9c1a-2d5e8f7a9b10",
"pnr": "YG7K2M",
"previousDriverFullName": "Mehmet Kaya",
"previousDriverPhone": "+905551112233",
"previousVehiclePlate": "34 YG 1907",
"eventType": "transfer.driver_unassigned",
"data": {
"transferId": "3f2b8c1e-7a4d-4e6b-9c1a-2d5e8f7a9b10",
"pnr": "YG7K2M",
"status": 6,
"statusName": "Sürücü Ataması Bekliyor",
"companyId": 501,
"companyName": "Örnek Turizm",
"pickUpTime": "2026-12-01T07:30:00Z",
"dropOffTime": null,
"vehicleTypeId": 9,
"vehicleTypeName": "Vito",
"pickUpLocation": "İstanbul Havalimanı (IST)",
"dropOffLocation": "Taksim Meydanı, Beyoğlu, İstanbul",
"driverFullName": null,
"driverPhone": null,
"vehiclePlate": null,
"passengerCount": 2,
"flightNo": "TK2121",
"note": null,
"totalNetAmount": 2200,
"supplierFee": 1700,
"currency": "TRY",
"totalVatAmount": 440,
"totalGrossAmount": 2640,
"linkedReservationId": null,
"linkedPnr": null,
"legOrder": null,
"passengers": [
{
"firstName": "Ayşe",
"lastName": "Yılmaz",
"email": "ayse.yilmaz@example.com",
"isLead": true
},
{
"firstName": "Can",
"lastName": "Yılmaz",
"email": null,
"isLead": false
}
],
"vehiclePhotos": null,
"extras": [
{
"id": 8801,
"type": 4,
"typeName": "Diğer",
"name": "VIP Karşılama",
"description": "VIP Karşılama",
"netAmount": 500,
"vatRate": 20,
"approvalStatus": 1,
"approvalStatusName": "Onaylandi"
}
],
"mergeStatus": 0,
"stateVersionUtc": "2026-11-29T08:05:40Z",
"pickUpTimeZoneId": "Europe/Istanbul",
"customerReference": "ACME-48213",
"pickUpLocalDateTime": "2026-12-01T10:30:00",
"pickUpTimeZoneLabel": "Türkiye",
"noMerge": false,
"isNoShow": false,
"noShowFee": null,
"customerTotalNet": 2200
}
}
transfer.updated — kurumsal planda sefere alındı

Kurumsal planlı rezervasyon (YG9P4T) plan yayımında bir sefere alındı ve planlı alış saatini aldı. corporatePlan.groupId null'dan sefer kimliğine geçti. corporatePlan.publishedVersion data'da güncel değeriyle bulunur, ama sayaç olduğu için changes'te yoktur.

{
"eventId": "e5e41f84-10b8-21a0-88df-d52b71f64d3e",
"apiVersion": "2026-12",
"occurredAt": "2026-11-30T15:00:40.0000000Z",
"transferId": "8a6d4f2c-1b3e-4c5d-8e7f-9a0b1c2d3e4f",
"pnr": "YG9P4T",
"changedFields": [
"corporatePlan.groupId",
"corporatePlan.pickUpTimeOrigin",
"pickUpLocalDateTime",
"pickUpTime"
],
"changes": [
{
"field": "corporatePlan.groupId",
"oldValue": null,
"newValue": "c0ffee00-4b1d-4a2e-8f3c-5d6e7f8a9b0c"
},
{
"field": "corporatePlan.pickUpTimeOrigin",
"oldValue": "Customer",
"newValue": "Planned"
},
{
"field": "pickUpLocalDateTime",
"oldValue": "2026-12-02T08:00:00",
"newValue": "2026-12-02T07:40:00"
},
{
"field": "pickUpTime",
"oldValue": "2026-12-02T05:00:00Z",
"newValue": "2026-12-02T04:40:00Z"
}
],
"eventType": "transfer.updated",
"data": {
"transferId": "8a6d4f2c-1b3e-4c5d-8e7f-9a0b1c2d3e4f",
"pnr": "YG9P4T",
"status": 6,
"statusName": "Sürücü Ataması Bekliyor",
"companyId": 501,
"companyName": "Örnek Turizm",
"pickUpTime": "2026-12-02T04:40:00Z",
"dropOffTime": null,
"vehicleTypeId": 9,
"vehicleTypeName": "Vito",
"pickUpLocation": "Levent Ofis, Beşiktaş, İstanbul",
"dropOffLocation": "İstanbul Havalimanı (IST)",
"driverFullName": null,
"driverPhone": null,
"vehiclePlate": null,
"passengerCount": 1,
"flightNo": "TK1981",
"note": null,
"totalNetAmount": 1200,
"supplierFee": 1200,
"currency": "TRY",
"totalVatAmount": 240,
"totalGrossAmount": 1440,
"linkedReservationId": null,
"linkedPnr": null,
"legOrder": null,
"passengers": [
{
"firstName": "Deniz",
"lastName": "Arslan",
"email": "deniz.arslan@example.com",
"isLead": true
}
],
"vehiclePhotos": null,
"extras": null,
"mergeStatus": 0,
"stateVersionUtc": "2026-11-30T15:00:40Z",
"pickUpTimeZoneId": "Europe/Istanbul",
"customerReference": null,
"pickUpLocalDateTime": "2026-12-02T07:40:00",
"pickUpTimeZoneLabel": "Türkiye",
"noMerge": false,
"corporatePlan": {
"planId": "5e4d3c2b-1a09-4f8e-9d7c-6b5a4f3e2d1c",
"publishedVersion": 1,
"groupId": "c0ffee00-4b1d-4a2e-8f3c-5d6e7f8a9b0c",
"pickUpTimeOrigin": "Planned",
"flightScheduledAtUtc": null,
"flightTimeZoneId": null,
"isInternationalFlight": null,
"rowVersion": 1,
"requestedPickUpTime": "2026-12-02T05:00:00Z"
},
"isNoShow": false,
"noShowFee": null,
"customerTotalNet": 1200
}
}
transfer.created — tek istekte rezervasyon (adres çözülemedi)

Tek istekte rezervasyon ile oluşturulan kayıt (YG3Q8R). Varış adresi bir lokasyona çözülemedi; dropOffLocation gönderdiğiniz adres metnidir ve fiyat havalimanı tavanından alındı (quickBooking.pricingSource: "AirportMaximum", fallbackReason: "AddressUnresolved").

{
"eventId": "4b5026d4-4c03-d4fb-3e4a-f3fb68fc8bf0",
"apiVersion": "2026-12",
"occurredAt": "2026-11-26T10:00:40.0000000Z",
"transferId": "6c1d9e2f-4a5b-4c7d-8e9f-0a1b2c3d4e5f",
"pnr": "YG3Q8R",
"eventType": "transfer.created",
"data": {
"transferId": "6c1d9e2f-4a5b-4c7d-8e9f-0a1b2c3d4e5f",
"pnr": "YG3Q8R",
"status": 6,
"statusName": "Sürücü Ataması Bekliyor",
"companyId": 501,
"companyName": "Örnek Turizm",
"pickUpTime": "2026-12-03T13:00:00Z",
"dropOffTime": null,
"vehicleTypeId": 9,
"vehicleTypeName": "Vito",
"pickUpLocation": "İstanbul Havalimanı (IST)",
"dropOffLocation": "Moda Cad. No:24, Kadıköy, İstanbul",
"driverFullName": null,
"driverPhone": null,
"vehiclePlate": null,
"passengerCount": 1,
"flightNo": "TK1856",
"note": null,
"totalNetAmount": 1800,
"supplierFee": 1800,
"currency": "TRY",
"totalVatAmount": 360,
"totalGrossAmount": 2160,
"linkedReservationId": null,
"linkedPnr": null,
"legOrder": null,
"passengers": [
{
"firstName": "Elif",
"lastName": "Demir",
"email": "elif.demir@example.com",
"isLead": true
}
],
"vehiclePhotos": null,
"extras": null,
"mergeStatus": 0,
"stateVersionUtc": "2026-11-26T10:00:40Z",
"pickUpTimeZoneId": "Europe/Istanbul",
"quickBooking": {
"pricingSource": "AirportMaximum",
"fallbackReason": "AddressUnresolved",
"address": "Moda Cad. No:24, Kadıköy, İstanbul",
"addressResolved": false,
"priceScope": "Account",
"requestedAccountCode": "CARI-77"
},
"customerReference": "BZG-20481",
"pickUpLocalDateTime": "2026-12-03T16:00:00",
"pickUpTimeZoneLabel": "Türkiye",
"noMerge": false,
"isNoShow": false,
"noShowFee": null,
"customerTotalNet": 1800
}
}
transfer.updated — tek istekte rezervasyonun adresi lokasyona bağlandı

Operasyon aynı kaydın varış adresini bir lokasyona bağladı: dropOffLocation değişti. quickBooking oluşturma anındaki kararı taşır ve değişmez (addressResolved hâlâ false).

{
"eventId": "2c9fd31d-5180-87d5-ccc9-baeaaa09dd1c",
"apiVersion": "2026-12",
"occurredAt": "2026-11-26T13:20:40.0000000Z",
"transferId": "6c1d9e2f-4a5b-4c7d-8e9f-0a1b2c3d4e5f",
"pnr": "YG3Q8R",
"changedFields": [
"dropOffLocation"
],
"changes": [
{
"field": "dropOffLocation",
"oldValue": "Moda Cad. No:24, Kadıköy, İstanbul",
"newValue": "Moda Caddesi, Kadıköy, İstanbul"
}
],
"eventType": "transfer.updated",
"data": {
"transferId": "6c1d9e2f-4a5b-4c7d-8e9f-0a1b2c3d4e5f",
"pnr": "YG3Q8R",
"status": 6,
"statusName": "Sürücü Ataması Bekliyor",
"companyId": 501,
"companyName": "Örnek Turizm",
"pickUpTime": "2026-12-03T13:00:00Z",
"dropOffTime": null,
"vehicleTypeId": 9,
"vehicleTypeName": "Vito",
"pickUpLocation": "İstanbul Havalimanı (IST)",
"dropOffLocation": "Moda Caddesi, Kadıköy, İstanbul",
"driverFullName": null,
"driverPhone": null,
"vehiclePlate": null,
"passengerCount": 1,
"flightNo": "TK1856",
"note": null,
"totalNetAmount": 1800,
"supplierFee": 1800,
"currency": "TRY",
"totalVatAmount": 360,
"totalGrossAmount": 2160,
"linkedReservationId": null,
"linkedPnr": null,
"legOrder": null,
"passengers": [
{
"firstName": "Elif",
"lastName": "Demir",
"email": "elif.demir@example.com",
"isLead": true
}
],
"vehiclePhotos": null,
"extras": null,
"mergeStatus": 0,
"stateVersionUtc": "2026-11-26T13:20:40Z",
"pickUpTimeZoneId": "Europe/Istanbul",
"quickBooking": {
"pricingSource": "AirportMaximum",
"fallbackReason": "AddressUnresolved",
"address": "Moda Cad. No:24, Kadıköy, İstanbul",
"addressResolved": false,
"priceScope": "Account",
"requestedAccountCode": "CARI-77"
},
"customerReference": "BZG-20481",
"pickUpLocalDateTime": "2026-12-03T16:00:00",
"pickUpTimeZoneLabel": "Türkiye",
"noMerge": false,
"isNoShow": false,
"noShowFee": null,
"customerTotalNet": 1800
}
}
test — OpsPortal Test düğmesi
{
"eventId": "0b6f1c2d-3e4a-4b5c-8d6e-7f8091a2b3c4",
"apiVersion": "2026-12",
"occurredAt": "2026-11-20T09:00:00.0000000Z",
"transferId": "00000000-0000-0000-0000-000000000000",
"pnr": "TEST",
"eventType": "test",
"data": {
"transferId": "00000000-0000-0000-0000-000000000000",
"pnr": "TEST",
"status": 0,
"statusName": "Test",
"companyId": 501,
"companyName": null,
"pickUpTime": "2026-11-20T09:00:00Z",
"dropOffTime": null,
"vehicleTypeId": 0,
"vehicleTypeName": null,
"pickUpLocation": "Test Alış Noktası",
"dropOffLocation": "Test Bırakış Noktası",
"driverFullName": null,
"driverPhone": null,
"vehiclePlate": null,
"passengerCount": 1,
"flightNo": null,
"note": "Bu bir test webhook bildirimidir.",
"totalNetAmount": 0,
"supplierFee": 0,
"currency": "TRY",
"totalVatAmount": 0,
"totalGrossAmount": 0,
"linkedReservationId": null,
"linkedPnr": null,
"legOrder": null,
"passengers": [
{
"firstName": "Test",
"lastName": "Yolcu",
"email": null,
"isLead": true
}
],
"vehiclePhotos": null,
"extras": null,
"mergeStatus": 0,
"stateVersionUtc": null,
"pickUpTimeZoneId": null,
"customerReference": null,
"pickUpLocalDateTime": null,
"pickUpTimeZoneLabel": null,
"noMerge": false,
"isNoShow": false,
"noShowFee": null,
"customerTotalNet": 0
}
}

Teslimat​

KonuDavranış
BaşarıYalnız 2xx yanıt. 2xx yanıtın gövdesi okunmaz; boş bırakabilirsiniz. 2xx dışı yanıtın gövdesinin başı (en çok 1000 karakter) Teslimat Geçmişi'nde hata metni olarak görünür; gövdeye gizli bilgi yazmayın.
4xx yanıtıBaşarısız deneme sayılır ve diğer hatalar gibi yeniden denenir (10 denemeye kadar); webhook'un hata dönemini de başlatır (Otomatik Devre Dışı). Kalıcı olarak reddetmek istediğiniz bir olayı kaydedip 2xx dönün. Hızlı tekrar yalnız 408 ve 429'da yapılır (aşağıda).
Yönlendirmeİzlenmez; 3xx başarısızdır. Son adresi kaydedin.
Zaman aşımıBir deneme, hızlı tekrarlarıyla birlikte toplam 30 saniyeyle sınırlıdır. Bu sürede 2xx alınamazsa deneme başarısız sayılır.
Deneme sayısıBir teslimat için en çok 10 deneme.
Denemeler arasıBaşarısız denemelerden sonra sırasıyla en az 1, 5, 15, 30, 60, 180, 360, 720, 1440 dakika beklenir. İlk denemeden onuncuya en az 2811 dakika (1 gün 22 saat 51 dakika, yaklaşık 1 gün 23 saat).
Denemeler tükeninceOnuncu deneme de başarısız olursa teslimat kalıcı olarak başarısız kalır ve kendiliğinden yeniden gönderilmez. Yalnız elle yeniden gönderilebilir; kaçan değişikliği mutabakat ile alın.
Hızlı tekrarBir deneme içinde 5xx, 408, 429 ve bağlantı hatalarında istek 2 ve 4 saniye arayla en çok iki kez daha gönderilir (aynı teslimat kimliği ve imza). Bu tekrarlar deneme sayısına eklenmez.
GecikmeOlaylar değişiklikten yaklaşık bir dakika içinde üretilir ve aynı çalışmada gönderilir (teslimat işleyicisi dakikada bir çalışır).
YoğunlukBir çalışmada webhook başına en çok 10 teslimat gönderilir. Toplu işlemlerden (ör. çok rezervasyonlu bir plan yayımı) sonra olayların tamamının gelmesi birkaç dakika sürebilir.
Kaynak adresSabit bir çıkış IP adresi ya da aralığı taahhüt edilmez; adres önceden duyurulmadan değişebilir. IP izin listesine dayanmayın; isteğin YolcuGo'dan geldiğini imzayla doğrulayın.
TLSSertifika doğrulanır: adresiniz, genel güvenilen bir sertifika otoritesinin verdiği geçerli bir sertifika sunmalıdır. Kendinden imzalı ya da süresi geçmiş sertifikada deneme başarısız olur.

En Az Bir Kez​

Aynı olay birden çok kez gelebilir: yanıtınız zaman aşımına uğradıysa, bağlantı koptuysa, hızlı tekrar devreye girdiyse ya da operasyon elle yeniden gönderdiyse. Yeniden denemede gövde bayt bayt aynıdır; eventId ve X-Webhook-Delivery-Id aynıdır. Elle yeniden gönderimde gövde ve eventId aynı, teslimat kimliği yenidir. Aynı firmanın iki webhook'u varsa aynı olay her birine aynı eventId ile ayrı teslimat olarak gider. Tekilleştirmeyi eventId ile yapın.

Gördüğünüz eventId'leri en az 90 gün saklayın: sonuçlanmış bir teslimat günler sonra elle yeniden gönderilebilir ve aynı eventId ile gelir; teslimat kayıtları 90 gün saklanır.

Sıra Garanti Edilmez​

Bir webhook'un teslimatları sırayla gönderilir, ama başarısız bir teslimat yeniden denemeye kalırken sonraki olaylar gönderilir; bu yüzden olaylar sizde farklı sırayla birikebilir.

data.stateVersionUtc, olayın taşıdığı data'nın sürümüdür. YolcuGo rezervasyonun size yayımlanan her yeni hâline yeni bir değer verir; değer rezervasyon başına kesin artar. Değişiklik rezervasyonun hangi bölümünde olursa olsun (yolcu, fiyat satırı, ödeme, sürücü kartı, ek hizmet) yeni hâl yeni bir değer alır.

  • Rezervasyon için sakladığınız stateVersionUtc ile gelen yükünkünü karşılaştırın.
  • Gelen değer daha büyükse yükü uygulayın ve yeni değeri saklayın.
  • Daha küçükse yük eskidir; uygulamayın (olayı yine 2xx ile kabul edin).
  • Eşitse aynı hâldir: aynı geçişin olayları (ör. transfer.status_changed ile transfer.updated), yeniden denemeler ve elle yeniden gönderimler aynı değeri ve aynı data'yı taşır. Uygulamak da atlamak da aynı sonucu verir.
  • Değerleri metin olarak değil zaman damgası olarak karşılaştırın: kesir basamak sayısı değişebilir (2026-11-20T09:30:40Z, 2026-11-20T09:30:40.123456Z). Değer mikrosaniye hassasiyetindedir.
  • Emin değilseniz rezervasyonu API'den okuyun (Mutabakat).

Kuyruğa giren gövde sonradan yenilenmez: geç teslim edilen bir olay, üretildiği andaki data'yı taşır.

Yönetim​

Test Bildirimi​

OpsPortal'daki Test, yalnız seçilen webhook'a eventType: "test" gönderir. Olay filtresini atlar ve kapalı webhook'a da gider ("test et, sonra etkinleştir"). Gövde gerçek olaylarla aynı ortak gövdedir: transferId sıfır GUID, pnr: "TEST", data.status: 0. Gerçek rezervasyon gibi işlemeyin. Aynı webhook'ta ilk gönderimini bekleyen ya da gönderimi süren bir test varken ya da son testin üzerinden 60 saniye geçmeden yeni test kuyruğa alınmaz (yeniden denemesi süren başarısız bir test yeni testi engellemez). Başarısız test teslimatı gerçek olaylar gibi yeniden denenir (aynı takvim, 10 deneme). Test teslimatlarının sonucu webhook sağlığını (aşağıda) etkilemez.

Teslimat Geçmişi ve Yeniden Gönderim​

Teslimat Geçmişi son 30 günün teslimatlarını, deneme sayısını, yanıt kodunu ve hata metnini gösterir. Yalnız sonuçlanmış bir teslimat Yeniden gönder ile kuyruğa yeniden alınabilir: başarılı, iptal edilmiş ya da 10 denemesinin tamamı başarısız olmuş teslimat. Yeniden denemesi süren başarısız teslimat yeniden gönderilemez; zaten kendiliğinden denenecektir. Yeniden gönderimde aynı gövde ve aynı eventId yeni bir teslimat kimliğiyle gönderilir. Yeniden gönderim yalnız aktif webhook'ta yapılır; aynı teslimatın sonuçlanmamış (gönderilmeyi bekleyen, gönderimi süren ya da yeniden denenecek) bir kopyası varken ya da son yeniden gönderimin üzerinden 60 saniye geçmeden yenisi kuyruğa alınmaz. Aynı anda iki kez basılırsa tek kopya oluşur. Sonuçlanmış teslimat kayıtları 90 gün saklanır.

Otomatik Devre Dışı​

  • Bir teslimat denemesi başarısız olunca webhook'un hata dönemi başlar (zaten başlamadıysa); herhangi bir başarılı teslimat dönemi sıfırlar.
  • Hata dönemi en az 3 gündür sürerken bir teslimat 10 denemesinin tamamını başarısız tüketirse webhook otomatik olarak kapatılır (gerekçe: AutoDisabledAfterFailures).
  • Yeniden denemesi kalmış tek bir başarısızlık webhook'u hiçbir zaman kapatmaz.

Kapatma, Açma ve Silme​

  • Webhook kapatıldığında (elle ya da otomatik) teslim edilmemiş gerçek olaylar iptal edilir; yeniden açınca eski birikim gönderilmez.
  • Kapatma ya da silme anında gönderimi süren bir teslimat tamamlanır; başarısız olursa yeniden denenmez, o da iptal edilir.
  • Kapalıyken yeni olay biriktirilmez. Kapalıyken size görünür olan rezervasyon için transfer.created sonradan da gelmez.
  • Yeniden açtıktan sonra gelen transfer.updated, kapalıyken yapılan değişiklikleri changes'te listelemez; yalnız kendi kaydındaki değişikliği listeler. data yine tam ve günceldir. Kapalı kaldığınız aralığı changes'e güvenerek kapatamazsınız: gelen her olayda data'yı uygulayın ve olay gelmeyen rezervasyonlar için mutabakat yapın.
  • Elle açmak hata dönemini ve devre dışı bilgisini temizler.
  • Silinen webhook'un teslim edilmemiş bütün teslimatları (test dahil) iptal edilir.
  • Endpoint URL ve secret gönderim anında okunur: değişiklik bekleyen yeniden denemeleri de etkiler.

Kaçırılan Olaylar ve Mutabakat​

Partnere açık bir olay geçmişi ucu yoktur. Değişiklik, onu yapan kayıtla aynı işlemde "bildirilecek" diye işaretlenir; olay bu işaretten üretilir, işaret kaybolmaz. Olay üretimi başarısız olursa rezervasyonun kendisi bundan etkilenmez ve üretim kendiliğinden yeniden denenir: olay rezervasyonun güncel data'sı ve aradaki bütün farklarla gelir (başka bir değişiklik beklenmez). Rezervasyon size o kayıtta ilk kez görünür olacaktıysa bu olay transfer.updated değil transfer.created'dır. Kapalı kalan webhook, uzun süren kesinti ya da şüpheli bir kayıt için güncel durumu REST API'den okuyun (Ortamlar, kimlik doğrulama):

  • Tek rezervasyon: GET /api/booking/{id} (rezervasyon detayı). id, webhook'taki transferId'dir; PNR kabul edilmez. Erişiminiz olmayan kayıt 404 döner.
  • Liste: GET /api/booking/user (listeleme) yıl, ay ve tarih filtresiyle oturum açan kullanıcının rezervasyonlarını döner; firmanızın bütün rezervasyonlarını döndürdüğünü varsaymayın. Yanıt sayfalıdır: page (varsayılan 1) ve pageSize (varsayılan ve en çok 200). page'i artırarak, pageSize'dan az kayıt dönene kadar bütün sayfaları okuyun.
curl 'https://test-api.yolcugo.com/api/booking/TRANSFER_ID' \
--header 'Authorization: Bearer ACCESS_TOKEN'

REST yanıtının biçimi webhook data'sından farklıdır. Sık kullanılan alanların karşılıkları (rezervasyon detayı yanıtının data nesnesinde):

Webhook dataREST rezervasyon detayı
transferIdtransferReservationId
pnr, status, flightNo, noteaynı ad
pickUpTime, pickUpTimeZoneId, pickUpLocalDateTime, pickUpTimeZoneLabelaynı ad
pickUpLocation, dropOffLocationaynı ad (REST ayrıca pickUpLocationAddress, dropOffLocationAddress ve koordinat verir)
vehicleTypeNamevehicleType
driverFullNamedriverFirstName + driverLastName (fark: aşağıdaki not)
driverPhonedriverPhone (fark: aşağıdaki not)
vehiclePlatelicensePlate (fark: aşağıdaki not)
passengerspassengerResponse
extrasextraResponse (fark: webhook yalnız onaylı ek hizmetleri taşır; REST onay bekleyen ve reddedilenleri de döner ve onay durumunu göstermez; onaylı liste için webhook'u esas alın)
customerReferencecustomerReference (yalnız rezervasyon detayında; listede yok)
totalNetAmount, totalVatAmount, totalGrossAmount, currency, customerTotalNetaynı ad
linkedReservationId, linkedPnr, legOrder, noMerge, isNoShowaynı ad

Sürücü ve araç farkı: Günlük planda aynı araca birleştirilmiş bir rezervasyonun kendi sürücü ataması boşsa webhook sürücüyü, telefonu ve plakayı grubun ana rezervasyonundan verir (yolcuyu taşıyan araç budur). REST detayı yalnız rezervasyonun kendi atamasını döner ve bu durumda alanlar boştur. Mutabakatta REST'teki boş sürücü/plaka değeriyle webhook'tan aldığınızı silmeyin.

stateVersionUtc, changes ve olay alanlarının REST karşılığı yoktur. Webhook gelmemesi rezervasyonun oluşmadığını göstermez; telafi için yeni rezervasyon açmayın. Webhook secret'ını Bearer token olarak kullanmayın.

Sorun Giderme​

BelirtiKontrol
Test kuyruğa alındı ama istek gelmediTeslimat Geçmişi'ndeki hata metni; TLS sertifikası, DNS, port (443/8443), güvenlik duvarı.
401 (alıcınız)Aynı ve kırpılmış secret; ham baytlar; V2'de t ile X-Webhook-Timestamp eşleşmesi ve saat senkronu.
İmza başlığı yokWebhook'ta secret tanımlı değil.
3xxYönlendirme izlenmez; son HTTPS adresini kaydedin.
413Proxy ve alıcı gövde sınırları.
Zaman aşımıYanıtı iş işleminden önce, kalıcı kayıttan hemen sonra dönün. Sınır 30 saniyedir.
Olay gelmiyorWebhook aktif mi (otomatik kapanmış olabilir), filtre, rezervasyonun sahibi firma, ödeme bekleyen rezervasyon.
Tanımadığınız rezervasyona olay geldiBeklenen durumdur; kaydı data'dan oluşturun (Bilinmeyen Rezervasyon).
Aynı işlem iki kezeventId ile kalıcı tekilleştirme.
Eski bilgi yeninin üzerine yazıldıstateVersionUtc kontrolü: zaman damgası olarak karşılaştırın, büyükse uygulayın.
transfer.updated geldi ama changes boşBeklenen durumdur; data'yı tam hâl olarak uygulayın (Boş changes).

Destek talebine webhook adı, eventId, teslimat kimliği, zaman ve yanıt kodunu ekleyin; secret, token ve yolcu verisi eklemeyin.

Canlıya Geçiş Kontrol Listesi​

  • Canlı ortamda secret tanımlı; alıcı imzayı ham baytlar üzerinde doğruluyor.
  • Alıcı kalıcı kayıttan sonra 30 saniyeden çok önce 2xx dönüyor.
  • eventId ile kalıcı tekilleştirme var; aynı gövde iki kez gönderilince iş etkisi bir kez. eventId'ler en az 90 gün saklanıyor.
  • data.stateVersionUtc zaman damgası olarak karşılaştırılıyor; daha küçükse yük uygulanmıyor.
  • Boş changes'li transfer.updated hata üretmiyor; data tam hâl olarak uygulanıyor (durum ve sürücü de dahil). Olay filtresi transfer.updated'ı kapsıyor.
  • Kalıcı olarak reddedilen olaylar için de 2xx dönülüyor (4xx yeniden denenir).
  • Bilinmeyen alanlar ve olay adları hata üretmiyor.
  • Tanımadığınız transferId ile gelen her olay kaydı data'dan oluşturuyor (transfer.created beklenmiyor).
  • transfer.updated, changes[].field alanlarını data adlarıyla (camelCase, nokta yolu) işliyor; tarih ve sayıları metin olarak ayrıştırmaya çalışmıyor.
  • Test bildirimi gerçek rezervasyon gibi işlenmiyor.
  • Kapalı kalma ve kesinti sonrası için GET /api/booking/{id} ile mutabakat yolu hazır.
  • Secret değişimi için iki secret'ı geçici kabul eden bir geçiş planınız var.
  • Güvenilir istemci ve canlıya geçiş adımları tamam.