--- title: "Amadeus Self-Service API Entegrasyonu ve Migration Rehberi" description: "17 Temmuz 2026'da decommission edilen Amadeus Self-Service entegrasyonlarını OAuth, offer lifecycle, booking recovery, coverage ve migration sınırlarıyla güvenli biçimde yönetin." slug: "amadeus-self-service" translationKey: "integration-amadeus-self-service" locale: "tr" type: "guide" category: "integration" tags: ["amadeus","hotel-api","flight-api","oauth","repricing","travel-api"] vertical: ["hotel","flight"] platform: "Amadeus for Developers" domain: "developers.amadeus.com" publishedAt: "2026-09-20" updatedAt: "2026-09-20" reviewedAt: "2026-09-20" sources: - title: "Amadeus Enterprise API Portal" url: "https://developers.amadeus.com/self-service" - title: "Amadeus Self-Service API FAQ (legacy)" url: "https://admin.developers.amadeus.com/self-service/apis-docs/guides/developer-guides/faq/" - title: "Self-Service API tutorials (legacy)" url: "https://admin.developers.amadeus.com/self-service/apis-docs/guides/developer-guides/resources/" - title: "Hotel APIs tutorial (legacy)" url: "https://admin.developers.amadeus.com/self-service/apis-docs/guides/developer-guides/resources/hotels/" - title: "Self-Service API Postman collection (legacy)" url: "https://admin.developers.amadeus.com/self-service/apis-docs/guides/developer-guides/developer-tools/postman/" --- Amadeus Self-Service portalı 17 Temmuz 2026'da decommission edildi. Bu nedenle yeni bir production entegrasyonu Self-Service erişiminin hâlâ satın alınabildiğini veya yeni credential üretilebildiğini varsayarak planlanmamalıdır. Güncel başlangıç noktası Amadeus Enterprise API Portal ve Amadeus'un ticari erişim sürecidir. Bu rehber, mevcut Self-Service bağlantılarındaki lifecycle ve veriyi güvenli biçimde işletmek, bağımlılıkları envanterlemek ve yeni bir Amadeus Enterprise ya da alternatif provider adapter'ına migration yapmak içindir. Eski endpoint davranışları mimari referans olarak değerlidir; erişim, coverage ve commercial entitlement için güncel sözleşme ve portal esas alınmalıdır. ## Production migration senaryosu Gerçek bir migration senaryosunda flight search hâlâ cevap verirken token yenileme veya order endpoint'i erişimi kapanabilir; açık PNR'lar ise consolidator tarafında ticketing bekliyor olabilir. Tüm entegrasyonu tek “Amadeus up/down” state'iyle yönetmek hem duplicate booking hem de görünmez coverage kaybı üretir. ## Entegrasyonun bugünkü sınırı nedir? Self-Service catalog; flight search/pricing/order, hotel discovery/search/booking ve cached inspiration gibi farklı ürün aileleri içeriyordu. Bu yüzeyler tek bir availability kaynağı veya tek lifecycle değildir. Bugün iki durum ayrılmalıdır: - **Mevcut entegrasyon:** credential, production traffic ve sözleşme durumunu Amadeus ile doğrula; değişiklik dondurma ve migration planı oluştur. - **Yeni proje:** legacy Self-Service endpoint'lerini target architecture olarak alma; güncel Enterprise erişimini veya başka bir supplier'ı değerlendir. Amadeus provider adapter'ı şu sorumlulukları kendi domain'inizden devralmamalıdır: - canonical airport, city, hotel ve traveler identity, - multi-provider normalized search contract, - offer lineage ve price observation, - order/booking attempt state, - ticketing veya hotel confirmation reconciliation, - coverage ve fallback kararı. ## Legacy erişim ve OAuth nasıl çalışıyordu? Self-Service uygulamaları API key ve secret ile OAuth 2.0 client-credentials token'ı alıyor, test ve production için ayrı base URL/credential kullanıyordu. Resmî legacy tooling token'ın 30 dakika geçerli olduğunu belirtiyordu. Mevcut bağlantıyı geçici olarak işletiyorsanız: - secret'ı yalnız backend secret manager'da tutun, - token'ı response expiry bilgisine göre cache edin, - expiry öncesi margin ile yenileyin, - concurrent refresh için single-flight kullanın, - test ve production key'lerini karıştırmayın, - yeni credential veya entitlement verileceğini varsaymayın. ```text Legacy Credential | v OAuth Token Manager ---> expiry-aware cache | v Amadeus Adapter ---> migration telemetry ``` Auth failure ile business search failure ayrı alarm olmalıdır. Portal decommission sonrası auth rejection otomatik olarak “geçici provider outage” sayılmamalı; entitlement veya product retirement ihtimali araştırılmalıdır. ## Flight lifecycle nasıl modellenmeli? Legacy Self-Service flight booking akışı aşağıdaki lifecycle'ı kullanıyordu: ```text Normalized Search Request | v Flight Offers Search | v Normalized Offer + Original Source Offer | v Flight Offers Price | +-----+------+ | | valid changed/unavailable | | v v Create Order user reconfirm / re-search | v Flight Order Management | +--> retrieve +--> cancel where supported +--> consolidator ticketing/reconciliation ``` Flight Offers Price seçili offer'ın son fiyat ve availability durumunu doğrulayan transaction boundary'dir. Search response'tan yalnız flight number ve total amount çıkarıp pricing request'ini yeniden kurmayın; pricing ve order creation için source offer'ın gerekli yapısını koruyun. Self-Service production flight booking'de ticket issuance ayrı bir sorumluluktu. Resmî FAQ, Flight Create Orders erişimi için approved market/local requirements ve airline consolidator ilişkisini açıklıyordu. Order creation ile ticket issued aynı business state değildir. ## Flight offer nasıl normalize edilmeli? ```ts interface NormalizedFlightOffer { provider: "amadeus-self-service"; sourceOfferId: string; origin: string; destination: string; departureAt: string; arrivalAt: string; segments: Array<{ marketingCarrier: string; operatingCarrier?: string; flightNumber: string; bookingClass?: string; }>; passengerTypes: string[]; fareBrand?: string; baggage?: unknown; baseAmount: number; taxAmount?: number; totalAmount: number; currency: string; observedAt: string; sourcePayloadRef: string; } ``` Air offer flight number + price değildir. Segment sırası, marketing/operating carrier, passenger type, fare family/class, baggage, refund/change rules ve source offer identity pricing'e kadar korunmalıdır. ## Hotel lifecycle ve identity nasıl ayrılmalı? Legacy hotel akışı iki farklı data türü taşıyordu: ```text City / geocode | v Hotel List --------> canonical property mapping | v Hotel Search ------> real-time offer and payment policy | v Hotel Booking -----> durable confirmation identity ``` Hotel List response'u identity/discovery data'dır; Hotel Search response'u dates, adults, room quantity ve market context'e bağlı transactional offer'dır. Amadeus hotel ID external identifier olarak saklanmalı, canonical property ID yerine kullanılmamalıdır. Legacy V3 dokümanı Hotel Search sonucunu real-time olarak tanımlar ve ayrı bir validation step gerektirmediğini belirtir. Bu, offer'ın süresiz geçerli olduğu anlamına gelmez. Booking gecikmişse eski offer ID'yi kalıcı inventory gibi kullanmayın; booking rejection'ı “provider error” altında gizlemek yerine expiry/availability/price nedeni olarak sınıflandırın. Payment policy de normalize edilmelidir: guarantee, deposit ve prepay aynı cash-flow veya risk anlamına gelmez. Hotel Booking kredi kartı ve guest data taşıyorsa PCI/PII sınırı backend'de kurulmalıdır. ## Normalized search contract nasıl görünmeli? Flight ve hotel için ayrı contract kullanın; ortak “travel search” objesi provider semantics'i kaybettirir. ```json { "origin": "IST", "destination": "FRA", "departureDate": "2026-10-12", "returnDate": "2026-10-16", "travelers": [{ "type": "ADULT", "count": 1 }], "cabin": "ECONOMY", "currency": "EUR", "market": "TR" } ``` ```json { "canonicalPropertyIds": ["..."], "checkIn": "2026-10-12", "checkOut": "2026-10-14", "adults": 2, "roomQuantity": 1, "currency": "EUR" } ``` Adapter canonical airport/property mapping'lerini Amadeus ID ve request shape'e çevirir. Response normalization original offer veya replay edilebilir source reference'ı kaybetmemelidir. ## Discovery cache ile transactional data nasıl ayrılmalı? Flight Inspiration Search ve Flight Cheapest Date Search gibi legacy discovery API'leri seçilmiş origin-destination çiftleri üzerinde precomputed cache kullanıyordu; boş sonuç market'te uçuş olmadığı anlamına gelmiyordu. Bunları `indicative` source olarak işaretleyin. ```text Inspiration / cheapest date -> indicative, incomplete coverage Flight Offers Search -> live shopping context Flight Offers Price -> selected-offer validation Flight Create Orders -> transactional state change ``` Migration sırasında cached discovery sonuçlarını yeni provider'ın live result'larıyla aynı confidence veya freshness sınıfına koymayın. ## Coverage limitation neden ürün state'idir? Legacy FAQ; Self-Service flight dataset'inin bazı carrier'ları, low-cost content'i, negotiated ve special fare'leri kapsamadığını açıklıyordu. Bu listeyi 2026 için aktif supply garantisi olarak kullanmayın; portal decommission nedeniyle legacy kapsamı gösteren tarihsel bir limitation'dır. Internal result status şu ayrımı korumalıdır: ```text NO_AVAILABILITY UNSUPPORTED_MARKET_OR_CONTENT PROVIDER_ACCESS_RETIRED PROVIDER_TIMEOUT QUOTA_EXHAUSTED ``` Hepsini boş results array'e çevirmek coverage kaybını talep yokluğu gibi gösterir. ## Hangi data durable, hangisi ephemeral? ### Durable saklayın - canonical-to-Amadeus airport/city/hotel mapping'leri, - normalized search context ve offer observation, - source payload reference ve schema version, - displayed ve repriced amount, - internal booking/order attempt ID, - provider order veya hotel confirmation ID, - order/ticket/booking lifecycle event'leri, - coverage ve migration audit sonuçları. ### Ephemeral ele alın - OAuth access token, - cached inspiration response, - live search offer ID ve booking input state, - temporary traveler/session context, - raw payment data. Ephemeral offer data troubleshooting için kısa süre tutulabilir; durable booking record yerine geçmemelidir. ## Idempotency ve unknown state nasıl yönetilmeli? Flight order veya hotel booking call'u timeout olduğunda provider tarafında işlem oluşmuş olabilir. Aynı create request'i kör retry etmek duplicate booking riski taşır. Önce internal attempt oluşturun: ```text booking_attempt - internal_attempt_id - provider - product_type - source_offer_id - traveler_fingerprint - displayed_amount - confirmed_amount - status - provider_confirmation_id - created_at ``` State transition: ```text READY -> SUBMITTED -> CONFIRMED \-> REJECTED \-> UNKNOWN -> retrieve/reconcile/manual review ``` `UNKNOWN` ile `FAILED` aynı değildir. Provider order/booking lookup mümkünse outcome'u retrieve edin; değilse duplicate riskini engelleyip operasyonel review'a taşıyın. ## Error taxonomy, timeout ve retry policy ```text AUTH_FAILED ACCESS_RETIRED_OR_DISABLED QUOTA_EXHAUSTED INVALID_SEARCH_CONTEXT UNSUPPORTED_CONTENT NO_AVAILABILITY OFFER_EXPIRED PRICE_CHANGED PROVIDER_TIMEOUT PROVIDER_5XX ORDER_REJECTED BOOKING_STATE_UNKNOWN TICKETING_PENDING CONFIRMATION_RETRIEVE_FAILED ``` Search/read çağrılarında network ve seçilmiş 5xx hataları bounded exponential backoff alabilir. Validation, unsupported content, price change, access retirement ve business rejection retry edilmemelidir. `429` cevabı yalnız backoff problemi değildir; legacy test quota veya erişim durumunu ayrıca kontrol edin. Interactive search için total timeout budget tanımlayın; Amadeus adapter'a bunun yalnız bir bölümünü verin. Booking/create için daha uzun fakat bounded deadline kullanın ve timeout sonrasında unknown-state recovery başlatın. ## Reconciliation ve migration nasıl birlikte yürütülmeli? Mevcut bir Self-Service entegrasyonu için migration inventory çıkarın: - kullanılan endpoint ve API version'ları, - test/production credential ve son başarılı çağrı, - traffic, revenue ve booking ownership, - flight/hotel provider ID mapping'leri, - açık order, booking ve ticketing state'leri, - cached discovery bağımlılıkları, - downstream response-field bağımlılıkları. Yeni adapter'ı normalized contract arkasına ekleyin. Shadow traffic veya recorded payload testleriyle mapping ve offer semantics'i karşılaştırın. Provider değişiminde source offer ID'leri birbirine çevrilemez; aktif booking lifecycle eski provider kimliğiyle reconcile edilmeye devam etmelidir. ## Failure mode'lar ### Decommissioned access'i transient outage sanmak Sonsuz retry ve alarm noise üretir. Entitlement/retirement state'i ayrı sınıflandırın. ### Lossy offer reconstruction Pricing veya order creation için gereken segment/fare data kaybolur. Original payload/reference koruyun. ### Cached discovery'yi live inventory saymak Unsupported route boş görünür veya stale price transaction-ready sanılır. ### Order ile ticket'ı aynı state saymak PNR/order oluşur fakat consolidator ticket issuance tamamlanmaz. Ayrı lifecycle ve SLA gerekir. ### Hotel identity collision Amadeus hotel ID canonical ID olarak kullanılır ve başka supplier mapping'iyle yanlış property birleşir. ### Blind booking retry Timeout sonrası ikinci create duplicate reservation üretir. ## Monitoring ve KPI'lar ### Access ve migration - last successful legacy call, - auth/access-retired failures, - endpoint traffic remaining, - migration coverage by use case, - legacy dependency count. ### Shopping ve pricing - search success ve empty-result rate, - unsupported-content rate, - provider latency p50/p95, - offer-to-price success, - price-change/unavailable rate, - indicative/live share. ### Booking ve fulfillment - create-order/hotel-booking success, - unknown-state rate, - duplicate-prevented count, - confirmation retrieval success, - order-to-ticket time ve ticketing pending age, - reconciliation gap. ### Coverage - demand coverage by route/property, - fallback-provider usage, - provider-specific no-result share, - conversion by source and freshness class. ## Go-live veya migration checklist - Self-Service'in decommission durumu stakeholder'lara açık mı? - Mevcut production entitlement Amadeus ile doğrulandı mı? - Yeni development legacy portal erişimine dayanmıyor mu? - Test ve production credential'ları ayrıldı mı? - OAuth secret ve token yalnız backend'de mi? - Flight ve hotel normalized contract'ları ayrı mı? - Canonical ID ile Amadeus ID ayrıldı mı? - Original flight offer pricing/order'a kadar korunuyor mu? - Hotel search context ve payment policy saklanıyor mu? - Indicative cache ile live/transactional result ayrılıyor mu? - Price change kullanıcı reconfirmation gerektiriyor mu? - Booking attempt ve unknown-state recovery var mı? - Order ile ticketing lifecycle ayrıldı mı? - Coverage limitation boş availability'den ayrılıyor mu? - Legacy endpoint inventory ve replacement plan tamam mı? - Aktif booking/order'lar eski provider ID ile reconcile edilmeye devam ediyor mu? - PII/payment logging ve retention güvenli mi? ## Meta Search yorumu Amadeus Self-Service'in decommission edilmesi entegrasyon mimarisindeki temel dersi daha görünür yapar: provider endpoint'i product domain'iniz olmamalıdır. Canonical identity, normalized request, source offer lineage, booking attempt ve coverage state provider adapter dışında kaldığında supply kaynağını değiştirmek mümkün olur. Yeni karar noktası eski endpoint'i nasıl çağıracağınız değil, legacy bağımlılığı ölçülebilir biçimde nasıl kaldıracağınızdır.