Müsaitlik

Katalog uçları villaların ne zaman dolu olduğunu birkaç biçimde verir:

İhtiyaç	Uç
Bir villanın önümüzdeki aylardaki dolu geceleri	GET /villas/{slug} yanıtındaki calendar (Villa takvimi)
Belirli tarihlerde hangi villalar uygun, toplam ne tutar	GET /villas?check_in=…&check_out=… (Tarihli liste)
Bir ayda villanın kaç boş haftası var	GET /villas?month=YYYY-MM (Ay modu)
Önümüzdeki aylarda kaç villa boş	GET /availability/months (Aylara göre boş villa)

Bunların hepsi okuma anının görüntüsüdür. Rezervasyon talebinden önceki kesin kontrol teklifte ve talepte yapılır: Müsaitlik kesin değildir.

Örneklerdeki ortam değişkenleri ve api() yardımcısı Katalog sayfasında.

Villa takvimi

Villa detayı takvimi bugünden calendar_months ay ileriye kadar verir (1–24, varsayılan 18).

12 aylık takvim

curl -s -u "$TRIMANGO_CLIENT_ID:$TRIMANGO_CLIENT_SECRET" \
  "$TRIMANGO_BASE_URL/villas/ABC-1042?calendar_months=12"

GET /villas/ABC-1042 → 200 (yalnız ilgili alanlar)

{
  "id": "01990c1e-7a3b-7c2d-9e4f-5a6b7c8d9e0f",
  "code": "ABC-1042",
  "status": "FOR_SALE",
  "closed_until": null,
  "calendar": {
    "from": "2026-10-27",
    "to": "2027-10-27",
    "busy": [
      { "start": "2027-06-12", "end": "2027-06-19" },
      { "start": "2027-07-03", "end": "2027-07-17" }
    ]
  },
  "stay_rules": [{ "from": "2027-06-01", "to": "2027-09-30", "min_nights": 7, "max_nights": null, "check_in_days": [6] }]
  // …
}

• busy[] dolu gece aralıklarıdır: start dahil, end hariç. end çıkış günüdür; o gün yeni bir misafir giriş yapabilir. Yukarıdaki örnekte 12 Haziran gecesinden 18 Haziran gecesine kadar dolu, 19 Haziran’da giriş yapılabilir.
• Dolu geceler rezervasyonları (opsiyondakiler dahil, bkz. Opsiyon takvimi kilitler), ev sahibinin kendi kullanımını, bakım kapatmalarını ve başka kanallardan gelen satışları kapsar. Nedeni yanıtta yoktur.
• Takvim yalnız doluluğu söyler. Bir konaklamanın satılabilmesi için ayrıca villa o tarihte satışa açık olmalı (Satışa kapalı villa), konaklama kurallarına (stay_rules: en az ve en çok gece, giriş günleri) uymalı ve her gecenin sezon fiyatı girilmiş olmalı.

Node: takvimde boş mu?

// checkIn, checkOut: 'YYYY-MM-DD'. Aralıklar [start, end) olduğundan dize karşılaştırması yeterli.
export function isFree(calendar, checkIn, checkOut) {
  if (checkIn < calendar.from || checkOut > calendar.to) return null // takvim bu dönemi kapsamıyor
  return calendar.busy.every((b) => checkOut <= b.start || checkIn >= b.end)
}

Takvimi kendi sisteminizde tutuyorsanız availability olayı geldiğinde villanın detayını yeniden okuyun (Değişiklikleri yakalama).

Tarihli liste

Villa listesine check_in ve check_out verirseniz her kartta stay dolar: villa bu tarihlerde uygun mu, değilse neden, uygunsa toplam fiyat.

19–26 Haziran, 4 yetişkin 2 çocuk, Kalkan

curl -s -u "$TRIMANGO_CLIENT_ID:$TRIMANGO_CLIENT_SECRET" \
  "$TRIMANGO_BASE_URL/villas?location=kalkan&check_in=2027-06-19&check_out=2027-06-26&adults=4&children=2&facets=false"

Node

const q = new URLSearchParams({ location: 'kalkan', check_in: '2027-06-19', check_out: '2027-06-26', adults: '4', children: '2', facets: 'false' })
const { data } = await api(`/villas?${q}`)
const available = data.items.filter((v) => v.stay.available)

Parametre	Kural
check_in, check_out	YYYY-MM-DD. İkisi birlikte verilir.
adults, children	Yetişkin (varsayılan 2) ve çocuk. guests verilmezse kapasite süzgeci adults + children ile yapılır.
available_only	true: takvimi dolu ya da giriş günü satışa kapalı villaları listeden çıkarır.

Uygun villa: stay

{
  "available": true,
  "reason": null,
  "nights": 7,
  "total": 2835,
  "list_total": 3150,
  "total_try": 103478,
  "currency": "EUR",
  "deals": ["EARLY_BOOKING"],
  "next_free": null
}

Dolu villa: stay

{
  "available": false,
  "reason": "occupied",
  "nights": 7,
  "total": null,
  "list_total": null,
  "total_try": null,
  "currency": "EUR",
  "deals": [],
  "next_free": { "check_in": "2027-06-26", "check_out": "2027-07-03", "total": 3150, "currency": "EUR" }
}

total fırsatlar düşülmüş toplamdır (kuponsuz, havuz ısıtmasız); list_total indirimsiz toplam. Fiyatın kalemleri ve ön ödeme tutarı için Fiyat ve teklif.

reason uygun olmamanın nedenidir; birden çok neden varsa şu sırayla ilki döner:

reason	Anlamı
closed	Villa giriş gününde satışa kapalı.
occupied	Takvimde bu tarihlerle çakışan dolu gece var. next_free aynı süreyle en yakın boş dönemi verir (en çok 4 hafta ileri ya da geri, haftalık kaydırarak; fiyatı yoksa total null).
min_stay	Gece sayısı konaklama kuralına uymuyor (en az ya da en çok gece).
check_in_day	Giriş günü kurala uymuyor (ör. yalnız cumartesi giriş).
capacity	Kişi sayısı kapasiteyi ve ek kişi hakkını aşıyor.
no_price	Konaklamanın en az bir gecesinin fiyatı girilmemiş.

Liste yanıtında tarihli sorguya özgü iki alan daha var:

• occupied_count: süzgece uyan ama bu tarihlerde takvimi dolu villa sayısı (satışa kapalılar sayılmaz).
• nearby_free[]: dolu villalardan aynı süreyle en yakın boş dönemi olan en çok 4 villa; her satırda tam villa kartı, dönem ve toplam.

Ay modu

month=YYYY-MM verirseniz kartlarda o ayın boş haftaları döner:

Haziran 2027

curl -s -u "$TRIMANGO_CLIENT_ID:$TRIMANGO_CLIENT_SECRET" \
  "$TRIMANGO_BASE_URL/villas?location=kalkan&month=2027-06&facets=false"

Kartta ay modu alanları

{
  "month_free_weeks": 2,
  "month_min_nightly_try": 9800,
  "month_weeks": [
    { "check_in": "2027-06-05", "check_out": "2027-06-12", "free": true },
    { "check_in": "2027-06-12", "check_out": "2027-06-19", "free": false },
    { "check_in": "2027-06-19", "check_out": "2027-06-26", "free": true },
    { "check_in": "2027-06-26", "check_out": "2027-07-03", "free": false }
  ]
}

Alan	Anlamı
month_free_weeks	O ayda villanın kendi giriş gününde başlayan, takvimi boş ve fiyatı girilmiş dönemlerin sayısı. Dönem 7 gecedir; villa o girişte 7’den uzun en az gece istiyorsa o kadar gecedir. Giriş günü villanın konaklama kuralından gelir (cumartesi izinliyse cumartesi, değilse izinli günlerin haftadaki ilki; kural yoksa cumartesi).
month_min_nightly_try	O ayın gecelerine düşen sezonların en düşük gecelik fiyatı, TL.
month_weeks[]	Ayın bugünden sonraki her cumartesisinden başlayan 7 gecelik dönem ve boş olup olmadığı (free: takvim boş, her gece fiyatlı, girişte satışa açık). Villanın giriş günü kuralına bakılmaz; cumartesi girişi kabul etmeyen villada bu dönemler talep için uygun olmayabilir.

Aylara göre boş villa

GET /availability/months önümüzdeki her ay için kaç villanın boş olduğunu verir. Bir ay seçici ya da “ne zaman gitmeli” özeti için uygundur; villa bazında bilgi vermez.

Kalkan, en az 6 kişilik, 12 ay

curl -s -u "$TRIMANGO_CLIENT_ID:$TRIMANGO_CLIENT_SECRET" \
  "$TRIMANGO_BASE_URL/availability/months?location=kalkan&guests=6&months=12"

Node

const { data: months } = await api('/availability/months?location=kalkan&guests=6&months=12')

Parametre	Kural
months	Bu aydan başlayarak kaç ay (1–18, varsayılan 12).
location, type, guests	Villa listesindeki süzgeçlerle aynı kural.

GET /availability/months → 200

[
  { "month": "2026-10", "villa_count": 21, "free_villa_count": 17, "min_nightly_try": 5200, "early_booking_percent": null },
  { "month": "2026-11", "villa_count": 21, "free_villa_count": 19, "min_nightly_try": 4800, "early_booking_percent": null },
  // …
  { "month": "2027-06", "villa_count": 21, "free_villa_count": 9, "min_nightly_try": 9800, "early_booking_percent": 15 }
]

Alan	Anlamı
villa_count	Süzgece uyan villa sayısı.
free_villa_count	O ayda kendi giriş gününde başlayan en az bir boş ve fiyatlı dönemi olan villa sayısı (Ay modu’ndaki month_free_weeks kuralı; bu ayda yalnız bugünden sonraki girişler sayılır).
min_nightly_try	Bu boş villaların o aydaki en düşük gecelik sezon fiyatı, TL; boş villa yoksa null.
early_booking_percent	Bugün geçerli erken rezervasyon indirimlerinin o ayın konaklamalarındaki en yüksek yüzdesi; yoksa null.

Satışa kapalı villa

Bir villa geçici olarak satışa kapatılabilir. Kapalı villa katalogda görünmeye devam eder:

• Kartta ve detayda status: "CLOSED".
• Detayda closed_until: kapalılığın son günü (o gün dahil). null ise villa süresiz kapalıdır.

Kapalılık giriş gününe göre değerlendirilir: girişi closed_until’den sonra olan konaklama satılabilir. closed_until null ise hiçbir tarih satılamaz.

Nerede	Kapalı villa
Tarihli liste	stay.available: false, stay.reason: "closed". available_only=true ise listeden çıkar.
Teklif	bookable: false, reason: "closed".
Rezervasyon talebi	409 villa:not-for-sale.

Kartta closed_until yoktur; listede tarihe göre kapalılığı tarihli sorgunun stay.reason alanından okuyun. Villa kapanınca ya da açılınca villa olayı status kapsamıyla gelir.

Opsiyon takvimi kilitler

Bir rezervasyon talebi (sizin ya da başka bir satış kanalının) villayı opsiyona alır: takvim opsiyon süresi boyunca kilitlenir (süre girişe kalan güne göre değişir) ve o geceler busy[] içinde dolu görünür. Bu süre içinde ödeme gelmezse talep iptal olur ve geceler yeniden boşalır.

• Opsiyondaki geceler takvimde kesin rezervasyondan ayırt edilmez. Bugün dolu görünen bir dönem, opsiyon düşerse birkaç gün sonra boşalabilir.
• Opsiyonun açılması, düşmesi ve iptali availability olayı gönderir.
• Kendi talebinizin opsiyon bitişi rezervasyon yanıtındaki option_expires_at alanındadır: Rezervasyon.

Müsaitlik kesin değildir

Takvim, tarihli liste ve aylık sayılar okuduğunuz andaki durumu gösterir. Okumanızla müşterinizin talebi arasında:

• başka bir kanal aynı tarihlere talep açabilir,
• ev sahibi takvimi kapatabilir ya da dış takvimler eşitlenebilir,
• fiyat ya da konaklama kuralı değişebilir.

Kendi veritabanınızda tuttuğunuz takvim, webhook gecikmesi kadar daha eskidir. Bu yüzden müşterinize kesin bilgi vermeden önce iki adımda doğrulayın:

1. Teklif: POST /quotes o tarihler ve kişi sayısı için bookable ve reason döner, dolu geceleri availability.busy_nights’ta listeler. Villa doluysa da 200 döner. Ayrıntı Fiyat ve teklif.
2. Talep: POST /reservations geceleri o anda yeniden denetler. Arada dolduysa 409 reservation:not-available döner; talep açılmaz. Ayrıntı Rezervasyon.

Dikkat

Müşteriye “müsait” bilgisini yalnız katalogdan, teklif almadan vermeyin. Listedeki stay ile teklif aynı fiyat motorundan gelir, ama aradaki sürede takvim değişmiş olabilir.

Değişiklikleri yakalama

Takvim değiştiğinde availability olayı calendar kapsamıyla gelir; villas[] takvimi değişen villaları listeler. Bu villaların detayını yeniden okuyup sakladığınız calendar’ı güncelleyin.

Node: availability olayı

if (event.type === 'availability') {
  for (const v of event.villas) {
    const saved = await db.villa(v.id)
    const { data } = await api(`/villas/${encodeURIComponent(saved?.code ?? v.slug)}?calendar_months=18`)
    await db.saveCalendar(v.id, data.calendar, data.status, data.closed_until)
  }
}

Olay şunlarda gönderilir: rezervasyon ya da opsiyon açıldı, iptal edildi, süresi doldu, tarihi ya da villası değişti; takvim kapatması eklendi ya da kaldırıldı; dış takvim eşitlendi; geceye özel fiyat girildi. Değişiklikler birkaç saniye toplanıp tek olayda gelir. Kurulum ve imza doğrulaması Webhook sayfasında.

İpucu

Takvim penceresi her gün bir gün ileri kayar. Kendi tarafınızda calendar.to’dan sonrasını “bilinmiyor” sayın; günlük tam eşitleme pencereyi yeniler.