API referansı · 4 uç nokta

Orders

Müşterinin kendi siparişleri — sepeti siparişe çevirme, geçmiş, iptal. Hiçbir rota müşteri kimliği almaz: davranan müşteri token'dan gelir, yol parametresi değildir, dolayısıyla gezinilecek bir `/customers/{id}` yüzeyi yoktur. Başkasına ait kayıt `404` döner — `403`, siparişin var olduğunu doğrulardı.

GET /v1/orders Bearer

Kendi sipariş geçmişi

Yeniden eskiye. Yanıt Cache-Control: no-store taşır.

Parametreler

Ad	Yer	Tip	Açıklama
`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: OrderDto[] }`	Sipariş sayfası.
400	`ApiError`	`validation_failed` — gövde veya query şemaya uymuyor (`details`).
401	`ApiError`	`missing_token`, `invalid_token` veya `unauthenticated`.

POST /v1/orders Bearer

Sipariş oluşturur (checkout)

Gövde bir öneridir. İstemcinin gönderdiği fiyat, toplam ve şube okunmaz; hepsi sunucuda yeniden hesaplanır. İstemci yalnızca ürünleri, adetleri, teslim yerini ve slotu adlandırır.

Bir ürün en fazla bir kez geçebilir — aynı ürün için iki satır validation_failed ile reddedilir, satırları toplayıp tek satır gönderin.

Sipariş PENDING_PAYMENT durumunda doğar ve stok rezerve edilir; reservationExpiresAt anına kadar ödenmezse süpürücü onu düşürür.

Parametreler

Ad	Yer	Tip	Açıklama
`Idempotency-Key`	header	`string` en fazla 200 karakter	Aynı checkout denemesinin tekrarlarında aynı değer gönderilir; çift dokunuş, kopuk ağ ve arka plana atılmış uygulama tek siparişte buluşur. Müşteri bazında ayrıştırılır, başkasının siparişine düşemez. Boş/boşluk = "tekilleştirme yok" (izinli). 200 karakterden uzun değer `invalid_idempotency_key` ile reddedilir — kırpmak iki ayrı denemeyi sessizce birleştirirdi.

İstek gövdesi CreateOrderRequest

Yanıtlar

Durum	Gövde	Açıklama
201	`OrderDto`	Sipariş oluşturuldu.
400	`ApiError`	`validation_failed` veya `invalid_idempotency_key`.
401	`ApiError`	`missing_token`, `invalid_token` veya `unauthenticated`.
404	`ApiError`	`delivery_location_not_found`, `slot_not_found` veya `product_unavailable`.
409	`ApiError`	Checkout reddi — `error` koduna bakın: `not_accepting_orders`, `below_minimum_order`, `slot_unavailable`, `slot_cutoff_passed`, `insufficient_stock` (gövdede `details`), `location_not_serviceable`, `product_unavailable`.

GET /v1/orders/{id} Bearer

Sipariş detayı

Ödeme WebView'ı açıkken saniyede bir yoklanır. Yanıt Cache-Control: no-store taşır — uygulamanın "ödendi" kararını verdiği yetkili kaynak budur, önbelleklenmiş bir kopya yanlış sonuca götürürdü.

Parametreler

Ad	Yer	Tip	Açıklama
`id` *	path	`string`

Yanıtlar

Durum	Gövde	Açıklama
200	`OrderDto`	Sipariş.
401	`ApiError`	`missing_token`, `invalid_token` veya `unauthenticated`.
404	`ApiError`	`order_not_found` — yok ya da sizin değil.

POST /v1/orders/{id}/cancel Bearer

Siparişi iptal eder

Yalnızca PENDING_PAYMENT ve PAID iptal edilebilir. PENDING_PAYMENT rezervasyonu ve slot yerini bırakır, para çekilmemiştir; PAID ayrıca stoğu geri koyar ve iade açar. PICKING ve sonrası reddedilir — toplanmış bir kasayı rafa geri koymak operasyonel bir karardır, self-servis değil.

Parametreler

Ad	Yer	Tip	Açıklama
`id` *	path	`string`

İstek gövdesi CancelOrderRequest

Yanıtlar

Durum	Gövde	Açıklama
200	`OrderDto`	Güncel sipariş.
400	`ApiError`	`validation_failed` — gövde veya query şemaya uymuyor (`details`).
401	`ApiError`	`missing_token`, `invalid_token` veya `unauthenticated`.
404	`ApiError`	`order_not_found`.
409	`ApiError`	`cancel_not_allowed` — gövde mevcut `status`u taşır.