RoomFollow · iOS / Mobile API

Oteliniz, aynı yetkilerle mobilde.

Mobil uygulama partner anahtarı kullanmaz. Otel kullanıcısının oturumu, aktif tesisi ve rolü üzerinden çalışır.

Temel adres ve erişim

Mobile APIUTF-8

https://app.roomfollow.com/api/mobile/v1

1. Kullanıcı oturumu açın

POST /auth/login · JSONUTF-8

{
  "hotelCode": "RF-EXAMPLE",
  "email": "personel@example.com",
  "password": "<KULLANICI_PAROLASI>",
  "deviceId": "<CIHAZ_UUID>",
  "deviceName": "iPhone"
}

RF kodu veya tesis kodu, e-posta ve parola doğrulanır. Mobil girişte yalnız e-posta kabul edilir; web panelindeki otel kullanıcı adı burada kullanılmaz. Aktif kullanıcı, aktif tesis üyeliği ve geçerli otel hesabı gerekir. Örnekler sentetiktir; gerçek parola veya kimlik bilgilerini dokümantasyona yazmayın.

E-posta doğrulaması etkinse yanıt challengeId, maskedEmail ve expiresAt içerir. Ardından POST /auth/verify gövdesine challengeId, code, deviceId ve deviceName gönderin. Doğrulama kapalıysa giriş doğrudan tokens ve profile döndürür; bu durumda deviceId giriş isteğinde zorunludur. Otel hesaplarında e-posta doğrulaması şu an varsayılan olarak kapalıdır; istemciler iki yanıt biçimini de desteklemelidir.

Başarılı oturum · yanıtın ilgili alanlarıUTF-8

{
  "tokens": {
    "accessToken": "<ACCESS_TOKEN>",
    "refreshToken": "<REFRESH_TOKEN>",
    "expiresIn": 900
  },
  "profile": {
    "userId": "<USER_ID>",
    "activePropertyId": "<PROPERTY_ID>",
    "properties": [
      {
        "id": "<PROPERTY_ID>",
        "code": "EXAMPLE",
        "name": "Örnek Otel",
        "permissions": [
          "<ROL_YETKILERI>"
        ]
      }
    ]
  }
}

2. Yetkili sorgu gönderin

DashboardUTF-8

curl https://app.roomfollow.com/api/mobile/v1/dashboard \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Tesis kapsamı oturumdan belirlenir. URL veya gövdeye başka bir tesis kimliği eklemek erişim hakkı vermez. Görüntüleme ve yazma yetkileri sunucuda ayrıca denetlenir.

3. Oturumu yenileyin ve kapatın

Access token 15 dakika geçerlidir. POST /auth/refresh için {"refreshToken":"<REFRESH_TOKEN>"} gönderin. Yeni refresh token döndüğünde eskisini atomik olarak değiştirin; eşzamanlı yenileme yapmayın. Oturum en fazla 30 günlüktür; yenileme bu mutlak süreyi uzatmaz. POST /auth/logout geçerli Bearer oturumunu iptal eder.

Operasyon sözleşmeleri

GET

/forecast?year=2026&month=9&includeOptions=true

Aylık forecast; rapor okuma yetkisi gerekir.

POST

/reports

Gövde: reportId, start, end (YYYY-MM-DD). Yanıt: ok, runId, name, rowCount, columns, rows, truncated. En çok 60 önizleme satırı; bu uç PDF dosyası döndürmez. catalogCode ile çağrıda yalnızca GET /reports?catalog=reference listesindeki raporlar çalışır; form alanları aynı adla gövdeye eklenir. Satır hücreleri görüntü etiketidir (ör. "Otelde"); durum kodları diğer uçlarda değişmez. Henüz hazırlanan rapor 400 report_not_ready döner.

POST

/night-audit

Gövde: expectedBusinessDate (YYYY-MM-DD). Önce GET ile ön kontrolleri gösterin; açık kullanıcı onayı ve gün sonu yetkisi olmadan çağırmayın.

POST

/identity-scan

multipart/form-data: documentType ve images. TC_KIMLIK için ön/arka iki fotoğraf; PASSPORT için tek fotoğraf. JPEG, PNG, WebP; fotoğraf başına en çok 6 MiB. Check-in yetkisi gerekir. Yanıt okunan alanları, confidence (0-100) ve uncertainFields listesini döner: MRZ kontrol hanesiyle doğrulanamayan veya basılı alanla çelişen alanlar bu listededir ve kullanıcıya belgeyle karşılaştırtılmalıdır. Okunamayan fotoğrafta 422 identity_scan_failed nedeni (karanlık, parlama, bulanıklık) açıklar. Uzun kenarı 2000 px civarı bir JPEG yeterlidir; daha büyük fotoğraf yalnız yüklemeyi uzatır.

Rezervasyon oluşturma

Önce GET /reservations/options ile gerçek tesis seçeneklerini alın. POST /reservations gövdesinde holderName, arrivalDate, departureDate, roomTypeId, ratePlanId, adults, totalMinor ve currency kullanılır. Opsiyonel alanlar arasında children, roomId, boardType, source, status ve notes bulunur. Tarihler YYYY-MM-DD, parasal tutarlar en küçük para birimi cinsindedir (ör. 10000 = 100,00). Yetki, tarih, oda ve fiyat doğrulamalarını sunucu yapar.

Kanal komutu: taslak ve gönderim ayrımı

GET /channels için rate.read gerekir. Yanıttaki companies ve summary.channels, artık şirket adı veya acente türünden tahmin edilmez: yalnız etkin CHANNEL_HUB bağlantısının aynı tesise ait etkin COMPANY eşlemesi, dolu uzak kimliği ve tanınan metadata.channelCode olan hedefler döner. Kanal adı ve kodu standartlaştırılır; eski komut geçmişi silinmez.

POST /channels · bağlantı olmadan yerel taslakUTF-8

{
  "startDate": "2026-10-01",
  "endDate": "2026-10-03",
  "queueNow": false,
  "targetCompanyIds": [],
  "description": "Örnek kontenjan hazırlığı",
  "lines": [
    {
      "roomTypeId": "<ROOM_TYPE_ID>",
      "allotment": 2
    }
  ]
}

rate.update yetkisiyle geçerli yerel oda ve kurallar için boş hedefli taslak kaydedilebilir; dış gönderim üretilmez. Başarılı yanıt {"ok":true,"id":"<COMMAND_ID>","number":"<COMMAND_NUMBER>","status":"DRAFT"}biçimindedir. Hedef belirtilirse taslakta da doğrulanır. Tarihler YYYY-MM-DD, satır alanları roomTypeId, priceMinor, allotment, minStay, maxStay ve stopSale olabilir; priceMinor en küçük para birimi cinsindedir; ana para birimindeki ondalık tutarla karıştırılmamalıdır.

queueNow: true ayrıca integration.operate ve en az bir doğrulanmış etkin kanal hedefi gerektirir. Boş hedef 400 channel_required, geçersiz/eski test hedefi veya ortak servis doğrulama hatası 400 channel_command_invalid döndürür. Kuyruğa alınmak OTA teslim edildiği anlamına gelmez. Bu uç web ile aynı createChannelCommand kurallarını kullanır.

Hatalar

JSON hata zarfıUTF-8

{"error":{"code":"unauthorized","message":"Oturum bulunamadı.","requestId":"<REQUEST_ID>"}}

401: oturum; 403: yetki; 400/422: geçersiz veri; 404: erişilebilir kayıt bulunamadı; 409: işlem çakışması; 429: hız sınırı. Başarılı ve hatalı mobil JSON yanıtları no-store ile gönderilir. Ağ geçidi kaynaklı hata yanıtları farklı formatta olabilir.

Tüm mobil uçları inceleyin →