trivago FastConnect Entegrasyonu: Developer Rehberi

trivago FastConnect klasik anlamda sizin çağırdığınız bir search API değildir. trivago sizin endpoint'lerinizi çağırır ve gerçek zamanlı hotel rate/availability bilgisi ister.

Temel akış:

Hotel inventory feed
      |
      v
trivago property mapping
      |
      v
User search on trivago
      |
      v
POST /hotel_availability
      |
      v
Your pricing engine
      |
      v
JSON room/rate response
      |
      v
trivago result
      |
      v
deeplink -> booking engine
      |
      v
conversion tracking

Bu nedenle FastConnect entegrasyonu aslında inbound realtime pricing API + property mapping + handoff quality problemidir.

Provider companion özeti

Capability boundary

Inventory/mapping        -> hotel data feed/API
Live user search         -> trivago -> /hotel_availability
Offer handoff            -> deeplink -> advertiser booking engine
Booking confirmation     -> advertiser -> Conversion API POST
Booking modification     -> advertiser -> Conversion API PUT
Booking cancellation     -> advertiser -> Conversion API DELETE

FastConnect booking oluşturmaz. Booking lifecycle downstream advertiser sisteminde yaşar; trivago'ya commercial attribution/conversion event'i geri gönderilir.

Pagination / polling neden N/A?

hotel_availability realtime request-response endpoint'idir. Session pagination veya client polling yoktur. Capacity planı:

inbound search traffic
x hotels/request
x cache miss
x supplier fan-out
x retry amplification

üzerinden yapılmalıdır.

Rate limit ve capacity yaklaşımı

Public FastConnect dokümanında tüm advertiser'lar için tek bir universal QPS limiti doğrulanmadı. Bu yüzden:

• trivago Technical Account Manager ile expected traffic profile hizalanmalı,
• inbound concurrency budget uygulanmalı,
• supplier fan-out bounded tutulmalı,
• timeout/circuit-breaker kullanılmalı,
• internal overload'da stale/partial/fallback policy açık olmalı.

Uydurma global QPS değeri companion'a yazılmamalıdır.

Conversion lifecycle ve idempotency

Conversion API aynı endpoint üzerinde booking lifecycle event'lerini method ile ayırır:

POST   -> booking confirmation
PUT    -> booking update
DELETE -> booking cancellation

trv_reference deeplink'ten booking'e attribution bağını taşır. Internal event key en az booking identity + lifecycle revision içermeli; duplicate notification double revenue/conversion üretmemelidir.

Platform sorumlulukları, ticari sınırlar ve operasyon kararları için trivago profiline bakın. Bu rehber uygulama sözleşmelerini ve request/response işlemlerini ele alır.

1. FastConnect'te sizin expose ettiğiniz endpoint'ler

trivago dokümantasyonu iki ana method tanımlar:

GET  /hotel_data
POST /hotel_availability

• hotel_data: advertiser inventory'sini döndürür.
• hotel_availability: search context için rate/availability döndürür.

Request parameter formatı:

Content-Type: application/x-www-form-urlencoded

Response:

Content-Type: application/json
Content-Encoding: gzip

trivago teknik gereksinimlerinde response'ların HTTP 200 dönmesi ve redirect kullanılmaması özellikle belirtilir.

2. Security boundary

FastConnect endpoint'i internete açık olacaktır. trivago optional HTTP Basic Authentication destekler; bunu yalnız HTTPS üzerinde kullanın.

interface FastConnectSecurityConfig {
  username?: string;
  passwordRef?: string;
  allowedNetworks?: string[];
  requireTls: true;
}

Ek olarak:

• request rate limiting,
• request signature/correlation logging,
• WAF,
• abuse protection,
• secret rotation

uygulanabilir.

3. Hotel inventory / mapping

trivago yalnız inventory feed'de bulunan ve map edilmiş hotelleri availability tarafında isteyebilir.

Internal canonical model:

interface Hotel {
  id: string;
  name: string;
  address?: string;
  city?: string;
  countryCode: string;
  latitude?: number;
  longitude?: number;
  active: boolean;
}

FastConnect mapping:

interface TrivagoHotelMapping {
  hotelId: string;
  partnerHotelId: string;
  mapped: boolean;
  lastSubmittedAt?: string;
}

Invariant:

internal hotel id != trivago partner reference

4. hotel_data response

trivago inventory'yi CSV veya API üzerinden alabilir. API kullanıyorsanız GET /hotel_data response'unuz advertiser inventory'yi temsil eder.

Basitleştirilmiş conceptual response:

[
  {
    "hotel_id": "HTL-84721",
    "hotel_name": "Example Bosphorus Hotel",
    "city": "Istanbul",
    "country": "TR",
    "latitude": 41.0423,
    "longitude": 29.0082
  }
]

Production field set'i güncel trivago hotel-data dokümanına göre oluşturun.

5. hotel_availability request modeli

trivago request'i hotel IDs, stay dates ve occupancy context taşır.

Adapter DTO:

interface TrivagoAvailabilityRequest {
  hotelIds: string[];
  checkIn: string;
  checkOut: string;
  adults: number;
  children?: number;
  locale?: string;
  currency?: string;
}

Internal request:

interface HotelAvailabilityRequest {
  hotelIds: string[];
  checkIn: string;
  checkOut: string;
  rooms: Array<{
    adults: number;
    childAges: number[];
  }>;
  currency?: string;
  market?: string;
}

Flow:

form-urlencoded request
   -> parse
   -> validate
   -> partner hotel id -> internal hotel id
   -> pricing engine
   -> normalize
   -> FastConnect serializer

6. Availability response

FastConnect response hotel -> room type -> offer hiyerarşisine sahiptir.

Conceptual response:

[
  {
    "hotel_id": "HTL-84721",
    "room_types": {
      "Deluxe Room": {
        "price": 5400.00,
        "currency": "TRY",
        "breakfast_included": true,
        "free_cancellation": true,
        "booking_fee": 0,
        "deeplink": "https://booking.example.com/..."
      }
    }
  }
]

Gerçek field isimleri ve mandatory/optional alanlar için güncel API objects dokümanını takip edin.

7. Internal offer modeli

interface HotelOffer {
  hotelId: string;
  roomName: string;
  ratePlanId?: string;

  price: {
    amount: number;
    currency: string;
  };

  breakfastIncluded?: boolean;
  refundable?: boolean;
  cancellationDeadline?: string;

  bookingFee?: number;

  deeplink: string;

  observedAt: string;
}

Provider-specific JSON business layer'da dolaşmamalı.

8. Rate semantics

trivago API update history pricing model'lerinin locale/POS bazında değişebildiğini gösterir.

Bu yüzden internal price modeliniz en az şunları ayırmalıdır:

interface PriceBreakdown {
  base: number;
  taxes?: number;
  mandatoryFees?: number;
  bookingFee?: number;
  total: number;
  currency: string;
  model: "all_in" | "tax_exclusive" | "other";
}

“En düşük fiyat” seçimi yalnız numeric amount'a göre yapılmamalıdır; room, occupancy, cancellation ve included benefits comparable olmalıdır.

9. No availability ile error'ı ayırın

AVAILABLE
SOLD_OUT
UNKNOWN_HOTEL
INVALID_STAY
UNSUPPORTED_OCCUPANCY
UPSTREAM_TIMEOUT
UPSTREAM_ERROR

trivago protocol seviyesinde 200 bekliyor olabilir; internal semantic state'i yine de kaybetmeyin.

Örnek:

type AvailabilityOutcome =
  | { kind: "available"; offers: HotelOffer[] }
  | { kind: "sold_out" }
  | { kind: "unsupported" }
  | { kind: "error"; code: string };

10. Latency budget

FastConnect user-facing request path üzerindedir.

Önerilen internal breakdown:

request parse          20 ms
mapping/cache          50 ms
supplier pricing     1200 ms
normalization         100 ms
serialization          50 ms
safety margin         ...

Rakamları kendi p95/p99 dağılımınıza göre belirleyin.

Track:

• p50/p95/p99,
• supplier timeout,
• cache hit,
• answer rate,
• partial coverage.

11. Cache

Cache key:

hotel
+ check-in
+ check-out
+ occupancy
+ currency
+ market/locale

Stale price, fast response'dan daha pahalı olabilir. Booking intent arttıkça freshness policy sıkılaştırılmalıdır.

12. Deeplink

Deeplink şu context'i mümkün olduğunca korumalıdır:

• hotel,
• dates,
• occupancy,
• currency,
• selected room/rate,
• tracking ID.

interface BookingHandoff {
  hotelId: string;
  checkIn: string;
  checkOut: string;
  adults: number;
  children: number[];
  currency: string;
  offerId?: string;
  clickId: string;
}

13. Conversion tracking

FastConnect sonrası conversion feedback commercial reconciliation için önemlidir.

Internal event:

interface TrivagoConversion {
  clickId?: string;
  bookingId: string;
  bookingValue: number;
  currency: string;
  bookingStatus: "booked" | "cancelled" | "modified";
  occurredAt: string;
}

Duplicate booking ID için idempotency uygulanmalıdır.

14. Error ve retry policy

Inbound request'i retry eden taraf trivago olabilir; sizin tarafınızda supplier call retry'ları bounded olmalıdır.

Retryable:

• transient supplier timeout,
• selected 5xx,
• temporary network failure.

Blind retry yapmayın:

• invalid hotel mapping,
• invalid occupancy,
• malformed request,
• unsupported currency/market.

15. Capacity planning

QPS yalnız hotel sayısıyla tahmin edilemez.

peak searches
x requested hotels/search
x cache miss ratio
x supplier fan-out
x retry amplification

Bu çarpanlar concurrency ihtiyacını belirler.

16. Monitoring

Inventory

• submitted hotels,
• mapped hotels,
• unmatched,
• inactive/closed drift.

Availability

• request count,
• answer rate,
• sold-out rate,
• timeout/error,
• p50/p95/p99.

Quality

• stale price,
• deeplink success,
• price mismatch,
• unsupported occupancy.

Commercial

• clicks,
• bookings,
• attributed bookings,
• cancellations,
• net conversion.

17. Test matrisi

18. Go-live checklist

• trivago onboarding aligned
• hotel inventory feed valid
• mapping coverage monitored
• hotel_data stable
• hotel_availability schema-valid
• UTF-8 / JSON response correct
• compression enabled
• no redirects
• TLS configured
• optional Basic Auth configured if required
• internal rate semantics explicit
• latency dashboard ready
• cache/freshness policy defined
• deeplink context tested
• conversion idempotency implemented
• failure modes load-tested

Sonuç

FastConnect'i “trivago'ya fiyat verme API'si” olarak değil, realtime inbound pricing service olarak tasarlamak gerekir.

Doğru boundary:

trivago request
   -> FastConnect adapter
   -> canonical availability request
   -> pricing engine
   -> normalized offers
   -> FastConnect JSON
   -> deeplink
   -> booking/conversion reconciliation

Bu yapı trivago-specific contract'ı ürün domain'inizden ayırır ve latency, price quality ve conversion zincirini ölçülebilir hale getirir.