Reference - IOM REST API - Communication 2.11

1 Download Specification 

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

2 Authentication

2.1 Basic Authentication

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

2.2 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).

3 Authorization

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

4 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

POST
/dispatches Create a order dispatch message

Request Path

/dispatches

Description

Persist a dispatch message and triggers the processing

Request Body

Dispatch application/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
      }
      ]
    }
    ]
}

Request Parameters

--

Response

201 - Created

Response HeaderDescription
LocationThe path to the newly created resource. | Format: url

400 - Bad Request

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

401 - Unauthorized

Authentication information is missing or invalid.

403 - Forbidden

415 - Unsupported Media Type

500 - Internal Server Error

An unexpected error occured.

Response API

POST
/responses Create a order response message

Request Path

/responses

Description

Persist a order response message and triggers the processing

Request Body

OrderResponse application/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
      }
      ]
    }
    ]
}

Request Parameters

--

Response

201 - Created

Response HeaderDescription
LocationThe path to the newly created resource. | Format: url

400 - Bad Request

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

401 - Unauthorized

Authentication information is missing or invalid.

403 - Forbidden

415 - Unsupported Media Type

500 - Internal Server Error

An unexpected error occured.

Return API

POST
/returns Create a order return message

Request Path

/returns

Description

Persist a return message and triggers the processing

Request Body

Return application/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
      }
      ]
    }
    ]
}

Request Parameters

--

Response

201 - Created

Response HeaderDescription
LocationThe path to the newly created resource. | Format: url

400 - Bad Request

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

401 - Unauthorized

Authentication information is missing or invalid.

403 - Forbidden

415 - Unsupported Media Type

500 - Internal Server Error

An unexpected error occured.

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.

Customer Support
Knowledge Base
Product Resources
Support Tickets