Dallas POS Altyapı

REST API v1.0.0

Genel Bakış ve Mimari Standartlar

Bu kılavuz, merkez ve şube ekosistemindeki sipariş yönetimi, mutfak otomasyonu, kurye lojistiği, anlık envanter takibi ve ön muhasebe hareketlerini harici servislerle senkronize etmek amacıyla geliştirilen RESTful API mimarisini açıklar.

Global Base Gateway URL https://api.dallasyemek.online/dallas

Tüm servis istekleri ve sunucu yanıtları standart application/json içerik türü (Content-Type) üzerinden yürütülür. Zaman damgaları global ISO 8601 formatındadır.

Sistem Uygulamaları ve İstemci Paketleri

ZIP Arch.

Fabrika Yazıcı Entegrasyonu

Üretim ve fabrika hattı otomatik çıktı senkronizasyon servisi istemci paketi.

İndir (.zip)
ZIP / Driver

Adisyon Fiş Yazıcısı

Şube kasa ve mutfak termal yazıcı yazdırma yöneticisi servisi.

İndir (.zip)
Android APK

Caller ID Uygulaması

Gelen aramalarda müşteri eşleşmesi sağlayan Android arayan kimliği uygulaması.

İndir (.apk)

HTTP Statü Kodları

İsteklerin sonuçları standart HTTP protokol kodları ile mühürlenir:

  • 200 OK / 201 Created: İşlem Başarılı.
  • 400 Bad Request: Hatalı veya eksik JSON gövdesi.
  • 401 Unauthorized: Geçersiz veya süresi dolmuş token.
  • 500 Internal Error: Sunucu içi işlem hatası.

Real-Time Olay Motoru

Veritabanı durum değişimleri, el terminalleri ve mutfak monitörlerinin senkronizasyonu için eşzamanlı olarak asenkron WebSocket (Socket.io) sinyalleri fırlatır:

  • • order_status_updated: Sipariş statü değişimleri.
  • • new_order_added: Yeni gelen anlık siparişler.
  • • refresh_tables: Masa doluluk matrisi güncellemeleri.
Global Hata Cevap Şeması (Global Error Schema) JSON 
{
  "status": "error",
  "message": "İşlem sırasında meydana gelen hatanın jenerik açıklaması.",
  "debug": "Geliştirici modu aktifse fırlatılan sistem veya SQL hata detayı."
}

Kimlik Doğrulama (Authentication)

API havuzundaki korumalı endpoint'lere erişim sağlamak için endüstri standardı olan JWT (JSON Web Token) mimarisi kullanılır. Kimlik doğrulaması başarılı olan her isteğin HTTP Header (Başlık) katmanına token bilgisi eklenmelidir.

Authorization: Bearer <JWT_TOKEN_STRING>

Giriş doğrulaması yapılan token sunucu tarafında otomatik olarak çözülerek; istek atan personelin yetki rolünü (role), bağlı olduğu şube kimliğini (branch_id) ve kullanıcı ID (user_id) verilerini arka planda işleme mühürler.

POST /api/auth/login
Sistem Girişi & Token Üretimi

Sistem havuzunda geçerli ve süreli bir JWT token üretebilmek için geçerli kullanıcı kimlik bilgileriyle bu endpoint'e asenkron istek atılmalıdır.

İstek Gövdesi (Request Body)

{
  "email": "user@domain.com",
  "password": "secure_password"
}

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "expires_in": 86400
}

Sipariş Yönetimi (Order Management)

POST /api/orders (Delivery)
Müşteri Adresli Teslimat

Dış sipariş kanallarından veya çağrı merkezinden gelen, kurye lojistiği gerektiren adresli teslimat adisyonlarını başlatmak için kullanılır. Telefon numarası eşleşmesi üzerinden CRM doğrulaması otomatik tetiklenir.

İstek Gövdesi (Request Body)

{
  "order_type": "delivery",
  "table_id": null,
  "table_name": "Paket Servis",
  "customer_name": "John Doe",
  "customer_phone": "5000000000",
  "delivery_address": "Sample Address String",
  "payment_method": "Nakit",
  "total_amount": 500.00,
  "items": [
    {
      "product_id": 1,
      "quantity": 1,
      "unit_price": 250.00,
      "total_price": 250.00,
      "notes": "Sample Item Note",
      "selected_options": { "removed": ["ingredient_name"] },
      "is_complimentary": 0
    }
  ]
}

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "message": "Sipariş oluşturuldu.",
  "order_id": 101
}
POST /api/orders (Takeaway)
Tezgah Üstü Müşteri Teslimatı

Fiziksel masa doluluğu veya harici kurye zimmetlemesi gerektirmeyen, doğrudan tezgahtan elden teslim edilecek durumlarda takeaway parametresi ile istek atılır. Sistem adisyon ismini otomatik mühürler.

İstek Gövdesi (Request Body)

{
  "order_type": "takeaway",
  "table_id": null,
  "customer_name": "Jane Doe",
  "customer_phone": "5000000001",
  "payment_method": "Kredi Kartı",
  "total_amount": 300.00,
  "items": [
    {
      "product_id": 2,
      "quantity": 1,
      "unit_price": 300.00,
      "total_price": 300.00,
      "notes": null,
      "selected_options": { "removed": [] },
      "is_complimentary": 0
    }
  ]
}

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "message": "Sipariş oluşturuldu.",
  "order_id": 102
}
GET /api/orders/history
Sipariş Geçmişini Listele

Şubeye ait tamamlanmış (completed) veya iptal edilmiş (cancelled) tüm geçmiş sipariş hareketlerini kronolojik olarak geriye dönük listelemek ve raporlamak için çağrılır.

Filtreleme ve Raporlama Notları

• İstek atan kullanıcının JWT token bilgilerinden çözülen branch_id filtresi otomatik uygulanır ve sadece o şubeye ait arşiv verileri listelenir.

• Yanıt içerisinde siparişe ait nihai ödeme yöntemi (payment_method) ve eğer uygulandıysa iskonto türü ile net tahsilat tutarları şematik olarak yer alır.

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "data": [
    {
      "id": 101,
      "branch_id": 1,
      "user_id": 5,
      "table_id": null,
      "order_type": "delivery",
      "table_name": "Paket Servis",
      "total_amount": 500.00,
      "final_amount": 450.00,
      "status": "completed",
      "customer_id": 12,
      "delivery_address": "Sample Address String",
      "payment_method": "Kredi Kartı",
      "discount_type": "amount",
      "discount_value": 50.00,
      "created_at": "2026-06-03 14:00:00"
    },
    {
      "id": 98,
      "branch_id": 1,
      "user_id": 3,
      "table_id": 4,
      "order_type": "dine_in",
      "table_name": "Masa-04",
      "total_amount": 320.00,
      "final_amount": 0.00,
      "status": "cancelled",
      "customer_id": null,
      "delivery_address": null,
      "payment_method": null,
      "discount_type": "none",
      "discount_value": 0.00,
      "created_at": "2026-06-03 11:15:00"
    }
  ]
}

Ürün & Kategori Yönetimi (Catalog Management)

GET /api/products
Menü Ürünlerini Listele

Şubeye ait aktif menü elemanlarını taban fiyat, lokasyon matris fiyatlandırması (dine_in, takeaway, delivery), içerik opsiyon nesnesi (content) ve kampanya süzgeçleriyle listeler.

Mekanik Özellikler

• content: Frontend katmanında ürün içerisinden çıkartılabilecek hammadde matrisini belirleyen JSON string yapısıdır.

• Fiyat öncelikleri el terminali ve sipariş tipine göre veritabanından dinamik olarak filtrelenerek optimize edilir.

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "branch_id": 1,
  "data": [
    {
      "id": 1,
      "category_id": 1,
      "branch_id": 1,
      "name": "Sample Product Name",
      "content": "{\"ingredient_key\": \"value_spec\"}",
      "price": 250.00,
      "price_dine_in": 250.00,
      "price_takeaway": 240.00,
      "price_delivery": 280.00,
      "image_url": "https://api.domain.com/uploads/image.jpg",
      "stock_quantity": 100,
      "unit_gr": 300,
      "status": "active",
      "is_campaign": 0,
      "campaign_discount_type": "none",
      "campaign_discount_value": "0.00",
      "category_name": "Category Name"
    }
  ]
}
POST /api/products/save
Ürün Ekleme & Düzenleme

Sisteme yeni bir ürün kazandırır ya da mevcut ürünü günceller. Gönderilen campaign_discount_type alanı ENUM yapısında olup kısıtlı değerleri kabul eder.

İstek Gövdesi (Request Body)

{
  "category_id": 1,
  "name": "New Product Name",
  "price": 250.00,
  "price_dine_in": 250.00,
  "price_takeaway": 240.00,
  "price_delivery": 280.00,
  "stock_quantity": 100,
  "unit_gr": 300,
  "status": "active",
  "is_campaign": 0,
  "campaign_discount_type": "none", // none, percentage, amount
  "campaign_discount_value": 0
}

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "message": "Ürün operasyonu başarıyla tamamlandı.",
  "data": {
    "id": 5,
    "name": "New Product Name"
  }
}
GET /api/categories
Ana Kategorileri Listele

Menü gruplarını şube kırılımına göre listelemek ve katalog hiyerarşisini oluşturmak için çağrılır.

Katalog Mimari Bilgisi

Her ürün mutlaka geçerli bir category_id ile ilişkilendirilmek zorundadır. Kategorisi pasife çekilen ürünler menü taramalarında otomatik olarak gizlenir.

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "branch_id": 1,
      "name": "Sample Category Name",
      "status": "active"
    }
  ]
}
POST /api/categories/delete
Kategori Sil

Belirtilen benzersiz kimliğe sahip menü kategorisini sistem havuzundan tamamen kaldırmak için kullanılır.

İstek Gövdesi (Request Body)

{
  "id": 12
}

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "message": "Kategori başarıyla kaldırıldı."
}

Masa Yönetimi (Table Management)

GET /api/tables
Şube Masalarını Listele

Şubeye bağlı tüm fiziksel masaların listesini, benzersiz ID'lerini, anlık durum kodlarını ve eğer masa doluysa içerisindeki aktif adisyonun benzersiz kimlik bilgisini (current_order_id) senkronize etmek için kullanılır.

Masa Durum Kodları (Status)

• empty: Masa boş ve yeni adisyon girişine hazır.

• occupied: Masada açık bir sipariş/adisyon kaydı var.

• reserved: Masa ileri saatli bir rezervasyona kilitli.

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "branch_id": 1,
      "name": "Masa-01",
      "status": "occupied",
      "current_order_id": 102
    },
    {
      "id": 2,
      "branch_id": 1,
      "name": "Masa-02",
      "status": "empty",
      "current_order_id": null
    }
  ]
}
POST /api/tables/status
Masa Statüsü Değiştir

Fiziksel masanın durumunu manuel veya el terminalleri üzerinden değiştirmek, masayı kilitlemek veya boşaltmak için tetiklenir. İşlem onaylandığında, tüm istemci ekranlarının anlık güncellenmesi için WebSocket katmanına refresh_tables eventi fırlatılır.

İstek Gövdesi (Request Body)

{
  "table_id": 1,
  "status": "occupied"
}

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "message": "Masa durumu güncellendi."
}

Tedarik & Envanter (Inventory Management)

GET /api/ingredients
Stok Durumunu Çek

Depoda veya mutfak standında yer alan tüm ham maddelerin anlık miktar, temel birim (Gr, Adet, Dilim vb.) ve kritik stok limiti verilerini eşzamanlı olarak listeler.

Kritik Stok Kontrolü

Adisyon kapatıldığında, adisyondaki ürünlerin reçeteleri (recipe) okunarak ilgili ham maddelerin stock_quantity değerinden otomatik düşüm yapılır. Stok miktarı critical_limit altına inen ham maddeler için sistem paneline uyarı bayrağı bırakılır.

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "branch_id": 1,
      "name": "Ingredient Name A",
      "stock_quantity": "10000.00",
      "unit": "Gr",
      "critical_limit": "500.00",
      "updated_at": "2026-06-03 12:00:00"
    },
    {
      "id": 2,
      "branch_id": 1,
      "name": "Ingredient Name B",
      "stock_quantity": "150.00",
      "unit": "Adet",
      "critical_limit": "50.00",
      "updated_at": "2026-06-03 12:00:00"
    }
  ]
}
POST /api/supplies/create
Yeni Tedarik Girişi Başlat

Toptancı, fabrika veya ana depodan talep edilen yeni ham madde girdilerini sisteme varsayılan olarak pending_factory statüsünde kaydetmek için kullanılır.

İstek Gövdesi (Request Body)

{
  "ingredient_id": 1,
  "supplier_name": "Supplier Company Name",
  "requested_amount": 500,
  "unit_price": 50.00
}

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "message": "Tedarik kaydı oluşturuldu.",
  "supply_id": 401
}
POST /api/supplies/update-status
Mal Kabulü & Otomatik Muhasebe Girişi

Gelen lojistik sevkiyatının statüsü completed (Kabul Edildi) yapıldığı an, miktar otomatik olarak mevcut stok envanterine eklenir. Sistem maliyeti hesaplayarak kasa hareketlerine gider (Gider/Masraf) kalemi olarak kilitler.

İstek Gövdesi (Request Body)

{
  "supply_id": 401,
  "status": "completed",
  "note": "Sevkiyat eksiksiz ve uygun sıcaklıkta teslim alındı."
}

Başarılı Yanıt (Response Schema)

{
  "status": "success",
  "message": "Mal kabulü tamamlandı, envanter ve kasa hareketleri güncellendi."
}