Road Order Creation - createRoadOrder()

Road Order Creation

The createRoadOrder() method on the Horoz Logistics E-Export Integration should be used to create the records that need to be processed for micro and macro exports from domestic to abroad that will take place in road transportation. Important information about the createRoadOrder() method and the things to be considered when creating a road export order in the Horoz system are listed below for the information of the clients.

• The first check to be performed while adding the order record to the system is that the documents in relation to the micro export, especially those which are included in the order creation structure, are sent through the FTP first.

• The order record process is required to consist of the records, whose invoiced has been issued, and whose documents have been completed and whose shipment process has been finalized, in terms of the features.

• There are no methods such as canceling or updating the order in this API library. In the event that the order is required to be canceled for any reason regarding any record, whose documents and request for order have been successfully sent to the Horoz system, then the seller is required to contact the HOROZ e-Export MT officer, and to proceed with the cancellation process manually.

• In the event that any of the information recorded regarding any order, which has been successfully sent, is wanted to be change, then the cancellation process, as stated herein above, is required to be completed first, and then a new order is required to be opened by using this method upon sending the documents in relation to such order through FTP.

• In the event that the export type is micro during the order placement, then the invoice value is required to be equal to or below the invoice value of 15,000 €, and the order weight is required to be equal to or below the total order weight of 300 kg. Macro export selection is not subject to any rule.

• Each order must be single on the basis of recipient. Purchase type, destination country, product quantity and desi-kg information are important information in order to determine the order pricing and additional costs that might be incurred.

• In case of selecting ATR Movement Certificate in the micro export type selection, there will be a issuance cost of 10 € ATR (January 2023). In the event that YDG is selected in the order entry features, then an international customs fee will be applied based on the reception type. In the event that Macro export type is selected, then ATR will not be selected, and the Customs Service will be selected. Based on such selection, the ATR document and bill of lading document will be issued and sent to the seller by Horoz. Such documents will be added as additional documents to the order.During the pricing phase of the products, their stacking status, package types and sizes are checked regarding occurrence of any additional cost.

• The content expected from the client regarding the createRoadOrder method basically consists of the sender, recipient, order information and product information. Whether the sender information is completed by the client while transmitting the order, or not varies based on whether free transmission is performed, or not (isFreeSenderInfo : yes/no) and the reception type (receptionType : itWillBring/receivedFromAddress).

• Regardless of the free selection (isfreeSenderInfo”:”yes/no”), in the event that the reception type is "it will bring" (receptionType”:”itWillBring”) in each record that will be created, then the “collectionPointId” information among the Horoz collection point definitions (“selectCollectionPoints”) is entered in the “outletLocationId” information.In the event that the "it will bring" is selected while entering the order, then it is required to determine the Horoz point, to which the product will be brought, through "selectCollectionPoints" based on the destination country.

• In the event that free is not selected (isFreeSenderInfo = no), and that the reception type will be " to be received from the address (receptionType: receivedFromAddress), then it indicates that the seller wants to depart from any address predefined. Therefore, it is required to select from the addresses available in listSellerAddressPoints, and to enter the sellerAddressPointId information, provided in the listSellerAddressPoints() method, in the outletLocationId information.

• Selection of free means use of an departure point without being subject to any situation defined in the system. In the event that free is selected, and that the reception type is to be "to be received from the address", then this requires the seller to complete the order with the sender information as a temporary information, for example, to express that s/he/it wants the product to be received from the address s/he/it has defined only once. In such case, the mandatory sender information (senderTitle, senderCountryName, senderCityName, senderCountyName, etc.) within the createRoadOrder() method is expected to be completed. Therefore, outletLocationId information is not expected to be as a value.

• In the event that isFreeSenderInfo:yes has been entered, and that receptionType:receivedFromAddress has been entered, then the sender information about the order is fed from the information sent by the client; therefore, in such case, the mandatory sender information (senderTitle, senderCountryName,senderCityName, senderCountyName, etc.) available within the createRoadOrder() method are expected to be sent in a manner to have been completed.

• In the event that isFreeSenderInfo:yes/no(regardless) has been entered, and that receptionType:itWillBring has been entered, then the sender's country, province, district, address and postal code information may be obtained from Horoz warehouse definitions, which may be obtained as GET from the selectCollectionPoints method, for outletLocationId. In the event that the outletLocationId information, as entered, is not available in Horoz warehouse definitions, then UNDEFINED COLLECTION POINT error is returned.

• In the event that isFreeSenderInfo:no has been entered, and that receptionType:receivedFromAddress has been entered, then the sender's country, province, district, address and postal code information may be obtained from Horoz departure point definitions, which may be obtained as GET from the listSellerAddressPoints method, for outletLocationId. In the event that the “outletLocationId information, as entered, is not available in the seller's address definitions, then UNDEFINED DEPARTURE POINT error is returned. In the event that a definition, which is selected from the system, other than the sellerAdressPointId or collectionPointId, is entered in the outletLocationId parameter, then the UNDEFINED DEPARTURE POINT error and the UNDEFINED COLLECTION POINT error are sent.

• No information other than itWillBring and receivedFromAddress can be entered in the receptionType field; otherwise, the error receptionType INFORMATION MAY NOT BE ENTERED AS ANY VALUE OTHER THAN receivedFromAddress/itWillBring. is returned.

• In respect of the receiver information, in the event that destinationLocation information has been entered in a manner to have been completed, then the receiver's country, province, district, address and postal code information may be obtained from Horoz warehouse definitions, which may be obtained as GET from the listHorozWareHouses method, for the relevant destinationLocation. In the event that the destinationLocation information, as entered, is not available in Horoz warehouse definitions, then UNDEFINED DESTINATION POINT error is returned. This usage will be meaningful through the WMS module.

• In the event that destinationLocation information has been entered in a manner to have not been completed, then the receiver information about the order is fed from the information sent by the client; therefore, in such case, the mandatory receiver information (recipientTitle, recipientCountryName,recipientCityName, etc.) available within the createRoadOrder() method are expected to be sent in a manner to have been completed.

• The currency information about the amount of invoice to be sent for road orders to be transmitted to the Horoz system through the integration is expected to be sent in TRY (Turkish Lira), EUR (European Union Currency), USD (American Dollar) and GBP (British Pound). Otherwise, an error is returned to the client.

• In respect of the order information, the postal code of the recipient country within the recipient information is required to be entered in the arrival information in terms of pricing, and such value entered is required to be numerical.

The documents required for the execution of road export orders and the description and export types of these documents are as follows;

REQUIRED DOCUMENTATION	DESCRIPTION	EXPORT TYPE
ETGB	Customs documentation for micro export purposes	MICRO EXPRORT
EN Invoice	The invoice issued in English by the seller to the recipient based on the sale	MICRO, MACRO EXPORT
TR Invoice	The invoice issued in Turkish by the seller to the recipient based on the sale	MICRO, MACRO EXPORT
Customs Representation Certificate	Certificate of authorization issued by the seller regarding the customs procedures once a year	NOT MANDATORY
POA Certificate	Certificate of authorization issued by the recipient for foreign customs	MICRO (RECIPIENT TYPE B2C)

• In the event that the purchase type is selected as "it will bring" during the order entry, then the departure point is expected to be selected from the appropriate departure points defined in the system. In respect of the selection "to be received from the address", in the event that the total weight of the order is below 30 kg, then it is required to be transported by Yurtici Kargo. In such , the seller is required to take the products to the nearest Yurtici Kargo branch along with the Yurtici Kargo delivery document.

The barcode label used in Yurtici Kargo operation is as follows;

• In respect of the loads over 30 kg, HOROZ domestic distribution operation unit receives the products from the relevant address based on the departure point information. At this phase, the address information selected from sellerAddressPointList() is expected to be completed in the departure address fields in the order.

• The products to be added to the order must be performed from the master records of the products defined in the HOROZ system by using the createProduct() method. The products that are not defined in the HOROZ system (main definitions of the component products such as Wardrobe) will receive an error warning during the order registration phase. The container and good quantity within the order is among the information to be included in the ETGB, and the container quantity should indicate the part to be transported physically, while the goods quantity should refer to the product quantity sold subject to the invoice.

• In respect of the B2C sales regarding the micro exports, the POA document is one of the documents that is required to be signed by the recipient and to be sent by the seller. The Customs Representation Certificate is a document that is required to be included in the micro exports and to be submitted annually. This document will be received in the contract to be executed by and between HOROZ and the seller at the beginning of the process.

• The representation certificate is not a document expected to be sent through FTP. When I Want Customs Service is selected during the Macro export selection, ATR and bill of lading documents will be issued to the seller.

---

POST createRoadOrder()

ENDPOINT

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

Parameter Descriptions & Rules

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

Fields

PARAMETER	DESCRIPTION	DATA TYPE	LENGTH	FIELD LOCATION	REQUIRMENT
processKey	processKey information defined for the client	string	100	Header	Mandatory
customerOrderNumber	Customer order number	string	50	inBody Request	Mandatory
isFreeSenderInfo	Can the sending information be entered freely?	Enum	50	inBody Request	Mandatory
outletLocationId	Departure point Id (based on receptionType and isFreeSenderInfo)	Integer	-	inBody Request	Mandatory
senderTitle	Sender title (If isFreeSenderInfo = Yes and receptionType = receivedFromAddress)	string	100	inBody Request	Mandatory
senderCountryName	Sender country name (If isFreeSenderInfo = Yes and receptionType = receivedFromAddress)	string	100	inBody Request	Mandatory
senderStateName	Sender state name (If isFreeSenderInfo = Yes and receptionType = receivedFromAddress)	string	100	inBody Request	Mandatory
senderCityName	Sender city name (If isFreeSenderInfo = Yes and receptionType = receivedFromAddress)	string	100	inBody Request	Mandatory
senderCountyName	Sender county name (If isFreeSenderInfo = Yes and receptionType = receivedFromAddress)	string	100	inBody Request	Mandatory
senderAddress	Sender address (If isFreeSenderInfo = Yes and receptionType = receivedFromAddress)	string	500	inBody Request	Mandatory
senderPostCode	Sender post code (If isFreeSenderInfo = Yes and receptionType = receivedFromAddress)	string	20	inBody Request	Mandatory
senderOfficialPerson	Sender official person (If isFreeSenderInfo = Yes and receptionType = receivedFromAddress)	string	100	inBody Request	Mandatory
senderPhone1	Sender phone 1 (If isFreeSenderInfo = Yes and receptionType = receivedFromAddress)	string	20	inBody Request	Mandatory
senderPhone2	Sender phone 2 (If isFreeSenderInfo = Yes and receptionType = receivedFromAddress)	string	20	inBody Request	Mandatory
senderEmail	Sender e-mail (If isFreeSenderInfo = Yes and receptionType = receivedFromAddress)	string	200	inBody Request	Mandatory
destinationLocation	Destination location (must be used in case of shipping to Horoz / Seller warehouses)	string	30	inBody Request	Optional
recipientTitle	Recipient title	string	100	inBody Request	Mandatory
recipientType	Recipient type	string	100	inBody Request	Mandatory
recipientCountryName	Recipient country name (based on destinationLocation)	string	100	inBody Request	Mandatory
recipientStateName	Recipient state name (based on destinationLocation)	string	100	inBody Request	Mandatory
recipientCityName	Recipient city name (based on destinationLocation)	string	100	inBody Request	Mandatory
recipientFloor	Recipient floor (based on destinationLocation)	Integer	-	inBody Request	Optional
recipientApartment	Recipient apartment (based on destinationLocation)	Integer	-	inBody Request	Optional
recipientAddress	Recipient address (based on destinationLocation)	string	500	inBody Request	Mandatory
recipientPostCode	Recipient post code (based on destinationLocation)	string	20	inBody Request	Mandatory
recipientOfficialPerson	Recipient official person (based on destinationLocation)	string	100	inBody Request	Mandatory
recipientPhone1	Recipient phone 1 (based on destinationLocation)	string	20	inBody Request	Mandatory
recipientPhone2	Recipient phone 2 (based on destinationLocation)	string	20	inBody Request	Mandatory
recipientEmail	Recipient e-mail (based on destinationLocation)	string	200	inBody Request	Mandatory
totalQuantity	Total quantity (Total quantity)	Integer	-	inBody Request	Mandatory
totalDesi	Total desi	Float	-	inBody Request	Mandatory
totalWeight	Total weight	Float	-	inBody Request	Mandatory
chargeableWeight	Chargeable weight (The larger value in case of comparing weight with desi)	Float	-	inBody Request	Mandatory
totalContainer	Total container quantity (Number of parts that appear to be subject to physical transportation to be barcoded)	Integer	-	inBody Request	Mandatory
orderNotes	Order note	string	1000	inBody Request	Optional
deliveryPerson	Delivery person	string	20	inBody Request	Optional
shippingType	Shipping type	Enum	100	inBody Request	Mandatory
deliveryMethod	Delivery type	Enum	100	inBody Request	Mandatory
recordType	Record type	Enum	100	inBody Request	Mandatory
receptionType	Reception type	Enum	100	inBody Request	Mandatory
invoiceNumber	Invoice number	Enum	100	inBody Request	Mandatory
invoiceDate	Invoice date	Date	-	inBody Request	Mandatory
invoiceAmount	Invoice amount	Float	-	inBody Request	Mandatory
invoiceCurrencyUnit	Invoice currency	string	5	inBody Request	Mandatory
exportType	Export type	Enum	100	inBody Request	Mandatory
paymentMethod	Payment method	Enum	100	inBody Request	Mandatory
isAtr	Is ATR? (based on micro export selection)	Enum	100	inBody Request	Mandatory
isInsured	Is insured?	Enum	100	inBody Request	Mandatory
isYdg	Foreign customs clearance	Enum	100	inBody Request	Mandatory
isCustomService	Customs Service (based on macro export selection)	Enum	100	inBody Request	Mandatory
orderDetail	SOrder detail	Array	-	inBody Request	-------
productCode	Product code	string	50	inBody Request	Mandatory
productName	Product name	string	100	inBody Request	Mandatory
quantity	Product sales quantity	Integer	-	inBody Request	Mandatory
containerPieces	Number of containers	Integer	-	inBody Request	Mandatory

Example Request

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

Example Response

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

Detailed information is given below for the expected enum values in the createRoadOrder method.

ENUM FIELD	FIELD NAME	DESCRIPTION
isFreeSenderInfo	Id the sender information free?	Whether the sender information within the request can be entered freely, or not, can be set based on the yes/no selection.
shippingType	Shipping type	The shipping type may be reported by entering the appropriate value for the order from one of the values of economic and express.(economic : economy, express : express)
deliveryMethod	Delivery method	The delivery method may be reported by entering the appropriate value for the order from one of the values of curbFront, deliveryToFloor and deliveryToFloorAndAssembly. (curbFront : curb front delivery, deliveryToFloor : delivery to the floor, deliveryToFloorAndAssembly : delivery to the floor and assembly)
recordType	Record type	The record type may be reported by entering the appropriate value for the order from one of the values of direct and partial. (direct : direct, partial : partial)
receptionType	Reception type	The reception type may be reported by entering the appropriate value for the order from one of the values of receivedFromAddress and itWillBring. (receivedFromAddress : to be received from the address, itWillBring : s/he/it will bring)
paymentMethod	Payment method	The payment method may be reported by entering the appropriate value for the order from one of the values of advance and free. (advance: advance, free : free)
İsAtr	Is ATR ?	The appropriate ATR status for the order may be reported by entering one of the values of yes and no. It is active in the micro export type.
isYdg	Is it foreign customs clearance ?	The appropriate YDG status for the order may be reported by entering one of the values of yes and no.
isInsured	Is insured ?	Whether it is insured for the order, or not, may be reported by entering one of the values of yes and no.
exportType	Export type	The export type status for the order may be reported by entering one of the values of macro and micro. (macro : macro, micro : micro”)
isCustomService	Is there customs service ?	The appropriate customService status for the order may be reported by entering one of the values of yes and no.It is active in the macro export type.

---

Service Responses

You can access the successful/unsuccessful service responses here.