Creating an Order – createShipping()

Creating an Order

createShipping() method, available on the Horoz Logistics Domestic Distribution Integration, is a web service method that should be used to create a shipping order that contains one or more physical products such as boxes, packages, pallets, etc. to be transported from the sender to the recipient in the Horoz system.

Any merchant, which has an agreement with Horoz Logistics as part of the domestic distribution operations, can create shipping order data to the Horoz system via Horoz Logistics Domestic Distribution Integration using the createShipping() method for the product shipments from its own warehouse to its end consumers and/or for product shipments from its marketplace merchants to its end consumers.

Any shipping order, sent by the client to the Horoz Logistics system, is a job order, and after the planning and goods acceptance processes carried out by the Horoz Logistics Domestic Distribution Operations Unit, such order enters the operation life cycle and becomes an order to be transferred from the respective merchant to the end consumer. Important information about the createShipping() method and the points to be considered when creating a shipping order in the Horoz system are listed below for the information of the clients.

createShipping() method is a RESFtul web service method that receives data in JSON format via POST method.
When sending a shipping order to the Horoz system by means of the createShipping() method, the details about such order must be entered into the body of the method in JSON data type. The client's processKey details must be entered into the header of the method as a parameter type. The shipment made by means of the createShipping() method must be encoded as UTF-8 and transmitted to the Horoz Logistics Domestic Distribution Integration Web service.
createShipping() method consists of a main shipping order data structure and a detailed shipping order structure, containing product information as an array list below such main shipping order data structure. Within a shipping order structure, there is the order number, sender details, recipient details, total quantity, total volume details about the order given by the end consumer to the merchant, and the product information including the product code, product name, product quantity, product volume, product weight, product category details that qualify one or more products pertaining to the respective order in the details of such shipping order.
When a shipping order is sent to the Horoz system by the client by means of the createShipping() method, the details to be entered by the client to the senderCity, senderCounty, recipientCity and recipientCounty fields must be the city and county details that are defined in the Horoz Logistics system. Otherwise, an error will be returned to the client from the createShipping() method. The client can obtain the city and county details defined in the Horoz Logistics system by using the listCountires() method, which works with the GET method available within the Horoz Logistics Domestic Distribution Integration. The city-county details defined in the Horoz Logistics system has been clustered and created by having received such details from the Republic of Türkiye Ministry of Internal Affairs and the Türkiye Civil Administration Departments Inventory system. Available data is checked manually at intervals.
When a shipping order is sent to the Horoz system by the client by making use of the createShipping() method, the total desi and total quantity details about the products in the order entered in the totalDesi and shipmentCount fields in the request to be sent to the Horoz Domestic Distribution Integration Web Service must be compatible with the product-based desi and quantity details entered into the desi and quantity fields in the product information entered as an item in the shippingDetail array list. While sending the order, an incorrect and expected examplary illustration for the quantity and desi compatibility relationship in the master and detailed information in the createShipping() method is given in the tables below.

Master Entry:

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

Incorrect Entry Detail:

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

Correct Entry Detail:

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

When a shipping order is sent to the Horoz system by the client by making use of the createShipping() method, the data to be entered into all fields that take values of string data type, except for the shippingType field that takes values other than enum data type, in the request to be sent to the Horoz Domestic Distribution Integration Web service, is expected to be entered as UPPERCASE and in Turkish characters.
When a shipping order is sent to the Horoz system by the client by making use of the createShipping() method, the requestNumber, shipmentCount, totalDesi, quantity, desi and weightInKg in the request to be sent to the Horoz Domestic Distribution Integration Web service must be filled in.
Among the order details in the shipping orders sent to the Horoz system by the client by making use of the createShipping() method, the actual desi details about the products in the order must be entered into the fields that specifically qualify the desi details (totalDesi, desi). Otherwise, there will be a problem in the logistics operation at the stage where the shipping order is approved and the vehicle planning is made before the goods acceptance process. Therefore, the shipping order data to be transmitted via the integration must actually contain the quantity and volume details about the products to be physically transported.
While passing the details about the products in the shipping orders sent to the Horoz system by the client by means of the createShipping() method, it is expected that the unit desi details, multiplied by the quantity on product basis, are entered into both the desi and weightInKg fields.
As part of the Horoz Logistics Domestic Distribution Integration, four types of shipping order data can be sent to the Horoz system by the client by means of the createShipping() method. For any shipping order sent by means of the createShipping() method, shipping type details are entered into the shippingType field in the request. See the detailed information about shipping order types under the headings given below.

ShippingRequest

ShippingRequest value is the value to be entered into the shippingType field when sending orders to the Horoz system by means of the createShipping() method, for the orders to be sent from the warehouse of the merchant that has an agreement with Horoz Logistics for domestic distribution operations.

The shipping order, in which this type is used, represents an order from the merchant with which Horoz Logistics has an agreement for domestic distribution operations, to the merchant's end customer. When sending data by means of the `createShipping() method for such type of notification, the client must pass the details about the warehouse or the departure point where the orders will be sent to the sender fields¹ in the request content. There are 2 methods for that.

As the first method, the client enters the code of the relevant departure point defined previously in the Horoz Logistics system into the senderCode field, and leaves the other sender fields¹ blank. The code details entered into the senderCode field in the createShipping() method fills in the other sender fields by looking at the customer's departure location details as defined in the Horoz system when the shipping order is created.

As the second method, the client is expected to fill in the other sender fields¹ by entering 0 to the senderCode field. Both methods can be applied to the recipientCode field.

Return

Return value is the value to be entered into the shippingType field when sending orders to the Horoz system by means of the createShipping() method for the orders that the merchant, which has an agreement with Horoz Logistics for domestic distribution operations, wishes to carry out a return operation to its warehouse from its customer.

Any shipping order, in which such type is used, represents an order from the customer of the merchant with which Horoz Logistics has an agreement for domestic distribution operations, to the merchant itself. When sending data by means of the createShipping() method for such type of notification, the client must enter the details about the end customer or warehouse from which the orders will be received into the sender fields¹ in the request content. There are 2 methods for that.

As the first method, the client enters the code of the relevant warehouse defined previously in the Horoz Logistics system to the senderCode field, and leaves the other sender fields¹ blank. The code details entered into the senderCode field in the createShipping() method fills in the other sender fields by looking at the details about the warehouse as defined in the Horoz system when the shipping order is created.

As the second method, the client is expected to fill in the other sender fields¹ by entering 0 to the senderCode field. Similarly, both methods can be applied to the recipientCode field.

BranchSales

BranchSales value is the value to be entered into the shippingType field when sending orders to the Horoz system by means of the createShipping() method for the marketplace and/or store departures of the merchant which has an agreement with Horoz Logistics for domestic distribution operations.

The shipping order, in which this type is used, represents an order from the marketplace of the merchant with which Horoz Logistics has an agreement for domestic distribution operations, to the merchant's end customer. When filling in the fields of the createShipping() method for the respective merchant's marketplace and/or store departures, the senderCode details are entered as 0, and the other sender fields¹ are completed with the details about the respective merchant marketplace. Similarly, in the recipient information, the recipientCode details are passed as 0, and the other recipient fields² are completed with the recipient details.

BranchReturn

BranchReturn value is the value to be entered into the shippingType field when sending orders to the Horoz system by means of the createShipping() method for the orders that will be returned to the marketplace and/or stores from the customers as part of the e-commerce operation of the merchant which has an agreement with Horoz Logistics for domestic distribution operations.

The shipping order, in which such type is used, represents an order from the end customer of the merchant with which Horoz Logistics has an agreement for domestic distribution operations, to the respective marketplace. When filling in the fields of the createShipping() method for the respective merchant's marketplace and/or store departures, the senderCode details are passed as 0, and the other sender fields¹ are completed with the details about the respective merchant's marketplace. Similarly, in the recipient information, the recipientCode details are passed as 0, and the other recipient fields² are completed with the recipient details.

POST createShipping()

ENDPOINT

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

Parameter Descriptions & Rules

The following table lists the input and output parameters of the createShipping() process, and the types and formats of such parameters.

Fields
Example Request
Example Response

Fields	Description	Data Type	Length	Field Location	Requirement
`processKey`	The `processKey` details identified for the client	string	100	Header	Mandatory
`requestNumber`	Order number	string	50	inBody Request	Mandatory
`senderCode`	Sender code	integer	-	inBody Request	Mandatory
`senderTitle`	Sender title	string	100	inBody Request	Mandatory
`senderCity`	Sender city name	string	50	inBody Request	Mandatory
`senderCounty`	Sender county name	string	50	inBody Request	Mandatory
`senderAdress`	Sender address	string	500	inBody Request	Mandatory
`senderPhoneNumber`	Sender phone number	string	20	inBody Request	Mandatory
`senderEmail`	Sender e-mail	string	100	inBody Request	Optional
`recipientCode`	Recipient code	integer	-	inBody Request	Mandatory
`recipientTitle`	Recipient title	string	100	inBody Request	Mandatory
`recipientCity`	Recipient city name	string	50	inBody Request	Mandatory
`recipientCounty`	Recipient county name	string	50	inBody Request	Mandatory
`recipientAddress`	Recipient address	string	500	inBody Request	Mandatory
`recipientPhoneNumber`	Recipient phone number	string	20	inBody Request	Mandatory
`recipientEmail`	Recipient e-mail	string	100	inBody Request	Optional
`taxOffice`	Tax office	string	20	inBody Request	Optional
`taxNumber`	Tax ID Number	string	20	inBody Request	Optional
`shipmentCount`	Total quantity	integer	-	inBody Request	Mandatory
`totalDesi`	Total desi	float	-	inBody Request	Mandatory
`shippingType`	Shipping type	string	20	inBody Request	Mandatory
`requestDate`	Date of sending of request	DATE	YYYY-MM-DD	inBody Request	Mandatory
`requestedDeliveryDate`	Requested delivery date	DATE	YYYY-MM-DD	inBody Request	Mandatory
`shippingDetail[]`	Shipping details	ArrayList	-	inBody Request	Mandatory
`productCode`	Product code	string	50	inBody Request	Mandatory
`productName`	Product name	string	100	inBody Request	Mandatory
`quantity`	Quantity	integer	-	inBody Request	Mandatory
`weightInKg`	Weight	float	-	inBody Request	Mandatory
`desi`	Desi	float	-	inBody Request	Mandatory
`productCategory`	Product category	string	100	inBody Request	Mandatory

{
    "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"
    }
}

Service Responses

Response Code	Response Message	Description
STA-100	Kayit islemi basarili	It refers to the fact that the shipment creation process is successful.
ERR-20001	HATALI IŞLEM ANAHTARI	Indicates that the entered processKey details are incorrect.
ERR-20002	EKSİK PARAMETRE: TALEP NUMARASI	Indicates that the `requestNumber` information has been entered incompletely.
ERR-20002	GİRİLEN DEĞER ÇOK UZUN: Alan Adı	Indicates that the value entered in the specified field is too long.
ERR-20003	BU TALEP NUMARASI SISTEMDE MEVCUT - Key: XXX TalepNo: XXX	Indicates that a shipment has already been created with the same `requestNumber` details.
ERR-20005	GEÇERSİZ GÖNDEREN BİLGİSİ	Indicates that the value entered in the `senderCode` field is not defined in the Horoz System.
ERR-20006	GEÇERSİZ ALICI BİLGİSİ	Indicates that the value entered in the `recipientCode` field is not defined in the Horoz System.
ERR-20007	EKSİK PARAMETRE: TOPLAM ADET/DESİ	Indicates that the `totalDesi` and shipmentCount fields have been left blank.
ERR-20008	EKSİK PARAMETRE: KARGO BİLGİLERİ	Indicates that the fields under the shippingDetail array are incomplete.
ERR-20009	DESI BILGISI SIFIR OLAMAZ.	The value entered in the `desi` fields must be greater than 0.
ERR-20012	TOPLAM DESI SIFIR OLAMAZ	The value entered in the `totalDesi` field must be greater than 0.
ERR-20056	`shippingType` BİLGİSİ BOŞ GEÇİLEMEZ.	Indicates that a value must be entered in the `shippingType` field.
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	It refers to the fact that an entry has been previously created with incorrect city and county details by making use of the `requestNumber` details entered in the request, and that an entry should be created with the same `requestNumber` by entering the city and county details correctly.

Footnotes

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