Sipariş Oluşturma - createShipping()

Sipariş Oluşturma

Horoz Lojistik Yurtiçi Dağıtım Entegrasyonu üzerinde bulunan createShipping() metodu, Horoz sisteminde göndericisinden alıcısına taşınacak, bünyesinde bir yada birden fazla koli, paket, palet vb taşınacak fiziksel ürün bulunduran bir sevk emri oluşturmak için kullanılması gereken web servis metodudur.

Horoz Lojistik ile yurtiçi dağıtım operasyonu kapsamında anlaşması olan satıcı kendi deposundan son tüketicilerine yapılacak ürün çıkışları için ve/veya bünyesindeki pazar yeri satıcılarının son tüketicilerine ürün çıkışları için createShipping() metodunu kullanarak Horoz Lojistik Yurtiçi Dağıtım Entegrasyonu üzerinden Horoz sistemine sevk emri verisi oluşturabilir.

İstemci tarafından Horoz Lojistik sistemine gönderilen sevk emri bir iş emri niteliğinde olup, Horoz Lojistik Yurtiçi Dağıtım Operasyon Birimi tarafından yapılan planlama ve mal kabul işlemlerinin akabinde operasyon yaşam döngüsüne girerek, satıcısından son tüketicisine taşınacak bir sipariş niteliği kazanır. createShipping() metodu ile ilgili önemli bilgiler ve Horoz sisteminde sevk emri oluşturulurken dikkat edilmesi gerekenler liste halinde aşağıda istemcilerin bilgisine sunulmuştur.

createShipping() metodu POST yöntem ile JSON formatta veri alan, bir RESTful web servis metodudur.
createShipping() metodu ile Horoz sistemine sevk emri gönderimi yaparken, siparişe ait bilgiler metodun body kısmına JSON veri tipinde geçilmelidir. İstemciye ait processKey bilgisi metodun header kısmına parametre tipinde geçilmelidir. createShipping() metodu ile yapılan gönderim UTF-8 olarak encode edilerek Horoz Lojistik Yurtiçi Dağıtım Entegrasyonu Web servisine iletilmelidir.
createShipping() metodu bir ana sevk emri verisi yapısı ve bu ana sevk emri verisi yapısının altında bir dizi listesi olarak içeriğinde ürün bilgileri bulunan bir detay sevk emri yapısından oluşur. Bir sevk emri yapısı içerisinde, son tüketicinin satıcıya verdiği siparişe ait sipariş numarası, gönderen bilgileri, alıcı bilgileri, toplam adet, toplam desi bilgileri ve bu sevk emrinin detayında ilgili siparişe ait bir veya birden fazla ürünü niteleyen ürün kodu, ürün adı, ürün adedi, ürün desisi, ürün ağırlığı bilgilerini içeren ürün bilgileri bulunur.
createShipping() metodu ile Horoz sistemine istemci tarafından bir sevk emri iletilirken, senderCity, senderCounty, recipientCity ve recipientCounty alanlarına istemci tarafından geçilecek bilgilerin Horoz Lojistik sisteminde tanımlı il ve ilçe bilgileri olması gerekir. Aksi halde istemciye createShipping() metodundan hata döner. İstemci Horoz Lojistik sisteminde tanımlı il ve ilçe bilgilerini Horoz Lojistik Yurtiçi Dağıtım Entegrasyonu içerisinde bulunan, GET yöntem ile çalışan listCounties() metodunu kullanarak elde edebilir. Horoz Lojistik sisteminde tanımlı il-ilçe bilgileri, Türkiye Cumhuriyeti İçişleri Bakanlığı Türkiye Mülki İdare Bölümleri Envanteri sisteminden alınarak kümelenip oluşturulmuştur. Mevcut veri aralıklar ile manuel olarak kontrol edilmektedir.
createShipping() metodu ile Horoz sistemine istemci tarafından bir sevk emri iletilirken, Horoz Yurtiçi Dağıtım Entegrasyonu Web servisine gönderilecek istek içerisindeki totalDesi ve shipmentCount alanlarına girilen siparişin bünyesindeki ürünlere ait toplam desi ve toplam adet bilgileri shippingDetail dizi listesi içerisine item olarak geçilen ürün bilgilerindeki desi ve quantity alanlarına geçilen ürün bazındaki desi ve adet bilgileri ile uyumlu olmalıdır. Sipariş gönderimi yapılırken createShipping() metodunun içerisindeki master ve detay bilgilerinde bulunan adet ve desi uyum ilişkisi için hatalı ve beklenen birer örnek gösterim aşağıdaki tablolarda belirtilmiştir.

Ana Kayıt;

REQUESTNUMBER	SENDERTITLE	RECIPIENTTITLE	SHIPMENTCOUNT	TOTALDESI
123456	SATICI UNVAN	ALICI UNVAN	2	320,000

Hatalı Kayıt Detayı;

PRODUCTCODE	PRODUCTNAME	QUANTITY	WEIGHTINKG	TOTALDESI	PRODUCTCATEGORY
PRODUCTCODE-1	PRODUCTNAME-1	1,000	20,650	160,000	YATAK
PRODUCTCODE-1	PRODUCTNAME-1	1,000	20,650	160,000	YATAK

Doğru Kayıt Detayı;

PRODUCTCODE	PRODUCTNAME	QUANTITY	WEIGHTINKG	TOTALDESI	PRODUCTCATEGORY
PRODUCTCODE-1	PRODUCTNAME-1	2,000	41,300	320,000	YATAK

createShipping() metodu ile Horoz sistemine istemci tarafından bir sevk emri iletilirken, Horoz Yurtiçi Dağıtım Entegrasyonu Web servisine gönderilecek istek içerisindeki alanlardan enum veri tipi dışında değer alan shippingType alanı dışındaki string veri tipinde değer alan diğer tüm alanlara geçilecek verilerin UPPERCASE ve Türkçe karakter olarak geçilmesi beklenir.
createShipping() metodu ile Horoz sistemine istemci tarafından bir sevk emri iletilirken, Horoz Yurtiçi Dağıtım Entegrasyonu Web servisine gönderilecek istek içerisindeki alanlardan requestNumber, shipmentCount, totalDesi, quantity, desi ve weightInKg alanları mutlaka dolu geçilmelidir.
İstemci tarafından createShipping() metodu ile Horoz sistemine iletilen sevk emirleri içerisindeki siparişlere ait bilgilerden özellikle desi bilgilerini niteleyen alanlara (totalDesi, desi), siparişlerin bünyesindeki ürünlere ait gerçek desi bilgileri geçilmelidir. Aksi halde sevk emrinin onaylanıp, mal kabul işlemi öncesinde araç planlaması yapılacak aşamada lojistik operasyon için sorun yaşanacaktır. Bu nedenle entegrasyon üzerinden iletilecek sevk emri verisinin gerçekten fiziksel olarak taşınacak ürünlere ait adet ve desi bilgilerini içermesi gerekir.
İstemci tarafından createShipping() metodu ile Horoz sistemine iletilen sevk emirleri içerisindeki ürünlerin bilgileri geçilirken desi ve weightInKg alanlarının her ikisinede ürün bazında birim desi bilgilerinin adet ile çarpılmış hallerinin geçilmesi beklenir.
Horoz Lojistik Yurtiçi Dağıtım Entegrasyonu kapsamında, istemci tarafından createShipping() metodu ile Horoz sistemine dört tip sevk emri verisi gönderilebilir. createShipping() metodu ile gönderilen sevk emirleri için sevk tipi bilgileri, istek içerisinde bulunan shippingType alanına geçilir. Sevk emri tipleri hakkında detaylı bilgi aşağıdaki başlıklar altından görebilirsiniz.

shippingRequest

shippingRequest değeri Horoz Lojistik ile yurtiçi dağıtım operasyonu için anlaşması bulunan satıcının kendi deposundan çıkış yapacağı siparişler için createShipping() metodu ile Horoz sistemine gönderim yapılırken shippingType alanına geçilecek değerdir.

Bu tipin geçildiği sevk emri Horoz Lojistik’in yurtiçi dağıtım operasyonu için anlaşmalı olduğu satıcısından, satıcının son müşterisine yönlü bir siparişi temsil eder. İstemci bu tip bir bildirim için createShipping() metodu ile veri gönderimi yaparken istek içeriğindeki gönderici alanlarına¹ siparişlerin çıkış yapacağı deposunun veya çıkış noktasının bilgilerini geçmelidir. Bunun 2 yöntemi vardır.

İlk yöntem olarak, istemci senderCode alanına daha önce Horoz Lojistik sisteminde tanımlanmış ilgili çıkış noktasının kodunu geçerek, diğer gönderici alanlarını¹ boş bırakır. createShipping() metodunda senderCode alanına geçilen kod bilgisi, sevk emri oluşurken Horoz sisteminde tanımlı müşterinin çıkış lokasyonu bilgilerine bakarak diğer gönderen alanlarını doldurur.

İkinci yöntem olarak, istemcinin senderCode alanına 0 geçerek diğer gönderici alanlarını¹ doldurması beklenir.
Aynı şekilde her iki yöntemde recipientCode alanına uygulanabilmektedir.

return

return değeri Horoz Lojistik ile yurtiçi dağıtım operasyonu için anlaşması bulunan satıcının müşterisinden kendi deposuna iade operasyonunun yürütülmesini istediği siparişler için createShipping() metodu ile Horoz sistemine gönderim yapılırken shippingType alanına geçilecek değerdir.

Bu tipin geçildiği sevk emri Horoz Lojistik’in yurtiçi dağıtım operasyonu için anlaşmalı olduğu satıcısının müşterisinden, satıcının kendisine yönlü bir siparişi temsil eder. İstemci bu tip bir bildirim için createShipping() metodu ile veri gönderimi yaparken istek içeriğindeki gönderici alanlarına¹ siparişlerin alınacağı son müşterinin bilgilerini veya deponun bilgilerini geçmelidir. Bunun 2 yöntemi vardır.

branchSales

branchSales değeri Horoz Lojistik ile yurtiçi dağıtım operasyonu için anlaşması bulunan satıcının e-ticaret operasyonu kapsamında pazaryeri ve/veya mağaza çıkışlarını yapacağı siparişler için createShipping() metodu ile Horoz sistemine gönderim yapılırken shippingType alanına geçilecek değerdir.

Bu tipin geçildiği sevk emri Horoz Lojistik’in yurtiçi dağıtım operasyonu için anlaşmalı olduğu satıcısından, pazaryerinden satıcının son müşterisine yönlü bir siparişi temsil eder. İlgili satıcının pazaryeri ve/veya mağaza çıkışları için createShipping() metodunun alanları doldurulurken senderCode bilgisi 0 geçilir ve diğer gönderici alanları¹ ilgili satıcı pazaryerinin bilgileri ile doldurulur. Aynı şekilde alıcı bilgileri içinde recipientCode bilgisi 0 geçilir ve diğer alıcı alanları² alıcı bilgileri ile doldurulur.

branchReturn

branchReturn değeri Horoz Lojistik ile yurtiçi dağıtım operasyonu için anlaşması bulunan satıcının e-ticaret operasyonu kapsamında pazaryeri ve/veya mağazalara müşterilerinden geri dönecek olan siparişler için createShipping() metodu ile Horoz sistemine gönderim yapılırken shippingType alanına geçilecek değerdir.

Bu tipin geçildiği sevk emri Horoz Lojistik’in yurtiçi dağıtım operasyonu için anlaşmalı olduğu satıcının son müşterisinden, ilgili pazaryerine yönlü bir siparişi temsil eder. İlgili satıcının pazaryeri ve/veya mağaza çıkışları için createShipping() metodunun alanları doldurulurken senderCode bilgisi 0 geçilir ve diğer gönderici alanları¹ ilgili satıcı pazaryerinin bilgileri ile doldurulur. Aynı şekilde alıcı bilgileri içinde recipientCode bilgisi 0 geçilir ve diğer alıcı alanları² alıcı bilgileri ile doldurulur.

POST createShipping()

EndPOINT

http://b2btest.horoz.com.tr:7801/horozshipping_test/v1/createShipping

Parametre Açıklamaları & Kuralları

Aşağıdaki tabloda createShipping() işleminin giriş ve çıkış parametreleri ve bu parametrelerin tür ve formatları listelenmiştir.

Alanlar
Örnek İstek
Örnek Cevap

Alanlar	Açıklama	Veri Tipi	Uzunluk	Alan Yeri	Zorunluluk
`processKey`	İstemci için tanımlanan `processKey` bilgisi	string	100	Header	Zorunlu
`requestNumber`	Sipariş numarası	string	50	inBody Request	Zorunlu
`senderCode`	Gönderen kodu	integer	-	inBody Request	Zorunlu
`senderTitle`	Gönderen unvanı	string	100	inBody Request	Zorunlu
`senderCity`	Gönderen il adı	string	50	inBody Request	Zorunlu
`senderCounty`	Gönderen ilçe adı	string	50	inBody Request	Zorunlu
`senderAdress`	Gönderen adres	string	500	inBody Request	Zorunlu
`senderPhoneNumber`	Gönderen telefon numarası	string	20	inBody Request	Zorunlu
`senderEmail`	Gönderen email	string	100	inBody Request	Opsiyonel
`recipientCode`	Alıcı kodu	integer	-	inBody Request	Zorunlu
`recipientTitle`	Alıcı unvanı	string	100	inBody Request	Zorunlu
`recipientCity`	Alıcı il adı	string	50	inBody Request	Zorunlu
`recipientCounty`	Alıcı ilçe adı	string	50	inBody Request	Zorunlu
`recipientAddress`	Alıcı adres	string	500	inBody Request	Zorunlu
`recipientPhoneNumber`	Alıcı telefon numarası	string	20	inBody Request	Zorunlu
`recipientEmail`	Alıcı email	string	100	inBody Request	Opsiyonel
`taxOffice`	Vergi dairesi	string	20	inBody Request	Opsiyonel
`taxNumber`	Vergi numarası	string	20	inBody Request	Opsiyonel
`shipmentCount`	Toplam adet	integer	-	inBody Request	Zorunlu
`totalDesi`	Toplam desi	float	-	inBody Request	Zorunlu
`shippingType`	Sevk tipi	string	20	inBody Request	Zorunlu
`requestDate`	İstek gönderim tarihi	DATE	YYYY-MM-DD	inBody Request	Zorunlu
`requestedDeliveryDate`	İstenilen teslimat tarihi	DATE	YYYY-MM-DD	inBody Request	Zorunlu
`shippingDetail[]`	Sevk detayı	ArrayList	-	inBody Request	Zorunlu
`productCode`	Ürün kodu	string	50	inBody Request	Zorunlu
`productName`	Ürün adı	string	100	inBody Request	Zorunlu
`quantity`	Adet	integer	-	inBody Request	Zorunlu
`weightInKg`	Ağırlık	float	-	inBody Request	Zorunlu
`desi`	Desi	float	-	inBody Request	Zorunlu
`productCategory`	Ürün kategorisi	string	100	inBody Request	Zorunlu

{
    "requestNumber": "TEST-12399999",
    "senderCode": 0,
    "senderTitle": "SENDER TITLE",
    "senderCity": "İSTANBUL",
    "senderCounty": "BEŞİKTAŞ",
    "senderAdress": "ÖRNEK ADRES İSTANBUL/BEŞİKTAŞ",
    "senderPhoneNumber": "05551112233",
    "senderEmail": "test@mail.com",
    "recipientCode": 0,
    "recipientTitle": "RECIPIENT TITLE",
    "recipientCity": "ANKARA",
    "recipientCounty": "MAMAK",
    "recipientAdress": "ÖRNEK ADRES ANKARA/MAMAK",
    "recipientPhoneNumber": "05443335511",
    "recipientEmail": "test2@mail.com",
    "taxOffice": "TEST OFFICE",
    "taxNumber": "TEST NUMBER",
    "shipmentCount": 5,
    "totalDesi": 50.5,
    "shippingType": "ShippingRequest",
    "requestDate": "2024-09-16",        
    "requestedDeliveryDate": "2024-09-19",
    "shippingDetail": [
        {
            "productCode": "PRODUCTCODE1",
            "productName": "PRODUCTNAME1",
            "quantity": 2,
            "weightInKg": 20.2,
            "desi": 20.2,
            "productCategory": "PRODUCTCATEGORY1"
        },
        {
            "productCode": "PRODUCTCODE2",
            "productName": "PRODUCTNAME2",
            "quantity": 3,
            "weightInKg": 30.3,
            "desi": 30.3,
            "productCategory": "PRODUCTCATEGORY2"
        }
    ]
}

{
    "response": {
        "responseCode": "STA-100",
        "responseMessage": "Kayit islemi basarili"
    }
}

Servis Cevapları

Response Kodu	Response Mesajı	Açıklama
STA-100	Kayit islemi basarili	Sevkiyat oluşturma işleminin başarılı olduğunu ifade eder.
ERR-20001	HATALI IŞLEM ANAHTARI	Geçilen processKey bilgisinin yanlış olduğunu belirtir.
ERR-20002	EKSİK PARAMETRE: TALEP NUMARASI	`requestNumber` bilgisinin eksik girildiğini ifade eder.
ERR-20002	GİRİLEN DEĞER ÇOK UZUN: Alan Adı	Belirtilen alana girilen değerin çok uzun olduğunu belirtir.
ERR-20003	BU TALEP NUMARASI SISTEMDE MEVCUT - Key: XXX TalepNo: XXX	Daha önce aynı `requestNumber` bilgisi ile bir sevkiyat oluşturulduğunu belirtir.
ERR-20005	GEÇERSİZ GÖNDEREN BİLGİSİ	`senderCode` alanına girilen değerin Horoz Sisteminde tanımlı olmadığını belirtir.
ERR-20006	GEÇERSİZ ALICI BİLGİSİ	`recipientCode` alanına girilen değerin Horoz Sisteminde tanımlı olmadığını belirtir.
ERR-20007	EKSİK PARAMETRE: TOPLAM ADET/DESİ	`totalDesi` ve `shipmentCount` alanlarının boş geçildiğini ifade eder.
ERR-20008	EKSİK PARAMETRE: KARGO BİLGİLERİ	shippingDetail arrayi altındaki alanlarda eksik olduğunu ifade eder.
ERR-20009	DESI BILGISI SIFIR OLAMAZ.	`desi` alanlarına girilen değerin 0'dan büyük olması gerekir.
ERR-20012	TOPLAM DESI SIFIR OLAMAZ	`totalDesi` alanına girilen değerin 0'dan büyük olması gerekir.
ERR-20056	`shippingType` BİLGİSİ BOŞ GEÇİLEMEZ.	`shippingType` alanına değer girilmesi gerektiğini belirtir.
ERR-20071	BU TALEP DAHA ÖNCE GÖNDEREN İL/İLÇE YADA ALICI İL/İLÇE BOZUK OLARAK SİSTEME GÖNDERİLMİŞ. KAYDI DÜZELTİP TEKRAR DENEYİNİZ	İstekte geçilen `requestNumber` bilgisi ile daha önce il ve ilçe bilgileri hatalı bir kayıt oluşturulduğunu ve il ilçe bilgilerini doğru bir şekilde girerek aynı `requestNumber` ile kaydın oluşturulması gerektiğini ifade eder.

Dip Notlar

(senderTitle, senderCity, senderCounty, senderAddress, senderPhone...) ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸
(recipeintTitle, recipientCity, recipientCounty, recipientAddress, recipientPhone...) ↩ ↩²