Sipariş Yaşam Döngüsü

Durum akışı

Durumu yazan eylemler iki dikeyde aynıdır: accept, ready, dispatch, deliver, cancel. Hedef durum dikeye göre değişir (aşağıdaki Durum yazma tablosu). Durum adları ve anlamları için Sipariş Durumları.

Sipariş listeleme ve okuma

curl "https://api.supergelsin.com/api/partner/v1/orders?updatedSince=2026-01-31T10:00:00Z&limit=50" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01"

GET /orders sayfalı listedir ve { items, nextCursor } döner. Sıralama updatedAt artan, ardından id artandır; liste en eski değişiklikten başlar ve imleçle ilerler. nextCursor doluysa sonraki istekte cursor olarak gönderilir, null ise akışın sonuna gelinmiştir. Ödeme tamamlanmamış siparişler hiçbir zaman listelenmez.

• Varsayılan: status ve updatedSince verilmezse yalnız aktif siparişler gelir (restoranda pending, preparing, ready, on_the_way; Çarşı'da pending, confirmed, preparing, on_the_way).
• updatedSince verilirse teslim ve iptal değişiklikleri dahil bütün durumlar gelir; kasa kendi kaydını böyle uzlaştırır.
• Bir sonraki çekimde son görülen updatedAt değerinden birkaç saniye geri verin ve tekrarları id ile updatedAt çiftiyle ayıklayın: kayıt değişikliğinin zamanı işlem tamamlanmadan önce yazıldığından, yeni değişen bir sipariş çok yakın bir zamanla görünmeyebilir.
• Çarşı'da status=return_pending, teslim edilemedi olarak iptal edilmiş ve dönüşü onay bekleyen siparişleri getirir; bu siparişlerde returnLines dolu gelir.

GET /orders/{id} tek siparişin tam gövdesini döner. Ödeme tamamlanmamış sipariş ve başka işletmenin siparişi aynı 404 not_found yanıtını alır. Webhook gövdesi (order alanı) bu gövdeyle aynıdır; webhook düşük gecikme sağlar, bu uçlar doğruluk kaynağıdır (Webhook).

Sipariş gövdesi

Müşteri bilgisi kapanıştan 2 saat sonra daraltılır (ad kısalır, telefon ve koordinat düşer, adres yalnız İlçe / İl kalır, not düşer); sipariş özeti (kalemler, tutarlar, ödeme, fatura) bu daraltmadan etkilenmez.

Kalemleri ürünlerinize eşleme

Kalemleri ada göre değil kimliğe göre eşleyin. Restoranda items[].id, GET /menu yanıtındaki ürün id değeridir; seçeneklerde selectedOptions[].choiceId, menüdeki modifierGroups[].choices[].id değeridir (Menü ve Ürün Eşleme). Çarşı işletmesinde eşleme anahtarı clientReferenceId değeridir; ürünü sizin gönderdiğiniz kimlikle eşleyin (Katalog).

Ödeme: kapıda alınacak tutar

Tahsilat bilgisi siparişin içindedir ve iki dikeyde aynıdır. Kasiyerin kapıda para alıp almayacağını channel ve dueAmount söyler.

"payment": {
  "channel": "door",           // door = kapıda alınır · online = platform üzerinden ödendi
  "instrument": "bank_card",   // cash | bank_card | meal_card
  "method": "pos_merchant",
  "dueAmount": 250             // kapıda alınacak tutar
}

dueAmount, kapıda alınacak tutardır. channel online ise ya da sipariş iptal edilmişse (teslim edilemedi dahil) 0 olur. Kapıda ödemede sipariş toplamıdır; Çarşı'da toplama bittikten sonra toplama eksiği düşülerek azalabilir. Toplama kapanmadan önce okunan tutar kesin değildir; toplama bittikten sonra siparişi yeniden okuyun.

instrument yemek kartı yöntemlerinde meal_card olur. Online yemek kartı yöntemleri (meal_card_online_*) şu an etkin değildir. Küme bu sürüm için kapalıdır; tanımadığınız bir kodla karşılaşırsanız yok saymak yerine channel ve instrument alanlarına bakın.

Durum yazma

curl -X POST "https://api.supergelsin.com/api/partner/v1/orders/cm_ornek_siparis/status" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "action": "accept", "prepMinutes": 25 }'

Hedef durum zaten yürürlükteyse sonuç değişmez ve yanıt 200 döner; aynı istek tekrarlanabilir. Yanıt güncel sipariş gövdesidir. Geçersiz geçişte 409 invalid_transition döner; current siparişin durumunu, allowed bu durumdan yapılabilecek eylemleri verir.

İptal ve iptal sebepleri

GET /cancel-reasons işletmenin dikeyine göre tüm iptal sebeplerini, kime atfedildiklerini (attributedTo), performansa etkisini (affectsPerformance), seçilebilir olup olmadığını (selectable) ve hangi sipariş durumlarında seçilebildiğini (allowedFrom) verir. cancel eyleminde yalnız selectable: true olan kodlar kullanılır. Liste sayfasızdır.

• Teslim edilemedi sebepleri (customer_unreachable, invalid_address) yalnız sipariş on_the_way iken kabul edilir; yoldaki sipariş başka bir sebeple iptal edilemez.
• Online ödenmiş siparişin iptali ödemeyi müşteriye iade eder. Teslim edilemedi sonucunda satışın nasıl kapandığı deliveryFailed.completedSale alanında yazar: restoranda true ise satış tamamlanmıştır, status cancelled olsa da kasada iptal edilmez ve online ödenmiş satış olarak kapatılır. Çarşı'da her zaman false; online ödemede tutarın tamamı müşteriye iade edilir.
• Çarşı'da teslim edilemedi olarak iptal edilen siparişin dönüşü POST /orders/{id}/return ile onaylanır (Toplama ve Dönüş).

Kabul edilmeyen siparişin otomatik iptali

Kabul edilmeyen pending sipariş, işletmeye düşmesinden 12 dakika sonra acceptance_timeout sebebiyle otomatik iptal edilir; iki dikeyde de geçerlidir ve işletmenin performansına yazılır. Süre siparişin işletmeye düştüğü andan işler; online ödemede bu an ödemenin onaylandığı andır. accept bu süre dolmadan yazılmalıdır.

Çarşı'da ileri tarihli (planlı) sipariş otomatik iptal edilmez. Restoranda planlı sipariş de bu süre içinde kabul edilmelidir. Test siparişleri (isTest: true) otomatik iptal kapsamına girmez.