T-SOFT/Admin API/Siparişler

Siparişler

Kapsam: okuma için read_orders, durum değiştirmek için write_order_status, fatura bilgisi ve not yazmak için write_orders. Müşterinin adı, e-postası, telefonu ve adresi için ayrıca read_customer_personal_data (Müşteri kişisel verisi).

Siparişleri listeleme

GET /order/orders

curl 'https://magaza.com/api/v3/admin/2026-01/order/orders?filter[placedBetween]=2026-10-01,2026-10-31&include=items&sort=-createdAt' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json'

Tek sipariş için GET /order/orders/{id}.

Alanlar

Alan	Tür	Açıklama
`orderNumber`	string	Sipariş numarası
`orderStatus`	integer	Durum; adı için Sipariş durumları
`fulfillmentStatusId`	integer	Hazırlık/gönderim durumu
`currency`	string	Para birimi
`paymentMethod`, `paymentSubMethod`	string	Ödeme yöntemi
`orderTotal`	number	Sipariş toplamı
`orderSubtotal`, `orderTax`	number	Ara toplam ve vergi
`productsTotal`, `cargoTotal`	number	Ürün ve kargo tutarı
`cargoNumber`	string	Kargo takip numarası
`customerId`	integer	Müşteri
`customerFirstName`, `customerLastName`, `customerEmail`, `customerPhone`	string	Sipariş anındaki müşteri bilgisi
`customerGroupName`	string	Müşteri grubu
`isInvoiced`, `invoiceNumber`, `waybillNumber`	boolean, string	Fatura ve irsaliye
`createdAt`	datetime	Sipariş zamanı

customerFirstName, customerLastName, customerEmail ve customerPhone yalnız read_customer_personal_data ya da read_customers kapsamı olan uygulamaya dolu gelir; diğerlerine null döner. Bu veriyi yalnız uygulamanızın işi için saklayın ve uygulama kaldırıldığında silin.

Filtreler ve sıralama

Filtre	Örnek
`id`	`filter[id]=1042,1043`
`orderNumber`	`filter[orderNumber]=TS-1042`
`customerId`	`filter[customerId]=318`
`orderStatus`	`filter[orderStatus]=1,2`
`placedBetween`	`filter[placedBetween]=2026-10-01,2026-10-31`

Sıralama: orderNumber, orderStatus, orderTotal, createdAt, id.

Yeni siparişleri periyodik çekmek yerine ORDER.CREATE olayına abone olun; kaçırılan olaylar için placedBetween ile aralık sorgusu yapın.

Sipariş kalemleri

?include=items ya da GET /order/orders/{id}/items ile gelir; tipi order-products'tır. ?include=items.product ürün kaydını da ekler.

Alan	Açıklama
`productId`	Ürün
`productName`, `productCode`, `barcode`	Sipariş anındaki ürün bilgisi
`variantName`, `variantProductCode`, `variantWsProductCode`	Varyant bilgisi
`quantity`, `quantityRefund`	Adet ve iade edilen adet
`salePrice`, `totalSalePrice`	Birim ve satır tutarı
`taxRate`	KDV oranı
`orderStatus`	Kalemin durumu

Müşteri kaydı için ?include=customer. Kişisel veri kapsamı yoksa müşterinin adı, e-postası ve telefonları null gelir.

Sipariş durumları

Durumlar mağazaya göre değişir; kimlikleri sabit kodlamayın, bu uçtan okuyun.

GET /order/order-statuses

curl 'https://magaza.com/api/v3/admin/2026-01/order/order-statuses' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json'

Alan	Açıklama
`name`	Paneldeki ad
`nameSeenByUser`	Müşteriye gösterilen ad
`isActive`	Kullanımda mı
`listNo`	Sıra
`disallowCargoAppPermission`	`1` ise uygulamalar siparişi bu durumdan başka duruma taşıyamaz

Sipariş durumunu değiştirme

POST /order/orders/{id}/-actions/status

curl -X POST 'https://magaza.com/api/v3/admin/2026-01/order/orders/1042/-actions/status' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/json' \
  -d '{"orderStatusId": 4, "currentStatusId": 2, "cargoNumber": "TRK123456"}'

Alan	Zorunlu	Açıklama
`orderStatusId`	Evet	Yeni durum; aktif bir durum olmalı
`currentStatusId`	Hayır	Siparişin şu an bu durumda olmasını beklediğinizi belirtir; değilse `409` döner
`cargoNumber`	Hayır	Kargo takip numarası
`cargoCompanyId`	Hayır	Kargo firması

Durum değişikliği panelden yapılan değişiklikle aynı akışı işletir ve ORDER.STATUS.CHANGE olayını tetikler. Durum aynı kalırsa (yalnız kargo numarası güncellenirse) olay gönderilmez. Yanıt güncellenmiş sipariş kaydıdır.

Şu durumlarda 422 döner:

Sipariş "tamamlanmamış" durumdaysa,
Siparişin mevcut durumunda disallowCargoAppPermission değeri 1 ise,
Mağazanın durum kuralları geçişe izin vermiyorsa (detail alanı nedeni yazar).

currentStatusId göndermek, mağaza sahibi siparişi panelden değiştirdikten sonra sizin eski bilgiyle üzerine yazmanızı engeller.

Fatura bilgisi yazma

E-fatura ve e-arşiv uygulamaları kestikleri faturanın bilgisini siparişe bu uçla yazar.

POST /order/orders/{id}/-actions/invoice

curl -X POST 'https://magaza.com/api/v3/admin/2026-01/order/orders/1042/-actions/invoice' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/json' \
  -d '{"isInvoiced": true, "invoiceNumber": "GIB2026000000001", "invoiceDate": 1793700000, "isEarchive": true, "einvoiceLink": "https://fatura.example.com/GIB2026000000001.pdf"}'

Alan	Zorunlu	Açıklama
`isInvoiced`	Evet	Sipariş faturalandı mı
`invoiceNumber`	Hayır	Fatura numarası (en fazla 128 karakter)
`invoiceDate`	Hayır	Fatura tarihi (Unix zaman damgası, saniye)
`waybillNumber`	Hayır	İrsaliye numarası (en fazla 16 karakter)
`isEarchive`	Hayır	E-arşiv faturası mı
`earchiveUuid`	Hayır	E-arşiv ETTN
`einvoiceLink`	Hayır	Faturanın görüntülenebileceği adres

Gövde düz JSON'dur. Kapsam write_orders. Yanıt güncellenmiş sipariş kaydıdır; yazılan değerler siparişin isInvoiced, invoiceNumber, invoiceDate, waybillNumber, isEarchive, earchiveUuid ve einvoiceLink alanlarında görünür.

Sipariş notları

Uç	Metot	Kapsam
`order/order-notes?filter[orderId]={id}`	`GET`	`read_orders`
`order/order-notes`	`POST`	`write_orders`

Listeleme sipariş filtresi ister. Uygulamanın yazdığı not, panelde uygulamanın adıyla görünür.

POST /order/order-notes

curl -X POST 'https://magaza.com/api/v3/admin/2026-01/order/order-notes' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{"data": {"type": "order-notes", "attributes": {"orderId": 1042, "text": "Fatura e-postayla gönderildi."}}}'

Alanlar: orderId, text, noteType, adminName, createdAt.