Reference - IOM REST API - Communication 2.9.4.0


Product Version

2.9.4.0

Product To Version


Status

final

Download Specification 

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

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 REST Communication API Version: 2.9.4.0

The IOM REST Communication 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 | Unique message ID | Example: 906090-42
  • "supplierName":
    string
    Required | Name of the supplier | Example: Demo-Supplier
  • "supplierShopName":
    string
    Required | Shop named by the supplier | Example: Demo-Shop
  • "shopOrderNumber":
    string
    Required | Order number as used by the shop | Min Length: 1 | Max Length: 50 | Example: 78231.2018
  • "supplierOrderNumber":
    string
    Order number as used by the supplier | Min Length: 0 | Max Length: 250 | Example: DE398-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
  • "deliveryNoteNumber":
    string
    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
      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 | Name of the product | Example: Demo-Product
      • "number":
        string
        Required | Product number (id / SKU) 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
      }
    • "items":
      array
      An array of DispatchItem objects. There are further information for each single article. Note: The number of items will be count as dispatched quantity
      [
      DispatchItem: There are further information for each single article. 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 | 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 | Key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
          • "value":
            string
            Required | 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 | 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 | Key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
        • "value":
          string
          Required | 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 | 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 | Key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
      • "value":
        string
        Required | 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 | Unique message ID | Example: 906090-42
  • "supplierName":
    string
    Required | Name of the supplier | Example: Demo-Supplier
  • "supplierShopName":
    string
    Required | Shop named by the supplier | Example: Demo-Shop
  • "shopOrderNumber":
    string
    Required | Order number as used by the shop | Min Length: 1 | Max Length: 50 | Example: 78231.2018
  • "supplierOrderNumber":
    string
    Order number as used by the supplier | Min Length: 0 | Max Length: 250 | Example: DE398-8923#556
  • "entryDate":
    string
    Timestamp when the supplier has created the response. Note: Must conform to the ISO 8601 format. | Format: date-time
  • "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 | 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 | Name of the product | Example: Demo-Product
      • "number":
        string
        Required | Product number (id / SKU) 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
      }
    • "quantityCanceled":
      integer
      Required | Number of canceled products | Format: int32 | Example: 0
    • "confirmedDelivery":
      object
      Required | A ConfirmedDelivery object. Confirmed delivery object
      {
      • "quantity":
        integer
        Required | Confirmed delivery quantity | Format: int32 | Example: 1
      • "plannedDeliveryDate":
        string
        Required | Planned delivery date. Note: Must conform to the ISO 8601 format and it must use the UTC. | Format: date
      }
    • "netPurchasePrice":
      object
      A NetPurchasePrice object. Net item purchase price object
      {
      • "amount":
        number
        Required | Net item purchase price of supplier | Format: double | Example: 6.43
      • "currency":
        string
        Required | Currency of the net amount. MUST conform to the ISO 4217 e.g.: EUR for Euro | 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 | 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 | Key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
        • "value":
          string
          Required | 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 | 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 | Key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
      • "value":
        string
        Required | 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 | Unique message ID | Example: 906090-42
  • "supplierName":
    string
    Required | Name of the supplier | Example: Demo-Supplier
  • "supplierShopName":
    string
    Required | Shop named by the supplier | Example: Demo-Shop
  • "shopOrderNumber":
    string
    Required | Order number as used by the shop | Min Length: 1 | Max Length: 50 | Example: 78231.2018
  • "supplierOrderNumber":
    string
    Order number as used by the supplier | Min Length: 0 | Max Length: 250 | Example: DE398-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
  • "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
      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 | Name of the product | Example: Demo-Product
      • "number":
        string
        Required | Product number (id / SKU) 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
      }
    • "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 articles
      [
      ReturnItem: There are further information for each single article. Note that the number of articles will be the count of the listed articles
      {
      • "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 | 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 | Key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
          • "value":
            string
            Required | 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 | 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 | Key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
        • "value":
          string
          Required | 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 | 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 | Key of the property. The keys at a property group must be unique. | Min Length: 1 | Max Length: 250 | Example: key
      • "value":
        string
        Required | 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