Toplama ve Dönüş

İkame tercihi (kalem başına)

Markette ürün her zaman rafta olmaz. Müşteri tercihini sipariş anında kalem kalem belirtir; sipariş kaleminde substitutionPreference olarak gelir:

Toplayıcının hangi işlemi yapabileceğini bu alan belirler; kendi ekranınızda da aynı kısıtı uygulayın. İkame daha pahalıysa fark müşteriden tahsil edilmez; daha ucuzsa fark iade edilir.

Toplama sonucunu yazma

curl -X POST "https://api.supergelsin.com/api/partner/v1/orders/cm_ornek_siparis/picking" \
  -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 '{ "items": [
    { "clientReferenceId": "POS-1042", "status": "not_found" },
    { "clientReferenceId": "POS-1043", "status": "partial", "pickedQuantity": 2, "note": "Stokta 2 adet kaldı" },
    { "clientReferenceId": "POS-1044", "status": "substituted", "substituteClientReferenceId": "POS-2010", "customerApproved": true }
] }'

{ "orderId": "cm_ornek_siparis", "applied": 3, "failed": 0, "completed": false,
  "results": [ { "clientReferenceId": "POS-1042", "ok": true, "refundAmount": 42.5 } ],
  "adjustmentTotal": 42.5 }

Kalem sonuçları ve kapanış tek istekte yazılır. Kalemler sırayla işlenir; bir kalemin reddi öbürlerini etkilemez, her kalemin sonucu results[] içindedir. İade tutarı sunucuda hesaplanır. İlk kalem sonucu yazıldığında confirmed sipariş preparing olur. Toplama yalnız confirmed ya da preparing siparişte yazılır.

Kalem düzeyindeki ret kodları (order_not_pickable, picking_closed, invalid_weight, substitution_not_allowed, approval_required ve diğerleri) results[].error içinde döner; tam liste Hata Kodları sayfasındadır.

Toplamayı kapatma

curl -X POST "https://api.supergelsin.com/api/partner/v1/orders/cm_ornek_siparis/picking" \
  -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 '{ "complete": true, "receiptUrl": "https://ornek-entegrator.example/fis/1044.jpg", "bagCount": 3 }'

complete: true toplamayı kapatır; yalnız items gönderen istek kapatmaz. items ya da complete: true alanlarından en az biri gerekir. receiptUrl ve bagCount yalnız complete: true ile gönderilir. Toplama kapandıktan sonra POST /orders/{id}/status ile dispatch yazılabilir.

• Kapanış reddedilirse önceki kalem sonuçları geri alınmaz.
• Tamamlanmış siparişe tekrar complete gönderilirse 200 ve completed: true döner; iade, defter ve bildirim yeniden çalışmaz. Tamamlanmış bir sipariş sonradan toplanamaz duruma geçerse (ör. iptal) complete tekrarı 409 picking_incomplete döner.
• Fiş görseli ve poşet adedi yalnız kapanış başarılıysa yazılır. Fiş görseli dış bir https bağlantısından indirilip platform deposuna alınır (görsel, en fazla 8 MB). Fiş zaten kayıtlıysa yeniden yazılmaz ve receipt_already_saved uyarısı döner; yalnız bagCount gönderilen tekrar isteğinde poşet adedi de yazılmaz. Fiş görseli kopyalanamazsa kapanış durmaz, receipt_not_saved uyarısı döner.
• Toplama eksiği kapıda tahsil edilecek tutardan düşer: adjustmentTotal yanıtta, payment.dueAmount sipariş gövdesinde güncellenir. Siparişi toplama sonrasında yeniden okuyun.

Müşteri verisi ve test siparişi

Çarşı siparişinde müşteri telefonu, enlem ve boylamı hiçbir zaman paylaşılmaz; customer.phone, latitude ve longitude her zaman null döner. Sipariş teslim edildikten ya da iptal edildikten 2 saat sonra müşteri bilgisi daraltılır: ad kısalır (Ayşe Y.), adres yalnız İlçe / İl olarak kalır ve müşterinin serbest notu note alanından düşer. customer.redacted daraltmanın yapıldığını, visibleUntil tam görünürlüğün bitiş anını söyler. Daraltılmış alanlar hata değildir; entegrasyonunuz bunlara hata vermemelidir. Bu veriyi kendi tarafınızda da süresiz saklamayın (KVKK m.4/2).

isTest: true, siparişin POST /orders/test ile açılmış bir test siparişi olduğunu gösterir. Test siparişi işletmenin toplama ekranına düşmez (toplama sonucu bu API ile yazılabilir); ciroya, komisyona ve hakedişe girmez.

Teslim edilemeyen siparişin dönüşü

Kurye müşteriye ulaşamaz ya da adres yanlışsa yoldaki sipariş yalnız customer_unreachable ya da invalid_address koduyla iptal edilir. Çarşı'da bu durumda online ödemede tutarın tamamı müşteriye iade edilir (deliveryFailed.completedSale her zaman false). Ürünler dükkâna dönünce dönüş kalem kalem onaylanır.

curl "https://api.supergelsin.com/api/partner/v1/orders?status=return_pending" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01"

curl -X POST "https://api.supergelsin.com/api/partner/v1/orders/cm_ornek_siparis/return" \
  -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 '{ "lines": [{ "lineId": "cm_ornek_satir", "returnedQuantity": 1, "reason": "lost" }] }'

Bekleyen satırlar GET /orders/{id} yanıtındaki returnLines alanındadır (lineId, clientReferenceId, sku, barcode, name, quantity). Her satır tam bir kez gönderilir. Dönen adet stoğa eklenir; dönmeyen adet için reason (lost kayıp, damaged hasarlı) zorunludur ve sebep siparişin kaydına geçer. İki eşzamanlı onaydan yalnız biri uygulanır. Yanıt { orderId, restockedLines } biçimindedir.