Barkod Oluşturma - createBarcode()

Barkod Oluşturma İşlemi

Horoz Lojistik Yurtiçi Dağıtım Entegrasyonu üzerinde bulunan createBarcode() metodu, daha önce createShipping() metodu ile Horoz Lojistik sisteminde başarılı olarak oluşturulmuş bir sevk emrini onaylayıp, mal kabul kaydını (ATF – Ambar Tesellüm Fişi kaydını) oluşturarak istemciye mal kabul kaydına istinaden barkod etiketi bilgilerini dönen web servis entegrasyonu metodudur.

Horoz Lojistik Yurtiçi Dağıtım operasyonunda sevk emri onay ve mal kabul işlemi operasyon görevlileri tarafından aşamalı olarak yapıldığı gibi, createBarcode() metodu kullanılarak createShipping() metodu ile başarılı olarak oluşturulmuş bir sevk emri kaydı içinde bu süreçler bypass edilerek yapılabilir. createBarcode() metodu ile ilgili önemli bilgiler ve Horoz sistemine daha önce createShipping() metodu ile gönderilmiş bir sevk emri için mal kabul kaydı (ATF kaydı) oluşturulup, barkod etiketi bilgilerini almak isterken dikkat edilmesi gerekenler liste halinde aşağıda istemcilerin bilgisine sunulmuştur.

• createBarcode() metodu POST yöntem ile JSON formatta veri alan, bir RESTful web servis metodudur.

• createBarcode() metodunu kullanarak istemci, daha evvel Horoz Lojistik Yurtiçi Dağıtım Entegrasyonu Web servisi aracılığı ile sevk emri gönderilmiş bir sipariş için barkod etiketi bilgilerini createBarcode() metodundan alır. İstemci bu bilgiler ile kendi barkodunu yada Horoz Lojistik Yurtiçi Dağıtım operasyonunda kullanılan barkodu basabilir.

• Horoz Lojistik Yurtiçi Dağıtım operasyonu kapsamında, Horoz Lojistik barkod etiketi iki şekilde basılabilir. İlk olarak; istemci createBarcode() metodu ile Horoz Lojistik Yurtiçi Dağıtım Entegrasyon Webservisi üzerinden aldığı barkod bilgilerini kendi ERP’sinde geliştirdiği barkod basım modülünde kullanıp, iki tarafın mutabık kaldığı barkod tasarımına istinaden aldığı bilgileri barkod tasarımı üzerindeki gerekli alanlara geçerek barkod basabilir. İkinci olarak, Horoz Lojistik tarafından entegrasyon yapan firmaya şube kurulumu yapılarak, daha evvel Horoz Lojistik sistemine createShipping() metodu ile iletilen sevk emri için ilgili şubedeki Horoz personeli tarafından barkod basılabilir. Eğer firma kendi barkodunu basmak istiyor ise Horoz Lojistik Yurtiçi Dağıtım operasyonunda kullanılan barkod etiketi tasarımı istemci ile paylaşılır ve her iki taraf içinde belirlenen alanlar barkod üzerinde oluşacak şekilde, karşılıklı mutabakat sağlanarak ortak barkod istemci tarafından hazırlanır.

• createBarcode() metodu istemcisi tarafından çağırıldığında, barkod bilgilerinin yanı sıra istemcisine Horoz Lojistik Yurtiçi Dağıtım operasyonunda mevcutta kullanılan, operasyonel alışkanlığa sahip olunan 10x10’luk ve 4x10’luk 2 barkod tasarımını da zpl veri formatında döner. İstemci dilerse bu tasarımlar için zpl verileri kendi ERP’sinde parse ederek barkod etiketlerini elde edebilir.

• createBarcode() metodu çağırılarak istemci tarafından talep edilen barkod etiketi alım işlemi, entegrasyon üzerinden sisteme bildirilen parça sayısı kadar (taşınacak fiziksel koli adedi kadar) çağırım yapılarak yapılmalıdır. Bu operasyonda, teslimatın bünyesinde taşınacak olan kolilerin içerisindeki ürün miktarı ve/veya detayı önemli değildir.

• createBarcode() metodu, daha önce Horoz Lojistik Yurtiçi Dağıtım Entegrasyonu Webservisi üzerinden createShipping() metodu ile Horoz Lojistik sistemine sevk emri iletilmiş siparişlerden kesin olarak Horoz Lojistik’e taşıması için verilecek, istemci-satıcı tarafında faturası kesilmiş ürünler için çağırılmalıdır. Horoz Lojistik’e verilmesi kesinleşmemiş ürünler için createBarcode() metodu çağırılmamalıdır.

• createBarcode() metodunun istemcisi tarafından daha önce Horoz Lojistik sisteminde createShipping() metodu ile oluşturulmuş bir sevk emri için çağırılmasının akabinde, Horoz Lojistik sisteminde oluşan mal kabul kaydına (ATF kaydına) istinaden oluşturulan barkod etiketi kaydı teslimatın bünyesinde kaç parça koli/palet/ürün vb.(fiziksel olarak taşınacak ürün) olursa olsun istemcisine her zaman teslimat bazında 1.parça için tek satır olarak döner.

• createBarcode() metodu ile Horoz Lojistik sistemine barkod etiketi almak için gönderim yapılırken; parça sayısı istek içerisinde quantity alanına yazılır. Gönderilen bu bilgiye istinaden parça sayısı kadar barkod etiketi createBarcode() metodunun yanıt içeriğinden temin edilebilir.

• createBarcode() metodunun kullanımının en önemli bilgilerinden biri olarak; createBarcode() metodunun daha önce createShipping() metodu ile gönderilen sevk emrinin bünyesindeki fiziksel olarak taşınacak ürünlerin parça sayısı kadar çağırılmasına gerek yoktur. createBarcode() metodunun çağırımı ile barkod etiketi alım işlemi yapılırken; sevk emrine ait ürünlerin shipmentCount (toplam adet) ve totalDesi (toplam desi) bilgileri daha önce createShipping() metodu ile sevk emri gönderimi yapan istemci tarafından bilindiğinden, createBarcode() metodunun yalnızca ilk parça için bir defa çağırılması yeterli olacaktır. İstemci tarafından 1.parça için createBarcode() metodu ile alınan barkod etiketi için, istemci kendi tarafında bildiği shipmentCount (toplam adet) bilgisi kadar sadece alınan barkod etiketi bilgileri içerisindeki parça sayısı bilgisini 1’er arttırarak tüm parçalar için barkod etiketlerini kendi ERP sisteminde oluşturabilir.

Örneğin; createShipping() metodu ile Horoz Lojistik sistemine daha evvel gönderilen bir sevk emri kaydının toplam adet bilgisi shipmentCount: 6 şeklinde olsun. createBarcode() metodu ile bu sevk emri için barkod etiketleri basılmak istendiğinde; createBarcode() metodu bir defa çağırılır ve metot sadece 1.parça için barkod etiketi bilgilerini istemciye döner. Ardından sıradaki barkodlar ilk barkod bilgisinde dönen bilgilerden, istemci tarafında bilgisi mevcut olan shipmentCount: 6 adet kadar istemci ERP sisteminde çoklanarak elde edilebilir.

Örnek Barkod Numarası: 824490000100001358 (ATFNo + ParcaNo + AlıcıSubeKodu)

• ATFNo: 82449000010
• ParcaNo: 0001
• AlıcıSubeKodu: 358

6 Parçalık Bir Barkod Basım İşlemi İçin Türetilen Barkodlar:

1. parça: 824490000100001358 : (createBarcode() çağrılarak elde edilir.)
2. parça: 824490000100002358 : (82449000010|0001 +1|358)
3. parça: 824490000100003358 : (82449000010|0002 +1|358)
4. parça: 824490000100004358 : (82449000010|0003 +1|358)
5. parça: 824490000100005358 : (82449000010|0004 +1|358)
6. parça: 824490000100006358 : (82449000010|0005 +1|358)

• createBarcode() metodu ile barkod etiketi alma işlemi sırasında toplam adet bilgisi istemci tarafından bilinmiyor ise, bu durumda createBarcode() metodunun ilk ve son parça için yalnızca 2 defa çağırılması yeterlidir. Böylece ilk barkod ve son barkod arasındaki diğer barkodlar bu iki barkod etiketi bilgisinden türetilerek istemcinin ERP sisteminde basılabilir.

• createBarcode() metodu, daha önce createShipping() metodu ile sevk emri verisi Horoz Lojistik sistemine gönderilmiş olan fakat shipmentCount bilgisi hatalı gönderilmiş olan bir teslimat için toplam adet bilgisinin güncellenebilmesini de olanak sağlar. Bunun için createBarcode() metodu ile istemci tarafından barkod etiketi alınırken; istek içerisindeki partNumberbilgisi 0 olarak geçilip, quantity bilgisine yeni/güncel/doğru adet bilgisi yazılırsa, ilgili teslimatın toplam adet bilgisi istemci tarafından güncellenebilir. Güncelleme işleminin ardından yapılan createBarcode() çağırımlarında, istemciye dönen quantity bilgileri güncel toplan adet bilgileri olacaktır.

• createBarcode() metodu ile alınan barkod etiketlerinin barkod tipi; Code128, karakter seti; CharsetC dir.

• createBarcode() metodunun istemci tarafından kullanımı, yurt içi dağıtım operasyonunda lojistik olarak barkodu oluşturulacak kaydın müşteri temsilcileri tarafından onaylanması ve Horoz Lojistik operasyon personeli tarafından ATF (Ambar Tesellüm Fişi) kesilmesi işlemlerini atlatarak by-pass etmektedir. Bu süreç kontrollü bir şekilde yapılmadığında lojistik süreç içerisinde sorunlara yol açabileceğinden dolayı bir müşteri tarafından ortak barkod entegrasyonu yapılmak isteniyorsa bir onay sürecinden geçilmesi gerekmektedir. Onay sürecinden geçemeyen firmalar için ortak barkod entegrasyonu ile ilgili destek verememekteyiz

• Bir sipariş için barkod etiketi oluşturulması Horoz Lojistik tarafında bu siparişin müşteri temsilcilerimiz tarafından onaylandığı ve Horoz Lojistik yurt içi dağıtım operasyonu personeli tarafından bu sipariş için bir ATF(Ambar Tesellüm Fişi) kesildiği anlamına gelmektedir. Bu sebeple barkod etiketi oluşturulduğu andan itibaren siparişin mal kabul işleminin yapıldığı ve teslim edilmek üzere lojistik sürece başladığı anlamına gelmektedir. Entegrasyon yapılırken firma tarafından bu bilginin bilindiği ve bu sürece onay verildiği kabul edilmektedir ve barkodların entegrasyon üzerinden bu bilgiye göre basılması beklenmektedir.

• createBarcode() metodu çağırıldığında, barkod bilgilerinin yanı sıra Horoz Lojistik operasyonlarında kullanılan barkodun ilgili bilgiler ile oluşturulmuş tasarımını ZPL veri formatında istemcilere döner. İstemci dönüşü yapılan ZPL veri kodunu kendi ERP sisteminde encode ederek ilgili barkod etiketinin tasarımına ulaşabilir ve bu barkod etiketi ile uyumlu barkod yazıcılarından çıktı alabilir. ZPL veri formatındaki kodları encode edebilmek için web üzerinde online portallar mevcuttur. Hazırlanan ZPL kodları ile bu web sitelerinde barkod tasarımlarını görüntüleyebilirsiniz.

ZPL Encoding Portal : https://labelary.com/viewer.html

10x10 ölçekli barkod etiketi için ZPL veri içeriği örneği:

Örnek ZPL

^XA ^FO220,20^GFA,^FS^CF0,50\ ^FWB\ ^FO95,120 ^FDRUT-3^FS\ ^FO150,20 ^GB3,580,3^FS\ ^CFT,80,100\ ^CI28\ ^FO10,210 ^FDALICI İL BİLGİSİ^FS\ ^FWN\ ^FT170,160 ^A0,40,30 ^FDGÖNDERİCİ/SATICI UNVANI^FS ^FT170, 230 ^A0,60,50 ^FDALICI ADI SOYADI^FS ^FT170, 295 ^A0,30,20 ^FDKARGO^FS ^FT320, 295 ^A0,30,20 ^FDİRSALİYE TARİHİ^FS ^FT490, 295 ^A0,30,20 ^FDÇIKIŞ ŞUBE BİLGİSİ^FS ^FT170, 340 ^A0,30,20 ^FDALICI AÇIK ADRES BİLGİSİ^FS ^FT170, 415 ^A0,60,50 ^FDALICI İL - ALICI İLÇE^FS ^FO170,430 ^GB630,1,3^FS^FT170, 500 ^A0,70,60 ^FDM123456^FS ^FT170, 535 ^A0,30,20 ^FDİRS.NO: MÜŞTERİ SİPARİŞ NUMARASI BİLGİSİ^FS ^FT170, 580 ^A0,30,20 ^FDİRS.TARİHİ: İRSALİYE TARİHİ^FS ^FT600, 540 ^A0,40,30 ^FDDESİ: 50.5^FS ^FT600, 580 ^A0,40,30 ^FDPARÇA: 1/5^FS ^BY2,2,150 ^FO240,605 ^BCN ^FD115090000190001358^FS\ ^FWN\ ^XZ

10x10 ölçekli barkod etiketi örneği:

4x10 ölçekli barkod etiketi örneği:

---

POST createBarcode()

ENDPOINT

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

Parametre Açıklamaları & Kuralları

Aşağıdaki tabloda createBarcode() 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
requestNumber	İstemci tarafından createShipping ile oluşturulan siparişin requestNumber bilgisi	string	50	inBody Request	Zorunlu
partNumber	Barkodu çıkartılacak olan ürünün parça numarası	integer	-	inBody Request	Zorunlu
quantity	Siparişin toplam parça bilgisi	integer	-	inBody Request	Zorunlu
desi	Barkodu oluşturulacak ürünün desi bilgisi	float	-	inBody Request	Zorunlu
weightInKg	Barkodu oluşturulacak ürünün ağırlık bilgisi	float	-	inBody Request	Zorunlu

Örnek İstek

  {
    "requestNumber": "Test123",
    "partNumber": 1,
    "quantity": 5,
    "desi": 150.5,
    "weightInKg": 125.5
  }

Örnek Cevap

  {
      "response": {
          "responseCode": "STA-100",
          "responseMessage": "Kayit islemi basarili",
          "barcodeList": [
              {
                  "senderTitle": "TEST SENDER",
                  "trackingNumber": "TEST123",
                  "cargoTrackingNumber": "29926575036874",
                  "transactionDate": "2024-09-03 15:20:22",
                  "waybillNumber": "M000518",
                  "recipientBranchName": "AVRUPA",
                  "senderBranchName": "ANADOLU",
                  "shippingType": "KARGO",
                  "recipientTitle": "TEST RECIPIENT",
                  "recipientAdress": "TEST ADRESS",
                  "recipientCity": "TEST CITY",
                  "recipientArea": "TEST COUNTY",
                  "operation1": "RUT-2",
                  "operation2": null,
                  "quantity": 1,
                  "barcode": "435590005180001328",
                  "zplContent": "10X10 ZPL CONTENT",
                  "zplContent2": "4X10 ZPL CONTENT"
              }
          ]
      }
  }

---

Servis Cevapları

Response Kodu	Response Mesajı	Açıklama
STA-100	Kayit islemi basarili	Barkod 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-20020	SEVK KAYDI BULUNAMADI YADA GEÇERSİZ KAYIT	Barkodu oluşturulmaya çalışılan siparişin sistemde var olmadığını yada geçersiz yapıldığını belirtir.
ERR-20020	SEVK KAYDI BULUNAMADI	Barkodu oluşturulmaya çalışılan siparişin sistemde var olmadığını yada geçersiz yapıldığını belirtir.
ERR-20021	GECERSIZ SEVK KAYDI.	Barkodu oluşturulmaya çalışılan siparişin geçersiz yapıldığını belirtir.
ERR-20025	ADET : X veya DESİ : X veya KG : X veya PARCANO : X HATALIDIR	Girilen Adet, Desi, Kilogram veya Parca numara bilgilerinin hatalı girildiğini ifade eder.