Siparişler

Sipariş ver

Siparişi doğrudan mekanın mutfağına gönderin. Onay adımı yoktur; mutfak fişi o an yazdırılır.

POST/public/v1/venues/{venueId}/orders

Kimlik doğrulama: X-Api-Key başlığında API anahtarı
Gereken izin: Sipariş gönderebilir
Hız sınırı: Anahtar başına dakikada yaklaşık 30 istek

Uyarı: Deneme ortamı yoktur. Gerçek bir anahtarla verilen sipariş, gerçek bir mekanda gerçek bir sipariştir ve mutfağında fiş basılır. Geliştirirken yönettiğiniz bir mekanı kullanın, ekibine haber verin ve sipariş olması gerekmeyen her şey için sepeti fiyatlayın.

Siparişi ve Idempotency-Key başlığını gönderin. Yanıt, GET /orders/{orderId} adresini gösteren bir Location başlığıyla 201 Created olur. İstek zaman aşımına uğrar ya da bağlantı koparsa aynı anahtarla yeniden gönderin: ilk çağrının verdiği siparişi mekandaki güncel haliyle 200 OK olarak alırsınız ve hiçbir şey iki kez sipariş edilmez. Yeni bir sipariş için yeni bir anahtar üretin. Ayrıntılar: Sipariş vermek.

201 yanıtındaki addedLineIds değerini saklayın. Bu çağrının order.lines içinden tam olarak hangilerini yazdığını söyler; başkalarının satırları bulunan bir masa hesabına eklenen siparişte önemlidir. Yeniden denemenin (200) yanıtında bu değer en iyi tahmindir.

Sunucu siparişi fiyatlar: satırlar ekstralarıyla menü fiyatından, mekanın otomatik kampanyaları ve hizmet bedeli. Toplamı önceden göstermek için sepeti fiyatlayın.

Masa (DineIn) tableId ister, müşteri almaz: tur masanın açık hesabına eklenir ya da yeni bir hesap açar.
Gel-al (Takeaway) customer.name ve customer.phone ister; paket (Delivery) ayrıca customer.address ister. Bu ikisi tableId almaz.
1 ile 30 arası satır, her satırda 1 ile 20 arası adet, satır başına en fazla 20 ekstra ve 20 çıkarılan malzeme; sipariş notu en fazla 300, satır notu en fazla 200 karakter.

Mekan şu an sipariş alıyor olmalı: etkin bir abonelik (PUBLIC_API_ORDERING_UNAVAILABLE), mutfak yoğunluğu olmaması (PLACE_IS_BUSY) ve çalışma saatleri içinde olmak (OUTSIDE_WORKING_HOURS). Her ürün menüde listelenen ve sipariş edilebilir bir ürün olmalı; tükenmiş ürün de reddedilir.

Rehber: Sipariş vermek

Parametreler

venueIdstring · uuidYol parametresizorunlu

Mekan; GET /venues listesindeki kimliklerden biri.

Idempotency-KeystringBaşlıkzorunlu

Her sipariş için bir kez ürettiğiniz ve o siparişin her yeniden denemesinde değiştirmeden gönderdiğiniz değer: 8 ile 64 arası harf, rakam, - ya da _ (bir UUID uygundur). Zorunlu.

8–64 karakter

Accept-LanguagestringBaşlık

Hata yanıtlarındaki userMessage metninin dili: tr (varsayılan), en, de, fr, it, es, ar ya da ru. Başlıktaki ilk dil belirler, bölgesi olmadan (en-US, en okunur) ve q ağırlıklarına bakılmadan; Cibusy'nin sunmadığı bir dil Türkçe yanıtlanır. Menünün dilini seçmez; o, menü çağrısındaki lang parametresidir.

İstek gövdesi

Mekanın sitesinin gönderdiği sipariş ya da önce fiyatlanmasını istediği sepet. Fiyat taşımaz: sunucu her satırı mekanın menüsünden fiyatlar, mekanın kampanyalarını ve hizmet bedelini uygular ve toplamı yanıtta söyler.

typestringzorunlu

Siparişin misafire nasıl ulaşacağı. Zorunlu.

DineIn: Masada: tur, masanın açık hesabına eklenir ya da yeni bir hesap açar.
Takeaway: Gel-al: müşteri siparişi mekandan alır.
Delivery: Paket: mekan siparişi müşteriye götürür.

tableIdstring · uuidnull olabilir

Masada verilen siparişin masası; GET /venues/{venueId}/tables listesindeki kimliklerden biri. DineIn için zorunlu, Takeaway ve Delivery için verilemez. Mekanın masalarından biri olmayan kimlik 404 alır.

customerobjectnull olabilir

Siparişin kimin için olduğu. Takeaway (ad ve telefon) ve Delivery (ad, telefon ve adres) için zorunlu; DineIn için verilemez: masadaki misafire oturduğu yerde servis edilir.

Müşteri alanları

namestringzorunlunull olabilir

Müşterinin adı, en fazla 100 karakter. Zorunlu.

phonestringzorunlunull olabilir

Siparişle ilgili aranacak numara; uluslararası biçimde ya da yerel yazıldığı gibi (+905321112233, 0532 111 22 33). En fazla 30 karakter. Zorunlu.

addressstringnull olabilir

Paketin gideceği adres, müşterinin kendi sözleriyle, en fazla 300 karakter. Delivery için zorunlu, Takeaway için verilemez.

paymentMethodstringnull olabilir

Gel-al ya da paket siparişte müşterinin nasıl ödeyeceğini söylediği. İsteğe bağlı; masada hesap masada kapandığı için DineIn siparişinde verilemez. Siparişi teslim edecek kişi için bir ipucudur: API üzerinden hiçbir ödeme alınmaz.

Cash: Nakit.
Card: Kart.
MealCard: Yemek kartı.

notestringnull olabilir

Mutfak için siparişin tamamıyla ilgili bir not, en fazla 300 karakter.

linesobject[]zorunlu

Sipariş edilen ürünler: 1 ile 30 arası satır.

Sipariş satırı isteği alanları

productIdstring · uuidzorunlu

Ürün; GET /venues/{venueId}/menu listesindeki kimliklerden biri. Zorunlu.

portionIdstring · uuidzorunlu

O ürünün porsiyonu. Zorunlu. Mekanın tartıyla sattığı porsiyon (menüde orderable: false) sipariş edilemez.

quantityintegerzorunlu

Kaç adet: 1 ile 20 arası.

notestringnull olabilir

Mutfak için bu satırla ilgili bir not, en fazla 200 karakter.

extraIdsstring[]

Satırın her bir adedi için seçilen ekstralar; ürünün menüdeki extras listesinden kimlikler, en fazla 20, her biri en fazla bir kez. Ürünün kendi ekstrası olmayan ya da ürünün seçim gruplarını bozan bir seçim (bir kahvede iki şeker seviyesi, zorunlu grupta hiç seçim) reddedilir.

removedIngredientIdsstring[]

Satırın her bir adedinden çıkarılacak malzemeler; ürünün menüdeki removableIngredients listesinden kimlikler, en fazla 20, her biri en fazla bir kez.

Yanıtlar

200

Yeniden deneme: aynı Idempotency-Key ile zaten verilmiş sipariş. Buradaki addedLineIds en iyi tahmindir; 201 yanıtındakileri saklayın.

201

Sipariş verildi. Location siparişi gösterir; addedLineIds bu çağrının siparişe koyduğu satırların tam listesidir, saklayın.

Location

Siparişin okunabileceği yer: /public/v1/orders/{orderId}.

400

PUBLIC_API_IDEMPOTENCY_KEY_INVALID, PUBLIC_API_ORDER_INVALID ya da PUBLIC_API_PRODUCT_OPTION_INVALID.

401

X-Api-Key başlığı yok (PUBLIC_API_KEY_MISSING) ya da anahtar geçersiz veya iptal edilmiş (PUBLIC_API_KEY_INVALID).

403

PUBLIC_API_SCOPE_MISSING: anahtar "Sipariş gönderebilir" izniyle oluşturulmamış.

404

PUBLIC_API_VENUE_NOT_FOUND, PUBLIC_API_TABLE_NOT_FOUND ya da PUBLIC_API_PRODUCT_NOT_FOUND.

409

PUBLIC_API_ORDERING_UNAVAILABLE, PLACE_IS_BUSY, OUTSIDE_WORKING_HOURS, PUBLIC_API_PRODUCT_UNAVAILABLE ya da ORDER_CREATION_IN_PROGRESS.

429

Anahtarın siparişler, rezervasyonlar ve testler için dakikada yaklaşık 30 isteklik bütçesi doldu; Retry-After kadar saniye bekleyin.

Retry-After

Beklenecek saniye. Bir sonraki dakikalık pencere bu süre içinde açılır.

Başarılı yanıtın `data` alanı

Sipariş vermenin yanıtı: siparişin mekandaki hali ve satırlarından hangilerini bu çağrının yazdığı (ilk yanıtta kesin, bir yeniden denemede yaklaşık; bkz. addedLineIds). Bir Idempotency-Key ilk kullanıldığında 201, tekrarlandığında 200 ile gelir.

orderobject

Sipariş. Zaten açık bir hesaba eklenen masa siparişi o hesabın tamamı olarak, başkalarının sipariş ettiği satırlarla birlikte gelir.

Sipariş alanları

idstring · uuid

Siparişin kimliği. GET /orders/{orderId} ile kullanın.

numberinteger

Mekanın siparişi çağırdığı numara, mekan içinde 1'den başlayarak sayılır. Müşteriye gösterin; mutfak fişinde yazan numaradır. Yalnız mekan içinde benzersizdir.

venueIdstring · uuid

Siparişin verildiği mekan.

typestring

Siparişin misafire nasıl ulaştığı.

DineIn: Masada: tur, masanın açık hesabına eklenir ya da yeni bir hesap açar.
Takeaway: Gel-al: müşteri siparişi mekandan alır.
Delivery: Paket: mekan siparişi müşteriye götürür.

statusstring

Siparişin geldiği aşama; sipariş satırlarından ve hesaptan her okumada yeniden hesaplanır.

Received: Mekan siparişi aldı, mutfak henüz başlamadı.
Preparing: Mutfak satırlardan en az birine başladı.
Ready: Her satır hazır ya da servis edildi.
Served: Her satır servis edildi.
OnTheWay: Paket mekandan çıktı.
Completed: Mekan hesabı kapattı.
Cancelled: Sipariş iptal edildi ya da üzerindeki her satır silindi.

paymentStatusstring

Hesabın ne kadarının mekanda ödendiği.

Unpaid: Mekanda henüz hiçbir şey ödenmedi.
PartiallyPaid: Hesabın bir kısmı ödendi.
Paid: Hesap ödendi.

tableobjectnull olabilir

Masa siparişinin masası. Gel-al ve pakette null.

Sipariş masası alanları

idstring · uuid

Masanın kimliği, GET /venues/{venueId}/tables listesindeki gibi.

namestring

Masanın adı.

customerobjectnull olabilir

Gel-al ya da paket siparişin kimin için olduğu. Masa siparişinde ve müşteri bilgisi alınmamış siparişte null.

Müşteri bilgisi alanları

namestringnull olabilir

Müşterinin adı.

phonestringnull olabilir

Müşterinin telefon numarası, uluslararası biçimde.

addressstringnull olabilir

Paketin gideceği adres.

paymentMethodstringnull olabilir

Müşterinin söylediyse nasıl ödeyeceği. Aksi halde null.

Cash: Nakit.
Card: Kart.
MealCard: Yemek kartı.

notestringnull olabilir

Siparişin verildiği mutfak notu. Not yoksa null.

linesobject[]

Siparişteki her satır; başkalarının masa hesabına koyduğu satırlar ve sonradan iptal edilenler dahil. Zaten açık bir hesaba eklenen masa siparişinde hesabın tüm satırları buradadır; sipariş verme yanıtındaki addedLineIds hangilerini o çağrının yazdığını söyler.

Sipariş satırı alanları

idstring · uuid

Satırın kimliği. Satır siparişte kaldığı sürece değişmez.

productIdstring · uuid

Ürün, menüdeki gibi.

productNamestring

Ürünün mekanın kendi sözleriyle adı.

portionIdstring · uuidnull olabilir

Sipariş edilen porsiyon, menüdeki gibi.

portionNamestringnull olabilir

Porsiyonun sipariş verildiği andaki adı.

quantityinteger

Kaç adet.

unitPricenumber

Bir adedin fiyatı, ekstralar dahil, sipariş verildiği andaki haliyle.

totalnumber

Satırın tuttuğu: unitPrice × quantity, kampanyalardan önce. İptal edilen ve mekanın ikram ettiği satırda 0.

statusstring

Satırın mutfakta geldiği aşama.

Pending: Mutfakta sırada.
Preparing: Hazırlanıyor.
Ready: Hazır.
Served: Servis edildi.
Cancelled: İptal edildi. İptal edilmiş bir siparişin satırları da böyle okunur.

extrasobject[]

Her adetteki ekstralar.

Satır ekstrası alanları

idstring · uuid

Ekstra, menüdeki gibi.

namestring

Ekstranın adı.

pricenumber

Sipariş verildiği anda adet başına tuttuğu.

removedIngredientsobject[]

Her adetten çıkarılan malzemeler.

Çıkarılan malzeme alanları

idstring · uuid

Malzeme, menüdeki gibi.

namestring

Malzemenin adı.

notestringnull olabilir

Bu satır için mutfak notu. Not yoksa null.

orderedAtstring · date-time

Satırın siparişe konduğu an (UTC).

totalsobject

Siparişin tuttuğu ve ne kadarının ödendiği.

Tutarlar alanları

subtotalnumber

Satırların ekstralarıyla menü fiyatı, kampanyalardan önce. İptal edilen satırlar sayılmaz.

discountnumber

Mekanın kampanyalarının ve indirimlerinin düştüğü tutar.

serviceFeenumber

Mekanın hizmet bedeli; kampanyalardan sonraki yiyecek tutarı üzerinden alınır. Mekan almıyorsa 0.

totalnumber

Siparişin tuttuğu.

paidnumber

Mekanda bunun ne kadarının ödendiği.

remainingnumber

Hala borç olan tutar. Hesap ödendiğinde 0.

currencystring

Tüm tutarların para birimi, ISO 4217 kodu. Her zaman TRY.

createdAtstring · date-time

Siparişin verildiği an (UTC).

closedAtstring · date-timenull olabilir

Mekanın siparişi kapattığı an (UTC). Sipariş açıkken ve iptal edilmiş siparişte null.

addedLineIdsstring[]

Bu çağrının siparişe koyduğu satırların kimlikleri, order.lines içinde. 201 yanıtında tam olarak bu çağrının yazdığı satırlardır; saklayın. Anahtar tekrarlandığında (200) sipariş hangi isteğin hangi satırı yazdığını bilmez, bu yüzden en iyi tahmindir: ilk çağrı kaydedilmeden önceki 15 saniye içinde siparişe konan satırlar. Başkalarının da eklediği bir masa hesabında, o arada başkasının eklediği bir satırı içerebilir.

İstek örneği

curl -X POST "https://api.cibusy.com/public/v1/venues/3fa85f64-5717-4562-b3fc-2c963f66afa6/orders" \
  -H "X-Api-Key: $CIBUSY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Takeaway",
    "customer": {
      "name": "Ayşe Yılmaz",
      "phone": "+905321112233"
    },
    "paymentMethod": "Card",
    "lines": [
      {
        "productId": "5d2c8a41-7b0e-4c36-8f1d-9e4a6b3c2d10",
        "portionId": "a8e1f6c3-2d94-4b70-b5a6-1c7d9e0f3a24",
        "quantity": 2,
        "note": "Köfteler ayrı paketlensin.",
        "extraIds": [
          "f1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
          "b4c5d6e7-f8a9-4b1a-8c2d-3e4f5a6b7c8d"
        ],
        "removedIngredientIds": [
          "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e"
        ]
      }
    ]
  }'

Yanıt örneği

201 Created

{
  "success": true,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null,
  "data": {
    "order": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "number": 57,
      "venueId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "Takeaway",
      "status": "Received",
      "paymentStatus": "Unpaid",
      "table": null,
      "customer": {
        "name": "Ayşe Yılmaz",
        "phone": "+905321112233",
        "address": null
      },
      "paymentMethod": "Card",
      "note": null,
      "lines": [
        {
          "id": "3b5d7f91-a2c4-4e6f-8b1d-9f3a5c7e1b24",
          "productId": "5d2c8a41-7b0e-4c36-8f1d-9e4a6b3c2d10",
          "productName": "Izgara köfte",
          "portionId": "a8e1f6c3-2d94-4b70-b5a6-1c7d9e0f3a24",
          "portionName": "Porsiyon",
          "quantity": 2,
          "unitPrice": 360,
          "total": 720,
          "status": "Pending",
          "extras": [
            {
              "id": "f1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
              "name": "Ekstra peynir",
              "price": 40
            },
            {
              "id": "b4c5d6e7-f8a9-4b1a-8c2d-3e4f5a6b7c8d",
              "name": "İyi pişmiş",
              "price": 0
            }
          ],
          "removedIngredients": [
            {
              "id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
              "name": "Soğan"
            }
          ],
          "note": "Köfteler ayrı paketlensin.",
          "orderedAt": "2026-10-01T09:30:00.000Z"
        }
      ],
      "totals": {
        "subtotal": 720,
        "discount": 0,
        "serviceFee": 0,
        "total": 720,
        "paid": 0,
        "remaining": 720
      },
      "currency": "TRY",
      "createdAt": "2026-10-01T09:30:00.000Z",
      "closedAt": null
    },
    "addedLineIds": [
      "3b5d7f91-a2c4-4e6f-8b1d-9f3a5c7e1b24"
    ]
  },
  "message": "Operation completed successfully"
}

Hata örneği

400 Bad Request

{
  "success": false,
  "userMessage": "Her siparişle birlikte 8-64 karakterlik (harf, rakam, '-' ya da '_') benzersiz bir Idempotency-Key başlığı gönderin.",
  "developerMessage": "The Idempotency-Key header must hold 8 to 64 characters: letters, digits, '-' or '_'.",
  "errorCode": "PUBLIC_API_IDEMPOTENCY_KEY_INVALID",
  "validationErrors": null,
  "details": null,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null
}

Sipariş ver

Parametreler

İstek gövdesi

Yanıtlar

Başarılı yanıtın data alanı

Başarılı yanıtın `data` alanı