FOM Platform
Front Office Management
v1.0.0 • REST API

API Dokümantasyonu

FOM Platform REST API ile otel yönetim sisteminizi genişletin

Tüm endpoint'ler, parametreler, örnek istekler ve yanıtlar. JWT tabanlı kimlik doğrulama, rate limiting ve webhook desteği.

Hızlı Başlangıç API Referansı
Base URL https://api.fom.services/v1
Auth Bearer <JWT>
Rate Limit 1000 req/min
Version v1 (latest)
Authentication
Revenue
Orders
Tips
Inventory
Staff
Customers
Analytics
Webhooks
Hatalar
Rate Limits

Hızlı Başlangıç

API'yi 5 dakikada entegre edin

1

API Anahtarı Al

Geliştirici portalından ücretsiz API anahtarınızı oluşturun. Her anahtar size özel rate limit ve kullanım hakları sağlar.

API Anahtarı Oluştur
2

Kimlik Doğrulama

JWT token almak için `/auth/token/` endpoint'ine istek yapın. Token'ı Authorization header'ında kullanın. 

curl -X POST https://api.fom.services/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your_api_key"}'
3

İlk İsteğinizi Yapın

Aldığınız token ile korumalı endpoint'lere erişin. Örnek: son 24 saatin gelir özeti. 

curl -X GET https://api.fom.services/revenue/summary \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Authentication

JWT tabanlı kimlik doğrulama

Token Alma

POST /auth/token/

API anahtarınızı kullanarak JWT token alın. Token 24 saat geçerlidir.

İstek Parametreleri

Parametre Tip Zorunlu Açıklama
api_key string Evet Geliştirici portalından aldığınız API anahtarı

Örnek İstek

curl -X POST https://api.fom.services/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "fom_live_abc123def456"
  }'

Başarılı Yanıt

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Token Yenileme

POST /auth/refresh/

Süresi dolan token'ı refresh token ile yenileyin.

Örnek İstek

curl -X POST https://api.fom.services/auth/refresh/ \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Revenue API

Gelir yönetimi ve analizleri

Gelir Özeti

GET /revenue/summary

Belirtilen tarih aralığı için gelir özeti döndürür.

Sorgu Parametreleri

Parametre Tip Zorunlu Açıklama
start_date date Evet Başlangıç tarihi (YYYY-MM-DD)
end_date date Evet Bitiş tarihi (YYYY-MM-DD)
property_id integer Hayır Belirli bir tesis için filtre
group_by string Hayır day, week, month (varsayılan: day)

Örnek İstek

curl -X GET "https://api.fom.services/revenue/summary?start_date=2024-01-01&end_date=2024-01-31&group_by=week" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Başarılı Yanıt

{
  "status": "success",
  "data": {
    "total_revenue": 125000.50,
    "total_orders": 342,
    "average_order_value": 365.50,
    "period": {
      "start_date": "2024-01-01",
      "end_date": "2024-01-31"
    },
    "breakdown": [
      {
        "period": "2024-W01",
        "revenue": 28500.75,
        "orders": 78
      },
      {
        "period": "2024-W02",
        "revenue": 31200.25,
        "orders": 85
      }
    ]
  }
}

Günlük Gelir

GET /revenue/daily/{date}

Belirli bir gün için detaylı gelir raporu.

URL Parametreleri

Parametre Tip Açıklama
date date Tarih (YYYY-MM-DD formatında)

Örnek İstek

curl -X GET https://api.fom.services/revenue/daily/2024-01-15 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Gelir Tahmini

GET /revenue/forecast

Geçmiş verilere dayalı gelir tahmini.

Örnek İstek

curl -X GET "https://api.fom.services/revenue/forecast?days=30" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Başarılı Yanıt

{
  "status": "success",
  "data": {
    "forecast": [
      {
        "date": "2024-02-01",
        "predicted_revenue": 4250.00,
        "confidence_lower": 3800.00,
        "confidence_upper": 4700.00
      }
    ],
    "model_accuracy": 0.92
  }
}

Orders API

Sipariş yönetimi

Siparişleri Listele

GET /orders

Sayfalama ve filtreleme ile sipariş listesi.

Sorgu Parametreleri

Parametre Tip Açıklama
page integer Sayfa numarası (varsayılan: 1)
limit integer Sayfa başına kayıt (max: 100)
status string Sipariş durumu (pending, paid, cancelled)
customer_id integer Müşteri ID'sine göre filtre
start_date date Başlangıç tarihi
end_date date Bitiş tarihi

Örnek İstek

curl -X GET "https://api.fom.services/orders?status=paid&limit=5&page=2" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Sipariş Detayı

GET /orders/{id}

Belirli bir siparişin detaylarını getirir.

Örnek İstek

curl -X GET https://api.fom.services/orders/12345 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Sipariş Oluştur

POST /orders

Yeni sipariş oluşturur.

İstek Gövdesi

{
  "customer_id": 789,
  "items": [
    {
      "product_id": 101,
      "quantity": 2,
      "price": 150.00
    }
  ],
  "payment_method": "credit_card",
  "notes": "Oda 204'e teslim edilecek"
}

Başarılı Yanıt

{
  "status": "success",
  "data": {
    "order_id": 12346,
    "total": 300.00,
    "status": "pending",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Sipariş Güncelle

PUT /orders/{id}

Sipariş durumunu veya detaylarını günceller.

Örnek İstek

curl -X PUT https://api.fom.services/orders/12346 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "confirmed",
    "notes": "Ödeme alındı"
  }'

Tips API

Bahşiş yönetimi ve dağıtımı

Tip Özeti

GET /tips/summary

Belirtilen dönem için tip özeti.

Örnek İstek

curl -X GET "https://api.fom.services/tips/summary?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Tip Dağıtımı

POST /tips/distribute

Toplanan tipleri personele dağıtır.

İstek Gövdesi

{
  "period_start": "2024-01-01",
  "period_end": "2024-01-31",
  "total_tips": 5000.00,
  "distribution_method": "equal_shift"  // equal, performance, shift_based
}

Başarılı Yanıt

{
  "status": "success",
  "data": {
    "distribution_id": "dist_123",
    "total_tips": 5000.00,
    "staff_count": 15,
    "average_per_staff": 333.33,
    "distributions": [
      {
        "staff_id": 101,
        "staff_name": "Ahmet Yılmaz",
        "amount": 350.00,
        "percentage": 7
      }
    ]
  }
}

Inventory API

Stok ve ürün yönetimi

Ürün Listesi

GET /inventory/products

Tüm ürünleri listeler.

Örnek İstek

curl -X GET "https://api.fom.services/inventory/products?category=food&page=1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Stok Güncelle

PUT /inventory/stock/{product_id}

Ürün stoğunu günceller.

İstek Gövdesi

{
  "quantity": 150,
  "operation": "set",  // set, add, subtract
  "reason": "stock_count"
}

Staff API

Personel yönetimi

Personel Listesi

GET /staff

Tüm personeli listeler.

Örnek İstek

curl -X GET "https://api.fom.services/staff?department=housekeeping&active=true" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Performans Raporu

GET /staff/performance

Personel performans metrikleri.

Örnek İstek

curl -X GET "https://api.fom.services/staff/performance?period=month&year=2024" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Customers API

Müşteri yönetimi

Müşteri Oluştur

POST /customers

Yeni müşteri kaydı oluşturur.

İstek Gövdesi

{
  "first_name": "Mehmet",
  "last_name": "Demir",
  "email": "mehmet@email.com",
  "phone": "+905551234567",
  "birth_date": "1985-05-15",
  "preferences": {
    "language": "tr",
    "notifications": true
  }
}

Müşteri Geçmişi

GET /customers/{id}/history

Müşterinin sipariş ve aktivite geçmişi.

Örnek İstek

curl -X GET https://api.fom.services/customers/789/history \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Analytics API

İş zekası ve raporlama

Doluluk Analizi

GET /analytics/occupancy

Oda doluluk oranları ve tahminleri.

Örnek İstek

curl -X GET "https://api.fom.services/analytics/occupancy?month=2024-02" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Özel Rapor

POST /analytics/custom

Özel kriterlere göre rapor oluşturur.

İstek Gövdesi

{
  "metrics": ["revenue", "orders", "avg_order_value"],
  "dimensions": ["day", "department"],
  "filters": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "department": ["restaurant", "spa"]
  },
  "format": "json"  // json, csv, xlsx
}

Webhooks

Gerçek zamanlı bildirimler

Webhook Kaydet

POST /webhooks/register

Yeni webhook endpoint'i kaydeder.

İstek Gövdesi

{
  "url": "https://your-system.com/webhook/fom",
  "events": ["order.created", "payment.received", "tips.distributed"],
  "secret": "your_webhook_secret",
  "active": true
}

Webhook Olayları

GET /webhooks/events

Desteklenen webhook olayları.

Olay Açıklama
order.created Yeni sipariş oluşturuldu
order.updated Sipariş güncellendi
payment.received Ödeme alındı
tips.distributed Bahşiş dağıtıldı
inventory.low Stok kritik seviyede
customer.registered Yeni müşteri kaydı

Hata Kodları

API hata mesajları ve çözümleri

Kod HTTP Status Açıklama Çözüm
AUTH001 401 Geçersiz API anahtarı API anahtarınızı kontrol edin
AUTH002 401 Süresi dolmuş token Token'ı yenileyin
AUTH003 403 Yetkisiz erişim API anahtarınızın yetkilerini kontrol edin
VAL001 400 Geçersiz parametre Parametre formatını kontrol edin
VAL002 400 Zorunlu parametre eksik Tüm zorunlu parametreleri gönderin
RATE001 429 Rate limit aşıldı İstek sıklığını azaltın veya limit artırımı talep edin
RES001 404 Kaynak bulunamadı ID'yi kontrol edin
SVR001 500 Sunucu hatası Daha sonra tekrar deneyin, sorun devam ederse destek ekibine bildirin
Hata Yanıt Formatı 
{
  "status": "error",
  "code": "VAL001",
  "message": "Geçersiz parametre",
  "details": {
    "field": "start_date",
    "error": "Tarih formatı YYYY-MM-DD olmalıdır"
  },
  "request_id": "req_abc123def456"
}

Rate Limits

API kullanım limitleri

Başlangıç Paketi

10,000 istek/gün
Burst: 100 istek/dakika

Profesyonel Paket

50,000 istek/gün
Burst: 500 istek/dakika

Kurumsal Paket

200,000 istek/gün
Burst: 2,000 istek/dakika

Rate Limit Headers

Rate limit durumunu response header'larından takip edebilirsiniz:

  • X-RateLimit-Limit: Maksimum istek sayısı
  • X-RateLimit-Remaining: Kalan istek sayısı
  • X-RateLimit-Reset: Limit sıfırlanma zamanı (Unix timestamp)

SDK & Kütüphaneler

Popüler diller için resmi kütüphaneler

Python pip install fom-api JavaScript npm install fom-api PHP composer require fom/api Java implementation 'com.fom:api:1.0.0'

API'yi Hemen Kullanmaya Başlayın

Ücretsiz API anahtarınızı alın, dokümantasyonu inceleyin ve entegrasyona başlayın. Sorularınız için destek ekibimiz 7/24 yanınızda.

API Anahtarı Al Destek Al