Entegrasyon API — Poyraz Network Dokümantasyon

Kimlik doğrulama

Her istekte Authorization başlığına Bearer token ekleyin. Token formatı pn_live_ ile başlar.

Ortam değişkenleri

export POYRAZ_API_KEY="pn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export API_BASE="https://hotspot.poyraznetwork.com"

curl -sS -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/devices"

Temel URL

Tüm entegrasyon endpoint'leri aşağıdaki önek altındadır:

text

https://hotspot.poyraznetwork.com/api/v1/integration

İstekler HTTPS üzerinden yapılmalıdır. JSON gövdesi gönderirken Content-Type: application/json kullanın.

Hatalar ve limitler

Hata yanıtları JSON formatındadır; message alanında Türkçe açıklama döner.

HTTP	Anlam	Tipik neden
401	Kimlik doğrulama başarısız	Eksik/hatalı token, iptal edilmiş anahtar
403	Yetkisiz	Kurumsal plan yok, otel modu kapalı (pms_reception), tenant dışı
409	Çakışma	Aktif guest_ref veya username kullanımda
429	Çok fazla istek	Rate limit (~60/dk genel, log export ~5/saat)
400	Geçersiz istek	Hatalı JSON, geçersiz tarih formatı

Örnek 403 yanıtı

{
  "error": true,
  "message": "API erişimi Kurumsal planda mevcuttur. Plan yükseltmesi için yönetici panelinden faturalandırmaya gidin."
}

Cihazlar

Tenant'a bağlı MikroTik cihazlarını listeler ve detay döner.

GET/integration/devices

Cihaz listesi

Tüm aktif MikroTik cihazlarınızı JSON dizisi olarak döner.

Örnek istek

bash

curl -sS -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/devices"

Yanıt: JSON — cihaz id, ad, konum, API host, durum alanları.

GET/integration/devices/:id

Cihaz detayı

Belirtilen UUID'ye sahip tek cihazın detayını döner.

Parametre	Tür	Açıklama
idzorunlu	uuid	Cihaz kimliği (panelden veya listeden)

Örnek istek

bash

curl -sS -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/devices/CİHAZ_UUID"

Oturumlar

Aktif RADIUS oturumlarını izleyin ve gerektiğinde kesin.

GET/integration/sessions

Aktif oturumlar

Şu anda bağlı misafir oturumlarını listeler.

Örnek istek

bash

curl -sS -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/sessions"

POST/integration/sessions/:id/disconnect

Oturumu kes

Belirtilen oturumu CoA/PoD ile sonlandırır. Erken check-out veya kota yönetimi için kullanılır.

Parametre	Tür	Açıklama
idzorunlu	string	Oturum kimliği (acctsessionid)

Örnek istek

bash

curl -sS -X POST -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/sessions/OTURUM_ID/disconnect"

Misafir hesapları (basit mod)

RADIUS kullanıcıları — doğrudan oda hesabı açmak için kullanılır. Otel PMS entegrasyonu için önerilen yol aşağıdaki guest-stays API'dir; bu endpoint'ler legacy / basit mod olarak kalır.

GET/integration/radius/users

Kullanıcı listesi

Tenant'a ait tüm misafir RADIUS hesaplarını listeler.

Örnek istek

bash

curl -sS -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/radius/users"

POST/integration/radius/users

Kullanıcı oluştur

Yeni misafir Wi‑Fi hesabı açar. Check-in anında PMS tarafından çağrılır.

Parametre	Tür	Açıklama
usernamezorunlu	string	Benzersiz kullanıcı adı (ör. oda-305)
passwordzorunlu	string	Wi‑Fi şifresi
profile	string	RADIUS profil adı; boşsa varsayılan profil

Örnek istek

bash

curl -sS -X POST -H "Authorization: Bearer $POYRAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "oda-305",
    "password": "Rz8kP2mN",
    "profile": "otel-misafir"
  }' \
  "$API_BASE/api/v1/integration/radius/users"

PUT/integration/radius/users/:username

Kullanıcı güncelle

Şifre veya profil günceller.

Örnek istek

bash

curl -sS -X PUT -H "Authorization: Bearer $POYRAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password": "yeni-şifre", "profile": "otel-misafir"}' \
  "$API_BASE/api/v1/integration/radius/users/oda-305"

DELETE/integration/radius/users/:username

Kullanıcı sil

Misafir hesabını kaldırır. Check-out anında PMS tarafından çağrılır.

Örnek istek

bash

curl -sS -X DELETE -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/radius/users/oda-305"

Analitik

GET/integration/analytics

KPI özeti

Oturum sayısı, benzersiz kullanıcı, trafik ve saatlik yoğunluk gibi panel analitiğiyle aynı özet verileri döner.

Parametre	Tür	Açıklama
days	integer	Geriye dönük gün (1–365, varsayılan 30)
nas	string	Belirli NAS IP filtresi

Örnek istek

bash

curl -sS -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/analytics?days=30"

Uyumluluk

GET/integration/compliance/alerts

5651 uyarıları

Log kesintisi, imzasız arşiv ve benzeri uyumluluk uyarılarını listeler.

Örnek istek

bash

curl -sS -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/compliance/alerts"

Log export

GET/integration/logs/export.csv

Ham log CSV

Belirtilen tarih aralığındaki ham logları CSV olarak indirir. Aralık zorunludur ve en fazla 92 gün olabilir; 100.000 satırı aşan istekler 413 döner.

Parametre	Tür	Açıklama
fromzorunlu	date	Başlangıç — YYYY-MM-DD veya RFC3339
tozorunlu	date	Bitiş — YYYY-MM-DD veya RFC3339 (gün dahil)

Örnek istek

bash

curl -sS -H "Authorization: Bearer $POYRAZ_API_KEY" \
  -o logs.csv \
  "$API_BASE/api/v1/integration/logs/export.csv?from=2026-07-01&to=2026-07-26"

Yanıt: text/csv dosyası — ts, kind, src_ip, username, raw_message sütunları.

Otel kurulumu (panel)

PMS entegrasyonundan önce işletme tarafında aşağıdaki adımlar tamamlanmalıdır. API yazma işlemleri yalnızca Kurumsal plan ve wifi_identity_mode = pms_reception iken çalışır.

Adım	Panel	Açıklama
1	Yönetim → API	`pn_live_` anahtarı oluşturun
2	Wi‑Fi kimlik modu	Otel — resepsiyon / PMS seçin
3	5651 Uyum	PMS kimlik beyanını (Madde 4/c) işaretleyin
4	PMS / middleware	Check-in ve check-out olaylarını guest-stays API'ye bağlayın
5	Konaklamalar	Aktif oda kayıtlarını ve entegrasyonu doğrulayın

Guest-stays API

Otel PMS entegrasyonunun ana sözleşmesi. Check-in'de RADIUS hesabı ve konaklama kaydı atomik oluşturulur; oturum logları oda ve guest_ref ile denetimde birleştirilir.

POST/integration/guest-stays

Check-in

RADIUS kullanıcısı + guest_stays kaydı oluşturur. Şifre boşsa sunucu üretir; username varsayılan oda-{room}.

Parametre	Tür	Açıklama
roomzorunlu	string	Oda numarası
guest_refzorunlu	string	PMS rezervasyon ID; aynı anda tek aktif kayıt
check_in_atzorunlu	datetime	RFC3339 veya YYYY-MM-DD
check_out_atzorunlu	datetime	Check-in'den sonra olmalı
password	string	Wi‑Fi şifresi; boşsa otomatik
profile	string	RADIUS profil adı
guest_label	string	Kısa etiket (ör. A.Y.)
username	string	Override; varsayılan oda-{room}

Örnek istek

bash

curl -sS -X POST -H "Authorization: Bearer $POYRAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "room": "305",
    "guest_ref": "RES-2026-88421",
    "guest_label": "A.Y.",
    "check_in_at": "2026-07-26T14:00:00Z",
    "check_out_at": "2026-07-28T11:00:00Z"
  }' \
  "$API_BASE/api/v1/integration/guest-stays"

Yanıt: 201 — guest_stay, username, password (yalnızca oluşturma anında).

GET/integration/guest-stays

Konaklama listesi

Filtreler: status (active|checked_out|cancelled), room, guest_ref.

Örnek istek

bash

curl -sS -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/guest-stays?status=active"

GET/integration/guest-stays/:id

Konaklama detayı

UUID ile tek kayıt.

PATCH/integration/guest-stays/:id

Güncelle

Oda değişimi, checkout uzatma, şifre/profil. Yalnızca active kayıtlar.

Parametre	Tür	Açıklama
room	string	Yeni oda
check_out_at	datetime	Çıkış uzatma
password	string	Yeni Wi‑Fi şifresi
profile	string	RADIUS profil
guest_label	string	Etiket

POST/integration/guest-stays/:id/checkout

Check-out (ID)

RADIUS hesabını siler, status=checked_out. RADIUS silme başarısızsa hata döner.

DELETE/integration/guest-stays/by-ref/:guest_ref

Check-out (PMS ref)

Rezervasyon referansı ile kapatma shortcut.

Örnek istek

bash

curl -sS -X DELETE -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/guest-stays/by-ref/RES-2026-88421"

GET/integration/audit/guest-sessions.csv

Denetim CSV

RADIUS oturumları + oda + guest_ref birleşimi. Otel 5651 denetiminde öncelikli export.

Parametre	Tür	Açıklama
fromzorunlu	date	YYYY-MM-DD veya RFC3339
tozorunlu	date	Bitiş tarihi

Örnek istek

bash

curl -sS -H "Authorization: Bearer $POYRAZ_API_KEY" \
  -o guest-sessions.csv \
  "$API_BASE/api/v1/integration/audit/guest-sessions.csv?from=2026-07-01&to=2026-07-26"

Yanıt: CSV: session_start, session_stop, username, room, guest_ref, guest_label, mac, framed_ip, nas_ip

Otel PMS entegrasyonu

Tipik entegrasyon akışı ve PMS olay eşlemesi. API referansı için Guest-stays API ve kurulum için Otel kurulumu bölümlerine bakın.

PMS olayı	API çağrısı
Check-in tamamlandı	POST /integration/guest-stays
Oda değişti	PATCH /integration/guest-stays/:id
Çıkış uzatıldı	PATCH (check_out_at)
Check-out	DELETE .../by-ref/:guest_ref
Erken çıkış + anında kes	GET /sessions → POST disconnect → checkout

1. Check-in (guest-stays)

Oda, PMS rezervasyon referansı ve çıkış saati ile RADIUS hesabı + konaklama kaydı oluşturulur. Şifre boş bırakılırsa sunucu üretir.

bash

curl -sS -X POST -H "Authorization: Bearer $POYRAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "room": "305",
    "guest_ref": "RES-2026-88421",
    "guest_label": "A.Y.",
    "password": "Rz8kP2mN",
    "profile": "otel-misafir",
    "check_in_at": "2026-07-26T14:00:00Z",
    "check_out_at": "2026-07-28T11:00:00Z"
  }' \
  "$API_BASE/api/v1/integration/guest-stays"

2. Check-out

Konaklamayı kapatır ve RADIUS hesabını siler.

bash

# ID ile
curl -sS -X POST -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/guest-stays/KONAKLAMA_UUID/checkout"

# PMS rezervasyon ref ile (shortcut)
curl -sS -X DELETE -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/guest-stays/by-ref/RES-2026-88421"

3. Denetim export (5651)

RADIUS oturumlarını oda ve guest_ref ile birleştirir. Ham syslog export yerine otel denetimlerinde bunu kullanın.

bash

curl -sS -H "Authorization: Bearer $POYRAZ_API_KEY" \
  -o guest-sessions.csv \
  "$API_BASE/api/v1/integration/audit/guest-sessions.csv?from=2026-07-01&to=2026-07-26"

Guest-stays endpoint özeti

GET/integration/guest-stays

Konaklama listesi

Filtre: status, room, guest_ref

Örnek istek

bash

curl -sS -H "Authorization: Bearer $POYRAZ_API_KEY" \
  "$API_BASE/api/v1/integration/guest-stays?status=active"

PATCH/integration/guest-stays/:id

Konaklama güncelle

Oda değişimi, checkout uzatma, şifre yenileme

Legacy — basit radius/users

Oda/rezervasyon metadata olmadan yalnızca RADIUS hesabı açmak için (önerilmez):

bash

curl -sS -X POST -H "Authorization: Bearer $POYRAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"oda-305","password":"Rz8kP2mN","profile":"otel-misafir"}' \
  "$API_BASE/api/v1/integration/radius/users"

Güvenlik önerileri

•Anahtarları ortam değişkeninde veya gizli kasada saklayın; kaynak koduna yazmayın.
•Her entegrasyon (PMS, raporlama, otomasyon) için ayrı anahtar oluşturun.
•Kullanılmayan anahtarları panelden iptal edin.
•Tüm API anahtarları tenant_admin düzeyinde yetki taşır; read-only anahtar ayrımı yoktur.