Binrota        Caretta

Binrota API Dokümantasyonu

Sürüm: Aralık 2025 · Entegrasyon (Integration) Servisleri

Bu doküman, Binrota API entegrasyon servislerinin kullanımını, örnek istek/yanıtları ve birlikte gelen Postman koleksiyonunu açıklar. Örneklerde gerçek test verileri kullanılmıştır.


🔑
API Anahtarı (X-API-KEY)
Güvenlik nedeniyle API anahtarı bu dokümanda paylaşılmaz. Binrota tarafından ayrıca sağlanacaktır. Tüm isteklerde header içinde X-API-KEY olarak gönderiniz.
Ortam Bilgileri
CANLIhttps://api2.binrota.com/api/Integration/
Entegrasyonlarınızda canlı (production) ortam adresini kullanınız.
ÖRNEKhttps://mybinrotaapi.caretta.net/api/Integration/
Bu dokümandaki örnek istek/yanıtlar bu ortam üzerinden hazırlanmıştır.

1. Genel Bilgiler

Dokümanda belirtilen API servislerini kullanabilmek için Binrota tarafından sağlanacak olan APIKEY parametresi gereklidir.

Konu Değer
Base URL https://mybinrotaapi.caretta.net/api/Integration/
Kimlik Doğrulama Header içinde X-API-KEY
Content-Type application/json
Content-Encoding UTF-8
Yanıt Formatı JSON

Önemli kurallar:

Ortak Yanıt Yapısı

Tüm servis yanıtlarında işlemin durumunu belirten alanlar yer alır. statusCode değerlerinin karşılıkları için İstek Durum Kodları bölümüne bakınız.

{
  "statusCode": 200,
  "statusDescription": "İşleminiz başarı ile yapıldı"
}

2. Postman Koleksiyonu

Bu doküman ile birlikte Binrota API (Integration).postman_collection.json dosyası gelir. Postman'de Import → File ile doğrudan içe aktarabilirsiniz (şema: Collection v2.1.0).

Yapı

Koleksiyon 6 klasörden oluşur; her klasör bir endpoint'e karşılık gelir ve içinde birden fazla örnek istek bulunur. Kimlik doğrulama koleksiyon seviyesinde X-API-KEY API Key auth olarak tanımlıdır; tüm istekler bunu otomatik miras alır.

Koleksiyon Değişkenleri

Variables sekmesinden düzenlenebilir:

Değişken Örnek Değer Açıklama
baseUrl https://mybinrotaapi.caretta.net/api/Integration Tüm isteklerin kök adresi
apiKey (Binrota tarafından ayrıca sağlanır) X-API-KEY header değeri
tourCode 23-01197 Örnek tur kodu
packageCode1 009297-000221 Örnek paket kodu 1
packageCode2 009298-000221 Örnek paket kodu 2
packageCode3 009302-000221 Örnek paket kodu 3

3. Endpoint'ler

Aşağıdaki tüm isteklerde header olarak X-API-KEY: <APIKEY> gönderilmelidir.


3.1 Integration/CreateOrder

Binrota sisteminde sipariş oluşturur. İstek sonucu dönen yanıtta orderNumber değeri bulunur; bu değer ile Binrota tarafında sipariş sorgulaması yapabilirsiniz.

URL {baseUrl}/CreateOrder
Method POST
Content-Type application/json

Request Parametreleri

Alan Zorunluluk Tip Açıklama
packageCode Zorunlu string Paket turların paket kodu.
note Opsiyonel string Siparişe ait not bilgisi.
agencyOrderNumber Opsiyonel string Acentenin kendi sistemindeki sipariş numarası.
userPaxes Zorunlu array Yolcu listesi. Aşağıdaki alanları içerir.

userPaxes içindeki alanlar:

Alan Zorunluluk Tip Açıklama
countryName Zorunlu string Ülke adı. Örn: "Türkiye"
userPaxType Zorunlu int Pax tipi: Adult=1, Child=2 (2–11,99 yaş), Baby=3 (0–1,99 yaş).
email Zorunlu string E-posta. Maks. 50 karakter.
name Zorunlu string Ad. Maks. 50 karakter.
surname Zorunlu string Soyad. Maks. 30 karakter.
phoneNumber Koşullu string Telefon. Maks. 15 karakter. Yetişkin (Adult) ise zorunludur. Örn: 5555555555
genderId Zorunlu int Cinsiyet: Male=1, Female=2, Other=3.
birthDate Zorunlu string Doğum tarihi. Format: YYYY-MM-DD. Örn: 1993-04-29
tckn Koşullu string T.C. Kimlik No. Yetişkin (Adult) ise zorunludur.
passportNo Opsiyonel string Pasaport numarası.
passportExpireDate Opsiyonel string Pasaport son kullanma tarihi. Format: YYYY-MM-DD. Örn: 2027-04-19

Not: Bir siparişe en fazla 5 pax eklenebilir.

Örnek İstek — Tek Yetişkin

curl -X POST "https://mybinrotaapi.caretta.net/api/Integration/CreateOrder" \
  -H "X-API-KEY: <APIKEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "packageCode": "009297-000221",
    "note": "Tek yetiskin sipariş notu",
    "agencyOrderNumber": "222222",
    "userPaxes": [
      {
        "countryName": "Türkiye",
        "userPaxType": 1,
        "email": "info@caretta.net",
        "name": "Caretta",
        "surname": "Caretta",
        "phoneNumber": "5555555555",
        "genderId": 1,
        "birthDate": "1993-04-29",
        "tckn": "31256952812",
        "passportNo": "TR35-PST2027",
        "passportExpireDate": "2027-04-19"
      }
    ]
  }'

Örnek İstek — Yetişkin + Çocuk + Bebek

{
  "packageCode": "009297-000221",
  "note": "Aile siparişi (yetişkin + çocuk + bebek)",
  "agencyOrderNumber": "222224",
  "userPaxes": [
    {
      "countryName": "Türkiye", "userPaxType": 1,
      "email": "aile@caretta.net", "name": "Mehmet", "surname": "Demir",
      "phoneNumber": "5556667788", "genderId": 1,
      "birthDate": "1988-03-10", "tckn": "31256952812"
    },
    {
      "countryName": "Türkiye", "userPaxType": 2,
      "email": "cocuk@caretta.net", "name": "Elif", "surname": "Demir",
      "genderId": 2, "birthDate": "2019-09-05"
    },
    {
      "countryName": "Türkiye", "userPaxType": 3,
      "email": "bebek@caretta.net", "name": "Can", "surname": "Demir",
      "genderId": 1, "birthDate": "2025-11-01"
    }
  ]
}

Çocuk (userPaxType=2) ve bebek (userPaxType=3) için phoneNumber ve tckn zorunlu değildir.

Örnek Yanıt

{
  "statusCode": 200,
  "statusDescription": "İşleminiz başarı ile yapıldı",
  "orderNumber": 10268
}

3.2 Integration/GetTourPriceAndCapacity

packageCode bilgisine göre ilgili tur ürününün fiyat, otel ve kapasite bilgilerini döner.

URL {baseUrl}/GetTourPriceAndCapacity
Method GET
Content-Type application/json

Query Parametreleri

Parametre Zorunluluk Açıklama
packageCode Zorunlu Paket kodu. Örn: 009297-000221

Örnek İstek

curl "https://mybinrotaapi.caretta.net/api/Integration/GetTourPriceAndCapacity?packageCode=009297-000221" \
  -H "X-API-KEY: <APIKEY>"

Örnek Yanıt

{
  "data": {
    "tourCode": "23-01197",
    "title": "Fas Turu Casablanca & Marakeş",
    "packageCode": "009297-000221",
    "tourCategoryId": 1,
    "tourTransportTypeId": 1,
    "tourProductApprovalStatus": 2,
    "tourApprovalStatus": 2,
    "price": 150,
    "currencyType": "EUR",
    "startDate": "2026-12-01T00:00:00",
    "endDate": "2026-12-06T00:00:00",
    "capacityPerson": 1923,
    "capacityRoom": 1041,
    "definiteDeparture": false,
    "commissionRate": 20.70,
    "tourOperator": "Binrota",
    "departureFlight": "3O438 Istanbul-Kazablanka 00:10-03:25",
    "returnFlight": "3O347 Kazablanka-Istanbul 16:50-23:30",
    "tourTags": [
      { "name": "4* Oteller", "type": 5 },
      { "name": "Akşam Yemekleri Dahil", "type": 3 },
      { "name": "Türkçe Rehberli", "type": 2 }
    ],
    "hotel": {
      "name": "4* Oteller (Merkezi)",
      "code": "000221",
      "capacityRoom": 987
    },
    "campaigns": [
      {
        "name": "Test Yeni Kampanya 2029",
        "discountType": 2,
        "amount": 150,
        "campaignId": "70cea9ed-a1b6-42c2-8155-8db4d4f4867f",
        "tourCampaignId": "7fcafa43-...ff_70cea9ed-...f",
        "campaignEndDate": "2030-12-31T00:00:00"
      }
    ],
    "departurePoints": [
      { "title": "Kalkış Noktası Bir", "sort": 1 },
      { "title": "Kalkış Noktası İki", "sort": 2 }
    ],
    "flights": [
      {
        "type": 1,
        "value": "3O438 Istanbul-Kazablanka 00:10-03:25",
        "flightNumber": "3O438",
        "airlineCompanyName": "Air Arabia",
        "departureCityName": "Istanbul",
        "departureHour": "00:10",
        "arrivalCityName": "Kazablanka",
        "arrivalHour": "03:25"
      },
      {
        "type": 2,
        "value": "3O347 Kazablanka-Istanbul 16:50-23:30",
        "flightNumber": "3O347",
        "airlineCompanyName": "Air Arabia",
        "departureCityName": "Kazablanka",
        "departureHour": "16:50",
        "arrivalCityName": "Istanbul",
        "arrivalHour": "23:30"
      }
    ],
    "prices": [
      { "typeId": 1, "price": 300.00, "currencyType": "EUR" },
      { "typeId": 2, "price": 200.00, "currencyType": "EUR" },
      { "typeId": 3, "price": 180.00, "currencyType": "EUR" },
      { "typeId": 5, "price": 50.00,  "currencyType": "EUR" },
      { "typeId": 6, "price": 50.00,  "currencyType": "EUR" },
      { "typeId": 7, "price": 200.00, "currencyType": "EUR" }
    ]
  },
  "statusCode": 200,
  "statusDescription": "İşleminiz başarıyla tamamlandı.",
  "isSuccess": true
}

Alan Açıklamaları

Alan Açıklama
capacityPerson Tur ürününe ait kalan kontenjan (kişi).
capacityRoom Tur ürününe ait kalan toplam kapasite.
hotel.capacityRoom Otele ait kalan toplam kapasite.
departureFlight / returnFlight Gidiş / dönüş uçuş bilgisi.
flights Pakete bağlı uçuş listesi. type: Gidiş=1, Dönüş=2, Tur içi=3.
prices Tur fiyatları. typeId: Single=1, Double=2, Triple=3, Child=5, Baby=6, DoubleChild=7.
campaigns Tur tarihine denk gelen kampanyalar. discountType 1=Yüzdesel, 2=Miktarsal; amount uygulanacak indirim miktarı.
tourProductApprovalStatus / tourApprovalStatus Onay durumu: AwaitingApproval=1, Approved=2, Rejected=3.

3.3 Integration/GetAllTourPriceAndCapacity

Satış başlangıç tarihi bugünden büyük olan tüm tur ürünlerinin fiyat/otel/kapasite bilgilerini listeler.

URL {baseUrl}/GetAllTourPriceAndCapacity
Method GET
Content-Type application/json

Query Parametreleri (Opsiyonel)

Parametre Açıklama
tourCode Tur kodu bazında filtreleme. Örn: 23-01197
pageSize Tek seferde istenen kayıt sayısı. Örn: 100
pageNumber Sayfa numarası. Örn: 1

Query parametreleri gönderilmezse tüm kayıtlar döner. Yanıtta sayfalama için totalRecordCount alanı bulunur.

Örnek İstekler

# Tüm kayıtlar
curl "https://mybinrotaapi.caretta.net/api/Integration/GetAllTourPriceAndCapacity" \
  -H "X-API-KEY: <APIKEY>"

# Filtreli + sayfalı
curl "https://mybinrotaapi.caretta.net/api/Integration/GetAllTourPriceAndCapacity?tourCode=23-01197&pageSize=100&pageNumber=1" \
  -H "X-API-KEY: <APIKEY>"

Örnek Yanıt (kısaltılmış)

{
  "totalRecordCount": 100,
  "data": [
    {
      "title": "Fas Turu Casablanca & Marakeş",
      "packageCode": "009297-000221",
      "tourCode": "23-01197",
      "tourProductApprovalStatus": 2,
      "tourApprovalStatus": 2,
      "price": 150,
      "currencyType": "EUR",
      "commissionRate": 20.70,
      "startDate": "2026-12-01T00:00:00",
      "endDate": "2026-12-06T00:00:00",
      "capacityPerson": 1923,
      "capacityRoom": 1041,
      "definiteDeparture": false,
      "tourCategoryId": 1,
      "tourTransportTypeId": 1,
      "hotel": { "name": "4* Oteller (Merkezi)", "code": "000221", "capacityRoom": 987 },
      "prices": [
        { "typeId": 1, "price": 300.00, "currencyType": "EUR" },
        { "typeId": 2, "price": 200.00, "currencyType": "EUR" }
      ],
      "campaigns": [],
      "flights": []
    }
  ],
  "statusCode": 200,
  "statusDescription": "İşleminiz başarıyla tamamlandı."
}

Alan açıklamaları 3.2 ile aynıdır. Ek olarak totalRecordCount toplam kayıt sayısını verir.


3.4 Integration/GetAllB2BToursDetails

Satış başlangıç tarihi bugünden büyük olan turları listeler.

URL {baseUrl}/GetAllB2BToursDetails
Method POST
Content-Type application/json

Query Parametreleri (Opsiyonel)

Parametre Açıklama
pageSize Tek seferde istenen kayıt sayısı. Örn: 100
pageNumber Sayfa numarası. Örn: 1

Query parametreleri gönderilmezse tüm kayıtlar döner. Yanıtta totalRecordCount alanı bulunur.

Örnek İstek

curl -X POST "https://mybinrotaapi.caretta.net/api/Integration/GetAllB2BToursDetails?pageSize=100&pageNumber=1" \
  -H "X-API-KEY: <APIKEY>" \
  -H "Content-Type: application/json"

Örnek Yanıt (tek kayıt, kısaltılmış)

{
  "totalRecordCount": 150,
  "data": [
    {
      "tourId": "7fcafa43-d045-4c92-844d-2f8f071817ff",
      "tourName": "Fas Turu Casablanca & Marakeş",
      "tourOperator": "Binrota",
      "tourCode": "23-01197",
      "tourProductCode": "008853",
      "tourCategoryId": 1,
      "tourTransportTypeId": 1,
      "hotelCode": "000221",
      "hotelName": "4* Oteller (Merkezi)",
      "startDate": "2027-12-01T00:00:00",
      "packageCode": "008853-000221",
      "tourApprovalStatus": 2,
      "commissionRate": 20.70,
      "tourTags": [
        { "name": "4* Oteller", "type": 5 },
        { "name": "Akşam Yemekleri Dahil", "type": 3 },
        { "name": "Türkçe Rehberli", "type": 2 }
      ],
      "departurePoints": [
        { "title": "Kalkış Noktası Bir", "sort": 1 },
        { "title": "Kalkış Noktası İki", "sort": 2 }
      ]
    }
  ],
  "statusCode": 200,
  "statusDescription": "İşleminiz başarıyla tamamlandı."
}

3.5 Integration/GetB2BTourDetailsWithTourCode

Tur koduna göre, satış başlangıç tarihi bugünden büyük olan turları (ilgili tüm paket varyantları ile) döner.

URL {baseUrl}/GetB2BTourDetailsWithTourCode
Method POST
Content-Type application/json

Request Parametreleri

Parametre Zorunluluk Açıklama
tourCode Zorunlu Tur kodu. Query parametresi olarak gönderilir. Örn: 23-01197

Örnek İstek

curl -X POST "https://mybinrotaapi.caretta.net/api/Integration/GetB2BTourDetailsWithTourCode?tourCode=23-01197" \
  -H "X-API-KEY: <APIKEY>" \
  -H "Content-Type: application/json"

Örnek Yanıt (tek kayıt, kısaltılmış)

Bu servis ilgili tur koduna ait tüm paket varyantlarını döndürür (data dizisi çok sayıda kayıt içerebilir).

{
  "data": [
    {
      "tourId": "7fcafa43-d045-4c92-844d-2f8f071817ff",
      "tourName": "Fas Turu Casablanca & Marakeş",
      "tourOperator": "Binrota",
      "tourCode": "23-01197",
      "tourProductCode": "008853",
      "tourCategoryId": 1,
      "tourTransportTypeId": 1,
      "hotelCode": "000221",
      "hotelName": "4* Oteller (Merkezi)",
      "startDate": "2027-12-01T00:00:00",
      "packageCode": "008853-000221",
      "tourApprovalStatus": 2,
      "commissionRate": 20.70,
      "tourTags": [
        { "name": "4* Oteller", "type": 5 },
        { "name": "Akşam Yemekleri Dahil", "type": 3 }
      ],
      "departurePoints": [
        { "title": "Kalkış Noktası Bir", "sort": 1 },
        { "title": "Kalkış Noktası İki", "sort": 2 }
      ]
    }
  ],
  "statusCode": 200,
  "statusDescription": "İşleminiz başarıyla tamamlandı."
}

3.6 Integration/GetTourDetail

Tur koduna göre ilgili turun detay bilgilerini (program, dahil/hariç hizmetler, oteller) döner.

URL {baseUrl}/GetTourDetail
Method GET
Content-Type application/json

Query Parametreleri

Parametre Zorunluluk Açıklama
code Zorunlu Turun kod bilgisi. Query parametresi olarak gönderilmelidir. Örn: 23-01197

Örnek İstek

curl "https://mybinrotaapi.caretta.net/api/Integration/GetTourDetail?code=23-01197" \
  -H "X-API-KEY: <APIKEY>"

Örnek Yanıt (kısaltılmış)

{
  "data": {
    "title": "Fas Turu Casablanca & Marakeş",
    "code": "23-01197",
    "tourCategoryId": 1,
    "tourTransportTypeId": 1,
    "tourApprovalStatus": 2,
    "tourOperator": "Binrota",
    "commissionRate": 20.70,
    "generalInfo": "<h4></h4><p><strong>Akşam Yemekleri Dahil</strong></p> ... (HTML içerik)",
    "tourTags": [
      { "name": "Türkçe Rehberli", "type": 2 },
      { "name": "Akşam Yemekleri Dahil", "type": 3 },
      { "name": "4* Oteller", "type": 5 }
    ],
    "departurePoints": [
      { "title": "Kalkış Noktası Bir", "sort": 1 },
      { "title": "Kalkış Noktası İki", "sort": 2 }
    ],
    "programs": [
      {
        "sort": 1,
        "title": "İstanbul (Saw) - Casablanca - Marakeş",
        "description": "İstanbul Sabiha Gökçen Havalimanı ... (program açıklaması)"
      }
    ],
    "includedServices": [
      { "sort": 1, "text": "Air Arabia ile İstanbul (SAW) – Casablanca – İstanbul (SAW)" },
      { "sort": 3, "text": "4* Otellerde konaklama (kahvaltı ve akşam yemekleri dahil)" },
      { "sort": 4, "text": "Türkçe Rehberlik Hizmeti" }
    ],
    "excludedServices": [
      { "sort": 1, "text": "Yurtdışı Çıkış Harç Pulu" },
      { "sort": 2, "text": "Programda Belirtilen Tüm Ekstra Turlar" },
      { "sort": 3, "text": "Öğle Yemekleri" }
    ],
    "hotels": [
      { "title": "4* Oteller (Merkezi)", "code": null, "city": null },
      { "title": "3* Oteller Vb.", "code": null, "city": null }
    ]
  },
  "statusCode": 200,
  "statusDescription": "İşleminiz başarıyla tamamlandı.",
  "isSuccess": true
}

Alan Açıklamaları

Alan Açıklama
generalInfo Tur ile ilgili genel bilgiler (HTML içerebilir).
programs Turun günlük program bilgilerini içeren liste.
includedServices Fiyata dahil hizmetler.
excludedServices Fiyata dahil olmayan hizmetler.
hotels Tur üzerinde tanımlı otel bilgileri.
tourApprovalStatus Onay durumu: AwaitingApproval=1, Approved=2, Rejected=3.

4. Tipler ve Açıklamalar

Tip Değerler
UserPaxType Adult = 1, Child = 2, Baby = 3
GenderId Male = 1, Female = 2, Other = 3
Flights.Type Gidiş = 1, Dönüş = 2, Tur içi = 3
Prices.Type Single = 1 (tek yetişkin pp), Double = 2 (iki yetişkin pp), Triple = 3 (üç yetişkin pp), Child = 5 (çocuk pp), Baby = 6 (bebek pp), DoubleChild = 7 (iki çocuk pp)
TourApprovalStatus / TourProductApprovalStatus AwaitingApproval = 1, Approved = 2, Rejected = 3
Campaign DiscountType Yüzdesel = 1, Miktarsal = 2
TourCategoryId Yurt Dışı = 1, Yurt İçi = 2, Cruise = 5
TourTransportTypeId Uçak = 1, Otobüs = 2, Gemi = 3, Tren = 4, Tekne = 5, Uçaksız Paket = 6
TourTags.Type Konsept = 2, Yiyecek = 3, Kesin Kalkış = 4, Konaklama = 5, Son Yerler = 6, Süper Promosyon = 7, Tren = 8, Tüm Turlar Dahil = 9

5. İstek Durum Kodları

Kod Açıklama
200 İşleminiz başarı ile yapıldı.
500 İşleminiz yapılırken hata oluştu. Sunucu taraflı hata oluşmuş olabilir.
1000 Paket kodu formatı geçersiz.
1001 Lütfen yolcu bilgisi giriniz.
1002 Ülke adı boş bırakılamaz.
1003 Ad boş bırakılamaz.
1004 Soyad boş bırakılamaz.
1005 Lütfen geçerli bir doğum tarihi giriniz.
1006 Email adresi boş bırakılamaz.
1007 Lütfen geçerli bir telefon numarası giriniz.
1008 Lütfen geçerli bir T.C. Kimlik numarası giriniz.
1020 Otel bulunamadı.
1021 Tur ürünü bulunamadı.
1022 Tur ürününe ait otel bulunamadı.
1023 Bu tura şu an rezervasyon yapılamamaktadır.
1024 Seçilen otelin kontenjanı dolmuştur. Lütfen başka bir oteli deneyiniz.
1025 Tur ürününün kapasitesi kalmamıştır.
1026 Maksimum pax sayısını aştınız. 5'ten fazla pax ekleyemezsiniz.
1027 Tur ürünü kullanılabilir değil.
1028 Lütfen pax tipini ve doğum tarihini kontrol ediniz.
1029 Tur bulunamadı.
1030 Pax tipine uygun fiyat bulunamadı.

6. Notlar


7. Ek: Test Değerleri

Aşağıdaki değerler test ortamı için kullanılabilir:

Alan Değer
APIKEY Binrota tarafından ayrıca sağlanır (dokümanda paylaşılmaz)
tourCode 23-01197
packageCode 009298-000108, 009298-000221, 009302-000221

Uyarı: APIKEY gizli bir bilgidir; herkese açık kaynak kodu depolarında veya paylaşılan ortamlarda saklanmamalıdır.


Bu doküman, Binrota API Dokümantasyonu (Aralık 2025) ve birlikte gelen Postman koleksiyonu temel alınarak hazırlanmıştır.