Personal Library

Reference - IOM REST API - Communication 2.11

https://support.intershop.com/kb/29G426

ReDoc View
Document View

Download Specification
Authentication
- Basic Authentication
- Bearer Token Authentication
Authorization
API Specification

Product Version	2.17
Product To Version
Status	New Labels

Download Specification

This API specification is available for download as an Open API 3.0 YAML file:

intershop-order-management-communication-2.11.yaml

Authentication

Basic Authentication

Please configure your clients to use this authentication method to submit user name and password.

Bearer Token Authentication

To generate a valid JWT, just log into the OMT, inspect the browser cookies and use the value of the cookie called 'OMS_IDENTITY' as JWT. Within a UI-client (e.g., Postman) choose "Bearer Token" and just type in a valid Json Web Token (JWT).

Authorization

The permission "Create delivery message" is required and must be assigned to the supplier and shop mentioned in the payload.

API Specification

Introduction

OpenAPI Version: 3.0.1

IOM Communication REST API Version: 2.11

The IOM Communication REST API supports dispatch, order response and return message transmission to the IOM.

Dispatch API

/dispatches

POST: Create a order dispatch message

Description

Persist a dispatch message and triggers the processing

Request Body

Dispatch application/vnd.intershop.dispatch-message.v1+json

Request Parameters

Response

201 - Created

Response Header	Description
`Location`	The path to the newly created resource. \| Format: `url`

400 - Bad Request

ErrorReport application/json

401 - Unauthorized Authentication information is missing or invalid.

403 - Forbidden

415 - Unsupported Media Type

500 - Internal Server Error An unexpected error occured.

Response API

/responses

POST: Create a order response message

Description

Persist a order response message and triggers the processing

Request Body

OrderResponse application/vnd.intershop.response-message.v1+json

Request Parameters

Response

201 - Created

Response Header	Description
`Location`	The path to the newly created resource. \| Format: `url`

400 - Bad Request

ErrorReport application/json

401 - Unauthorized Authentication information is missing or invalid.

403 - Forbidden

415 - Unsupported Media Type

500 - Internal Server Error An unexpected error occured.

Return API

/returns

POST: Create a order return message

Description

Persist a return message and triggers the processing

Request Body

Return application/vnd.intershop.return-message.v1+json

Request Parameters

Response

201 - Created

Response Header	Description
`Location`	The path to the newly created resource. \| Format: `url`

400 - Bad Request

ErrorReport application/json

401 - Unauthorized Authentication information is missing or invalid.

403 - Forbidden

415 - Unsupported Media Type

500 - Internal Server Error An unexpected error occured.

Request and Response Object Schemata

Dispatch application/vnd.intershop.dispatch-message.v1+json

{

"messageId":
string
Required | The unique message Id. | Example: 906090-42
"supplierName":
string
Required | The name of the supplier. | Example: Demo-Supplier
"supplierShopName":
string
Required | The name of the shop as used by the supplier. | Example: Demo-Shop
"shopOrderNumber":
string
Required | The order number as used by the shop. | Min Length: 1 | Max Length: 50 | Example: 78231.2018
"supplierOrderNumber":
string
The order number as used by the supplier. | Min Length: 0 | Max Length: 250 | Example: 398-8923#556
"dispatchDate":
string
Required | Date of the hand over of the package to the carrier. Note: Must conform to the ISO 8601 format. | Format: date-time | Example: 2018-05-10T14:52:26.467Z
"deliveryNoteNumber":
string
The delivery note number. | Min Length: 0 | Max Length: 70 | Example: DE-3290-030-9023
"carrier":
object
Required | A Carrier object. Information about the carrier and the shipment.
{
- "name":
  string
  Required | Name of the carrier as used by the supplier. Possible values must be configured via Supplier2CarrierDO. | Example: DHL
- "packages":
  integer
  Required | Number of packages. Note: Packages with different tracking numbers should be handled by separate dispatch messages. | Format: int32 | Example: 1
- "trackingNumber":
  string
  The tracking number of the delivered package. | Example: A1S044987623
}
"positions":
array
Required | An array of DispatchPosition objects. List of dispatch positions. Note: The attribute orderPositionNumber must be unique per dispatch message.
[
DispatchPosition: List of dispatch positions. Note: The attribute `orderPositionNumber` must be unique per dispatch message.
{
- "orderPositionNumber":
  integer
  The relative number of the order position within the order. Numbering starts with 1. | Format: int32 | Example: 1
- "dispatchedQuantity":
  integer
  Required | Number of shipped products. | Format: int32 | Example: 1
- "product":
  object
  Required | A Product object. The product to return.
  {
  "name":
  string
  Required | The name of the product. | Example: Demo-Product
  "number":
  string
  Required | @Deprecated and will be removed mit next major version. You may additionally set shopProductNumber or supplierProductNumber which will be used privileged! - The product number as used by the supplier or shop. Note: It's used to determine the corresponding order position. | Min Length: 1 | Max Length: 2147483647 | Example: 47119910
  "shopProductNumber":
  string
  The product number as used by the shop. Note: It's used to determine the corresponding order position. | Example: so-7119910
  "supplierProductNumber":
  string
  The product number as used by the supplier. Note: It's used to determine the corresponding order position. | Example: su-47119910
  }
- "items":
  array
  An array of DispatchItem objects. There are further information for each single product. Note: The number of items will be count as dispatched quantity.
  [
  DispatchItem: There are further information for each single product. Note: The number of items will be count as dispatched quantity.
  {
  "serialNumber":
  string
  Required | Serial number of the dispatched product. | Example: 667002
  "propertyGroups":
  array
  An array of PropertyGroup objects. Properties of the dispatch item, grouped by a name.
  [
  PropertyGroup: Properties of the return, grouped by a name.
  {
  "name":
  string
  Required | The name of the property group. | Min Length: 1 | Max Length: 250 | Example: DEMO-Group
  "properties":
  array
  Required | An array of Property objects. The list of properties.
  [
  Property: The list of properties.
  {
  "key":
  string
  Required | The key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
  "value":
  string
  Required | The value of the property. | Min Length: 1 | Max Length: 1000 | Example: value
  }
  ]
  }
  ]
  }
  ]
- "propertyGroups":
  array
  An array of PropertyGroup objects. Properties of the order response position, grouped by a name.
  [
  PropertyGroup: Properties of the return, grouped by a name.
  {
  "name":
  string
  Required | The name of the property group. | Min Length: 1 | Max Length: 250 | Example: DEMO-Group
  "properties":
  array
  Required | An array of Property objects. The list of properties.
  [
  Property: The list of properties.
  {
  "key":
  string
  Required | The key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
  "value":
  string
  Required | The value of the property. | Min Length: 1 | Max Length: 1000 | Example: value
  }
  ]
  }
  ]
}
]
"propertyGroups":
array
An array of PropertyGroup objects. Properties of the dispatch, grouped by a name.
[
PropertyGroup: Properties of the return, grouped by a name.
{
- "name":
  string
  Required | The name of the property group. | Min Length: 1 | Max Length: 250 | Example: DEMO-Group
- "properties":
  array
  Required | An array of Property objects. The list of properties.
  [
  Property: The list of properties.
  {
  "key":
  string
  Required | The key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
  "value":
  string
  Required | The value of the property. | Min Length: 1 | Max Length: 1000 | Example: value
  }
  ]
}
]

}

ErrorReport application/json

{

"status":
integer
The HTTP status code applicable to this problem, expressed as a string value | Format: int32 | Example: 400
"errors":
array
An array of Error objects.
[
Error
{
- "code":
  string
  Required | Exception / Error code | Example: VALIDATION_EXCEPTION
- "message":
  string
  Required | Exception / Error message | Example: Attribute XYZ is mandatory
- "value":
  object
  Value which caused the exception / error
}
]

}

OrderResponse application/vnd.intershop.response-message.v1+json

{

"messageId":
string
Required | The unique message Id. | Example: 906090-42
"supplierName":
string
Required | The name of the supplier. | Example: Demo-Supplier
"supplierShopName":
string
Required | The name of the shop as used by the supplier. | Example: Demo-Shop
"shopOrderNumber":
string
Required | The order number as used by the shop. | Min Length: 1 | Max Length: 50 | Example: 78231.2018
"supplierOrderNumber":
string
The order number as used by the supplier. | Min Length: 0 | Max Length: 250 | Example: 398-8923#556
"entryDate":
string
Timestamp when the supplier has created the response. Note: Must conform to the ISO 8601 format. | Format: date-time | Example: 2018-12-09T15:32:32.123Z
"supplierStateCode":
string
Required | Status code of the response. Note: Must refer to an entry of the "SupplierResponseStateCodeDefDO" configuration or one of the IOM internal response state codes. | Min Length: 1 | Max Length: 50
"positions":
array
Required | An array of OrderResponsePosition objects. List of order response positions. Note: The attribute orderPositionNumber must be unique per response message.
[
OrderResponsePosition: List of order response positions. Note: The attribute `orderPositionNumber` must be unique per response message.
{
- "orderPositionNumber":
  integer
  Required | The relative number of the order position within the order. Numbering starts with 1. | Format: int32 | Example: 1
- "product":
  object
  Required | A Product object. The product to return.
  {
  "name":
  string
  Required | The name of the product. | Example: Demo-Product
  "number":
  string
  Required | @Deprecated and will be removed mit next major version. You may additionally set shopProductNumber or supplierProductNumber which will be used privileged! - The product number as used by the supplier or shop. Note: It's used to determine the corresponding order position. | Min Length: 1 | Max Length: 2147483647 | Example: 47119910
  "shopProductNumber":
  string
  The product number as used by the shop. Note: It's used to determine the corresponding order position. | Example: so-7119910
  "supplierProductNumber":
  string
  The product number as used by the supplier. Note: It's used to determine the corresponding order position. | Example: su-47119910
  }
- "quantityCanceled":
  integer
  Required | Number of canceled products. | Format: int32 | Example: 0
- "confirmedDelivery":
  object
  Required | A ConfirmedDelivery object. Confirmed delivery object.
  {
  "quantity":
  integer
  Required | Confirmed quantity to deliver. | Format: int32 | Example: 1
  "plannedDeliveryDate":
  string
  Required | Planned delivery date. Must be conform to ISO 8601 date format. | Format: date | Example: 2020-01-20T00:00:00.000Z
  }
- "backorderedDelivery":
  object
  A BackorderedDelivery object. Backordered delivery object.
  {
  "quantity":
  integer
  Required | Backordered quantity to deliver. | Format: int32 | Example: 1
  "plannedDeliveryDate":
  string
  Required | Backordered delivery date. Must be conform to ISO 8601 date format. | Format: date | Example: 2020-01-31T00:00:00.000Z
  }
- "netPurchasePrice":
  object
  A NetPurchasePrice object. Net item purchase price object.
  {
  "amount":
  number
  Required | Net item purchase price of the supplier. | Format: double | Example: 6.43
  "currency":
  string
  Required | Currency of the net amount. Must be conform to ISO 4217. | Example: EUR
  }
- "propertyGroups":
  array
  An array of PropertyGroup objects. Properties of the order response position, grouped by a name.
  [
  PropertyGroup: Properties of the return, grouped by a name.
  {
  "name":
  string
  Required | The name of the property group. | Min Length: 1 | Max Length: 250 | Example: DEMO-Group
  "properties":
  array
  Required | An array of Property objects. The list of properties.
  [
  Property: The list of properties.
  {
  "key":
  string
  Required | The key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
  "value":
  string
  Required | The value of the property. | Min Length: 1 | Max Length: 1000 | Example: value
  }
  ]
  }
  ]
}
]
"propertyGroups":
array
An array of PropertyGroup objects. Properties of the order response, grouped by a name.
[
PropertyGroup: Properties of the return, grouped by a name.
{
- "name":
  string
  Required | The name of the property group. | Min Length: 1 | Max Length: 250 | Example: DEMO-Group
- "properties":
  array
  Required | An array of Property objects. The list of properties.
  [
  Property: The list of properties.
  {
  "key":
  string
  Required | The key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
  "value":
  string
  Required | The value of the property. | Min Length: 1 | Max Length: 1000 | Example: value
  }
  ]
}
]

}

Return application/vnd.intershop.return-message.v1+json

{

"messageId":
string
Required | The unique message Id. | Example: 906090-42
"supplierName":
string
Required | The name of the supplier. | Example: Demo-Supplier
"supplierShopName":
string
Required | The name of the shop as used by the supplier. | Example: Demo-Shop
"shopOrderNumber":
string
Required | The order number as used by the shop. | Min Length: 1 | Max Length: 50 | Example: 78231.2018
"supplierOrderNumber":
string
The order number as used by the supplier. | Min Length: 0 | Max Length: 250 | Example: 398-8923#556
"reason":
string
Required | Reason of return. Note: Must refer to an entry of the "Supplier2ReturnReasonDefDO" configuration or one of the IOM internal return reasons. | Example: RET010
"entryDate":
string
Required | Date of entrance of the return at the supplier. Note: Must conform to the ISO 8601 format. | Format: date-time | Example: 2018-09-14T14:22:32.123Z
"positions":
array
Required | An array of ReturnPosition objects. List of return positions. Note: The attribute orderPositionNumber must be unique per return message.
[
ReturnPosition: List of return positions. Note: The attribute `orderPositionNumber` must be unique per return message.
{
- "orderPositionNumber":
  integer
  The relative number of the order position within the order. Numbering starts with 1. | Format: int32 | Example: 1
- "returnedQuantity":
  integer
  Required | Number of returned products. | Format: int32 | Example: 1
- "product":
  object
  Required | A Product object. The product to return.
  {
  "name":
  string
  Required | The name of the product. | Example: Demo-Product
  "number":
  string
  Required | @Deprecated and will be removed mit next major version. You may additionally set shopProductNumber or supplierProductNumber which will be used privileged! - The product number as used by the supplier or shop. Note: It's used to determine the corresponding order position. | Min Length: 1 | Max Length: 2147483647 | Example: 47119910
  "shopProductNumber":
  string
  The product number as used by the shop. Note: It's used to determine the corresponding order position. | Example: so-7119910
  "supplierProductNumber":
  string
  The product number as used by the supplier. Note: It's used to determine the corresponding order position. | Example: su-47119910
  }
- "items":
  array
  An array of ReturnItem objects. There are further information for each single article. Note that the number of articles will be the count of the listed products.
  [
  ReturnItem: There are further information for each single article. Note that the number of articles will be the count of the listed products.
  {
  "serialNumber":
  string
  Required | Serial number of the returned product | Example: 109312
  "propertyGroups":
  array
  An array of PropertyGroup objects. Properties of the return item, grouped by a name.
  [
  PropertyGroup: Properties of the return, grouped by a name.
  {
  "name":
  string
  Required | The name of the property group. | Min Length: 1 | Max Length: 250 | Example: DEMO-Group
  "properties":
  array
  Required | An array of Property objects. The list of properties.
  [
  Property: The list of properties.
  {
  "key":
  string
  Required | The key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
  "value":
  string
  Required | The value of the property. | Min Length: 1 | Max Length: 1000 | Example: value
  }
  ]
  }
  ]
  }
  ]
- "propertyGroups":
  array
  An array of PropertyGroup objects. Properties of the return position, grouped by a name.
  [
  PropertyGroup: Properties of the return, grouped by a name.
  {
  "name":
  string
  Required | The name of the property group. | Min Length: 1 | Max Length: 250 | Example: DEMO-Group
  "properties":
  array
  Required | An array of Property objects. The list of properties.
  [
  Property: The list of properties.
  {
  "key":
  string
  Required | The key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
  "value":
  string
  Required | The value of the property. | Min Length: 1 | Max Length: 1000 | Example: value
  }
  ]
  }
  ]
}
]
"propertyGroups":
array
An array of PropertyGroup objects. Properties of the return, grouped by a name.
[
PropertyGroup: Properties of the return, grouped by a name.
{
- "name":
  string
  Required | The name of the property group. | Min Length: 1 | Max Length: 250 | Example: DEMO-Group
- "properties":
  array
  Required | An array of Property objects. The list of properties.
  [
  Property: The list of properties.
  {
  "key":
  string
  Required | The key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
  "value":
  string
  Required | The value of the property. | Min Length: 1 | Max Length: 1000 | Example: value
  }
  ]
}
]

}

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.