Wego Affiliate API Entegrasyonu: Developer Rehberi

Wego Affiliate API, travel search için klasik synchronous API yerine token -> search session -> poll -> merge -> handoff lifecycle'ı sunar.

Flight flow:

OAuth token
    |
    v
POST /metasearch/flights/searches
    |
    v
search ID
    |
    v
GET /metasearch/flights/searches/{searchId}/results
    |
    v
offset-based polling
    |
    v
Trips + Fares + Providers
    |
    v
Wego handoff URL

Affiliate, distribution ve provider sorumlulukları için Wego profiline bakın. Bu rehber affiliate uygulama akışını ele alır.

1. Authentication

Token endpoint:

POST https://affiliate-api.wego.com/apps/oauth/token
Content-Type: application/json

Request:

{
  "client_id": "<client-id>",
  "grant_type": "client_credentials",
  "scope": "affiliate"
}

Response:

{
  "access_token": "<token>",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "affiliates",
  "created_at": 1500000000
}

API calls:

Authorization: Bearer <access-token>

Secret/token frontend bundle'a konmamalıdır.

2. Token manager

interface WegoToken {
  value: string;
  expiresAt: string;
}

interface WegoCredentials {
  clientId: string;
  secretRef?: string;
}

Token refresh single-flight olmalı; her worker aynı anda token istememelidir.

3. Flight search create endpoint

POST https://affiliate-api.wego.com/metasearch/flights/searches
Authorization: Bearer <token>
Content-Type: application/json

Basitleştirilmiş request:

{
  "search": {
    "adultsCount": 1,
    "childrenCount": 0,
    "infantsCount": 0,
    "cabin": "economy",
    "currencyCode": "TRY",
    "locale": "tr",
    "siteCode": "TR",
    "deviceType": "DESKTOP",
    "appType": "WEB_APP",
    "legs": [
      {
        "departureCityCode": "IST",
        "arrivalCityCode": "LON",
        "outboundDate": "2026-10-12"
      }
    ]
  }
}

Create response'un asıl kritik alanı search ID'dir.

4. Internal search model

interface TravelSearchRequest {
  vertical: "flight" | "hotel";

  market: string;
  locale: string;
  currency: string;

  flight?: {
    legs: Array<{
      origin: string;
      destination: string;
      departureDate: string;
    }>;
    adults: number;
    children: number;
    infants: number;
    cabin: string;
  };

  hotel?: {
    locationId: string;
    checkIn: string;
    checkOut: string;
    rooms: Array<{
      adults: number;
      childAges: number[];
    }>;
  };
}

Provider request'i doğrudan UI contract yapmayın.

5. Search session modeli

interface WegoSearchSession {
  internalSearchId: string;
  providerSearchId: string;
  vertical: "flight" | "hotel";

  status: "created" | "polling" | "complete" | "failed";

  requestHash: string;

  offset: number;
  stableCountPolls: number;
  pollCount: number;

  createdAt: string;
  lastPolledAt?: string;
}

Search ID short-lived operational state'tir, durable booking identity değildir.

6. Poll flight results

GET https://affiliate-api.wego.com/metasearch/flights/searches/{searchId}/results
  ?offset=0
  &locale=TR
  &currencyCode=TRY
Authorization: Bearer <token>

İlk response subset olabilir. Wego progressive rendering'i destekler.

7. Offset merge

Poll response'daki count/offset modeli aynı entity'leri tekrar taşıyabilir veya yeni fare'lar getirebilir.

Blind append yapmayın.

interface WegoFlightResultStore {
  trips: Map<string, Trip>;
  legs: Map<string, Leg>;
  airports: Map<string, Airport>;
  airlines: Map<string, Airline>;
  providers: Map<string, Provider>;
  fares: Map<string, Fare>;
}

Merge:

poll response
  -> upsert shared entities
  -> append/update fares
  -> deduplicate
  -> rerank
  -> update offset

8. Polling strategy

Wego dokümantasyonu artan polling interval'i önerir:

poll 1 -> 500 ms
poll 2 -> 1 sec
poll 3 -> 2 sec
poll 4 -> 3 sec
poll 5 -> 4 sec

Stop heuristic:

üç ardışık poll aynı count dönüyorsa sonuç set'i mature kabul edilebilir.

Bu kuralı provider-specific orchestration policy olarak adapter içinde tutun.

9. Trip ve Fare ayrımı

Wego Flights response modelinde Trip itinerary'yi, Fare ise provider + price'ı temsil eder.

interface FlightTrip {
  id: string;
  legIds: string[];
}

interface FlightFare {
  id: string;
  tripId: string;
  providerId: string;

  amount: number;
  currency: string;

  handoffUrl: string;

  bookingFee?: number;
  paymentFee?: number;
}

trip != fare

Bir trip birden fazla provider/fare ile satılabilir.

10. Shared entity dictionaries

Wego response data'yı tekrar azaltmak için referanslarla modeller.

Trip
  -> legIds

Leg
  -> airport codes
  -> airline refs

Fare
  -> trip
  -> provider
  -> handoff

Frontend için canonical model üretirken referansları resolve edin; source IDs'i de koruyun.

11. More fares endpoint

Default search bir trip için best fare döndürebilir. Kullanıcı belirli trip'e ilgi gösterdiğinde ek fare'lar istenebilir.

GET https://affiliate-api.wego.com/metasearch/flights/trips/{tripId}
Authorization: Bearer <token>

Bu endpoint'i tüm trip'ler için eagerly çağırmak yerine user intent ile tetiklemek latency/quota açısından daha verimlidir.

12. Hotel search

Hotel lifecycle da create + poll mantığını kullanır. Poll response hotel/rate entity'leri progressive getirir.

Internal model:

interface HotelSearchResult {
  hotelId: string;
  name: string;

  bestRate?: {
    providerId: string;
    amount: number;
    currency: string;
    handoffUrl: string;
  };

  observedAt: string;
}

Hotel merge sırasında amenity, brand, chain, district ve property type dictionaries de deduplicate edilmelidir.

13. Handoff URL

Wego policy, search result'ta Wego deep link'lerinin kullanılmasını ister.

Bu nedenle provider'ın son URL'sini kendiniz reconstruct etmeyin; Wego handoff URL'ini contract olarak ele alın.

interface AffiliateClick {
  internalSearchId: string;
  providerSearchId: string;
  vertical: "flight" | "hotel";
  resultId: string;
  providerId: string;
  handoffUrl: string;
  clickedAt: string;
}

Redirect safety:

• HTTPS only,
• Wego-owned destination allowlist,
• raw arbitrary URL passthrough yok.

14. Search-to-click policy

Wego Affiliate policy, gerçek kullanıcı search'leri ve minimum search-to-click davranışı bekler.

Bu nedenle:

• bot-generated search yapmayın,
• prefetch ile gereksiz search üretmeyin,
• duplicate query suppression uygulayın,
• search-to-click metriğini product KPI olarak izleyin.

15. Rate limits

Wego get-started dokümantasyonu search request'lerine rate limit uygular. Polling aynı şekilde search quota'sına sayılmayabilir; yine de backend pressure açısından kontrol edilmelidir.

Response headers:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Internal metric:

wego_rate_limit_remaining
wego_search_429
wego_search_to_click
wego_polls_per_search

16. Error taxonomy

WEGO_AUTH
WEGO_RATE_LIMIT
WEGO_BAD_REQUEST
WEGO_SEARCH_CREATE_FAILED
WEGO_SEARCH_EXPIRED
WEGO_POLL_FAILED
WEGO_PARSE
WEGO_EMPTY_RESULT
WEGO_HANDOFF_INVALID
WEGO_PROVIDER_RESULT_INVALID

400/401 genellikle blind retry edilmemelidir.

429/5xx için bounded backoff uygulanabilir.

17. Cache

Search response cache key:

vertical
+ market
+ locale
+ currency
+ dates
+ occupancy/passengers
+ cabin/location

Live travel price cache'i kısa ömürlü olmalıdır. Duplicate suppression için faydalıdır; booking truth değildir.

18. Observability

Auth

• token success,
• token age,
• refresh failures.

Search

• create success,
• p50/p95 create latency,
• first-result latency,
• poll count,
• stable-count completion,
• empty-result rate.

Quota

• remaining quota,
• 429,
• search-to-click.

Handoff

• click count,
• invalid link,
• provider landing success.

Commercial

• attributed booking,
• commission state,
• cancellation-adjusted conversion.

19. Commercial reconciliation

search
  -> Wego fare/rate
  -> handoff click
  -> provider booking
  -> conversion/commission
  -> cancellation

Normalize:

interface AffiliateConversion {
  clickId?: string;
  bookingId: string;
  providerId: string;
  bookingValue: number;
  currency: string;
  status: "pending" | "approved" | "cancelled";
}

20. Test matrisi

21. Go-live checklist

• Wego credentials server-side
• token cache/refresh implemented
• search request mapper tested
• search ID lifecycle tracked
• offset merge idempotent
• polling backoff implemented
• stop rule implemented
• flight Trip/Fare model separated
• hotel rate model normalized
• rate-limit headers monitored
• search-to-click KPI monitored
• only valid Wego handoff URLs exposed
• redirect security applied
• client disconnect stops polling
• commercial reconciliation ownership defined

Sonuç

Wego Affiliate API'yi “OAuth + search endpoint” olarak görmek eksik kalır.

Doğru architecture:

user query
  -> normalized request
  -> Wego search
  -> provider search ID
  -> progressive poll
  -> entity merge
  -> canonical trip/hotel offers
  -> Wego handoff
  -> commercial reconciliation

Bu yapı async search lifecycle'ını, quota/commercial policy'yi ve downstream handoff'u aynı operasyonel modelde toplar.

Provider companion özeti

Capability boundary

OAuth token → create search → Search ID → poll result offsets → merge Trips/Fares/Providers → Wego redirect/deeplink → downstream provider.

Search result booking confirmation değildir.

Rate-limit ve polling contract

Wego public docs standard key için 500 search request/saat, test key için 50/saat belirtir. Poll çağrıları search request limitine dahil değildir. Yine de tight-loop polling yapmayın; progress-aware backoff ve maximum duration kullanın.

Idempotency / ordering

Aynı search ID ve offset tekrar işlendiğinde duplicate trip/fare oluşmamalıdır. Offset monoton ilerlemeli; eski snapshot yeni provider/fare state'ini ezmemelidir.

Commercial handoff ve observability

Production affiliate traffic gerçek user search'e dayanmalı ve Wego deeplink'leri kullanılmalıdır. Search-to-click ratio, 429/limit kullanımı, poll count, time-to-first-result, time-to-complete, empty result ve deeplink success birlikte izlenmelidir.