Saha POS Arayüzü (SPI) Spesifikasyonu

Bu belge, Genel SPI Sağlayıcısı aracılığıyla Saha sistemi ile entegre olan harici POS sağlayıcıları için REST API spesifikasyonunu açıklamaktadır.

Genel Bakış

SPI sağlayıcısı, POS sisteminizin API'si ile iletişim kuran bir istemci olarak çalışır. Ürünlerin, siparişlerin ve konumların senkronizasyonunu sağlamak için API'nizin aşağıda açıklanan uç noktaları uygulaması gerekmektedir.

Örnekler

Kimlik Doğrulama

Saha sistemi, entegrasyon kurulumu sırasında yapılandırılan özel başlıklar kullanarak API'nize yapılan istekleri doğrulayacaktır.

• Auth Header: Başlık adını (örn. Authorization, X-API-Key) ve gizli değeri siz sağlarsınız.
• Client ID Header (İsteğe bağlı): Tarafınızda ek kimlik doğrulama için isteğe bağlı olarak bir client ID başlığı talep edebilirsiniz.

Örnek İstek Başlıkları:

Authorization: Bearer <your-secret-token>
X-Client-ID: <your-client-id>
X-Project-ID: <project-id>
X-Timestamp: <unix-timestamp>
Content-Type: application/json
Accept: application/json

Veri Tipleri

Çevrilebilir Alanlar: name, description, ingredients, unit ve label seçeneği gibi alanlar şu şekillerde sağlanabilir:

• Dil kodlarından stringlere bir Map (örn. {"en": "Burger", "tr": "Burger"}).
• Bir String (örn. "Burger"), yapılandırılmış default_language'e atanacaktır.

Para Birimi: Ürün nesnesindeki currency alanı isteğe bağlıdır. Atlanırsa, entegrasyonun default_currency değeri kullanılacaktır.

Uç Noktalar

1. Ürünleri Senkronize Et

Ürün listesini alır. Cursor aracılığıyla artımlı senkronizasyonu destekler.

• Metod: GET
• Yol: /products
• Sorgu Parametreleri:
  • cursor (isteğe bağlı): Bir sonraki grubu veya son senkronizasyondan bu yana yapılan güncellemeleri almak için API'niz tarafından önceki yanıtta sağlanan opak bir string.

Yanıt:

{
  "products": [
    {
      "id": "prod-101",
      "name": "Simple Burger",
      "description": "Classic burger",
      "price": 120.0,
      "category": {
        "id": "cat-1",
        "name": "Burgers"
      }
    },
    {
      "id": "prod-102",
      "name": {
        "en": "Cheeseburger",
        "tr": "Peynirli Burger"
      },
      "description": {
        "en": "Delicious burger with cheese",
        "tr": "Peynirli lezzetli burger"
      },
      "price": 150.0,
      "currency": "TRY",
      "category": {
        "id": "cat-1",
        "name": { "en": "Burgers", "tr": "Burgerler" }
      },
      "options": [
        {
          "name": "opt-sauce",
          "label": { "en": "Sauce", "tr": "Sos" },
          "options": [
            {
              "value": "val-ketchup",
              "label": { "en": "Ketchup", "tr": "Ketçap" },
              "additional_price": 0
            },
            {
              "value": "val-mayo",
              "label": "Mayonnaise",
              "additional_price": 5.0
            }
          ]
        }
      ]
    }
  ],
  "next_cursor": "token-for-next-page"
}

2. Sipariş Oluştur

POS sisteminizde yeni bir sipariş oluşturur.

• Metod: POST
• Yol: /orders

İstek:

{
  "items": [
    {
      "product_id": "prod-102",
      "quantity": 2,
      "note": "No onions",
      "options": [
        {
          "name": "opt-sauce",
          "values": ["val-ketchup"]
        }
      ]
    }
  ],
  "location": "loc-1",
  "note": "Allergy: Peanuts",
  "number_of_people": 4,
  "existing_order_id": "order-999"
}

Not: existing_order_id, açık bir hesaba ürün ekleniyorsa gönderilir.

Yanıt:

{
  "id": "order-1001",
  "status": "accepted",
  "is_addition": false
}

3. Sipariş Durumunu Al

Bir siparişin mevcut durumunu alır.

• Metod: GET
• Yol: /orders/{id}

Yanıt:

{
  "id": "order-1001",
  "status": "ready"
}

4. Siparişi İptal Et

Mevcut bir siparişi iptal eder.

• Metod: POST
• Yol: /orders/{id}/cancel

İstek:

{
  "reason": "Customer changed mind"
}

Yanıt:

{
  "status": "cancelled"
}

5. Konumları Al

Mevcut konumları (masalar, odalar vb.) alır.

• Metod: GET
• Yol: /locations

Yanıt:

[
  {
    "id": "loc-1",
    "name": "Table 1"
  },
  {
    "id": "loc-2",
    "name": "Table 2"
  }
]

]

Veri Modelleri

Product Nesnesi

Category Nesnesi

Product Option Nesnesi

Product Option Value Nesnesi

Create Order İsteği

Order Item Nesnesi

Order Item Option Nesnesi

Create Order Yanıtı

Sipariş Durumları

API'niz aşağıdaki durum stringlerinden birini döndürmelidir (büyük/küçük harf duyarsız):

Yapılandırma

Entegrasyon için şunları sağlamanız gerekmektedir:

1. Base URL: API'nizin kök URL'i (örn. https://api.pos-provider.com/saha/v1).
2. Auth Header Name: Kimlik doğrulama için başlık anahtarı.
3. Auth Header Secret: Başlık değeri (Bearer gibi herhangi bir ön ek dahil).
4. Default Language (İsteğe bağlı): Çevrilebilir alanlar string olarak sağlandığında kullanılacak dil kodu (varsayılan: en).
5. Default Currency (İsteğe bağlı): Ürün para birimi atlandığında kullanılacak para birimi kodu (varsayılan: TRY).