Structure of the order
Our system exclusively receives orders in an XSD-valid OpenTrans version 2.1 format.
Description of the individual order elements
Order number (ORDER_ID):
- Own order number, maximum length: 18 characters.
<ORDER_INFO>
<!-- Unique order ID for the customer -->
<ORDER_ID>ORDER_180801-004</ORDER_ID>Participants (PARTIES):
- The distributor (as the supplier) with the PartyID that is deposited in your system for the distributor
- Buyer, i.e. invoice recipient, PARTY_ROLE->buyer with the PartyID that is deposited in your system as the customer number for the buyer
- Recipient of delivery, may differ from the buyer, for example due to drop shipment.
<!-- MANDATORY: Delivery address for the order -->
<PARTY>
<ns2:PARTY_ID type="supplier_specific">123456</ns2:PARTY_ID>
<PARTY_ROLE>delivery</PARTY_ROLE>
<ADDRESS>
<!-- MANDATORY: Company name -->
<ns2:NAME>ITscope GmbH</ns2:NAME>
<!-- Address supplement 1 -->
<ns2:NAME2>5th floor</ns2:NAME2>
<!-- Address supplement 2 -->
<ns2:NAME3>Attn. Peter Müller</ns2:NAME3>
<CONTACT_DETAILS>
<ns2:CONTACT_NAME>Support</ns2:CONTACT_NAME>
<ns2:FIRST_NAME>ITscope</ns2:FIRST_NAME>
<ns2:PHONE type="office">+49 721/6273760</ns2:PHONE>
<ns2:EMAILS>
<ns2:EMAIL>support@itscope.com</ns2:EMAIL>
</ns2:EMAILS>
</CONTACT_DETAILS>
<ns2:STREET>Ludwig-Erhard-Allee 20</ns2:STREET>
<ns2:ZIP>76131</ns2:ZIP>
<ns2:CITY>Karlsruhe</ns2:CITY>
<ns2:COUNTRY>Deutschland</ns2:COUNTRY>
<ns2:COUNTRY_CODED>DE</ns2:COUNTRY_CODED>
</ADDRESS>
</PARTY>Partial delivery (PARTIAL_SHIPMENT_ALLOWED):
- Set this field if the order is to be split into partial deliveries
- This field is defined as a mandatory field in OpenTrans, so it must be set to false as default value.
<!-- Indication of whether partial delivery is allowed -->
<PARTIAL_SHIPMENT_ALLOWED>true</PARTIAL_SHIPMENT_ALLOWED>Delivery date (DELIVERY_DATE):
- Set this field if the order is to be sent with a fixed or requested delivery date
- The attribute type=”fixed” indicates that it is a fixed delivery date, the value type=”optional” indicates that it is a requested delivery date.
<DELIVERY_DATE type="fixed">
<DELIVERY_START_DATE>2021-10-22T00:00:00</DELIVERY_START_DATE>
<DELIVERY_END_DATE>2021-10-22T00:00:00</DELIVERY_END_DATE>
</DELIVERY_DATE>Own delivery note (UDX.DROPSHIPMENT):
- This field must be set if shipping with your own delivery note (drop shipment) is desired. The custom delivery note can be requested from the respective supplier. Costs may be involved in this, meaning this should be coordinated in advance with the distributor.
<HEADER_UDX>
<!-- Own delivery note (i.e. drop shipping) should be used (true) / should NOT be used (false) -->
<UDX.DROPSHIPMENT>true</UDX.DROPSHIPMENT>
</HEADER_UDX>Customer order reference (CUSTOMER_ORDER_REFERENCE -> ORDER_ID):
- This field is the end customer’s order ID
- This field is optional.
<CUSTOMER_ORDER_REFERENCE>
<!-- End customer order reference (the end order ID that is given to the end customer -->
<ORDER_ID>ORDER_019203</ORDER_ID>
</CUSTOMER_ORDER_REFERENCE>Distributor product number (SUPPLIER_PID type=”supplier_specific”):
- This number is the supplier’s unique item number (SKU). We use this number to search for the item that is to be ordered. This information is given at line item level.
<!-- Supplier's product ID - mandatory field -->
<ns2:SUPPLIER_PID type="supplier_specific">123002</ns2:SUPPLIER_PID>ITscope PUID (INTERNATIONAL_PID type=”itscope”):
- This number is the ITscope product number. It is a unique reference to the ITscope product. This information is given at line item level.
<!-- ITscope product ID - not a mandatory field -->
<ns2:INTERNATIONAL_PID type="itscope">6676919000</ns2:INTERNATIONAL_PID>Quote number for an order referencing to a quote (QUOTATION_ID):
- This number is the unique quote number for a specific quote from the supplier. This information is given at line item level.
<!-- Supplier quote reference -->
<SOURCING_INFO>
<!-- Distributor quote number - mandatory field -->
<QUOTATION_ID>1040104240</QUOTATION_ID>
</SOURCING_INFO>Project number for project orders (AGREEMENT_ID):
- This number is the manufacturer project number for a project order. With this number, the Sales Team can assign the correct items to the corresponding manufacturer project. This information is given at line item level.
<!-- Conditions for the project price -->
<SOURCING_INFO>
<!-- Distributor project/quote number - not a mandatory field -->
<QUOTATION_ID>1040104240</QUOTATION_ID>
<AGREEMENT>
<!-- Manufacturer project number - Mandatory, so that the supplier can assign the project price -->
<ns2:AGREEMENT_ID>HPPSK1234500</ns2:AGREEMENT_ID>
<!-- Time period during which the project conditions are valid - not mandatory fields -->
<ns2:AGREEMENT_START_DATE>2018-09-05T00:00:00</ns2:AGREEMENT_START_DATE>
<ns2:AGREEMENT_END_DATE>2019-12-31T00:00:00</ns2:AGREEMENT_END_DATE>
<!-- End customer of the project item - not a mandatory field -->
<AGREEMENT_DESCR>City of Karlsruhe</AGREEMENT_DESCR>
</AGREEMENT>
</SOURCING_INFO>Download sample order files
The sample order files linked at the end of this article contain XML comments (in German), in order to simplify the understanding of the structure of an ORDER. These files can also be used as reference files, for sending a test order with the ITscope API method business/deals/send to the ‘Partner Test’ (SupplierId 10000735).
The file Example_ORDER_Testdistributor_Bestellung.xml is an ordinary order.
The file Example_ORDER_Testdistributor_Bestellung_Eigener_Lieferschein.xml is an order with own delivery note (drop shipment).
The file Example_ORDER_Testdistributor_Bestellung_Projekt.xml is an order with a project price. The third line item in this sample contains exemplary project conditions. From this sample, it can be seen that it is possible to have a mix of different prices (‘normal’ or project prices) as well as different projects within the same order, as the project is specified on a line-by-line basis.