Creating a Supplier Order – createPaysSupplierShipping()

Supplier Order Creation

createPaysSupplierShipping method, available on Horoz Logistics Domestic Distribution Integration, is a web service method that should be used to create a shipping order containing one or more physical products such as boxes, packages, pallets, etc. to be transported from the sender to the recipient, which will be sent to the relevant method by the respective sales platform for the order data of the sales made by a merchant which has an agreement with Horoz via the sales platform of a client defined in the Horoz system.

The e-commerce merchant, which sells the products of a client that has a supplier-pays agreement with Horoz Logistics for the Domestic Distribution Integration, and which also has an agreement with Horoz Logistics, can create a supplier-pays type shipping order data to the Horoz system via the Horoz Logistics Domestic Distribution Integration, by making use of the createPaysSupplierShipping method for the product shipments from the client's warehouse to the client's end consumers as part of the respective client's agreement.

The supplier-pays type shipping order, sent by the client to the Horoz Logistics system, is a job order and, following the planning and goods acceptance processes carried out by the Horoz Logistics Domestic Distribution Operations Unit, it enters the operational life cycle and becomes an order to be transferred from the supplier to the end consumer. Important information about the createPaysSupplierShipping() method and the points to be considered while creating a supplier pays type shipping order in the Horoz system are listed below for the information of the clients.

createPaysSupplierShipping() method is a RESTful web service method that receives data in JSON format via the POST method.
When sending a shipping order to the Horoz system by means of the createPaysSupplierShipping() 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 createPaysSupplierShipping() method must be encoded as UTF-8 and transmitted to the Horoz Logistics Domestic Distribution Integration Web service.
createPaysSupplierShipping() 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 createPaysSupplierShipping() 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 createPaysSupplierShipping() 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 of supplier-pays type is sent to the Horoz system by the client by means of the createPaysSupplierShipping() method, the total desi and total quantity details about the products within 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 information entered in 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

While a shipping order of supplier-pays type is being sent to the Horoz system by the client by means of the createPaysSupplierShipping() method, the data to be entered in 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 shipment order is sent to the Horoz system by the client with the createPaysSupplierShipping() method, the requestNumber, shipmentCount, totalDesi, quantity, desi and weightInKg fields in the request to be sent to the Horoz Domestic Distribution Integration Web service must be filled.
Among the details about the orders in the supplier-pays type shipping orders sent to the Horoz system by the client by means of the createPaysSupplierShipping() method, the actual desi details about the products in the orders should be entered in the fields that specifically qualify the desi information (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 entering the details about the products in the shipping orders sent to the Horoz system by the client by means of the createPaysSupplierShipping() method, if the client has weight details about the respective products, the weight details about the products should be entered in the weightInKg field and the desi details should be entered into the desi field. In the event that the client does not have the weight details about the products that can be transported physically, then it is expected that the unit desi information multiplied by the quantity will be entered in both the desi and weightInKg fields.
In order to create a supplier pays type shipment order by the client in the Horoz system with the createPaysSupplierShipping() method, the current code information of the relevant supplier defined in the Horoz Logistics system must be previously registered in the Horoz Logistics supplier pays system. For this registration process, the responsible of the e-commerce platform that will send data for supplier pays integration can contact Horoz Logistics customer representatives. Then, with the information requested by Horoz Logistics customer representatives for the relevant current account, Horoz Logistics customer representatives can check the compliance of the current account with the supplier pays integration and perform the identification process.
With the createPaysSupplierShipping() method, 2 types of shipments can be made by the client in the Horoz system when creating a supplier pays type shipment order. For shipments made from the supplier of the company to the supplier's end customer who placed an order to the supplier through the company, PaySupplier should be entered in the shippingType field, supplier code should be entered in the senderCode field, and 0 (zero) should be entered in the recipientCode field. For submissions to the recipient, it is expected to fill in the recipient information¹, for the sender information, it is sufficient to pass only the supplier code information in the senderCode field and leave the other sender information² blank.
For shipments made to the supplier of the company from the last customer of the company who placed an order to the supplier through the company, PaysSupplierReturn should be entered in the shippingType field, supplier code should be entered in the recipientCode field, 0 (zero) should be entered in the senderCode field. It is expected to fill in the sender information² in the return submissions made to the supplier, for the recipient information, it will be sufficient to pass only the supplier code information in the recipientCode field and pass the other recipient information¹ blank.
In order for the shipment to be carried out properly as part of the supplier-pays integration, care should be taken to pass the relevant fields completely and in the expected manner as based on the information shared above.

POST createPaysSupplierShipping()

ENDPOINT

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

Parameter Descriptions & Rules

The following table lists the input and output parameters of the createPaysSupplierShipping() process, and also 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
`customerRefNo`	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": "20230619",
    "customerRefNo": "20230619",
    "senderCode": 801452,
    "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": "PaysSupplier",
    "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 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

(recipientTitle, recipientCity, recipientCounty, recipientAddress, recipientPhone…) ↩ ↩²
(senderTitle, senderCity, senderCounty, senderAddress, senderPhone…) ↩ ↩²

Supplier Order Creation​

POST createPaysSupplierShipping()​

Parameter Descriptions & Rules​

Servis Cevapları​

Footnotes​

Footnotes​

Supplier Order Creation

POST createPaysSupplierShipping()

Parameter Descriptions & Rules

Servis Cevapları

Footnotes

Footnotes