Introduction
The Intershop Order Management (IOM) uses the Simple Object Access Protocol (SOAP). The present concept gives some basic information about the SOAP web service handling of the IOM and is primarily intended for all developers implementing a project or working in the core product of IOM.
Glossary
| HTTP | Hypertext Transfer Protocol |
| HTTPS | Hypertext Transfer ProtocolSecure |
| IOM | The abbreviation for Intershop Order Management |
| SOAP | Simple Object Access Protocol |
| SSL | Secure Sockets Layer |
| WSDL | Web Service Description Language |
| PSP | Payment Service Provider |
Wording | Description |
|---|
References
General Assumptions
The IOM is a transaction platform that can be used as meta-shop or meta-supplier to handle multiple shops/suppliers. From a shop's perspective the IOM works as a supplier that processes and transmits the data to the actual supplier. This way a shop system has to communicate with only one supplier, the IOM instead handles a large number of suppliers. From a supplier's perspective the IOM works as a shop which is connected to multiple shops, sales channels, marketplaces and so on.
The business process transaction is a transmission exchange between the business partners, in which each part can have the role as a sender and a receiver of a message. For technical clarification it has to be defined how to transmit data between the business partners. For this different business protocols have to be considered.
The IOM assumes that messages are pushed. That means that the sender is always the active part of the transmission.
Transmission Logging
Each transmission and also each attempt of a transmission, both sending and receiving, has to be logged by both communication partners. So the complete message content together with the response (or error response) has to be saved and called with suitable access paths (e.g., message IDs, time stamps, etc.).
Note
Only a message which can present the original message together with the response applies as a successful message.
Uniqueness of a Transmission and Attempt of a Transmission
During an attempt of a transmission different errors can appear. When a transmission failed the same message must be sent again. If a message-ID is part of the message, the ID has to be the same in a repeated transmission try. Only that way duplicates can be avoided reliably.
Fault Tolerance and Error Handling
Message ID
Messages which are at risk to be duplicated, must be identifiable with a message ID. Special attention should be for messages of orders, deliveries and returns. If a transmission attempt is responded with a receipt confirmation, no further message with the same ID is allowed to be sent. Otherwise the message receiver gets an duplication error. Plain requests without any kind of payload do not need a unique message ID. Also messages which refer to immutable objects does not require a unique message ID.
Note
For an order a message ID could be for example
ORDER123456. A message ID of a delivery notification might look like this DISPATCH654543.Acknowledgment of Receipt
For each object which is transmitted synchronously by a message, an acknowledgment of receipt has to be sent synchronously. An acknowledgment of receipt tells the sender that the message was received and confirmed that the message is available in a form which is expected by the receiving system. This does not mean that the message is semantically correct. This will be checked by some asynchronous processes. Problems at a asynchronous process will be handled separately.
When objects, which can be requested again anytime, are requested, no receipt confirmation is necessary. But if an object is not available after sending, the requesting system has to send a asynchronous acknowledgement.
Renewed Message Transfer After Fault
The sender of a message has to continue his transmission until he gets a positive receive confirmation from the receiver. The following error types have to be considered in the transmission attempts:
- Technical error: The receiving system cannot process the message because of internal reasons. The sender should send the unchanged message later again.
- Validation error: The sender has received a wrong message regarding the content. It must correct the content mostly manually and send the message later again. Authentication errors also belongs in this section.
- Duplication error: The receiver already received a message with the same message ID. The sender can stop further transmission tries for this message.
- Further errors: All errors which are produced by the application environment such as timeouts, HTTP-error codes, etc. should be handled like technical errors.
Escalation for Repeated Failed Transmission Attempts
If despite several delivery attempts no positive acknowledgment from the receiver arrives, the sender has to identify the problem. A threshold value has to be defined for technical error, which determines whether an error case has to escalated. Escalation means that the error has to be checked manually. Technical errors should be checked by the receiver, meanwhile validation errors should be checked by the sender. For technical errors over the threshold value (or a multiple of the threshold value) the sender must also check the problem.
General Semantic and Plausibility Rules
The SOAP-based web services are tied to syntactic rules of the WSDL. Certain plausibility rules, which have to be semantically fulfilled, are applied for messages but not represented in the WSDL files themselves. Such plausibility rules can relate to consistency and completeness of the sent data and are specified in the description of the individual interface specification. Furthermore, message elements are limited in length. This is not syntactically given to avoid changes of the syntax due to database internal field changes. The limit of length has to be defined in the interface coordination.
Return Values
In case of a successful service call, the service sends a response message instead of a fault. In the response the client gets:
- A string: This can be the ID of the object in the target system
- Null: The return value null shows no error, but no object was created on the target system, so no ID can be given back
- The requested object
Error Handling
The error handling follows the semantic check like described in section Concept - IOM SOAP Web Services#Fault Tolerance and Error Handling. Each error leads to the corresponding Java exception. This leads to according follow-up activities.
System Requirements
The system of the communication partner has to be able to understand a WSDL definition to validate incoming and outgoing messages and to decrypt the message channel. For Java systems, various binding frameworks to map WSDL definitions to Java classes exists. The developer can implement the application against the generated Java classes.
The decryption of the message channel takes place like described in chapter Concept - IOM SOAP Web Services#Security.
Versioning of IOM Web Services
Intershop continues to develop the web service interfaces for the IOM. An interface set to deprecated will be available at least for two minor releases. Different versions are located in different name spaces and URLs. IOM follows the recommendations of IONA (https://dl.dropboxusercontent.com/u/59555997/20070410-WSDL-Versioning-Best-Practise.pdf) for versioning.
Reserved Properties
Some use cases / business processes need additional information. TheXML Schema Definition provides additional fields to sending additional information via the existing interfaces if it is necessary for a business model. For this, many messages have the possibility to add properties at header, position level and in some cases at item level. These properties can also be grouped in a grouped code („PropertyGroup/@id“) and specified by key-value pairs („PropertyGroup/Property/@key“ und „PropertyGroup/Property/@value“).
Some combinations of property group and property key have a fixed meaning in the interface. These are called "Reserved Properties". These combinations are only allowed to use after previous agreement with the communication partner. These are in detail:
| PropertyGroup | Key | Description |
|---|---|---|
| payment | method | Payment method |
| paymentProviderOrderNo | Order number at PSP (Payment Service Provider) | |
| RefNr | Reference number at PSP | |
| merchantAccount | Merchant account at PSP | |
| recall | returnReason | Return reason |
| returnReasonText | Description of a return reason | |
| returnReasonComment | Comment for a return reason | |
| shopReturnType | Name of a return type like it is used in the shop | |
| references | articleRef | Article number as used by the IOM |
| shopArticleNo | Article number as used by the shop | |
| supplierArticleNo | Article number as used by the supplier | |
| positionNumber | Order position number | |
| quantities | quantityRemaining | Remaining article count in a position |
| identification | retour_label_no | Return slip number |
| salesChannel | Sales channel Deprecated since 2.17 Removed since 3.0 | |
| basketToken | Token of an article validation from the ValidateArticleService | |
| orderToken | Token of an order with immaterial articles | |
| coupon | couponUnit | Unit of a coupon |
| percentageValue | Percentage value of a coupon | |
shippingClass Deprecated since 2.2 Removed since 3.4 | shippingClassName | Name of the shipping cost class |
| ShopSumGross | Sum of the shipping costs of this class, gross | |
| shopSumNet | Sum of the shipping costs of this class, net | |
| shopSumTax | Sales tax | |
| taxType | Sales tax type | |
| documents | invoiceDownloadURL | Download URL of an invoice pdf document |
| creditnoteDownloadURL | Download URL of a credit note pdf document | |
BonusPoints Deprecated since 2.17 Removed since 3.0 | partnerName | Name of the bonus point partner like PAYBACK |
| cardNo | Bonus card number | |
| bonusType | Type of bonus
| |
| unitPoints | Points for a single product within the order position | |
| unitIncentivePrice | Sales price related to the points | |
| unitPrice | Sales price of a single product within the order position | |
| quantity | Quantity of points | |
| marketingCode | Code of the marketing campaign | |
| delivery_address | streetName | Street name without house number |
| houseNumber | Street number | |
| billing_address | streetName | Street name without street number |
| houseNumber | Street number | |
| reservation | reservationId | ID of a product stock reservation. See also the REST service "Stock Reservation" |
pagination Note Only relevant at the | limit | Limit (maximum) of result set - aka page size |
| offset | Page offset - usually a multiple of the limit (page size) - starts with 0 |
Security
Securing of the Communication Channel
To secure the compliance of data protection all data connections need to be SSL-encrypted. For this, business partners have to offer their web services in HTTPS. The key length of the symmetric encryption needs to be at least 128 bit. The communication partners need server- and client-side certificates. Self-validated certificates are sufficient and do not need to be signed by a public certificate authority. Before the first communication starts certificates need to be exchanged and if necessary validated.
Authentication
For every communication attempt, the sender has to authenticate itself towards the recipient. The sender transmits a combination of name, username and password, which is deposited for the sender at the receiver. A sender who cannot be authenticated by the recipient with this combination receives a validation error. The sender is responsible for correcting the message after a validation error. The sender also has to check whether the authentication data is correct.
Authorization
The authenticated sender is only authorized for the agreed actions. In case a sender sends an unauthorized message, it receives a validation error. The sender is responsible to check the message.