swagger: '2.0'
info:
  description: 'The IOM REST Communication API supports dispatch, order response and return message transmission to the IOM.'
  version: 2.9.0.0
  title: IOM REST Communication API
  contact:
    name: Intershop Communications AG
    url: 'http://intershop.com'
basePath: /rest/communication
tags:
  - name: Dispatch
  - name: Response
  - name: Return
schemes:
  - http
  - https
paths:
  /dispatches:
    post:
      tags:
        - Dispatch
      summary: Create a order dispatch message
      description: Persist a dispatch message and triggers the processing
      operationId: createDispatch
      consumes:
        - application/vnd.intershop.dispatch-message.v1beta1+json
      parameters:
        - in: body
          name: dispatch
          required: true
          schema:
            $ref: '#/definitions/Dispatch'
      responses:
        '201':
          description: Created
          headers:
            Location:
              type: string
              format: url
              description: The path to the newly created resource
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorReport'
        '401':
          description: Authentication information is missing or invalid
        '403':
          description: Forbidden
        '415':
          description: Unsupported Media Type
        '500':
          description: An unexpected error occured
      security:
        - basicAuth: []
        - bearerAuth: []
  /responses:
    post:
      tags:
        - Response
      summary: Create a order response message
      description: Persist a order response message and triggers the processing
      operationId: createOrderResponse
      consumes:
        - application/vnd.intershop.response-message.v1alpha1+json
      parameters:
        - in: body
          name: orderResponse
          required: true
          schema:
            $ref: '#/definitions/OrderResponse'
      responses:
        '201':
          description: Created
          headers:
            Location:
              type: string
              format: url
              description: The path to the newly created resource
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorReport'
        '401':
          description: Authentication information is missing or invalid
        '403':
          description: Forbidden
        '415':
          description: Unsupported Media Type
        '500':
          description: An unexpected error occured
      security:
        - basicAuth: []
        - bearerAuth: []
  /returns:
    post:
      tags:
        - Return
      summary: Create a order return message
      description: Persist a return message and triggers the processing
      operationId: createReturn
      consumes:
        - application/vnd.intershop.return-message.v1alpha1+json
      parameters:
        - in: body
          name: orderReturn
          required: true
          schema:
            $ref: '#/definitions/Return'
      responses:
        '201':
          description: Created
          headers:
            Location:
              type: string
              format: url
              description: The path to the newly created resource
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorReport'
        '401':
          description: Authentication information is missing or invalid
        '403':
          description: Forbidden
        '415':
          description: Unsupported Media Type
        '500':
          description: An unexpected error occured
      security:
        - basicAuth: []
        - bearerAuth: []
securityDefinitions:
  bearerAuth:
    description: JWT Bearer token
    type: apiKey
    name: Authorization
    in: header
  basicAuth:
    description: Basic Authentication
    type: basic
definitions:
  Error:
    type: object
    required:
      - code
      - message
    properties:
      code:
        type: string
        example: VALIDATION_EXCEPTION
        description: Exception / Error code
      message:
        type: string
        example: Attribute XYZ is mandatory
        description: Exception / Error message
      value:
        type: object
        description: Value which caused the exception / error
  ErrorReport:
    type: object
    properties:
      status:
        type: integer
        format: int32
        example: 400
        description: 'The HTTP status code applicable to this problem, expressed as a string value'
      errors:
        type: array
        items:
          $ref: '#/definitions/Error'
    description: Detailed information about what went wrong
  Carrier:
    type: object
    required:
      - name
      - packages
    properties:
      name:
        type: string
        example: DHL
        description: Name of the carrier as used by the supplier. Possible values must be configured via Supplier2CarrierDO
      packages:
        type: integer
        format: int32
        example: 1
        description: 'Number of packages. Note: Packages with different tracking numbers should be handled by separate dispatch messages'
        minimum: 1
      trackingNumber:
        type: string
        example: A1S044987623
        description: The tracking number of the delivered package
    description: Information about the carrier and the shipment
  Dispatch:
    type: object
    required:
      - carrier
      - dispatchDate
      - messageId
      - positions
      - shopOrderNumber
      - supplierName
      - supplierShopName
    properties:
      messageId:
        type: string
        description: Unique message ID
      supplierName:
        type: string
        description: Name of the supplier
      supplierShopName:
        type: string
        description: Shop named by the supplier
      shopOrderNumber:
        type: string
        description: Order number as used by the shop
        minLength: 1
        maxLength: 50
      supplierOrderNumber:
        type: string
        description: Order number as used by the supplier
        minLength: 0
        maxLength: 250
      dispatchDate:
        type: string
        format: date
        example: '2018-05-10T16:52:26.467+02:00'
        description: Date of the hand over of the package to the carrier
      deliveryNoteNumber:
        type: string
        description: Delivery note number
        minLength: 0
        maxLength: 70
      carrier:
        $ref: '#/definitions/Carrier'
      positions:
        type: array
        description: List of dispatch positions
        items:
          $ref: '#/definitions/DispatchPosition'
        maxItems: 2147483647
        minItems: 1
      propertyGroups:
        type: array
        description: 'Properties of the dispatch, grouped by a name'
        items:
          $ref: '#/definitions/PropertyGroup'
  DispatchItem:
    type: object
    required:
      - serialNumber
    properties:
      serialNumber:
        type: string
        description: Serial number of the dispatched product
      propertyGroups:
        type: array
        description: 'Properties of the dispatch item, grouped by a name'
        items:
          $ref: '#/definitions/PropertyGroup'
  DispatchPosition:
    type: object
    required:
      - dispatchedQuantity
      - product
    properties:
      dispatchedQuantity:
        type: integer
        format: int32
        example: 1
        description: Number of shipped products
        minimum: 1
      product:
        $ref: '#/definitions/Product'
      items:
        type: array
        description: There are further information for each single article.
        items:
          $ref: '#/definitions/DispatchItem'
      propertyGroups:
        type: array
        description: 'Properties of the order response position, grouped by a name'
        items:
          $ref: '#/definitions/PropertyGroup'
  Product:
    type: object
    required:
      - name
      - number
    properties:
      name:
        type: string
        description: Name of the product
      number:
        type: string
        description: Product number (id / SKU) as used by the supplier or shop.
        minLength: 1
        maxLength: 50
  Property:
    type: object
    required:
      - key
      - value
    properties:
      key:
        type: string
        example: key
        description: Key of the property. The keys at a property group must be unique.
        minLength: 1
        maxLength: 250
      value:
        type: string
        example: value
        description: Value of the property
        minLength: 1
        maxLength: 1000
  PropertyGroup:
    type: object
    required:
      - name
      - properties
    properties:
      name:
        type: string
        example: DEMO-group
        description: Name of the property group
        minLength: 1
        maxLength: 250
      properties:
        type: array
        description: The list of properties
        items:
          $ref: '#/definitions/Property'
        maxItems: 2147483647
        minItems: 1
  ConfirmedDelivery:
    type: object
    required:
      - plannedDeliveryDate
      - quantity
    properties:
      quantity:
        type: integer
        format: int32
        example: 1
        description: Confirmed delivery quantity
      plannedDeliveryDate:
        type: string
        format: date
        example: '2018-07-11T23:52:26.467+06:00'
        description: Planned delivery date
  NetPurchasePrice:
    type: object
    required:
      - amount
      - currency
    properties:
      amount:
        type: number
        format: double
        example: amount
        description: Net purchase price of supplier
      currency:
        type: string
        example: currency
        description: 'TODO: Currency of the net amount'
        minLength: 2
        maxLength: 3
  OrderResponse:
    type: object
    required:
      - messageId
      - positions
      - shopOrderNumber
      - stateCode
      - supplierName
      - supplierShopName
    properties:
      messageId:
        type: string
        description: Unique message ID
      supplierName:
        type: string
        description: Name of the supplier
      supplierShopName:
        type: string
        description: Shop named by the supplier
      shopOrderNumber:
        type: string
        description: Order number as used by the shop
        minLength: 1
        maxLength: 50
      supplierOrderNumber:
        type: string
        description: Order number as used by the supplier
        minLength: 0
        maxLength: 250
      stateCode:
        type: string
        description: 'Status code of the response. Note: Must refer to the  "SupplierResponseStateCodeDefDO" configuration or one of the IOM internal response status codes.'
        minLength: 0
        maxLength: 50
      positions:
        type: array
        description: List of order response positions
        items:
          $ref: '#/definitions/OrderResponsePosition'
      propertyGroups:
        type: array
        description: 'Properties of the order response, grouped by a name'
        items:
          $ref: '#/definitions/PropertyGroup'
  OrderResponsePosition:
    type: object
    required:
      - canceledQuantity
      - dispatchedQuantity
      - number
      - orderedQuantity
      - product
    properties:
      number:
        type: integer
        format: int32
        example: 1
        description: Referenced order position number. Was transmitted to the supplier with the order
        minimum: 1
      product:
        $ref: '#/definitions/Product'
      orderedQuantity:
        type: integer
        format: int32
        example: 2
        description: Number of ordered products
        minimum: 1
      dispatchedQuantity:
        type: integer
        format: int32
        example: 1
        description: Number of already shipped products
      canceledQuantity:
        type: integer
        format: int32
        example: 0
        description: Number of already canceled products
      confirmedDelivery:
        $ref: '#/definitions/ConfirmedDelivery'
      netPurchasePrice:
        $ref: '#/definitions/NetPurchasePrice'
      propertyGroups:
        type: array
        description: 'Properties of the dispatch position, grouped by a name'
        items:
          $ref: '#/definitions/PropertyGroup'
  Return:
    type: object
    required:
      - entryDate
      - messageId
      - positions
      - reason
      - shopOrderNumber
      - supplierName
      - supplierShopName
    properties:
      messageId:
        type: string
        description: Unique message ID
      supplierName:
        type: string
        description: Name of the supplier
      supplierShopName:
        type: string
        description: Shop named by the supplier
      entryDate:
        type: string
        format: date
        example: '2018-05-14T16:22:32.123+02:00'
        description: Date of creation of the return at the supplier
      carrier:
        $ref: '#/definitions/Carrier'
      positions:
        type: array
        description: List of return positions
        items:
          $ref: '#/definitions/ReturnPosition'
      shopOrderNumber:
        type: string
        description: Order number as used by the shop
        minLength: 1
        maxLength: 50
      supplierOrderNumber:
        type: string
        description: Order number as used by the supplier
        minLength: 0
        maxLength: 250
      reason:
        type: string
        example: RET010
        description: 'Reason of return. Must match with an entry at Supplier2ReturnReasonDefDO, or be one of the IOM default ReturnReasonDefDOs'
      propertyGroups:
        type: array
        description: 'Properties of the return, grouped by a name'
        items:
          $ref: '#/definitions/PropertyGroup'
  ReturnItem:
    type: object
    required:
      - payment
      - serialNumber
    properties:
      serialNumber:
        type: string
        description: Serial number of the returned product
      reason:
        type: string
        example: RET055
        description: To overwrite the reason of return on position level
      payment:
        $ref: '#/definitions/ReturnPayment'
      propertyGroups:
        type: array
        description: 'Properties of the return item, grouped by a name'
        items:
          $ref: '#/definitions/PropertyGroup'
  ReturnPayment:
    type: object
    required:
      - reductionId
    properties:
      reductionId:
        type: string
        description: Reason of reduction
      returnReductionNetAmount:
        $ref: '#/definitions/ReturnReductionNetAmount'
  ReturnPosition:
    type: object
    required:
      - number
      - payment
      - product
      - returnedQuantity
    properties:
      number:
        type: integer
        format: int32
        example: 1
        description: Return position number
        minimum: 1
      returnedQuantity:
        type: integer
        format: int32
        example: 1
        description: Number of returned products
        minimum: 1
      reason:
        type: string
        example: RET170
        description: To specify the reason of return per position
      product:
        $ref: '#/definitions/Product'
      payment:
        $ref: '#/definitions/ReturnPayment'
      items:
        type: array
        description: There are further information for each single article. Note that the number of articles will be the count of the listed articles
        items:
          $ref: '#/definitions/ReturnItem'
      propertyGroups:
        type: array
        description: 'Properties of the return position, grouped by a name'
        items:
          $ref: '#/definitions/PropertyGroup'
  ReturnReductionNetAmount:
    type: object
    required:
      - type
      - value
    properties:
      value:
        type: number
        format: double
        example: 6.99
        description: Amount value related to type
      type:
        type: string
        description: Type of return payment (net)
        enum:
          - REFUND
          - REDUCE