Para, dil ve biçim

Para

Villanın para birimi ve TL karşılığı

Her villanın fiyatı kendi para biriminde girilir: TRY, EUR, USD ya da GBP. Yanıtlarda tutarlar iki biçimde gelir:

Alan	Anlamı
`total`, `prepayment`, `amount` … ve yanlarındaki `currency`	Villanın kendi para birimindeki tutar.
`total_try`, `prepayment_try`, `amount_try` … (`*_try`)	Aynı tutarın TL karşılığı.

Misafirden ödeme her zaman TL alınır. Bu yüzden acentelere ve misafire gösterdiğiniz fiyat için *_try alanlarını kullanmanızı öneririz.

Tutarlar sayıdır (metin değil), iki ondalığa yuvarlanmıştır. TL tutarlar kuruşa yarım yukarı yuvarlanır.
Kalemlerin TL tutarlarının toplamı total_try’ı tutar; due_on_arrival_try = total_try − prepayment_try.
TL tutarı kendiniz hesaplamayın. Yuvarlama ve kur günü yüzünden kuruş farkı çıkabilir; yanıttaki *_try esastır.
İndirim kalemleri eksi işaretlidir; discounts gibi toplam indirim alanları artıdır.
Hasar depozitosu (damage_deposit) toplama girmez; girişte alınır, çıkışta iade edilir.

Kur

Kur TCMB döviz satış kurudur; 1 birim dövizin TL karşılığı. Hafta içi 10:00 ve 15:45’te (İstanbul saati) güncellenir.
Güncel kurlar GET /site yanıtında: rates_try ({"EUR": 36.5, "USD": 33.9, "GBP": 43.1}) ve rates_date.
Teklif yanıtındaki fx_rate ve fx_date, o anda açılacak bir talepte kullanılacak kurla aynıdır. TL villada fx_rate 1’dir.
Kur talepte donar. Rezervasyon talebi açıldığında kur ve TL tutarlar rezervasyona yazılır; sonradan kur değişse de o rezervasyonun TL tutarları değişmez.
Kur henüz yoksa (TCMB verisi gelmemişse) *_try ve fx_* alanları null olur. Talep yine açılır; kur gelince doldurulur.
Kur değişince webhook’a reference türünde, currency kapsamlı bir olay gelir (Webhook).

`expected_total`

Rezervasyon talebinde acenteye gösterdiğiniz toplamı expected_total ile gönderirsiniz. İki biçimden biri kabul edilir: villanın para birimindeki total ya da teklifteki TL toplam total_try. Tutmazsa talep açılmaz ve 409 reservation:price-changed döner (Hatalar).

Dil

Nerede	Nasıl
Rezervasyon talebi	Gövdede `language`: `tr` ya da `en`. Trimango’nun misafire göndereceği e-posta ve mesajlar bu dilde gider. İsteğe bağlıdır, ama her talepte gönderin; boş kalırsa misafirin kayıtlı dili, o da yoksa Türkçe kullanılır.
Hata mesajları	`title` ve `errors` mesajları Türkçedir.
Katalog	Kapsamdaki katalog uçlarında dil parametresi yoktur; villa adları, açıklamalar, lokasyon ve özellik adları Türkçe gelir. Her villada İngilizce adres `slug_en` de vardır (çeviri yoksa `slug` ile aynıdır); `GET /villas/{slug}` iki adresle de açılır.

Alan adları ve JSON

Alan adları snake_case: check_in, total_try, option_expires_at.
İstek gövdesi Content-Type: application/json ile, UTF-8 gönderilir.
API başvurusunda zorunlu işaretli alanlar yanıtta her zaman bulunur; değeri yoksa null döner. Zorunlu olmayan alanlar yalnız ilgili durumda gelir. Her iki durumda da null’a ve eksik alana hazırlıklı olun.
Bilinmeyen alanları yok sayın. Yanıtlara habersiz yeni alan eklenebilir (Değişiklikler).
Durum, neden ve tür gibi sabit değer listelerinde (status, reason, type) tanımadığınız bir değer gelirse güvenli tarafta kalın: villayı o tarihler için satılamaz sayın, rezervasyonu elle kontrol edilecekler arasına alın.

Tarih ve zaman

Tür	Biçim	Örnek
Tarih	`YYYY-MM-DD`	`2026-07-04`
Zaman	ISO 8601, UTC	`2026-10-15T09:40:00.123Z`

check_in giriş günü, check_out çıkış günüdür. Gece sayısı ikisinin farkıdır: 2026-07-04 → 2026-07-11 7 gecedir.
Takvimdeki dolu aralıklar [start, end) biçimindedir: end çıkış günüdür ve o gün yeni giriş yapılabilir.
Sezon aralıklarında (from–to) son gece dahildir.
Zaman alanlarını (ör. option_expires_at, created_at) acenteye kendi saat diliminizde gösterin. Trimango’nun iş kuralları İstanbul saatine göre işler.

Kimlikler

Kimlik	Biçim	Not
Villa `id`	UUID	Değişmez. Villaları kendi tarafınızda bununla saklayın.
Villa `code`	Metin, ör. `ABC-1042`	Biçimini varsaymayın; eski kodlar farklı biçimde olabilir. Kod değişebilir; eski kodla açma bir süre çalışır.
Villa `slug`, `slug_en`	Metin	Adres; değişebilir. Değişince webhook olayında eski adres `previous_slug` ile gelir.
Rezervasyon `code`	Metin, ör. `ABC-10001`	Rezervasyon numarası. Biçimini varsaymayın.
`submission_id`	UUID	Rezervasyon talebi için sizin ürettiğiniz kimlik; çift gönderimi önler (Hatalar).
Özellik ve lokasyon	`id` ve `slug`	Süzgeçlerde kullanılır; ayrıntı Katalog.

Telefon numaraları ülke koduyla yazılır: +905321234567 (boşluk ve tire serbest).

Sayfalama

Uç	Nasıl
`GET /villas`	`page` (1’den başlar, varsayılan 1) ve `page_size` (1–48, varsayılan 24). Yanıtta `items`, `total`, `page`, `page_size`. Son sayfa: `page × page_size ≥ total`.
`GET /villas/summaries`	Sayfalama yok; bütün villalar tek yanıtta. `ids` ile en çok 100 villa seçilebilir.
`POST /quotes/batch`	Bir istekte 1–48 villa.
`POST /quotes/recheck`	Bir istekte 1–12 satır.

Aralık dışı değerler hata döner; errors nesnesinde hangi parametrenin kabul edilmediği yazar. Bütün kataloğu almak için sayfalı listeyi dolaşmak yerine GET /villas/summaries kullanın (Sınırlar ve önbellek).