Rezervasyon

Siz rezervasyon talebi gönderirsiniz. Talep villayı hemen opsiyona alır ve bir rezervasyon kodu döner. Bundan sonrasını Trimango ekibi yürütür: ev sahibinden teyit alır, misafire ödeme bağlantısını gönderir, misafirle iletişimi kurar ve ödemeyi tahsil eder. Siz ve acenteleriniz misafirden para almazsınız; rezervasyonun durumunu API’den izlersiniz.

Akış

#	Kim	Ne olur	Durum (status)
1	Siz	Acente villayı, tarihi ve kişi sayısını seçer; POST /quotes ile teklif alırsınız.
2	Siz	Acente misafirin bilgileriyle onaylar; POST /reservations ile talep gönderirsiniz. Villa opsiyona alınır, rezervasyon kodu döner.	requested
3	Trimango	Misafire Trimango adıyla “Talebiniz alındı” e-postası gider. Trimango ekibi ev sahibinden teyit alır.	requested
4	Trimango	Teyit gelince ekip ödemeyi açar; ödeme bağlantısı misafire e-posta ve SMS ile Trimango adıyla gider.	awaiting_payment
5	Misafir	Trimango’nun ödeme sayfasında TL olarak öder: ön ödeme ya da tamamı.	awaiting_payment
6	Trimango	Ödeme alınınca rezervasyon kesinleşir. Kalan tutar (varsa) girişte ödenir.	confirmed
7		Konaklama biter.	completed

Opsiyon süresi içinde ödeme gelmezse ya da villa verilemezse rezervasyon iptal olur ve takvim açılır: cancelled.

Payınız (sözleşmenizdeki oran) Trimango’nun tahsil ettiği tutar üzerinden doğar, iade ve iptalde düşer; aylık ekstreyle size ödenir. Misafire ayrıca ödeme bağlantısı göndermeniz ya da misafirden ödeme almanız gerekmez, almamalısınız.

Talep gönderme

curl -s "$TRIMANGO_BASE_URL/reservations" \
  -u "$TRIMANGO_CLIENT_ID:$TRIMANGO_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "submission_id": "6f1c2a9e-3b7d-4e8a-9c41-0d2e5f6a7b8c",
    "villa_id": "01990c1e-7a4b-7c21-9f3e-2b1d5c6a7e80",
    "check_in": "2027-07-10",
    "check_out": "2027-07-17",
    "adults": 2,
    "children": 1,
    "heating": false,
    "expected_total": 72635,
    "language": "tr",
    "guest": {
      "name": "Ayşe Yılmaz",
      "phone": "+90 532 123 45 67",
      "email": "ayse@example.com"
    },
    "note": "Geç giriş yapacağız, 22:00 civarı."
  }'

reserve.mjs

import crypto from "node:crypto";

const BASE = process.env.TRIMANGO_BASE_URL; // ör. https://…/api/public/v1
const AUTH = "Basic " + Buffer.from(`${process.env.TRIMANGO_CLIENT_ID}:${process.env.TRIMANGO_CLIENT_SECRET}`).toString("base64");

// submission_id'yi talep ilk kez gönderilirken üretin ve kendi kaydınıza yazın; yeniden denemede aynısını kullanın.
const submissionId = crypto.randomUUID();

const res = await fetch(`${BASE}/reservations`, {
  method: "POST",
  headers: { Authorization: AUTH, "Content-Type": "application/json" },
  body: JSON.stringify({
    submission_id: submissionId,
    villa_id: "01990c1e-7a4b-7c21-9f3e-2b1d5c6a7e80",
    check_in: "2027-07-10",
    check_out: "2027-07-17",
    adults: 2,
    children: 1,
    expected_total: 72635, // acentenin gördüğü TL toplam (teklifteki total_try)
    language: "tr",
    guest: { name: "Ayşe Yılmaz", phone: "+905321234567", email: "ayse@example.com" },
  }),
});

if (res.status === 201 || res.status === 200) {
  const { reservation, access_token, access_expires_at } = await res.json();
  // Üçünü de saklayın: takip için kod ve erişim anahtarı gerekir.
  console.log(reservation.code, reservation.status, reservation.option_expires_at);
} else {
  const problem = await res.json(); // application/problem+json
  console.log(res.status, problem.type, problem.errors ?? "");
}

Alanlar

Alan	Zorunlu	Açıklama
submission_id	Evet	Sizin ürettiğiniz uuid. Çift gönderime karşı koruma (bkz. Aynı talebi iki kez göndermek).
villa_id ya da slug	Biri	Teklifteki villa. Kimliği kullanın.
check_in, check_out	Evet	YYYY-MM-DD; teklifle aynı.
adults	Evet	En az 1.
children	Hayır	Varsayılan 0.
heating	Hayır	Havuz ısıtma istendiyse true; teklifle aynı olmalı.
expected_total	Önerilir	Acenteye gösterdiğiniz toplam: teklifteki TL toplam (total_try) ya da villanın para birimindeki total. Tutmazsa talep açılmaz.
guest.name	Evet	Misafirin adı soyadı, en az 2 harf, en çok 200 karakter.
guest.phone	Evet	Misafirin telefonu, ülke koduyla (+905321234567; boşluk ve tire serbest).
guest.email	Evet	Misafirin e-postası.
language	Önerilir	tr ya da en. Misafire giden e-postalar ve mesajlar bu dilde gider; boşsa Türkçe.
note	Hayır	Misafirin özel istekleri, en çok 2000 karakter. Trimango ekibi görür.

Misafir bilgisi misafirin kendisine ait olmalı. Talep alındı e-postası, ödeme bağlantısı ve giriş bilgileri bu adrese ve numaraya gider; Trimango ekibi gerektiğinde misafiri bu numaradan arar. Acentenin ya da sizin iletişim bilgilerinizi yazmayın.

Göndermeyin

Sözleşmede başka alanlar da var; bunlar Trimango’nun kendi web siteleri için. Kanal ortağı olarak göndermeyin ya da boş bırakın:

Alan	Neden
coupon	Portföy villalarında kupon geçmez. Geçersiz kuponla talep açılmaz (422 coupon).
quote_id, quote_token	Trimango’nun sohbet teklif kartına ait.
lead_ref, lead_source, partner_code	Web sitesi ziyaretçisinin kaynağı. Sizi istemci kimliğinizden tanırız.
tracking	Reklam tıklama kimlikleri (gclid, fbclid, ttclid …) ve utm_*; web sitesi ölçümüne ait.
page_url	Talebin gönderildiği web sayfası.
consent	Web sitesindeki pazarlama izni kutusu.

Talepte X-Visitor-IP başlığını şimdilik göndermeyin; kanal ortakları için kuralı netleşince duyurulacak. Başlığa kendi sunucunuzun IP’sini asla 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. Başlık yoksa yalnız istemci başına genel sınır geçerlidir (bkz. Sınırlar ve önbellek).

Yakında

Talepte isteğe bağlı agency nesnesiyle villayı asıl satan acenteyi bildirebileceksiniz:

"agency": { "code": "ACN-0042", "name": "Örnek Turizm", "agent_name": "Mehmet Kaya" }

code acentenin sizin sisteminizdeki kodu, name adı, agent_name satışı yapan kişi. Alan yalnız bilgi içindir: Trimango ekibi rezervasyonda görür, raporlarda acenteyi ayırır. Yetkiye ve paraya etkisi yoktur; payınız size ödenir, acentelerinize dağıtımı sizdedir. Alan gelene kadar göndermeyin.

Yanıt

Talep açılınca 201, aynı submission_id daha önce alındıysa 200 döner. Gövde ikisinde de aynı biçimdedir:

{
  "reservation": {
    "code": "TRM-10234",
    "status": "requested",
    "created_at": "2027-03-02T09:15:04Z",
    "option_expires_at": "2027-03-04T09:15:04Z",
    "villa": {
      "id": "01990c1e-7a4b-7c21-9f3e-2b1d5c6a7e80",
      "code": "V-1042",
      "slug": "villa-defne",
      "title": "Villa Defne",
      "location": "Kalkan",
      "photo_url": "https://…/villa-defne/kapak.jpg",
      "path": "/kalkan-kiralik-villa/villa-defne"
    },
    "check_in": "2027-07-10",
    "check_out": "2027-07-17",
    "nights": 7,
    "adults": 2,
    "children": 1,
    "heating": false,
    "guest": { "name": "Ayşe Yılmaz", "email": "a***@example.com", "phone": "+90 532 *** ** 67" },
    "price": {
      "currency": "EUR",
      "lines": [
        { "kind": "STAY", "label": "7 gece konaklama", "amount": 2100, "amount_try": 76650 },
        { "kind": "DISCOUNT", "label": "Erken rezervasyon %10", "amount": -210, "amount_try": -7665 },
        { "kind": "CLEANING", "label": "Temizlik", "amount": 100, "amount_try": 3650 }
      ],
      "total": 1990,
      "prepayment": 597,
      "due_on_arrival": 1393,
      "damage_deposit": 500,
      "fx_rate": 36.5,
      "fx_date": "2027-03-02",
      "total_try": 72635,
      "prepayment_try": 21790.5,
      "due_on_arrival_try": 50844.5,
      "damage_deposit_try": 18250
    },
    "paid": 0,
    "balance": 1990,
    "paid_try": 0,
    "balance_try": 72635,
    "payment": null,
    "payment_options": null,
    "last_payment": null
  },
  "access_token": "eyJ…",
  "access_expires_at": "2027-09-14T21:00:00Z"
}

• code rezervasyon kodudur (örnekteki önek temsilîdir). Acenteye ve Trimango ekibine bu kodla başvurun; biçimine güvenip ayrıştırmayın.
• access_token bu rezervasyonu okumanın anahtarıdır. Kodla birlikte saklayın; takipte X-Reservation-Token başlığıyla gönderilir. access_expires_at anahtarın geçerlilik sonudur (çıkıştan 60 gün sonra).
• price talep anında dondurulan fiyattır. Kur ve TL tutarlar bundan sonra değişmez; konaklama Trimango ekibince değiştirilirse aynı kurla yeniden hesaplanır.
• guest içinde telefon ve e-posta maskelenmiş döner.
• villa.path Trimango’nun kendi web sitesindeki sayfa yoludur; sizin için anlamı yoktur.
• Kalem türleri (price.lines[].kind) büyük harflidir ve liste genişleyebilir; ekranda label gösterin.

Talep anında kur henüz yoksa (TCMB verisi gelmemişse) talep yine açılır; fx_rate, fx_date ve *_try alanları null olur ve kur gelince doldurulur.

Aynı talebi iki kez göndermek

Ağ hatası ya da zaman aşımında talebin açılıp açılmadığını bilemezsiniz. Bu durumda aynı submission_id ile yeniden gönderin:

• Talep daha önce açıldıysa yeni rezervasyon açılmaz; ilk rezervasyon 200 ile ve yeni bir erişim anahtarıyla döner.
• Talep açılmadıysa (ör. 409 fiyat değişti) aynı kimlikle düzeltilmiş isteği gönderebilirsiniz.
• Aynı submission_id ile farklı villa ya da tarih gönderirseniz yine ilk talep döner. Yeni bir talep için yeni kimlik üretin.

submission_id’yi acente “Talep gönder”e ilk bastığında üretip talep kaydınıza yazmanızı, yeniden denemelerde oradan okumanızı öneririz.

Durumlar

status	Anlamı	Acenteye ne gösterilir
requested	Villa opsiyonda. Trimango ekibi ev sahibinden teyit alıyor; ödeme henüz açılmadı.	“Talep alındı, teyit bekleniyor” ve opsiyon bitişi (option_expires_at).
awaiting_payment	Villa opsiyonda, teyit alındı, ödeme açık. Misafire ödeme bağlantısı gitti (payment ve payment_options dolu).	“Misafirin ödemesi bekleniyor” ve ödeme son zamanı.
confirmed	Ödeme alındı, rezervasyon kesinleşti.	“Kesinleşti”; ödenen ve girişte kalan tutar (paid_try, balance_try).
completed	Konaklama bitti.	“Tamamlandı”.
cancelled	İptal edildi. Süresi dolan opsiyon da bu durumdadır.	“İptal”. Takvim yeniden satışa açıktır.

Olağan sıra requested → awaiting_payment → confirmed → completed; her aşamadan cancelled’a geçilebilir. Trimango ekibi açık ödeme bağlantısını geri çekerse rezervasyon awaiting_payment’tan requested’a dönebilir. Sıraya güvenmeyin, her seferinde yanıttaki durumu esas alın.

Opsiyon süresi

Talep villayı opsiyona alır: süre boyunca o geceler başka satışa kapanır. Süre girişe kalan güne göre belirlenir; girişe yakın tarihlerde kısalır. Kesin bitiş her rezervasyonda option_expires_at alanındadır (requested ve awaiting_payment durumlarında dolu, diğerlerinde null).

Bu süre içinde Trimango ekibi teyidi alır ve ödemeyi açar; misafirin ödemesi de bu süre içinde gelmelidir. Süre dolduğunda ödeme alınmamışsa rezervasyon kendiliğinden cancelled olur ve takvim açılır. Acenteye opsiyon bitişini göstermeniz misafiri zamanında ödemeye yönlendirmek için önemlidir.

Teyit ve ödeme

Teyit ve tahsilat Trimango’dadır:

1. Trimango ekibi ev sahibinden villanın verilebileceğini teyit eder.
2. Ekip ödemeyi açar. Misafire Trimango markalı ödeme sayfasının bağlantısı e-posta ve SMS ile gider. Ödeme sayfası, e-posta ve mesajlar Trimango adıyla çıkar; sizin ya da acentenin adı misafire gösterilmez.
3. Misafir ödeme sayfasında ön ödemeyi ya da tamamını seçer ve kartla TL olarak öder. Kart ödeme kuruluşu üzerinden 3D Secure ile alınır; kart bilgisi size gelmez.
4. Ödeme alınınca rezervasyon confirmed olur. Kalan tutar girişte ödenir.

Acenteniz misafire “Ödeme bağlantısı Trimango’dan e-posta ve SMS ile gelecek” bilgisini vermelidir.

Ödeme bağlantısını göstermek

awaiting_payment durumunda rezervasyon detayındaki payment alanı doludur:

"payment": {
  "url": "https://…",
  "amount": 597,
  "amount_try": 21790.5,
  "expires_at": "2027-03-04T09:15:04Z"
}

payment.url Trimango’nun misafire gönderdiği bağlantının aynısıdır ve expires_at’e kadar geçerlidir. Misafir bağlantıyı bulamazsa acenteniz bu bağlantıyı misafire gösterebilir ya da iletebilir. Kendi ödeme bağlantınızı üretmeyin; misafirden kendi hesabınıza ödeme almayın.

payment_options misafirin seçebileceği tutarları (deposit_amount_try ön ödeme, full_amount_try kalanın tamamı; deposit_only: true ise yalnız ön ödeme), last_payment misafirin son ödeme denemesinin sonucunu verir:

last_payment.status	Anlamı
processing	Ödeme sayfası açık ya da banka sonucu henüz bildirmedi. Misafire tekrar ödeme yaptırmayın.
paid	Ödeme alındı.
failed	Banka onay vermedi; karttan para çekilmedi. Misafir yeniden deneyebilir.
abandoned	Ödeme sayfası sonuçsuz kapandı.

Ödeme başlatma ucu

POST /reservations/{code}/payments ucu Trimango’nun kendi web sitelerinde misafirin ödemeyi sitede seçmesi içindir. Kanal ortağı olarak bu ucu kullanmanız gerekmez: ödeme seçimini misafir Trimango’nun ödeme sayfasında yapar. Uç dönüş adresi olarak yalnız Trimango alan adlarını kabul eder; kendi adresinizi verirseniz 422 döner.

Takip

Rezervasyonun güncel durumunu GET /reservations/{code} ile okuyun. Talep yanıtındaki erişim anahtarını X-Reservation-Token başlığıyla gönderin:

curl -s "$TRIMANGO_BASE_URL/reservations/TRM-10234" \
  -u "$TRIMANGO_CLIENT_ID:$TRIMANGO_CLIENT_SECRET" \
  -H "X-Reservation-Token: $ACCESS_TOKEN"

Yanıt, talep yanıtındaki reservation nesnesiyle aynı biçimdedir: durum, opsiyon bitişi, dondurulmuş fiyat, ödenen (paid, paid_try) ve kalan (balance, balance_try), açık ödeme bağlantısı ve son ödeme denemesi.

Sorgulama aralığı

Rezervasyon durum bildirimi gelene kadar durumları düzenli sorgulayın. Önerimiz:

• requested ve awaiting_payment: 15 dakikada bir, ayrıca option_expires_at geçtikten birkaç dakika sonra bir kez.
• confirmed: günde bir kez, çıkış gününe kadar (iptal ve tarih değişikliğini yakalamak için).
• completed ve cancelled: sorgulamayı bırakın.

Önceki yanıtın ETag değerini If-None-Match başlığıyla gönderin; değişiklik yoksa 304 döner. Hepsi istemci başına genel sınıra girer (dakikada 1.200 istek).

Yakında

Rezervasyon durumu değişince Trimango sizin webhook adresinize bir reservation olayı gönderecek. O zaman düzenli sorgulama yerine olay gelince GET /reservations/{code} çağırmanız yeterli olacak. Ayrıntı: Webhook.

Erişim anahtarının süresi dolarsa

Anahtar çıkıştan 60 gün sonra geçersiz olur. Süresi dolmuş anahtarla detay 403 reservation:token-expired, tutmayan anahtar ya da bilinmeyen kod 404 reservation:not-found döner. Anahtarı kaybettiyseniz ya da süresi dolduysa sorgulama ile yenisini alın.

Kodla sorgulama

POST /reservations/lookup rezervasyon kodunu misafirin e-postası ya da telefonuyla eşleştirir; tutarsa rezervasyonu ve yeni bir erişim anahtarı döndürür. Kanal ortağı için tek kullanımı, erişim anahtarını kaybettiğinizde ya da süresi dolduğunda yenisini almaktır. Talepte acentenin girdiği e-postayı ya da telefonu kullanın.

curl -s "$TRIMANGO_BASE_URL/reservations/lookup" \
  -u "$TRIMANGO_CLIENT_ID:$TRIMANGO_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "code": "TRM-10234", "email": "ayse@example.com" }'

• E-posta büyük/küçük harf duyarsızdır; telefon ülke koduyla, biçimi serbesttir. İkisinden biri yeterlidir.
• Eşleşmezse 404; hangisinin tutmadığı söylenmez.
• Aynı koda saatte 10 tutmayan denemeden sonra o saatin sonuna kadar 429 reservation:too-many-attempts döner; gövdedeki retry_after saatin dolmasına kalan saniyedir.

İptal ve değişiklik

API’de iptal ya da değişiklik (tarih, kişi, villa) ucu yoktur. Acente iptal ya da değişiklik isterse rezervasyon kodunu belirterek Trimango ekibine yazın. Ekip işlemi yapar; iptal edilen rezervasyon cancelled olur, değişen tarih ve tutarlar detayda görünür. Misafire iade gerekiyorsa Trimango yapar; payınız iade ve iptale göre düzeltilir.

Hatalar

Hatalar application/problem+json biçimindedir; type alanı urn:trimango:<kod> olur (bkz. Hatalar). Kararı type’a göre verin.

Talep (POST /reservations)

Durum	type ya da alan	Anlamı	Ne yapılmalı
409	reservation:price-changed	Fiyat ya da kur değişti; talep açılmadı. Gövdede güncel total, currency ve total_try.	Acenteye yeni tutarı gösterip onay alın; aynı submission_id ve yeni expected_total ile yeniden gönderin.
409	reservation:not-available	Geceler dolu; talep açılmadı.	Başka tarih ya da villa önerin.
409	villa:not-for-sale	Villa satışa kapalı.	Başka villa önerin.
422	check_in, check_out	Geçmiş giriş, 120 geceden uzun konaklama, en az ya da en çok gece kuralı, izinli olmayan giriş günü, fiyatı olmayan gece.	Teklifteki rules ve reason’a göre tarihleri düzeltin.
422	adults	Kişi sayısı villanın alabileceğinden fazla ya da 0.	Kişi sayısını düzeltin.
422	guest.name, guest.phone, guest.email	Ad 2 harften kısa, telefon ülke kodsuz ya da e-posta geçersiz.	Alanı düzeltip gönderin.
422	villa_id	Ne villa_id ne slug var.	Villayı belirtin.
404	villa:not-found	Villa yok, yayında değil ya da sizinle paylaşılmıyor.	Katalogdan güncel listeyi alın.
429	site:visitor-rate-limit	Gönderen başına dakikada 5 talep aşıldı (yalnız X-Visitor-IP gönderildiğinde). Gövdede retry_after (saniye).	retry_after kadar bekleyin.
429	—	İstemci başına genel sınır aşıldı. Retry-After başlığı (saniye).	Başlıktaki süre kadar bekleyin.
401	—	Kimlik eksik ya da yanlış.	Bkz. Kimlik.

422 hatalarında errors nesnesi alan → mesaj eşlemesidir (ör. {"check_out": "Bu dönemde en az 7 gece"}). Mesajlar Türkçedir ve acenteye gösterilebilir.

Takip ve sorgulama

Uç	Durum	type	Anlamı
GET /reservations/{code}	403	reservation:token-expired	Erişim anahtarının süresi doldu; kodla sorgulayıp yenisini alın.
GET /reservations/{code}	404	reservation:not-found	Kod ya da anahtar tutmuyor.
POST /reservations/lookup	404	reservation:not-found	Kod, e-posta ya da telefon eşleşmedi.
POST /reservations/lookup	429	reservation:too-many-attempts	Bu koda saatte 10 tutmayan deneme aşıldı; retry_after kadar bekleyin.
POST /reservations/lookup	429	site:visitor-rate-limit	Gönderen başına dakikada 20 sorgu aşıldı (yalnız X-Visitor-IP gönderildiğinde).