T-SOFT/Admin API/Gönderiler ve Kargo

Gönderiler ve Kargo

Kapsam: gönderileri okumak read_orders, oluşturmak ve güncellemek write_fulfillments; kargo firması, ücret ve bölge tanımları read_shipping / write_shipping.

Bu uçlar kargo entegrasyonu yapan uygulamalar içindir: siparişten gönderi açmak, kargo firmasından gelen hareketi mağazaya işlemek ve mağazanın kargo tanımlarını okumak.

Gönderiler

Uç	Metot	Kapsam
`order/shipments`	`GET`	`read_orders`
`order/shipments`	`POST`	`write_fulfillments`
`order/shipments/{id}`	`PATCH`, `DELETE`	`write_fulfillments`
`order/shipments/{id}/-actions/log`	`POST`	`write_fulfillments`

Listeleme bir sipariş filtresi ister; filtresiz istek 400 döner:

GET /order/shipments

curl 'https://magaza.com/api/v3/admin/2026-01/order/shipments?filter[orderId]=1042' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json'

Filtreler: orderId, cargoKey. Başlıca alanlar:

Alan	Açıklama
`orderId`, `orderNumber`	Sipariş
`cargoKey`	Gönderinin kargo anahtarı
`cargoCompanyId`, `cargoCompany`	Kargo firması
`cargoTrackingNo`, `cargoTrackingUrl`	Takip numarası ve adresi
`status`, `statusDescription`	Gönderi durumu
`receiver`, `receiverAddress`, `receiverPhone1`, `city`	Alıcı bilgisi
`cargoCount`, `weight`, `volumetricWeight`	Koli sayısı, ağırlık ve desi
`invoiceNumber`, `waybillNumber`	Fatura ve irsaliye numarası
`shipmentType`	`0` gönderi, `1` iade gönderisi
`shippedDate`, `deliveryDate`	Kargoya veriliş ve teslim zamanı

Gönderi oluşturma

POST /order/shipments

curl -X POST 'https://magaza.com/api/v3/admin/2026-01/order/shipments' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "shipments",
      "attributes": {
        "orderId": 1042,
        "cargoCompanyId": 3,
        "carryOrderProduct": [{"id": 5521, "count": 1}, {"id": 5522, "count": 2}],
        "weight": [1.2],
        "volumetricWeight": [2]
      }
    }
  }'

Alan	Zorunlu	Açıklama
`orderId`	Evet	Sipariş
`cargoCompanyId`	Evet	Kargo firması (Kargo firmaları)
`carryOrderProduct`	Evet	Gönderiye girecek sipariş kalemleri: kalem kimliği (`id`, Sipariş kalemleri) ve adet (`count`)
`weight`, `volumetricWeight`	Hayır	Koli başına ağırlık ve desi
`cargoCount`	Hayır	Koli sayısı

Kargo hareketi bildirme

Kargo firmasından gelen hareketi gönderiye işler. Teslim ve kargoya veriliş kodları siparişin durumunu da ilerletir.

POST /order/shipments/{id}/-actions/log

curl -X POST 'https://magaza.com/api/v3/admin/2026-01/order/shipments/881/-actions/log' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/json' \
  -d '{"messageCode": "IQU001", "cargoTrackingNo": "TRK123456", "cargoTrackingUrl": "https://kargo.example.com/TRK123456"}'

`messageCode`	Anlamı	Siparişe etkisi
`IQU001`, `IQU002`, `IQU003`, `IQU004`	Kargoya verildi / yolda	Sipariş "Kargoya verildi" durumuna geçer
`IQU009`	Teslim edildi	Sipariş "Teslim edildi" durumuna geçer
`IQU007`, `IQU099`	Kargo firmasının olumsuz yanıtı	Yalnız gönderinin durumu güncellenir
Diğer kodlar	Bilgi	Takip numarası, şube ve tutar alanları işlenir

Diğer alanlar (hepsi isteğe bağlı): messageText, cargoTrackingNo, cargoTrackingUrl, realTotalDesi, realCargoAmount, shipperBranchOffice, receiverBranchOffice, cargoLastMovement, cargoStatusDate. Gövde düz JSON'dur.

Durumu ilerleten kodlar, sipariş durumunu değiştirmeyle aynı kurala bağlıdır: siparişin mevcut durumu uygulamaların değiştiremeyeceği bir durumsa 422 döner (Sipariş durumunu değiştirme).

Kargo firmaları

order/cargo-companies: okuma read_shipping, yazma write_shipping.

Alan	Açıklama
`name`	Firma adı
`wsCode`	Entegrasyon kodu
`integration`	Bağlı kargo entegrasyonu
`isCustomerActive`, `isVendorActive`	Müşteriye ve bayiye açık mı
`isDefaultCargo`	Varsayılan firma
`customerFreeCargoLimit`, `vendorFreeCargoLimit`	Ücretsiz kargo alt sınırı
`isRegionalShippingActive`	Bölgesel gönderim açık mı (Kargo bölgeleri)
`returnable`	İade gönderisinde kullanılabilir mi

Filtreler: id, name, isCustomerActive, isVendorActive, isRegionalShippingActive; tam eşleşme için exact. öneki.

Kargo ücretleri

order/shipping-costs: okuma read_shipping, yazma write_shipping. Her kayıt bir firmanın bir desi aralığındaki ücretidir.

Alan	Açıklama
`companyId`	Kargo firması
`lowerLimit`, `upperLimit`	Desi aralığı
`inCitySum`, `outOfCitySum`, `globalSum`	Şehir içi, şehir dışı ve yurt dışı ücret
`additionalPricePerCbm`	Aralığın üstündeki her desi için ek ücret

Filtre: companyId. Oluştururken companyId, lowerLimit, upperLimit ve üç ücret alanı zorunludur; upperLimit, lowerLimit'ten büyük olmalıdır.

Kargo bölgeleri

order/cargo-regions: bir bölgeye (il, ilçe) hangi kargo firmalarının gidebileceği. Okuma read_shipping, yazma write_shipping.

Alan	Açıklama
`regionType`	Bölge türü
`regionCode`	Bölge kodu (Bölgeler)
`cargoIds`	Bu bölgeye gönderim yapan firmalar
`defaultCargoId`	Bölgenin varsayılan firması

cargoIds yazılırken dizinin tamamı gönderilir; tek firma eklemek için mevcut listeyi okuyup yeni firmayı ekleyin. Listedeki firmaların bölgesel gönderimi açık olmalıdır.