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 filtresi ile)
✅ Rezervasyon status güncelleme

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

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

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`	Sent
`3`	Modification
`4`	Confirmed
`5`	Declined
`6`	Cancelled
`7`	Pending Cancellation
`8`	Sent Resbox

6) Status Güncelleme Kuralları

6.1 İzinli Status Listesi

Status update işleminde gönderilebilecek status değerleri yalnızca aşağıdaki listedeki değerlerdir:

1, 2, 3, 4, 5, 6, 7, 8

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: 1,2,3,4,5,6,7,8."
}

6.2 Cancelled Kilidi

Kural 2 (Cancelled Kilidi): Rezervasyonun mevcut status değeri 6 (Cancelled) ise status başka bir değere değiştirilemez.

Hata kodu: 409 Conflict

Özet: İstemci sadece izinli değerleri gönderir; ayrıca Cancelled olan kayıtlar değiştirilemez.

7) Endpoint’ler

7.1 Rezervasyon Listeleme

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

Örnek curl:

curl -k "https://reservationapi.siouxglobal.com/api/reservations?status=1" \
  -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
Request Body	`{ "status": 6 }`
Başarılı Yanıt	`204 No Content`

Örnek curl:

curl -k -X PUT "https://reservationapi.siouxglobal.com/api/reservations/123/status" \
  -H "X-Api-Key: <PROD_API_KEY>" \
  -H "Content-Type: application/json" \
  -d "{\"status\":6}"

8) İş Kuralları – Cancelled (İptal) Kilidi

Cancelled kilidi status update işlemi için geçerlidir.

Sistemde Cancelled durumunun integer karşılığı:

CancelledValue: 6

Kural:

Rezervasyonun mevcut status değeri 6 (Cancelled) ise, status başka bir değere değiştirilemez.
Sadece tekrar 6 gönderilirse idempotent olarak kabul edilir (204 No Content).

Hata durumu:

409 Conflict

{
  "title": "Conflict",
  "status": 409,
  "detail": "Reservation is cancelled (Status=6). Status cannot be changed."
}

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 → Cancelled kilidi nedeniyle değişim 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.