Satıcı entegrasyonu
Satıcının kendi yazılımının konuştuğu karşılama (fulfilment) yüzeyi. Personel JWT'si değil, `x-api-key` makine anahtarı kullanılır. Bu bölümdeki her uç, çağıran anahtarın sahibi satıcının **kendi** siparişlerine kapalıdır: hiçbir rota satıcı kimliği almaz, yetki anahtardan türer. Başka bir satıcının sipariş id'si `404` döner — `403` değil, çünkü "senin değil" ile "yok" ayrımı platformun sipariş hacmini ele verir. Satıcıya iptal, iade ve teslim işaretleme **verilmez**. Kasa teslim noktasında zilyetlik bize geçer ve sonrasındaki her kayıt bizimdir.
/v1/integration/orders x-api-key Karşılanacak sipariş beslemesi
Satıcının kendi şubelerine düşen siparişler. Sıralama, kasası en önce sahilde olması gereken siparişten başlar (slotStartAt artan).
Varsayılan süzgeç eylem bekleyen kümedir (PAID + PICKING), arşiv değil: status verilmezse kapanmış siparişler beslemeye girmez.
Yoklama (polling) için updatedSince kullanın. Karşılaştırma siparişin son durum değişikliğine göredir; bizim tarafımızdan girilen bir eksik toplama da, bir iptal de siparişi tekrar pencerenize sokar.
Müşteri adı, telefonu, teknesi ve konumu bu yanıtta yoktur. Karşılama modelinde satıcı müşteriyle buluşmaz, dolayısıyla bu veriler satıcının tutacağı veriler değildir.
Parametreler
| Ad | Yer | Tip | Açıklama |
|---|---|---|---|
status | query | "PAID" | "PICKING" | "PACKED" | Tek bir duruma daraltır. Verilmezse PAID + PICKING. |
updatedSince | query | string (date-time) | Yoklama imi — bu andan sonra durumu değişmiş siparişler. |
page | query | integer ≥ 1 · varsayılan 1 | |
perPage | query | integer 1–100 · varsayılan 24 |
Yanıtlar
| Durum | Gövde | Açıklama |
|---|---|---|
| 200 | PageMeta + { items: SellerOrderDto[] } | Sipariş sayfası. |
| 400 | ApiError | validation_failed — gövde veya query şemaya uymuyor (details). |
| 401 | ApiError | missing_api_key — x-api-key başlığı yok; veya invalid_api_key.
İkinci kod tek bir koddur ve her başarısızlık modunu kapsar:
çözümlenemeyen anahtar, bilinmeyen önek, yanlış gizli bölüm, iptal
edilmiş anahtar, kapatılmış satıcı. Hangisinin yanlış olduğunu söylemek,
çağırana doğruya nasıl yaklaşacağını söylemek olurdu. |
| 403 | ApiError | insufficient_scope — anahtar geçerli ama bu ucun kapsamı yok; eksik
kapsamlar gövdedeki missing dizisindedir. |
/v1/integration/orders/{id} x-api-key Sipariş detayı
Tek siparişin tam hâli. Başka bir satıcıya ait id 404 döner.
Parametreler
| Ad | Yer | Tip | Açıklama |
|---|---|---|---|
id * | path | string |
Yanıtlar
| Durum | Gövde | Açıklama |
|---|---|---|
| 200 | SellerOrderDto | Sipariş. |
| 401 | ApiError | missing_api_key — x-api-key başlığı yok; veya invalid_api_key.
İkinci kod tek bir koddur ve her başarısızlık modunu kapsar:
çözümlenemeyen anahtar, bilinmeyen önek, yanlış gizli bölüm, iptal
edilmiş anahtar, kapatılmış satıcı. Hangisinin yanlış olduğunu söylemek,
çağırana doğruya nasıl yaklaşacağını söylemek olurdu. |
| 403 | ApiError | insufficient_scope — anahtar geçerli ama bu ucun kapsamı yok; eksik
kapsamlar gövdedeki missing dizisindedir. |
| 404 | ApiError | order_not_found — yok ya da sizin değil. |
/v1/integration/orders/{id}/accept x-api-key Siparişi toplamaya al
PAID → PICKING. Siparişi kendi toplama listenize aldığınızı bildirir.
Sipariş PAID değilse 409 order_status_conflict döner ve gövde expected ile actual durumu taşır. Bu uç idempotent değildir: zaten PICKING olan bir siparişi tekrar kabul etmek çakışma verir, ki bu doğrudur — ikinci çağrı yeni bir olay değil, ya tekrar ya yarıştır.
Parametreler
| Ad | Yer | Tip | Açıklama |
|---|---|---|---|
id * | path | string |
Yanıtlar
| Durum | Gövde | Açıklama |
|---|---|---|
| 200 | SellerOrderDto | Güncel sipariş. |
| 401 | ApiError | missing_api_key — x-api-key başlığı yok; veya invalid_api_key.
İkinci kod tek bir koddur ve her başarısızlık modunu kapsar:
çözümlenemeyen anahtar, bilinmeyen önek, yanlış gizli bölüm, iptal
edilmiş anahtar, kapatılmış satıcı. Hangisinin yanlış olduğunu söylemek,
çağırana doğruya nasıl yaklaşacağını söylemek olurdu. |
| 403 | ApiError | insufficient_scope — anahtar geçerli ama bu ucun kapsamı yok; eksik
kapsamlar gövdedeki missing dizisindedir. |
| 404 | ApiError | order_not_found — yok ya da sizin değil. |
| 409 | ApiError | order_status_conflict — expected ve actual gövdededir. |
/v1/integration/orders/{id}/items/{itemId}/pick x-api-key Kalem için toplanan adedi bildir
"Bu kalem eksik çıktı." Mağazadaki kendi toplayıcımızın yürüttüğü yolun aynısını çalıştırır: stok defteri kaydı, raf sayım uyarısı ve müşterinin kısmi iadesi bunun arkasından gelir.
pickedQty yalnızca aşağı inebilir. Daha önce bildirilen bir adedi yükseltmek picked_qty_cannot_increase ile reddedilir; müşteriye iadesi yapılacağı söylenmiş parayı geri almak demek olurdu. Sipariş adedinin üstü picked_qty_above_ordered verir.
Sipariş PICKING durumunda değilse 409 order_not_picking döner — yani önce accept çağrılmalıdır.
Parametreler
| Ad | Yer | Tip | Açıklama |
|---|---|---|---|
id * | path | string | |
itemId * | path | string | items[].id — sipariş kalemi id'si, SKU değil. |
İstek gövdesi SellerPickItemRequest
Yanıtlar
| Durum | Gövde | Açıklama |
|---|---|---|
| 200 | SellerOrderDto | Güncel sipariş. |
| 400 | ApiError | validation_failed — gövde veya query şemaya uymuyor (details). |
| 401 | ApiError | missing_api_key — x-api-key başlığı yok; veya invalid_api_key.
İkinci kod tek bir koddur ve her başarısızlık modunu kapsar:
çözümlenemeyen anahtar, bilinmeyen önek, yanlış gizli bölüm, iptal
edilmiş anahtar, kapatılmış satıcı. Hangisinin yanlış olduğunu söylemek,
çağırana doğruya nasıl yaklaşacağını söylemek olurdu. |
| 403 | ApiError | insufficient_scope — anahtar geçerli ama bu ucun kapsamı yok; eksik
kapsamlar gövdedeki missing dizisindedir. |
| 404 | ApiError | order_not_found veya order_item_not_found. |
| 409 | ApiError | order_not_picking, picked_qty_above_ordered veya
picked_qty_cannot_increase. |
/v1/integration/orders/{id}/dispatch x-api-key Kasa teslim noktasına çıktı
Kasanın mağazanızdan kasa teslim noktasına doğru yola çıktığını damgalar.
Bilerek durum geçişi değildir: kasa yoldayken zilyetlik hâlâ satıcıdadır, teslim noktasında bizim personelimizin kabulü (PICKING → PACKED) onu taşır. Zaman damgası olarak kalması, "hiç çıkmadı" ile "çıktı ama ulaşmadı" sorularının farklı cevapları olmasını sağlar.
Idempotenttir: tekrarlanan çağrı İLK çıkış saatini korur. İkinci çağrı ikinci bir çıkış değil, ağın emin olamamasıdır.
Sipariş PICKING değilse 404 order_not_picking döner.
Parametreler
| Ad | Yer | Tip | Açıklama |
|---|---|---|---|
id * | path | string |
Yanıtlar
| Durum | Gövde | Açıklama |
|---|---|---|
| 200 | SellerOrderDto | Güncel sipariş; sellerDispatchedAt dolu. |
| 401 | ApiError | missing_api_key — x-api-key başlığı yok; veya invalid_api_key.
İkinci kod tek bir koddur ve her başarısızlık modunu kapsar:
çözümlenemeyen anahtar, bilinmeyen önek, yanlış gizli bölüm, iptal
edilmiş anahtar, kapatılmış satıcı. Hangisinin yanlış olduğunu söylemek,
çağırana doğruya nasıl yaklaşacağını söylemek olurdu. |
| 403 | ApiError | insufficient_scope — anahtar geçerli ama bu ucun kapsamı yok; eksik
kapsamlar gövdedeki missing dizisindedir. |
| 404 | ApiError | order_not_found veya order_not_picking. |