General information
- The industry standard OpenTrans 2.1 format is used for orders
- use this link to download the OpenTrans 2.1 documentation and sample files
- the MimeType must be application/xml
- sending only works via HTTP POST
- in the POST body, the ORDER can only be in OpenTrans 2.1 format and encoded as UTF-8
- an order can only be directly sent to a single distributor, so a new OpenTrans order has to be created for each distributor.
A list of distributors and their master data can be retrieved via API. The Supplier->ID is the unique ITscope number of the distributor.
The order is subject to a number of validations before it is actually sent:
- verification that the order is in a valid OpenTrans 2.1 format
- maximum length of the order number is 18 characters
- validation of whether the individual line items can be found in our catalogue from the respective distributor
- NO validation regarding valid price or availability
- validation of whether the sum of the individual items and the quantities match the final total
- for project orders: NO validation whether the specified project number is included in your project list configured on ITscope.com.
Errors may of course also occur during sending, or synchronous error messages may be received from the distributor’s system.
The API will always return appropriate error messages and HTTP codes >400.
If an order is fully sent, the HTTP code 200 is returned in addition a response with the following data:
- the new OrderID
- the current status of the order.
Sending a test order to the ITscope Partner Test supplier
Test orders can be carried out in the live system via the API, by sending orders to a test supplier maintained by ITscope named ‘ITscope Partner Test‘. This test supplier has the supplier ID 10000735.
You can find information about the activation of the ITscope partner test supplier under the following help entry: https://guide.itscope.com/en/kb/itscope-partner-test/
Whether the test supplier is activated can be easily checked in 2 ways:
- On the ITscope platform: if the supplier “ITscope Partner-Test for test orders” is visible as one of the sources of supply (incl. price and stock) when calling up the assortment link.
- a list of all distributors can be loaded directly via the API (with the API key), the test supplier should be listed here.
E.g.: https://api.itscope.com/2.0/business/deals/send/10000735
Automatically generate response documents
It is possible to carry out a realistic test of whether your system can also process our response documents (order confirmation, shipping notification and invoice). For this purpose, you have the option of specifying the documents to be generated including their quantity.
Note: the number of documents to be generated is limited to 6 each.
This can be done using the order number or order ID. Simply add a ‘§’ symbol to the order number, followed by the parameters listed below. The parameters are given as follows:
§<shortcut1><count1><shortcut2><count2> etc.
These shortcuts (case insensitive) are available to generate the appropriate document:
| Shortcut | Action | Generated document |
|---|---|---|
| R | reject order | ORDERRESPONSE |
| C | confirm order | ORDERRESPONSE |
| A | advise order (mark as sent) | DISPATCHNOTIFICATION |
| I | invoice order (mark as invoiced) | INVOICE |
Capitalisation does not have to be taken into account here.
Example for an order ID:
TEST180620§C3A1I2
Our system will immediately issue 3 order confirmations (C3), 1 delivery note (A1) and 2 invoices (I2) for an order with this order number.
TEST180620§R1
For an order with this order number, our system will issue 1 response document (R1) in which the order is rejected.
TEST180620
If no additional parameters are specified, the test order is triggered without generating response documents.
Sending an order to a supplier
The order document must be created, validated and then sent to the respective distributor by means of its ID as described in the above sections.
The sending must be done via HTTP POST and the contents of the POST is the pure ORDER as XML. The content type of the post should be in the form of application/xml;charset=UTF-8.
E.g.: https://api.itscope.com/2.0/business/deals/send/10000136