TMS API

CommerceLab TMS (CargoHub) Open API; siparişlerinizi ve gönderilerinizi TMS'e aktarmanızı, sepet için uygun taşıyıcı ve servis tiplerini sorgulamanızı, kargo etiketi almanızı, gönderi durumunu izlemenizi ve iade süreçlerini yönetmenizi sağlar.

Kimlik doğrulama

1. POST /openapi/Auth/Login ile size verilen API kullanıcı adı ve parolasıyla oturum açın.
2. Yanıttaki token değerini sonraki tüm isteklerde Authorization: Bearer <token> başlığıyla gönderin.
3. Token 24 saat geçerlidir (expiration alanı bitiş zamanını verir). Süresi dolunca yeniden giriş yapın.

Token'sız ya da süresi dolmuş token'la yapılan isteklere 401 Unauthorized (gövdesiz) döner.

Organizasyon ve hesap kodları

Çoğu istek gövdesinde clientCode (organizasyon kodu) ve accountCode (hesap kodu) beklenir. Bu kodlar CommerceLab tarafından size iletilir; API kullanıcınızın ilgili hesapta yetkisi yoksa istek Kullanıcının accounta işlem yapma yetkisi bulunmuyor mesajıyla reddedilir. İade uçlarında bu iki alan kullanımdan kalkmaktadır: kimlik token'dan çözülür.

İstek ve yanıt biçimi

• Tüm gövdeler JSON'dur. Alan adları büyük/küçük harf duyarsız okunur; yanıtlar camelCase döner.
• Tarihler yyyy-MM-ddTHH:mm:ss (ISO 8601) biçimindedir ve Türkiye saatiyle yorumlanır.
• Bazı uçlar yalnızca bir mesaj metni döner; bu yanıtlar text/plain gelir (Accept: application/json gönderirseniz aynı metin JSON dizesi olarak gelir).
• Birçok uç { success, message, code, data } zarfı kullanır; success: false olduğunda HTTP durumu 400 olur ve hata nedeni message alanındadır.
• Gövde JSON olarak çözülemezse 400 ile ASP.NET doğrulama yanıtı (application/problem+json) döner.
• Beklenmeyen sunucu hatalarında 500 ile { "Message": "Internal Server Error", "StatusCode": 500 } döner.

İstek sınırları

Kullanıcı başına tüm uçlar için 10 saniyede 200 istek sınırı vardır. Shipment/GetShipmentStatus ve Shipment/UpdateShipmentAttributeData için sınır saniyede 1 istektir. Sınır aşıldığında 429 döner. Auth/Login sınıra tabi değildir.

Asenkron kayıt (ticket)

Order/SaveOrder ve Consignment/SaveConsignment istekleri kuyruğa alınır ve bir ticketNumber döner. İşlemin sonucunu IntegrationHistory/GetTicketNumberStatus ile sorgulayın. Organizasyonunuz için asenkron kayıt kapatılmışsa istek anında işlenir ve synchronous: true döner.

Ortamlar

• Test: https://openapi.tms.awstest.hebiar.com
• Prod: https://openapi.tms.prod.hebiar.com

Kimlik Doğrulama

• POST /openapi/Auth/Login — Token al

Taşıyıcı Seçimi

• POST /openapi/Checkout/GetAvailableCarriersAndServiceTypes — Uygun taşıyıcı ve servis tiplerini getir

Sipariş ve Gönderi Kaydı

• POST /openapi/Order/SaveOrder — Sipariş kaydet
• POST /openapi/Order/QuickLabel — Hızlı etiket
• POST /openapi/Order/UnArchiveOrder — Arşivlenmiş siparişi geri al
• POST /openapi/Consignment/SaveConsignment — Gönderi kaydet
• POST /openapi/IntegrationHistory/GetTicketNumberStatus — Kayıt (ticket) durumunu sorgula

Gönderi Güncelleme ve İptal

• POST /openapi/Consignment/UpdateConsignmentAddress — Gönderi adresini güncelle
• POST /openapi/Consignment/UpdateConsignmentCarrier — Gönderi taşıyıcısını değiştir
• POST /openapi/Consignment/UpdateShippingInfo — Sevk bilgisini güncelle
• POST /openapi/Consignment/CancelConsignment — Gönderiyi iptal et
• POST /openapi/Shipment/CancelShipmentOnCarrier — Gönderiyi taşıyıcıda iptal et
• POST /openapi/Shipment/RecallShipment — Gönderiyi taşıyıcıdan geri çek

Etiket

• POST /openapi/Document/CreateLabel — Etiket oluştur
• POST /openapi/Document/CreateLabelInAdvance — Etiketi önceden oluştur
• POST /openapi/Document/GetCreatedLabel — Oluşturulmuş etiketi getir

Takip ve Durum

• POST /openapi/Consignment/GetConsignmentInfo — Sipariş ve gönderi bilgisi
• POST /openapi/Shipment/GetShipmentStatus — Koli durumunu sorgula
• POST /openapi/Report/GetShipmentReport — Değişen gönderiler raporu

Durum Bildirimi

• POST /openapi/Shipment/UpdateShipmentVendorTrackingData — Takip bilgisi bildir
• POST /openapi/Shipment/UpdateShipmentVendorTrackingDataAndCarrier — Takip bilgisi ve taşıyıcı bildir
• POST /openapi/Shipment/UpdateShipmentStatusForAlternativeDelivery — Alternatif teslimat başladı
• POST /openapi/Shipment/UpdateAlternativeDeliveryToDelivered — Alternatif teslimat teslim edildi
• POST /openapi/Shipment/UpdateShipmentAttributeData — Gönderi ek alanlarını güncelle
• POST /openapi/DeliveryReceipt/UpdateShipmentDelivery — Tesellüm durumunu aç/kapat
• POST /deliveryotpinfo — Teslimat noktası OTP bildirimi

İade

• POST /openapi/Return/SaveReturnCode — İade kodu oluştur
• POST /openapi/Return/GetReturnCodeStatus — İade durumu
• POST /openapi/Return/GetReturnLabel — İade etiketi
• POST /openapi/Return/CancelReturnCode — İade kodunu iptal et
• POST /openapi/Return/GetAvailableReturnDates — Uygun iade randevu tarihleri

Ana Veriler

• GET /openapi/MasterData/GetPaymentTypes — Ödeme tipleri
• GET /openapi/MasterData/GetCities — İller
• POST /openapi/MasterData/GetTownsByCityCode — İlçeler
• POST /openapi/MasterData/GetDistrictsByCityTownCode — Mahalleler