Kanal API geliştirici belgesi

1. Giriş

Platform, turizm acentelerinin otel ve tur satışını yönettiği bir hizmettir. Kanal API ile bir kanal yöneticisi (CM) ya da otel yönetim sistemi, acentenin sattığı otelin fiyat, müsaitlik ve kısıtlarını bize iter; biz de o otelde oluşan rezervasyonları kanal yöneticisine bildiririz.

Bağlantı acente × otel başınadır: her bağlantının kendi otel kodu (hotel_code), API anahtarı ve bildirim adresi vardır. Bir kanal yöneticisi birçok acenteye bağlanabilir; her acente kendi bağlantısını panelinden açar.

• Ortamlar: test ve canlı. Test bağlantısında gelen değişiklikler uygulanır ve bildirimler test=true taşır.
• Başvuru ve destek: bağlantıyı açan acente üzerinden; destek isteğinde yanıtın X-Request-Id değerini verin.

2. Hızlı başlangıç

• Acente panelde Entegrasyonlar › Kanal yöneticisi ekranında bağlantıyı açar; API anahtarı ve otel kodu bir kez gösterilir, size güvenli yoldan iletilir.
• İlk çağrı GET test_connection?hotel_code=… olur: bağlantı eşleme beklemeye geçer.
• GET mapping_details?hotel_code=… acentenin kanala açtığı oda ve plan kodlarını verir; kendi kodlarınızı bunlara eşleyin.
• POST changes ile tam eşitleme gönderin (full_sync, sync_id, sync_part, sync_last); ardından yalnız değişiklikleri (delta) gönderin.
• Acente bildirim adresinizi yazar ve test bildirimi gönderir; kabul ettiğinizde bağlantı rezervasyon almaya hazırdır.

curl -H 'api-key: kyk_test_…' 'https://api.<platform>/api/kanal/v1/test_connection?hotel_code=01HZXK4M8Q2W3E5R7T9Y'

3. Kimlik ve güvenlik

• Anahtar api-key başlığında ya da Authorization: Bearer ile gelir; ikisi birden gelirse aynı olmalıdır.
• Anahtar döndürmede eski ve yeni anahtar bir süre birlikte geçer; iptal edilen anahtar hemen 401 alır.
• Aynı adresten 5 dakikada 20 başarısız kimlik denemesi o adresi 15 dakika engeller.
• Bağlantıya IP izin listesi yazılabilir; liste dışı adres 403 ip_not_allowed alır.
• Bildirimlerimiz imzalıdır (bölüm 6): imzayı her istekte doğrulayın, zaman damgası ±300 sn dışındaysa reddedin, karşılaştırmayı sabit zamanlı yapın.

4. Kanonik model

• Oda envanteri: bağlantı × oda tipi × gün müsaitliği (availability_changes, rate_plan_id olmadan).
• Plan hücresi: bağlantı × oda tipi × plan × gün; fiyat (per_room için rate, per_person için doluluk başına rates), plan düzeyi müsaitlik, stop_sell, closed_to_arrival, closed_to_departure, min_stay_arrival, min_stay_through, max_stay.
• Delta: yalnız gönderilen alan değişir; kısıt kaldırma asgari konaklamada 0, azamide 0 ile yapılır.
• Ufuk 750 gündür; dünden eski gün yok sayılır (past_date_ignored), ufuk dışı gün yok sayılır (beyond_horizon_ignored).
• Tutar ondalıklı sayıdır (ana birim) ya da fraction_size ile tamsayı; kuruştan küçük kesir reddedilir. Para birimi bağlantınınkiyle aynı olmalıdır.
• Türetilmiş fiyat (ör. yüzde indirim kuralı) yoktur: her hücrenin fiyatını gönderin.

5. Uç başvurusu

Taban adres https://api.<platform>/api/kanal/v1'dir; sonda eğik çizgili ve çizgisiz yol yönlendirmesiz kabul edilir. Alan tabloları ve örnekler OpenAPI dosyasındadır.

Yanıt zarfı: success, request_id; başarıda uç yükü; hatada errors[] (ilk satır istek düzeyi kod) ve gerekirse warnings[]. Her yanıtta X-Request-Id ve X-Kanal-Api-Version başlıkları vardır.

Öğe düzeyi uyarılar (200 içinde): öğeyi uygulatmayanlar unmapped_room_type, unmapped_rate_plan, read_only_rate_plan, currency_mismatch, sell_mode_mismatch, occupancy_out_of_range, invalid_amount, invalid_restriction, invalid_date_range; bilgi uyarıları past_date_ignored, beyond_horizon_ignored, duplicate_cell_in_request, stale_sequence_ignored.

6. Rezervasyon bildirimleri

Rezervasyonun her revizyonu (booking.new, booking.modified, booking.cancelled) bildirim adresinize imzalı POST olarak gelir. Bir rezervasyonun revizyonları sırayla gider; önceki revizyon teslim edilmeden sonraki gönderilmez.

• Yanıtınız: decision accepted | rejected | received; accepted ile cm_reservation_id, rejected ile reject_reason (full, price, date, restriction, mapping, closed, other) ve isteğe bağlı note. Kararsız 2xx "alındı" sayılır; kararı sonra ACK ucuyla verin.
• Yeniden deneme: 429'da Retry-After kadar, 5xx ve zaman aşımında üstel geri çekilmeyle (5 sn'den 1 saate); 24 saat içinde teslim edilemeyen revizyon teslim edilemedi olur.
• Karar vermeden alındı dediğiniz revizyon 15 dakikada bir yeniden itilir; 60 dakika sonra acentenin onay bekleyenler listesine düşer.
• Idempotency-Key revizyon kimliğidir ve her denemede aynıdır: aynı anahtara aynı kararı döndürün.
• Test bildirimi (connection.test) ve tam eşitleme isteği (ari.full_sync_requested) de aynı adrese aynı imzayla gelir.

İmza: X-Kanal-Signature başlığı v1=<onaltılık HMAC-SHA256> taşır (sır döndürmede virgülle birden çok). Kanonik dizge satır sonuyla birleşen şu satırlardır; sonda satır sonu yoktur:

KANAL1-HMAC-SHA256
<YÖNTEM>
<yol ve sorgu>
<X-Kanal-Timestamp>
<Idempotency-Key>
<content-type, küçük harf>
<gövdenin SHA-256'sı, onaltılık>

Kart ve teminat verisi gönderilmez; tahsilatı acente yapar. Misafirin e-posta ve telefonu yalnız acente bağlantıda izin verdiyse gelir.

7. İsteğe bağlı yetenekler

• Canlı müsaitlik kontrolü: bağlantıda kontrol adresi varsa satıştan önce availability_check isteği gelir; available=false ya da farklı amount satışı durdurur.
• sequence: gönderdiğiniz kesin artan sayı; daha küçük sequence'lı istek daha yeni değeri ezmez (stale_sequence_ignored).
• Tam eşitleme dizisi: sync_id ile parçalayın, son parçada sync_last=true gönderin; kapsanmayan hücreler eski sayılır ve satılmaz.
• Tutma (hold) v1'de yoktur.

8. İdempotens, sıra ve sürüm

• Her changes isteğinin request_id'si tekildir: aynı gövdeyle tekrar ilk yanıtı döndürür (Idempotent-Replay: true), farklı gövdeyle 409 idempotency_conflict.
• Kabul edilen istek version (bağlantının olay numarası) alır ve kuyruğa girer; uygulama birkaç saniye içinde tamamlanır (p95 ≤ 10 sn).
• Aynı hücrenin fiyat, kısıt ve müsaitlik grupları ayrı sürümlenir: eski sürüm yenisini ezmez.

9. Hız sınırları ve iyi davranış

• Gövde en çok 10.485.760 bayt (gzip açıldıktan sonra da); istekte en çok 200.000 hücre-gün; öğe tarih aralığı en çok 750 gün.
• IP başına dakikada 600 istek; uç kovaları bölüm 5'teki tablodadır. 429'da Retry-After kadar bekleyin.
• Yalnız değişikliği gönderin; tam eşitlemeyi yalnız ilk bağlantıda, eşleme değişince ve istendiğinde yapın.
• 401 ve 403'te aynı isteği yeniden denemeyin; yapılandırmayı düzeltin.

10. Sürümleme ve kullanımdan kaldırma

Yol ana sürümü taşır (v1). v1 içinde yalnız geriye uyumlu değişiklik yapılır (yeni isteğe bağlı alan, yeni uyarı kodu, yeni uç); bilinmeyen yanıt alanlarını yok sayın. Kırıcı değişiklik /v2/ yolunda açılır ve v1 en az 12 ay birlikte çalışır; kaldırma Deprecation ve Sunset başlıkları, bu belge ve panel duyurusuyla bildirilir. test_connection desteklenen ana sürümleri, bildirim yükü schema_version alanını taşır.

• 1.0 — ilk sürüm: test_connection, mapping_details, changes, booking_revisions, ACK, imzalı bildirimler ve canlı kontrol.

11. Sertifikasyon

Bağlanan her kanal yöneticisi aşağıdaki adımları test ortamında tamamlar; geçen kanal yöneticisinin bağlantısı canlı ortama alınabilir.

12. Sorun giderme

• unmapped_room_type ya da unmapped_rate_plan: kod mapping_details'te yok; acente eşlemeyi tamamlamalı ya da kodunuzu düzeltmelisiniz.
• sell_mode_mismatch: per_room plana rates ya da per_person plana rate gönderildi.
• currency_mismatch: öğenin para birimi bağlantınınkiyle aynı değil.

13. Hukuki ve veri

• Kart verisi hiçbir uçta ve bildirimde yoktur.
• Kişisel veri asgaridir: misafir adı ve soyadı; iletişim bilgisi yalnız acentenin izniyle.
• Kişisel veri işleme ve yurt dışına aktarım koşulları acenteyle yapılan sözleşmededir.