Booking API

Bu yöntem, Search API'den dönen oda BookingCode değeriyle yeni bir otel rezervasyonu oluşturur.

📍 Endpoint

POST {BaseURL}/api/booking/book

Özellik	Değer
URI	`{BaseURL}/api/booking/book`
Method	POST
Content-Type	application/json

Yetkilendirme

Authentication sayfasında açıklanan Basic Auth header'ını gönderin.

📋 Request Parametreleri

Önemli: RoomBookingCodes, Search API'den dönen 1–32 benzersiz GUID içermelidir. Aynı arama bağlamı ve otele ait kodları kullanın; süresi dolmuş BookingCode değerlerini tekrar kullanmayın. MescoGo seçilen odaların birlikte rezerve edilebilirliğini doğrular. Geniş entegrasyon uyumluluğu için tek bir RoomBookingCodes değeri göndermek önerilir.

Parametre	Tip	Açıklama
`RoomBookingCodes`	GUID List	Search API'den dönen 1–32 benzersiz oda booking kodu. Kodlar aynı arama bağlamına ve otele ait olmalıdır.
`CustomerDetails`	Object List	Müşteri bilgileri. Yetişkin/çocuk dağılımı ve çocuk yaşları ilgili Search isteğindeki konaklama bilgileriyle eşleşmelidir.
`ClientReferenceId`	String	API istemcisi tarafından gönderilen referans numarası. İstek/yanıt eşleşmesi için önerilir.
`BookingReferenceId`	String	API istemcisi sistemindeki rezervasyon, PNR, sipariş veya referans numarası. İsteğe bağlıdır.
`TotalFare`	Decimal	Seçilen odaların toplam fiyatı. Search yanıtındaki toplamla eşleşmelidir.
`EmailId`	String	Müşteri listesindeki ilk kişinin email adresi
`PhoneNumber`	String	Zorunlu. Geçerli bir telefon numarası, max 20 karakter.
`BookingType`	String	Sabit booking modu. `Voucher` gönderin. Desteklenen tek değerdir ve onaylı rezervasyon/voucher akışını ifade eder.
`PaymentMode`	String	Limit veya NewCard. Varsayılan: Limit
`PaymentInfo`	Object	Müşteri ödeme bilgileri (PaymentMode NewCard ise zorunlu)
`BillingAmount`	Decimal	Faturalandırılacak toplam tutar. `TotalFare` ile eşleşmelidir.
`BillingCurrency`	String	Zorunlu. USD gönderin; Search yanıtındaki para birimiyle eşleşmelidir.
`CardHolderAddress`	Object	Müşteri kart adresi (PaymentMode NewCard ise zorunlu)

Referans Numaraları Hakkında Not

ClientReferenceId ve BookingReferenceId API istemcisi tarafından gönderilen opsiyonel referans değerleridir.

ClientReferenceId: İstek/yanıt eşleşmesi için önerilen API istemcisi sistem değeridir. Gönderilirse başarılı yanıtta aynı değer döndürülür.
BookingReferenceId: Çağıran sistemdeki rezervasyon, sipariş, PNR, booking veya referans numarasıdır. Ayrı bir referans yoksa boş bırakılabilir.

Bu alanlar korelasyon değerleridir; idempotency veya kalıcılık garantisi sağlamaz.

Bu Alanlar Nasıl Doldurulmalı?

ClientReferenceId, booking isteğini kendi sisteminizde takip etmek için kullanılan değerdir.
Önerilen kaynaklar: request numaranız, sepet/sipariş numaranız, CRM korelasyon ID'niz veya booking deneme ID'niz.
Örnek değer: CLIENT-EXAMPLE-001.
BookingReferenceId, MescoGo çağrısından önce kendi sisteminizde oluşmuş bir rezervasyon, order, PNR veya booking referansı varsa kullanılabilir.
Nihai rezervasyon numaranızı yalnızca onaydan sonra üretiyorsanız boş string gönderin.
Bu değerler request içinde gönderilir; önceden MescoGo endpoint'inden alınmaz.

BookingType

BookingType bu API için sabittir. Voucher gönderin; farklı bir değer göndermeyin.

PaymentMode Değerleri

Değer	Açıklama
`Limit`	Eksiksiz kart bilgisi gönderilmediğinde API hesabınıza tanımlı hesap ödeme düzenini kullanır.
`NewCard`	`PaymentInfo` içindeki kart bilgileriyle ödeme yapar.

Ödeme Notları

Hesap üzerinden ödeme için PaymentMode = "Limit" gönderin; PaymentInfo ve CardHolderAddress göndermeyin.
Kart ile ödeme yapmak için PaymentMode = "NewCard" gönderin ve eksiksiz PaymentInfo ile CardHolderAddress bilgilerini ekleyin.
Eksiksiz kart bilgisi gönderildiğinde, istek kart ödemesi olarak işlenir.
Kısmi kart bilgisi göndermeyin. BillingAmount ve TotalFare aynı toplam tutarı göstermelidir.

Kart verisi güvenliği

PaymentInfo hassas kart verisi içerir. Yalnızca HTTPS üzerinden gönderin; kart numarasını veya CVV'yi tam olarak loglamayın ya da saklamayın, kart verisini URL'ye koymayın ve ödeme entegrasyonunuz için geçerli güvenlik ve PCI DSS gereksinimlerine uyun. Gerçek kart verisini dokümana, testlere veya destek kayıtlarına eklemeyin.

CustomerDetails Yapısı

Parametre	Tip	Açıklama
`Title`	String	Müşteri unvanı
`FirstName`	String	Müşteri adı
`LastName`	String	Müşteri soyadı
`BirthDate`	String	Müşteri doğum tarihi. Mümkünse `YYYY-MM-DD` kullanın.
`Type`	String	Müşteri tipi. Yetişkin misafirler için `Adult`, çocuk misafirler için `Child`

PaymentInfo Yapısı

Parametre	Tip	Açıklama
`CvvNumber`	String	Müşteri kart CVV numarası
`CardNumber`	String	Müşteri kart numarası
`CardExpirationMonth`	String	Kart son kullanma ayı
`CardExpirationYear`	String	Kart son kullanma yılı
`CardHolderFirstName`	String	Kart sahibi adı
`CardHolderLastName`	String	Kart sahibi soyadı

CardHolderAddress Yapısı

Parametre	Tip	Açıklama
`AddressLine1`	String	Adres 1
`AddressLine2`	String	Adres 2
`City`	String	Müşteri şehri
`PostalCode`	String	Müşteri posta kodu
`CountryCode`	String	Müşteri ülke kodu

📤 Örnek Request'ler

Örnek veri notu: Aşağıdaki istek örneklerindeki tanımlayıcılar, misafir bilgileri, tarihler, iletişim değerleri ve tutarlar sentetik ve açıklama amaçlıdır. Canlı rezervasyon veya müşteri verisi olarak kopyalamayın.

Örnek Request — Hesap Üzerinden Ödeme

{
  "RoomBookingCodes": ["00000000-0000-4000-8000-000000000003"],
  "CustomerDetails": [
    {
      "Title": "Mr",
      "FirstName": "Sample",
      "LastName": "Guest",
      "BirthDate": "1990-01-01",
      "Type": "Adult"
    }
  ],
  "ClientReferenceId": "CLIENT-EXAMPLE-001",
  "BookingReferenceId": "00000000-0000-4000-8000-000000000004",
  "TotalFare": 100.0,
  "EmailId": "guest@example.com",
  "PhoneNumber": "+10000000000",
  "BookingType": "Voucher",
  "PaymentMode": "Limit",
  "BillingAmount": 100.0,
  "BillingCurrency": "USD"
}

Örnek Request — Kart Ödemesi

{
  "RoomBookingCodes": ["00000000-0000-4000-8000-000000000003"],
  "CustomerDetails": [
    {
      "Title": "Mr",
      "FirstName": "Sample",
      "LastName": "Guest",
      "BirthDate": "1990-01-01",
      "Type": "Adult"
    }
  ],
  "ClientReferenceId": "CLIENT-EXAMPLE-001",
  "BookingReferenceId": "00000000-0000-4000-8000-000000000004",
  "TotalFare": 100.0,
  "EmailId": "guest@example.com",
  "PhoneNumber": "+10000000000",
  "BookingType": "Voucher",
  "PaymentMode": "NewCard",
  "BillingAmount": 100.0,
  "BillingCurrency": "USD",
  "PaymentInfo": {
    "CvvNumber": "<cvv>",
    "CardNumber": "<kart-numarasi>",
    "CardExpirationMonth": "<son-kullanma-ayi>",
    "CardExpirationYear": "<son-kullanma-yili>",
    "CardHolderFirstName": "Sample",
    "CardHolderLastName": "Guest"
  },
  "CardHolderAddress": {
    "AddressLine1": "100 Example Avenue",
    "AddressLine2": "Example Suite",
    "City": "Sample City",
    "PostalCode": "00000",
    "CountryCode": "US"
  }
}

✅ Başarılı Response

Örnek veri notu: Bu yanıttaki tanımlayıcılar sentetik ve açıklama amaçlıdır. Canlı rezervasyon verisi olarak kopyalamayın.

{
  "Status": {
    "Code": 200,
    "Description": "Successful"
  },
  "ClientReferenceId": "CLIENT-EXAMPLE-001",
  "ConfirmationNumber": "00000000-0000-4000-8000-000000000001"
}

❌ Hata durumları

İş doğrulama hataları Status objesi döner.

Ödeme Bilgisi Bulunamadı

{
  "Status": {
    "Code": 404,
    "Description": "Payment Information Not Found"
  }
}

Hesap ödeme limiti kullanılamıyor

{
  "Status": {
    "Code": 404,
    "Description": "<description>"
  }
}

İşleme hatası

{
  "StatusCode": 500,
  "Reason": "<sebep>",
  "Error": "<hata-mesaji>",
  "ErrorDetails": "<opsiyonel-detaylar>"
}

Doğrulama ve iş kuralları hataları HTTP 200 ile birlikte gövde içinde Status.Code olarak 404, 409 veya 500 dönebilir. Başarılı rezervasyon için hem Status.Code = 200 hem de boş olmayan ConfirmationNumber kontrol edilmelidir.

Her başarısız yanıt gövdesini HTTP durumundan bağımsız olarak inceleyin. Bu alanlar döndürülüyorsa şu şekilde işleyin:

Alan	Anlamı
`RequiresNewSearch`	Seçilen search sonucu tekrar kullanılmamalıdır; yeni booking denemesinden önce yeni arama yapın.
`RequiresReconciliation`	Yeniden denemeden önce rezervasyon sonucu kontrol edilmelidir.
`RetryAllowed`	Yanıta göre aynı işlemin yeniden denenip denenemeyeceğini belirtir.

RequiresReconciliation true veya RetryAllowed false ise aynı isteği otomatik olarak tekrar göndermeyin. HTTP durumundan bağımsız bir conflict yanıtı şu şekilde olabilir:

{
  "StatusCode": 409,
  "Reason": "<sebep>",
  "Error": "<hata-mesaji>",
  "RequiresNewSearch": true,
  "RequiresReconciliation": false,
  "RetryAllowed": false
}

📍 Endpoint​

Yetkilendirme​

📋 Request Parametreleri​

Referans Numaraları Hakkında Not​

Bu Alanlar Nasıl Doldurulmalı?​

BookingType​

PaymentMode Değerleri​

Ödeme Notları​

Kart verisi güvenliği​

CustomerDetails Yapısı​

PaymentInfo Yapısı​

CardHolderAddress Yapısı​

📤 Örnek Request'ler​

Örnek Request — Hesap Üzerinden Ödeme​

Örnek Request — Kart Ödemesi​

✅ Başarılı Response​

❌ Hata durumları​

Ödeme Bilgisi Bulunamadı​

Hesap ödeme limiti kullanılamıyor​

İşleme hatası​