Sioux Global Reservation API Dokümanı

Bu doküman, Sioux Global tarafından sağlanan Reservation API servisine bağlanacak istemci sistem için entegrasyon bilgilerini içerir.

1) Amaç ve Kapsam

Bu API yalnızca rezervasyon listeleme ve rezervasyon status güncelleme işlemleri için tasarlanmıştır.

Desteklenen işlemler

✅ Rezervasyonları listeleme (opsiyonel status ve hotelId filtresi ile)
✅ Rezervasyon status güncelleme
✅ Rezervasyon PDF çıktısı (otel formu)
✅ Otel listesi çekme (Id + HotelName)

Desteklenmeyen işlemler

❌ Yeni rezervasyon oluşturma (POST yok)
❌ Rezervasyon silme (DELETE yok)
❌ Rezervasyon bilgisi (detay) güncelleme (status dışında güncelleme yok)

2) Ortam ve Erişim Bilgileri

Production (Canlı)

Base URL: https://reservationapi.siouxglobal.com

Test

Base URL: https://reservationapi.codebw.com

Health Check

GET /healthz

3) Güvenlik Gereksinimleri (Zorunlu)

3.1 IP Allowlist (Zorunlu)

API yalnızca izin verilen istemci çıkış IP adreslerinden gelen istekleri kabul eder.

Hata durumu:

403 Forbidden

{"title":"Forbidden","status":403,"detail":"IP address is not allowed."}

3.2 API Key (Zorunlu)

Reservations endpoint’leri için her istekte aşağıdaki header zorunludur:

Header: X-Api-Key
Değer: Sioux Global tarafından iletilecek Production API Key (gizli bilgi)

Örnek:

X-Api-Key: <PROD_API_KEY>

Hata durumları:

Header yoksa: 401 Unauthorized / “Missing API key.”
Yanlışsa: 401 Unauthorized / “Invalid API key.”

4) İstek Formatı

JSON gönderilen isteklerde: Content-Type: application/json

Not (Alan Formatları): Aşağıdaki alanlar belirli kod/format standartlarına göre tutulur:

Nationality (Guest) → 2 karakter ülke kodu (ISO 3166-1 alpha-2). Örn: TR, DE, GB
CountryCode / Market→ 2 karakter ülke kodu (ISO 3166-1 alpha-2)
CurrencyCode → 3 karakter para birimi kodu (ISO 4217). Örn: USD, EUR, TRY, GBP
Tarih/saat alanları → ISO 8601 formatında döner. Örn: 2026-01-20T10:15:00

5) Status Değerleri

Rezervasyon durumları integer olarak tutulur. Aşağıdaki tablo, status kodlarının anlamlarını belirtir:

Status	Açıklama
`1`	Pending
`2`	New Reservation
`3`	Modification
`4`	Confirmed
`5`	Declined
`6`	Cancelled
`7`	Pending Cancellation

Not (Guests): Misafir kayıtlarındaki Gender alanı aşağıdaki değerleri alır:

1 = Mr.
2 = Ms.
3 = Child

6) Status Güncelleme Kuralları

6.1 İzinli Status Listesi

GET ve PUT işlemlerinde kullanılabilecek status değerleri yalnızca aşağıdakilerdir:

2, 3, 4, 5, 6, 7

Kural 1 (Geçersiz Status): İstek body içinde gönderilen status değeri bu liste dışında ise istek reddedilir.

Hata kodu: 400 Bad Request

Örnek Hata Yanıtı (Geçersiz Status):

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid status value. Allowed values: 2,3,4,5,6,7."
}

6.2 Kilit Kuralı

Kural 2 (Kilit): Rezervasyonun mevcut status değeri 4 (Confirmed) veya 6 (Cancelled) ise PUT işlemi yapılamaz.

Hata kodu: 409 Conflict

Kural 3 (Güncellenebilir Alanlar): Status güncelleme endpoint’i üzerinden aşağıdaki alanlar güncellenebilir:

Status (zorunlu)
Description (opsiyonel)
ConfirmedBy (opsiyonel)

Opsiyonel alanlar gönderilmezse mevcut değer korunur.

Özet: İstemci sadece izinli değerleri gönderir; ayrıca 4 (Confirmed) veya 6 (Cancelled) olan kayıtlar için PUT işlemi yapılamaz.

7) Endpoint’ler

7.1 Rezervasyon Listeleme

HTTP	`GET /api/reservations` `GET /api/reservations?hotelId={hotelId}` `GET /api/reservations?status={status}` `GET /api/reservations?status={status}&hotelId={hotelId}`
Query Parametre	`status` (opsiyonel, int): Sadece belirtilen status değerindeki rezervasyonları getirir. `hotelId` (opsiyonel, int): Sadece belirtilen otele ait rezervasyonları getirir.
Başarılı Yanıt	`200 OK` JSON array Yanıt alanları (minimum): `id` (int), `status` (int)

Not: GET /api/reservations (parametre verilmezse) yalnızca 2, 3, 7 status değerindeki kayıtları döner.

Not (hotelId): GET /api/reservations?hotelId={hotelId} isteğinde status parametresi verilmezse yalnızca 2, 3, 7 status değerindeki kayıtlar döner.

Örnek curl (status):

curl -k "https://reservationapi.siouxglobal.com/api/reservations?status=2" \
  -H "X-Api-Key: <PROD_API_KEY>"

Örnek curl (hotelId):

curl -k "https://reservationapi.siouxglobal.com/api/reservations?hotelId=123" \
  -H "X-Api-Key: <PROD_API_KEY>"

Örnek curl (status + hotelId):

curl -k "https://reservationapi.siouxglobal.com/api/reservations?status=2&hotelId=123" \
  -H "X-Api-Key: <PROD_API_KEY>"

Örnek curl (parametre yok):

curl -k "https://reservationapi.siouxglobal.com/api/reservations" \
  -H "X-Api-Key: <PROD_API_KEY>"

7.2 Rezervasyon Status Güncelleme

HTTP	`PUT /api/reservations/{id}/status`
Path Parametre	`id` (int): Rezervasyon Id
Güncellenebilir Alanlar	`Status` (zorunlu) `Description` (opsiyonel) `ConfirmedBy` (opsiyonel)
Request Body	`{ "status": 6 }` Genişletilmiş Örnek (Opsiyonel Alanlar ile): `{ "status": 6, "description": "Reservation cancelled by operator.", "confirmedBy": "OperatorName" }` Not: `description` ve `confirmedBy` opsiyoneldir. Gönderilmezse mevcut değer korunur.
Başarılı Yanıt	`204 No Content`

7.3 Rezervasyon PDF Çıktısı (Otel Formu)

HTTP	`GET /api/reservations/{id}/hotel-pdf`
Path Parametre	`id` (int): Rezervasyon Id
Header	`X-Api-Key: <PROD_API_KEY>` (zorunlu) IP Allowlist uygulanır.
Başarılı Yanıt	`200 OK` `Content-Type: application/pdf` Response body: PDF binary
Hata Durumları	`404 Not Found` → Rezervasyon bulunamadı `401 Unauthorized` → API Key yok/yanlış `403 Forbidden` → IP allowlist dışı

Örnek curl (PDF indir):

curl -k -L "https://reservationapi.siouxglobal.com/api/reservations/123/hotel-pdf" \
  -H "X-Api-Key: <PROD_API_KEY>" \
  -o reservation_123.pdf

7.4 Otel Listesi (Id + HotelName)

HTTP	`GET /api/reservations/hotels`
Header	`X-Api-Key: <PROD_API_KEY>` (zorunlu) IP Allowlist uygulanır.
Başarılı Yanıt	`200 OK` JSON array Yanıt alanları: `id` (int), `hotelName` (string)
Örnek Yanıt	`[ { "id": 1, "hotelName": "Hotel A" }, { "id": 2, "hotelName": "Hotel B" } ]`

Örnek curl (otel listesi):

curl -k "https://reservationapi.siouxglobal.com/api/reservations/hotels" \
  -H "X-Api-Key: <PROD_API_KEY>"

8) İş Kuralları – Kilit (Confirmed / Cancelled)

Kilit kuralı status update işlemi için geçerlidir.

Kural:

Rezervasyonun mevcut status değeri 4 (Confirmed) veya 6 (Cancelled) ise PUT işlemi yapılamaz.

Hata durumu:

409 Conflict

{
  "title": "Conflict",
  "status": 409,
  "detail": "Reservation is locked (Status=4 or Status=6). Update is not allowed."
}

9) Health Check

HTTP	`GET /healthz`
Güvenlik	✅ IP Allowlist uygulanır ❌ X-Api-Key gerekmez
Başarılı Yanıt	`200 OK` — Body: `"OK"`

10) Hata Kodları (Özet)

200 OK → Listeleme başarılı
204 No Content → Status güncelleme başarılı
400 Bad Request → İstek formatı/parametre hatası (ör. izinli status listesi dışında değer)
401 Unauthorized → API Key yok veya yanlış
403 Forbidden → IP allowlist dışı
404 Not Found → Rezervasyon bulunamadı
409 Conflict → Kilit kuralı nedeniyle güncelleme reddedildi

11) Paylaşım Notu (Önemli)

<PROD_API_KEY> gizli bilgidir; public repo, mail zinciri veya ticket içine açık şekilde yazılmamalıdır.
İstemci IP bilgisi netleştiğinde Sioux Global ekibine iletilmelidir.