Sınırlar ve önbellek

İstek sınırı

Sınır	Değer	Aşılınca
İstemci başına, bütün uçlar	Dakikada 1.200 istek	`429`, `Retry-After` başlığı (saniye)
`POST /reservations`	Gönderen başına dakikada 5	`429` `site:visitor-rate-limit`, gövdede `retry_after` (saniye)
`POST /reservations/lookup`	Gönderen başına dakikada 20	`429` `site:visitor-rate-limit`, gövdede `retry_after`
`POST /reservations/lookup`, aynı rezervasyon numarası	Saatte 10 tutmayan deneme (gönderenden bağımsız)	`429` `reservation:too-many-attempts`, gövdede `retry_after` (saat dolana kalan saniye)

Sınır istemci başınadır: test ve canlı istemcinizin sayaçları ayrıdır. Katalog eşitlemesi, teklif ve rezervasyon istekleri aynı dakikalık sınırı paylaşır.

Gönderen başına sınırlar ve `X-Visitor-IP`

“Gönderen başına” sınırlar isteği başlatan kişinin IP adresine göre sayılır. Sunucudan sunucuya çağrıda bu adres Trimango’ya ulaşmadığı için isteğe bağlı X-Visitor-IP başlığıyla bildirilir: tek bir IPv4 ya da IPv6 adresi (ör. 203.0.113.9, 2001:db8::7), en çok 45 karakter, port ve liste olmadan.

Başlık yoksa ya da geçersizse istek kabul edilir; gönderen başına sınır uygulanmaz, yalnız istemci başına sınır geçerlidir.
Başlığa kendi sunucunuzun adresini yazmayın: bütün acentelerinizin talepleri tek gönderen sayılır ve dakikada 5 talep sınırına hep birlikte takılırsınız.

429 aldığınızda

Bekleme süresini bulun:
- İstemci başına sınırda süre Retry-After başlığındadır (saniye).
- site:visitor-rate-limit ve reservation:too-many-attempts türlerinde süre gövdedeki retry_after alanındadır (saniye).
Beklerken aynı istemciyle başka istek göndermeyin; sınır istemcinin bütün isteklerini kapsar.
Bekleme süresi dolunca isteği bir kez yeniden deneyin.
Acenteye “Biraz sonra tekrar deneyin” gibi kısa bir mesaj gösterin; teknik ayrıntı göstermeyin.

Sık 429 alıyorsanız eşitleme işinizi yavaşlatın (aşağıda) ya da size verilen iletişim kanalından Trimango ekibine yazın.

Önbellek: ETag ve 304

Bütün GET yanıtları ETag başlığı taşır ve Cache-Control: no-cache ile gelir: yanıtı saklayabilirsiniz, ama yeniden kullanmadan önce Trimango’ya hâlâ geçerli olup olmadığını sormalısınız. Bunu koşullu istekle yaparsınız:

curl -si -u "$TRIMANGO_CLIENT_ID:$TRIMANGO_CLIENT_SECRET" \
  "$TRIMANGO_BASE_URL/villas/villa-defne"
# HTTP/1.1 200 OK
# ETag: "a1b2c3"

curl -si -u "$TRIMANGO_CLIENT_ID:$TRIMANGO_CLIENT_SECRET" \
  -H 'If-None-Match: "a1b2c3"' \
  "$TRIMANGO_BASE_URL/villas/villa-defne"
# HTTP/1.1 304 Not Modified   (gövde yok; elinizdeki kopya güncel)

ETag değerini tırnaklarıyla birlikte, olduğu gibi saklayıp geri gönderin.
ETag adrese ve sorgu parametrelerine bağlıdır: /villas?page=1 ile /villas?page=2 ayrı ETag taşır.
304 yanıtı da bir istek sayılır ve sınıra girer. Kazancınız aktarılan veri ve işleme süresidir.
Rezervasyon yanıtlarını (/reservations/...) paylaşılan önbelleklerde tutmayın; misafir bilgisi içerir. Durumu her seferinde güncel okuyun.

Kataloğu toplu eşitleme

Villaları kendi sisteminizde göstermek için kataloğu kendi veritabanınıza alırsınız. Önerilen yol: bir kez tam eşitleme, sonra webhook ile değişenleri güncelleme, yedek olarak da düzenli kontrol.

1. İlk eşitleme

GET /villas/summaries: bütün villaların hafif listesi, sayfalama olmadan tek istekte.
Her villa için GET /villas/{slug}: içerik, fotoğraflar, odalar, kurallar, sezon fiyatları ve takvim (dolu geceler). calendar_months ile takvimin kaç ay ileri döneceğini seçin (1–24, varsayılan 18).
Sözlükler: GET /features, GET /locations, GET /types/counts.
Kurlar: GET /site (rates_try).

Villaları kendi tarafınızda id ile saklayın. slug ve code değişebilir; id değişmez.

2. Değişiklikleri webhook ile alın

Bir webhook adresi tanımlattığınızda Trimango, veri değişince birkaç saniye içinde sunucunuza kısa ve imzalı bir olay gönderir. Olay veriyi taşımaz, yalnız neyin değiştiğini söyler; güncel veriyi yine API’den okursunuz.

Olay türü	Ne değişti	Ne okunmalı
`availability`	Takvim: yeni rezervasyon, opsiyon, iptal, kapatma	Olaydaki villaların detayı (takvim)
`price`	Sezon fiyatları, ücretler, kampanyalar	Olaydaki villaların detayı; `all_villas` kapsamı varsa bütün villalar
`villa`	İçerik, fotoğraf, yayın durumu, adres (`slug`)	Olaydaki villaların detayı; villa yayından kalktıysa detay `404` döner
`reference`	Lokasyonlar, sözlükler ya da döviz kuru	Kapsama göre `/locations`, `/features`, `/types/counts` ya da `GET /site`

Kurulum, imza doğrulama ve olay ayrıntısı: Webhook.

3. Yedek olarak düzenli kontrol

Webhook teslimatı birkaç kez denenir, sonra bırakılır; sizin sunucunuz uzun süre kapalı kalırsa olay kaçabilir. Bu yüzden webhook kullansanız da düzenli kontrol yapın:

Saatte bir: GET /villas/summaries ile listeyi alın. Yeni gelen villaları ekleyin, listeden çıkanları satıştan kaldırın. updated_at içerik değişikliğini gösterir; takvim ve fiyat değişiklikleri için ona güvenmeyin.
Günde bir: bütün villaların detayını If-None-Match ile yeniden okuyun. Değişmeyenler 304 döner.
Webhook kullanmıyorsanız takvimi daha sık (ör. 15–30 dakikada bir) yenileyin; yine de satıştan önce teklifle doğrulayın.

4. Sınırı paylaşın

Eşitleme işi, acentelerin anlık teklif ve talep istekleriyle aynı dakikalık sınırı kullanır. Eşitlemeyi sınırın yarısını geçmeyecek hızda yapın: ör. saniyede en çok 10 istek (dakikada 600). 500 villalık bir portföyün detayları bu hızla bir dakikadan kısa sürede okunur. 429 alırsanız eşitlemeyi duraklatın, anlık isteklere öncelik verin.

5. Fiyatı kendiniz hesaplamayın

Detaydaki sezon fiyatları ve başlayan fiyat (from_price) liste ve gösterim içindir. Kesin toplam; kampanya, erken rezervasyon, ek kişi, temizlik gibi kalemlere bağlıdır ve yalnız teklif uçlarıyla alınır:

Arama sonucunda çok villa için POST /quotes/batch (bir istekte en çok 48 villa) ya da tarihli GET /villas.
Seçilen villa için POST /quotes.
Rezervasyon talebinden hemen önce teklifi yeniden alın ve toplamı expected_total olarak gönderin.

Ayrıntı: Fiyat ve teklif.