Karayolu Sipariş Oluşturma - createRoadOrder()

Karayolu Sipariş Oluşturma

Horoz Lojistik E-İhracat Entegrasyonu üzerinde bulunan createRoadOrder() metodu, karayolu taşımacılığında yer alacak yurt içinden yurt dışına yapılacak micro ve macro ihracat için işleme alınması gereken kayıtları oluşturmak için kullanılmalıdır. createRoadOrder() metodu ile ilgili önemli bilgiler ve Horoz sisteminde karayolu ihracat siparişi oluşturulurken dikkat edilmesi gerekenler liste halinde aşağıda istemcilerin bilgisine sunulmuştur.

• Sipariş oluşturma yapısının içinde yer alan özellikle micro ihracatın bağlı belgelerinin FTP üzerinden öncelikle gönderilmiş olması sipariş kaydının sisteme eklenmesinde yapılacak ilk kontroldür.

• Sipariş kayıt işleminin özellik açısından faturası kesilmiş belgeleri tamamlanmış ve sevkiyat süreci kesinleşmiş kayıtlardan oluşması gerekir.

• Horoz Lojistik E-İhracat Entegrasyonu Webservis kütüphanesinde siparişin iptal edilmesi veya güncellenmesi gibi metotlar bulunmamaktadır. Horoz sistemine belgeleri ve sipariş isteği başarılı olarak gönderilmiş bir kayıt için herhangi bir nedenden dolayı siparişin iptal edilmesi gereken durumda satıcının HOROZ e-ihracat MT görevlisiyle iletişime geçerek iptal işlemini manuel olarak ilerletmesi gerekir.

• Başarılı olarak gönderilmiş bir siparişin kayıtlı bilgilerinden herhangi biri değiştirilmek istenirse önce üstte bildirilen iptal sürecinin tamamlanması ardından bu metotla yeni bir sipariş olarak o siparişe bağlı olan belgelerin de FTP üzerinden gönderilmesi ile yeni bir sipariş olarak açılması gerekmektedir.

• Sipariş girişinde ihracat tipi micro ise fatura değeri, 15.000 € fatura değerine eşit veya altında ve sipariş ağırlığı, 300 kg sipariş toplam ağırlığına eşit veya altında olması gerekmektedir. Macro ihracat seçimi ise bir kurala tabi değildir.

• Her bir sipariş alıcı bazında tekil olmak zorundadır. Alım tipi, varış ülkesi, ürün adet ve desi-kg bilgisi siparişin fiyatlaması için ve oluşacak ek maliyetlerin belirlenmesi için önemli bilgilerdir.

• Micro ihracat tipi seçiminde ATR Dolaşım Belgesi seçimi durumunda 10 € ATR düzenleme maliyeti oluşacaktır. Sipariş giriş özelliklerinde YDG seçimi yapılmış ise alıcı tipine göre bir yurtdışı gümrük bedeli uygulanacaktır. Macro ihracat tipi seçilmiş ise ATR seçimi yapılmayacak Gümrük Hizmeti seçimi yapılacaktır. Bu seçime göre satıcıya ATR belgesi ve konşimento belgesi Horoz tarafından düzenlenip gönderilecektir. Bu belgelerin sipariş üstüne ek doküman olarak eklenmesi sağlanacaktır. 29 Ürünlerin fiyatlama aşamasında istif durumları, paket tipleri, boyutları ek maliyet oluşması için kontrol edilmektedir.

• createRoadOrder metodu için istemciden beklenen içerik; temel olarak gönderici, alıcı, sipariş bilgileri ve ürün bilgilerinden oluşur. Sipariş iletimi yapılırken gönderen bilgilerinin istemci tarafından dolu geçilip geçilmemesi; serbest gönderim yapılıp, yapılmaması (isFreeSenderInfo: yes/no) ve alım tipi (receptionType : itWillBring/receivedFromAddress) seçeneğine bağlı olarak değişir.

• Serbest seçimi (isfreeSenderInfo: yes/no) fark etmeksizin her oluşacak kayıtta alım tipi kendisi getirecek (receptionType: itWillBring) ise outletLocationId bilgisine horoz toplama noktası tanımlarından (selectCollectionPoints) collectionPointId bilgisi geçilir. Sipariş girişinde kendisi getirecek seçimi yapıldığında varış ülkesine göre ürünün hangi Horoz noktasına getirileceğinin selectCollectionPoints içerisinden belirlenmesi gerekir.

• Serbest seçimi yapılmadıysa (isFreeSenderInfo= no) ve alım tipi adresten alınacak (receptionType: receivedFromAddress) ise satıcının daha önceden tanımlı bir adresten çıkış yapmak istediğini gösterir. O nedenle listSellerAddressPoints()'te bulunan adreslerden seçim yapılması ve outletLocationId bilgisine listSellerAddressPoints metodundaki sellerAddressPointId bilgisi geçilmesi gerekir.

• Serbest seçimi sistemde tanımlı bir duruma tabi olmadan bir çıkış noktası kullanmak demektir. Serbest seçimi yapıldıysa ve alım tipi adresten alınacaksa; bu satıcının örneğin, sadece bir kereliğine tanımladığı adresten ürünün alınmasını istediğini ifade etmek için geçici bir bilgi olarak siparişi gönderen bilgileri (sender bilgileri) ile doldurmasını gerektirir. Bu durumda createRoadOrder() metodu içerisindeki zorunlu gönderen bilgilerinin (senderTitle, senderCountryName, senderCityName, senderCountyName..vb) dolu olarak geçilmesi beklenir. Bu sebeple outletLocationId bilgisinin bir değer olarak gelmesi beklenmez.

• Eğer isFreeSenderInfo: yes geçildi ise ve receptionType: receivedFromAddress olarak geçildi ise siparişe ait gönderen bilgileri istemcinin göndereceği bilgilerden beslenir, bu nedenle bu durumda createRoadOrder() metodu içerisindeki zorunlu gönderen bilgilerinin (senderTitle, senderCountryName, senderCityName, senderCountyName..vb) dolu olarak gönderilmesi beklenir.

• Eğer isFreeSenderInfo: yes/no(farketmeksizin) geçildi ise ve receptionType: itWillBring olarak geçildi ise gönderene ait ülke, il, ilçe, adres ve posta kodu bilgileri selectCollectionPoints metodundan GET olarak alınabilen Horoz depo tanımlarından ilgili outletLocationId için alınır. Eğer geçilen outletLocationId bilgisi Horoz depo tanımlarında mevcut değilse; TANIMSIZ TOPLAMA NOKTASI hatası dönülür.

• Eğer isFreeSenderInfo: no geçildi ise ve receptionType: receivedFromAddress olarak geçildi ise gönderene ait ülke, il, ilçe, adres ve posta kodu bilgileri listSellerAddressPoints metodundan GET olarak alınabilen Horoz çıkış noktaları tanımlarından ilgili outletLocationId için alınır. Eğer geçilen outletLocationId bilgisi satıcı adres tanımlarında mevcut değilse; TANIMSIZ ÇIKIŞ NOKTASI hatası dönülür. TANIMSIZ ÇIKIŞ NOKTASI hatası ve TANIMSIZ TOPLAMA NOKTASI hatası sistemden seçilen sellerAdressPointId ya da collectionPointId dışında bir tanımın outletLocationId parametresine geçilmesi durumunda gönderilir.

• receptionType alanına itWillBring, receivedFromAddress bilgilerinden başka bir bilgi geçilemez, aksi halde receptionType BİLGİSİ receivedFromAddress/itWillBring DIŞINDA BİR DEĞER GEÇİLEMEZ. hatası dönülür.

• Alıcı bilgileri için; eğer destinationLocation bilgisi dolu geçildi ise alıcıya ait ülke, il, ilçe, adres ve posta kodu bilgileri listHorozWareHouses metodundan GET olarak alınabilen Horoz depo tanımlarından ilgili destinationLocation için alınır. Eğer geçilen destinationLocation bilgisi Horoz depo tanımlarında mevcut değilse; TANIMSIZ VARIŞ NOKTASI hatası dönülür. WMS modülü ile bu kullanım anlamlı olacaktır.

• Eğer destinationLocation bilgisi boş geçildi ise siparişe ait alıcı bilgileri istemcinin göndereceği bilgilerden beslenir, bu nedenle bu durumda createRoadOrder metodu içerisindeki zorunlu alıcı bilgilerinin (recipientTitle, recipientCountryName, recipientCityName, vb) dolu olarak gönderilmesi beklenir.

• Entegrasyon üzerinden Horoz sistemine iletilecek karayolu siparişleri için gönderilecek fatura tutarı para birimi bilgilerinin; TRY (Türk Lirası), EUR (Avrupa Birliği Para Birimi), USD (Amerikan Doları) ve GBP (İngiliz Sterlini) olarak gönderilmesi beklenir. Aksi halde istemciye hata dönülür.

• Sipariş bilgilerinde alıcı bilgileri içerisindeki alıcı ülkenin posta kodu fiyatlama açısından varış bilgilerinin içerisine girilmesi zorunlu olmalıdır ve bu girilen değerin sayısal olması zorunludur.

Karayolu ihracat siparişlerinin yürütülmesi için gerekli belgeler ve bu belgelere ait açıklama ve ihracat tipleri aşağıdaki gibidir;

GEREKLİ BELGELER	AÇIKLAMA	İHRACAT TİPİ
ETGB	Mikro ihracat için gümrük belgesi	MİKRO İHRACAT
EN Fatura	Satıcı tarafından satışa istinaden alıcıya kesilen ingilizce fatura	MİKRO, MAKRO İHRACAT
TR Fatura	Satıcı tarafından satışa istinaden alıcıya kesilen Türkçe fatura	MİKRO, MAKRO İHRACAT
Gümrük Temsil Belgesi	Satıcı tarafından yılda bir kere gümrük işlemleri için verilen izin belgesi	ZORUNLU DEĞİL
POA Belgesi	Alıcının yurt dışı gümrüğü için verdiği izin belgesi	MİKRO (ALICI TİPİ B2C)

• Sipariş girişinde alım tipi kendisi getirecek olarak seçildiğinde çıkış noktasının sistemde tanımlı olan çıkış noktalarından uygun olanının seçilmiş olması beklenir. Adresten alınacak seçiminde siparişin toplam ağırlığı 30 kg altında ise Yurtiçi kargo tarafından taşınması gerekir. Satıcının bu durumda Yurtiçi Kargo teslim belgesi ile ürünlerini en yakın Yurtiçi Kargo şubesine götürmesi gerekir.

Yurtiçi Kargo operasyonunda kullanılan barkod etiketi aşağıdaki gibidir;

• 30 kg üstündeki yükler için HOROZ Yurtiçi Dağıtım operasyon birimi çıkış noktası bilgisine göre ilgili adresten ürünlerin alımını gerçekleştirir. Bu aşamada sellerAddressPointList()'ten seçilen adres bilgileri siparişin içindeki çıkış adres alanlarını doldurmasını beklenir.

• Siparişe eklenecek ürünler createProduct() metoduyla HOROZ sistemine tanımlanmış ürünlerin ana kayıtları içinden yapılmalıdır. (Bileşenli ürünlerin ana tanımları Gardırop gibi) HOROZ sistemine tanımlanmamış ürünler sipariş kayıt aşamasında hata uyarısı alacaktır. Siparişin içinde kap ve eşya adeti ETGB’nin üstünde yer alacak olan bilgilerden olup kap adeti fiziksel olarak taşınacak parçayı, eşya adeti ise faturaya tabi olmuş satılan ürün adetini ifade etmelidir.

• Micro ihracattaki B2C satışlarında POA belgesi alıcı tarafından imzalanarak satıcının göndermesi gereken belgelerden biridir. Gümrük Temsil Belgesi mikro ihracat içinde yer alıp yıllık olarak iletilmesi gereken belgedir. Sürecin başlangıcında HOROZ tarafından satıcıyla yapılacak olan kontratta bu belge alınacaktır.

• Temsil belgesi FTP üzerinden gönderilmesi beklenen bir belge değildir. Macro ihracat seçiminde Gümrük Hizmeti İstiyorum seçimi yapıldığında satıcıya ATR ve konşimento belgeleri düzenlenecektir.

---

POST createRoadOrder()

ENDPOINT

http://b2btest.horoz.com.tr:7801/eexport_test/v1/createRoadOrder

Parametre Açıklamaları & Kuralları

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

Alanlar

Parametre	Açıklama	Veri Tipi	Uzunluk	Alan Yeri	Zorunluluk
processKey	İstemci için tanımlanan processKey bilgisi	string	100	Header	Zorunlu
customerOrderNumber	Müşteri sipariş numarası	string	50	inBody Request	Zorunlu
isFreeSenderInfo	Gönder bilgileri serbest geçilebilir mi	Enum	50	inBody Request	Zorunlu
outletLocationId	Çıkış yeri Id (receptionType ve isFreeSenderInfo ’ya bağlı)	Integer	-	inBody Request	Zorunlu
senderTitle	Gönderen unvan (isFreeSenderInfo = Yes ve receptionType = receivedFromAddress ise)	string	100	inBody Request	Zorunlu
senderCountryName	Gönderen ülke adı (isFreeSenderInfo = Yes ve receptionType = receivedFromAddress ise)	string	100	inBody Request	Zorunlu
senderStateName	Gönderen eyalet adı (isFreeSenderInfo = Yes ve receptionType = receivedFromAddress ise)	string	100	inBody Request	Zorunlu
senderCityName	Gönderen il adı (isFreeSenderInfo = Yes ve receptionType = receivedFromAddress ise)	string	100	inBody Request	Zorunlu
senderCountyName	Gönderen ilçe adı (isFreeSenderInfo = Yes ve receptionType = receivedFromAddress ise)	string	100	inBody Request	Zorunlu
senderAddress	Gönderen adres (isFreeSenderInfo = Yes ve receptionType = receivedFromAddress ise)	string	500	inBody Request	Zorunlu
senderPostCode	Gönderen posta kodu (isFreeSenderInfo = Yes ve receptionType = receivedFromAddress ise)	string	20	inBody Request	Zorunlu
senderOfficialPerson	Gönderen yetkili kişi (isFreeSenderInfo = Yes ve receptionType = receivedFromAddress ise)	string	100	inBody Request	Zorunlu
senderPhone1	Gönderen telefon 1 (isFreeSenderInfo = Yes ve receptionType = receivedFromAddress ise)	string	20	inBody Request	Zorunlu
senderPhone2	Gönderen telefon 2 (isFreeSenderInfo = Yes ve receptionType = receivedFromAddress ise)	string	20	inBody Request	Zorunlu
senderEmail	Gönderen email (isFreeSenderInfo = Yes ve receptionType = receivedFromAddress ise)	string	200	inBody Request	Zorunlu
destinationLocation	Varış yeri (Horoz / Satıcı depolarına sevkiyat yapılacağı zaman kullanılmalı)	string	30	inBody Request	Opsiyonel
recipientTitle	Alıcı unvan	string	100	inBody Request	Zorunlu
recipientType	Alıcı tipi	string	100	inBody Request	Zorunlu
recipientCountryName	Alıcı ülke adı (destinationLocation ‘ a bağlı)	string	100	inBody Request	Zorunlu
recipientStateName	Alıcı eyalet adı (destinationLocation ‘ a bağlı)	string	100	inBody Request	Zorunlu
recipientCityName	Alıcı il adı (destinationLocation ‘ a bağlı)	string	100	inBody Request	Zorunlu
recipientFloor	Alıcı kat (destinationLocation ‘ a bağlı)	Integer	-	inBody Request	Opsiyonel
recipientApartment	Alıcı daire (destinationLocation ‘ a bağlı)	Integer	-	inBody Request	Opsiyonel
recipientAddress	Alıcı adres (destinationLocation ‘ a bağlı)	string	500	inBody Request	Zorunlu
recipientPostCode	Alıcı posta kodu (destinationLocation ‘ a bağlı)	string	20	inBody Request	Zorunlu
recipientOfficialPerson	Alıcı yetkili kişi (destinationLocation ‘ a bağlı)	string	100	inBody Request	Zorunlu
recipientPhone1	Alıcı telefon 1 (destinationLocation ‘ a bağlı)	string	20	inBody Request	Zorunlu
recipientPhone2	Alıcı telefon 2 (destinationLocation ‘ a bağlı)	string	20	inBody Request	Zorunlu
recipientEmail	Alıcı email (destinationLocation ‘ a bağlı)	string	200	inBody Request	Zorunlu
totalQuantity	Toplam adet (Satış adeti)	Integer	-	inBody Request	Zorunlu
totalDesi	Toplam desi	Float	-	inBody Request	Zorunlu
totalWeight	Toplam ağırlık	Float	-	inBody Request	Zorunlu
chargeableWeight	Fiyatlanabilir ağırlık (Desi ile ağırlığın karşılaştırılmasında büyük olan değer)	Float	-	inBody Request	Zorunlu
totalContainer	Toplam kap adeti (Barkod basılacak fiziki taşımaya tabi görünen parça sayısı)	Integer	-	inBody Request	Zorunlu
orderNotes	Sipariş notu	string	1000	inBody Request	Opsiyonel
deliveryPerson	Teslim eden kişi	string	20	inBody Request	Opsiyonel
shippingType	Nakliye tipi	Enum	100	inBody Request	Zorunlu
deliveryMethod	Teslimat tipi	Enum	100	inBody Request	Zorunlu
recordType	Kayıt tipi	Enum	100	inBody Request	Zorunlu
receptionType	Alım tipi	Enum	100	inBody Request	Zorunlu
invoiceNumber	Fatura numarası	Enum	100	inBody Request	Zorunlu
invoiceDate	Fatura tarihi	Date	-	inBody Request	Zorunlu
invoiceAmount	Fatura tutarı	Float	-	inBody Request	Zorunlu
invoiceCurrencyUnit	Fatura para birimi	string	5	inBody Request	Zorunlu
exportType	İhracat tipi	Enum	100	inBody Request	Zorunlu
paymentMethod	Ödeme yöntemi	Enum	100	inBody Request	Zorunlu
isAtr	ATR mi (Micro ihracat seçimine bağlı)	Enum	100	inBody Request	Zorunlu
isInsured	Sigortalı mı	Enum	100	inBody Request	Zorunlu
isYdg	Yurt dışı gümrükleme	Enum	100	inBody Request	Zorunlu
isCustomService	Gümrük Hizmeti (Macro ihracat seçimine bağlı)	Enum	100	inBody Request	Zorunlu
orderDetail	Sipariş detayı	Array	-	inBody Request	-------
productCode	Ürün kodu	string	50	inBody Request	Zorunlu
productName	Ürün adı	string	100	inBody Request	Zorunlu
quantity	Ürün satış adeti	Integer	-	inBody Request	Zorunlu
containerPieces	Kap adeti	Integer	-	inBody Request	Zorunlu

Örnek İstek

{
  "customerOrderNumber": "20230217-1",
  "receptionType": "itWillBring",
  "isFreeSenderInfo": "no",
  "outletLocationId": 3,
  "senderTitle": null,
  "senderCountryName": null,
  "senderStateName": null,
  "senderCityName": null,
  "senderCountyName": null,
  "senderAddress": null,
  "senderPostCode": null,
  "senderOfficialPerson": null,
  "senderPhone1": null,
  "senderPhone2": null,
  "senderEmail": null,
  "recipientTitle": "ALMANYA DEPO",
  "recipientType": "B2B",
  "destinationLocation": null,
  "recipientCountryName": "ALMANYA",
  "recipientStateName": null,
  "recipientCityName": "SALZGITTER",
  "recipientFloor": null,
  "recipientApartment": null,
  "recipientAddress": "YALMANS LOGISTICS HÜTTENSTRASSE 32 SALZGİTTER 38239",
  "recipientPostCode": "38239",
  "recipientOfficialPerson": "NACI ZERMAN",
  "recipientPhone1": "4917624376130",
  "recipientPhone2": "4917624376130",
  "recipientEmail": "logistics@yalmans.com",
  "totalQuantity": 3,
  "totalDesi": 30,
  "totalWeight": 30,
  "chargeableWeight": 30,
  "totalContainer": 3,
  "orderNotes": "SİPARİŞ KATA TESLİM EDİLECEK",
  "deliveryPerson": "HASAN SABIRLI",
  "shippingType": "express",
  "deliveryMethod": "deliveryToFloor",
  "recordType": "direct",
  "invoiceNumber": "FAT123456",
  "invoiceDate": "2022-01-19",
  "invoiceAmount": 16000,
  "invoiceCurrencyUnit": "EUR",
  "valueAddedTaxAmount": 22,
  "shippingAmount": 123,
  "paymentMethod": "advance",
  "isAtr": "no",
  "isInsured": "yes",
  "exportType": "macro",
  "isYdg": "yes",
  "isCustomService": "yes",
  "orderDetail": [
    {
      "productCode": "TV10010",
      "productName": "TELEVİZYON",
      "quantity": 3,
      "containerPieces": 30
    }
  ]
}

Örnek Cevap

{
  " response ": {
    "responseCode": "STA-100",
    "responseMessage": "Basarili"
  }
}

createRoadOrder metodu içerisinde beklenen enum değerler için aşağıda detaylı bilgi verilmiştir.

ENUM ALAN ADI	ENUM ALAN ADI (Türkçe)	AÇIKLAMA
isFreeSenderInfo	Gönderen bilgisi serbest mi	İstek içerisinde bulunan gönderen bilgilerinin serbest geçilip, geçilemeyeceği yes/no seçimine bağlı olarak set edilebilir.
shippingType	Nakliye tipi	economic, express değerlerinden sipariş için uygun olan değer geçilerek nakliye tipi bildirilebilir. (economic : ekonomi, express : ekspres)
deliveryMethod	Teslimat yöntemi	curbFront, deliveryToFloor, deliveryToFloorAndAssembly değerlerinden sipariş için uygun olan değer geçilerek teslimat yöntemi bildirilebilir. (curbFront : kaldırım önü teslimat, __deliveryToFloor : kata teslim, deliveryToFloorAndAssembly : kata teslim ve montaj)
recordType	Kayıt tipi	direct, partial değerlerinden sipariş için uygun olan değer geçilerek kayıt tipi bildirilebilir. (direct : direkt, partial : parsiyel/kısmi)
receptionType	Alım tipi	receivedFromAddress, itWillBring değerlerinden sipariş için uygun olan değer geçilerek alım tipi bildirilebilir. (receivedFromAddress : adresten alınacak, itWillBring : kendisi getirecek)
paymentMethod	Ödeme yöntemi	advance, free değerlerinden sipariş için uygun olan değer geçilerek ödeme yöntemi bildirilebilir. (advance: peşin, free : ücretsiz)
İsAtr	ATR mi ?	yes, no değerlerinden biri geçilerek sipariş için uygun olan ATR durumu bildirilebilir. Micro ihracat tipinde aktiftir.
isYdg	Yurtdışı gümrükleme mi ?	yes, no değerlerinden biri geçilerek sipariş için uygun olan YDG durumu bildirilebilir.
isInsured	Sigortalı mı ?	yes, no değerlerinden biri geçilerek sipariş için sigortalı olup/olmama durumu bildirilebilir.
exportType	İhracat tipi	macro, micro değerlerinden biri geçilerek sipariş için ihracat tipi durumu bildirilebilir. (macro : makro, micro : mikro)
isCustomService	Gümrük hizmeti var mı ?	yes, no değerlerinden biri geçilerek sipariş için uygun olan customService durumu bildirilebilir. Macro ihracat tipinde aktiftir.

---

Servis Cevapları

Servise ait başarılı/başarısız servis cevaplarına buradan erişebilirsiniz.