swagger: '2.0'
info:
  description: The IOM RMA REST API supports programmatic access to objects related to the Return Merchandise Authorization process.
  version: 2.9.3.0
  title: IOM RMA REST API
  contact:
    name: Intershop Communications AG
    url: 'http://intershop.com'
basePath: /rest/rma
tags:
  - name: shop
    description: 'API endpoints, that could be used by the shop.'
schemes:
  - http
  - https
paths:
  '/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/contact-persons':
    get:
      tags:
        - shop
      summary: List the return request contact persons
      description: 'Returns a list of return request contact persons for a given returnRequestId, shopName and shopOrderNumber.'
      operationId: getContactPersons
      produces:
        - application/vnd.intershop.contact-person.v1beta1+json
      parameters:
        - name: returnRequestId
          in: path
          description: The return request id of the related order
          required: true
          type: integer
          format: int64
        - name: shopOrderNumber
          in: path
          description: The order number of the shop
          required: true
          type: string
        - name: shopName
          in: path
          description: The shop name
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/ContactPerson'
        '401':
          description: Authentication information is missing or invalid
          headers:
            WWW-Authenticate:
              type: string
              description: ''
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '406':
          description: Not Acceptable
      security:
        - basicAuth: []
        - bearerAuth: []
  '/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}':
    get:
      tags:
        - shop
      summary: Get a return request
      description: 'Returns a return request for a given shopName, shopOrderNumber and returnRequestId.'
      operationId: getReturnRequest
      produces:
        - application/vnd.intershop.return-request.v1beta1+json
      parameters:
        - name: returnRequestId
          in: path
          description: The return request id of the related order
          required: true
          type: integer
          format: int64
        - name: shopOrderNumber
          in: path
          description: The order number of the shop
          required: true
          type: string
        - name: shopName
          in: path
          description: The shop name
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ReadReturnRequest'
        '401':
          description: Authentication information is missing or invalid
          headers:
            WWW-Authenticate:
              type: string
              description: ''
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '406':
          description: Not Acceptable
      security:
        - basicAuth: []
        - bearerAuth: []
  '/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/positions/{returnRequestPositionId}/items':
    get:
      tags:
        - shop
      summary: List the return request position items
      description: 'Returns a list of return request position items for a given returnRequestId, shopName and shopOrderNumber.'
      operationId: getReturnRequestItems
      produces:
        - application/vnd.intershop.return-request-item.v1beta1+json
      parameters:
        - name: returnRequestPositionId
          in: path
          description: The return request position id of the related return request
          required: true
          type: integer
          format: int64
        - name: returnRequestId
          in: path
          description: The return request id of the related order
          required: true
          type: integer
          format: int64
        - name: shopOrderNumber
          in: path
          description: The order number of the shop
          required: true
          type: string
        - name: shopName
          in: path
          description: The shop name
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/ReadReturnRequestItem'
        '401':
          description: Authentication information is missing or invalid
          headers:
            WWW-Authenticate:
              type: string
              description: ''
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '406':
          description: Not Acceptable
      security:
        - basicAuth: []
        - bearerAuth: []
  '/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/positions':
    get:
      tags:
        - shop
      summary: List the return request positions
      description: 'Returns a list of return request positions for a given returnRequestId, shopName and shopOrderNumber.'
      operationId: getReturnRequestPositions
      produces:
        - application/vnd.intershop.return-request-position.v1beta1+json
      parameters:
        - name: returnRequestId
          in: path
          description: The return request id of the related order
          required: true
          type: integer
          format: int64
        - name: shopOrderNumber
          in: path
          description: The order number of the shop
          required: true
          type: string
        - name: shopName
          in: path
          description: The shop name
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/ReadReturnRequestPosition'
        '401':
          description: Authentication information is missing or invalid
          headers:
            WWW-Authenticate:
              type: string
              description: ''
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '406':
          description: Not Acceptable
      security:
        - basicAuth: []
        - bearerAuth: []
  '/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/positions/{returnRequestPositionId}':
    get:
      tags:
        - shop
      summary: Get a return request position
      description: 'Returns a return request position for a given returnRequestId, shopName, shopOrderNumber and a returnRequestPositionId.'
      operationId: getReturnRequestPosition
      produces:
        - application/vnd.intershop.return-request-position.v1beta1+json
      parameters:
        - name: returnRequestPositionId
          in: path
          description: The return request position id of the related return request
          required: true
          type: integer
          format: int64
        - name: returnRequestId
          in: path
          description: The return request id of the related order
          required: true
          type: integer
          format: int64
        - name: shopOrderNumber
          in: path
          description: The order number of the shop
          required: true
          type: string
        - name: shopName
          in: path
          description: The shop name
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ReadReturnRequestPosition'
        '401':
          description: Authentication information is missing or invalid
          headers:
            WWW-Authenticate:
              type: string
              description: ''
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '406':
          description: Not Acceptable
      security:
        - basicAuth: []
        - bearerAuth: []
  '/shops/{shopName}/orders/{shopOrderNumber}/return-requests':
    get:
      tags:
        - shop
      summary: List the return requests
      description: Returns a list of return requests for a given shopName and shopOrderNumber.
      operationId: getReturnRequests
      produces:
        - application/vnd.intershop.return-request.v1beta1+json
      parameters:
        - name: shopOrderNumber
          in: path
          description: The order number of the shop
          required: true
          type: string
        - name: shopName
          in: path
          description: The shop name
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/ReadReturnRequest'
        '401':
          description: Authentication information is missing or invalid
          headers:
            WWW-Authenticate:
              type: string
              description: ''
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '406':
          description: Not Acceptable
      security:
        - basicAuth: []
        - bearerAuth: []
    post:
      tags:
        - shop
      summary: Create a return request
      description: Creates a new return request
      operationId: createReturnRequest
      consumes:
        - application/vnd.intershop.return-request.v1beta1+json
      parameters:
        - in: body
          name: returnRequest
          required: true
          schema:
            $ref: '#/definitions/WriteReturnRequest'
        - name: shopOrderNumber
          in: path
          description: The order number of the shop
          required: true
          type: string
        - name: shopName
          in: path
          description: The shop name
          required: true
          type: string
      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
          headers:
            WWW-Authenticate:
              type: string
              description: ''
        '403':
          description: Forbidden
        '415':
          description: Unsupported Media Type
        '500':
          description: An unexpected error occured
      security:
        - basicAuth: []
        - bearerAuth: []
  '/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/custom-attributes':
    get:
      tags:
        - shop
      summary: List the return request custom attributes
      description: 'Returns a list of return request custom attributes for a given returnRequestId, shopName and shopOrderNumber.'
      operationId: getCustomAttributes
      produces:
        - application/vnd.intershop.custom-attribute.v1beta1+json
      parameters:
        - name: returnRequestId
          in: path
          description: The return request id of the related order
          required: true
          type: integer
          format: int64
        - name: shopOrderNumber
          in: path
          description: The order number of the shop
          required: true
          type: string
        - name: shopName
          in: path
          description: The shop name
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/ReadCustomAttribute'
        '401':
          description: Authentication information is missing or invalid
          headers:
            WWW-Authenticate:
              type: string
              description: ''
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '406':
          description: Not Acceptable
      security:
        - basicAuth: []
        - bearerAuth: []
  '/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/pickup-addresses':
    get:
      tags:
        - shop
      summary: List the return request pickup addresses
      description: 'Returns a list of return request pickup addresses for a given returnRequestId, shopName and shopOrderNumber.'
      operationId: getReturnRequestPickupAddresses
      produces:
        - application/vnd.intershop.pickup-address.v1beta1+json
      parameters:
        - name: returnRequestId
          in: path
          description: The return request id of the related order
          required: true
          type: integer
          format: int64
        - name: shopOrderNumber
          in: path
          description: The order number of the shop
          required: true
          type: string
        - name: shopName
          in: path
          description: The shop name
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/ReadPickupAddress'
        '401':
          description: Authentication information is missing or invalid
          headers:
            WWW-Authenticate:
              type: string
              description: ''
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '406':
          description: Not Acceptable
      security:
        - basicAuth: []
        - bearerAuth: []
  '/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/approvals':
    post:
      tags:
        - shop
      summary: Create an approval
      description: Creates a new approval
      operationId: createApproval
      consumes:
        - application/vnd.intershop.approval.v1beta1+json
      parameters:
        - in: body
          name: approval
          required: true
          schema:
            $ref: '#/definitions/WriteApproval'
        - name: returnRequestId
          in: path
          description: The return request id of the related order
          required: true
          type: integer
          format: int64
        - name: shopOrderNumber
          in: path
          description: The order number of the shop
          required: true
          type: string
        - name: shopName
          in: path
          description: The shop name
          required: true
          type: string
      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
          headers:
            WWW-Authenticate:
              type: string
              description: ''
        '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:
  CustomAttribute:
    type: object
    required:
      - key
      - value
    properties:
      key:
        type: string
        example: Example Key
        description: The key of a custom attribute.
        minLength: 1
        maxLength: 250
      value:
        type: string
        example: Example Value
        description: The value of a custom attribute.
        minLength: 1
        maxLength: 1000
    description: Represents a custom attribute (key/value pair) of a return request from an order of a shop.
  Link:
    type: object
    properties:
      href:
        type: string
      rel:
        type: string
  ReadCustomAttribute:
    allOf:
      - $ref: '#/definitions/CustomAttribute'
      - type: object
        properties:
          links:
            type: array
            items:
              $ref: '#/definitions/Link'
          id:
            type: integer
            format: int64
            example: 10000
            description: The custom attribute identifier.
        description: Represents a custom attribute (key/value pair) of a return request from an order of a shop.
  ReadReturnRequest:
    allOf:
      - $ref: '#/definitions/ReturnRequest'
      - type: object
        properties:
          links:
            type: array
            items:
              $ref: '#/definitions/Link'
          id:
            type: integer
            format: int64
            example: 10000
            description: The return request identifier.
          creationDate:
            type: string
            format: date-time
            example: '2018-02-27T09:15:37.562+02:00'
            description: The date when the return request was created.
          shopOrderNumber:
            type: string
            example: '20180303_123'
            description: The order number as used by the shop.
          shopName:
            type: string
            example: Test Shop US DE
            description: The name of the shop.
          supplierOrderNumber:
            type: string
            example: '20180303_321'
            description: The order number as used by the supplier.
          supplierName:
            type: string
            example: Test Supplier US DE
            description: The name of the supplier.
          status:
            type: string
            example: accepted
            description: The status of the return request.
        description: Represents a return request from a shop.
  ReadReturnRequestItem:
    allOf:
      - $ref: '#/definitions/ReturnRequestItem'
      - type: object
        properties:
          links:
            type: array
            items:
              $ref: '#/definitions/Link'
          id:
            type: integer
            format: int64
            example: 10000
            description: The return request item identifier.
        description: Represents a return request item of a return request from an order of a shop.
  ReadReturnRequestPosition:
    allOf:
      - $ref: '#/definitions/ReturnRequestPosition'
      - type: object
        properties:
          links:
            type: array
            items:
              $ref: '#/definitions/Link'
          id:
            type: integer
            format: int64
            example: 10000
            description: The return request position identifier.
          productName:
            type: string
            example: test_product_1
            description: The product name as used by the shop.
          supplierProductNumber:
            type: string
            example: '20180303_123'
            description: The article number as used by the supplier.
        description: Represents a return request position of a return request from an order of a shop.
  ReturnRequest:
    type: object
    required:
      - type
    properties:
      type:
        type: string
        example: RETURN
        description: The type that specifies the return request.
        enum:
          - RETURN
          - PICKUP
      rmaNumber:
        type: string
        example: '10901095'
        description: The actual number of the return request.
        minLength: 1
        maxLength: 50
      comment:
        type: string
        example: The battery is draining quickly
        description: The comment of the return request.
        minLength: 0
        maxLength: 255
    description: Represents a return request from a shop.
  ReturnRequestItem:
    type: object
    required:
      - productSerialNumber
    properties:
      productSerialNumber:
        type: string
        example: W88401231AX
        description: The serial number of the product.
        minLength: 1
        maxLength: 70
    description: Represents a return request item of a return request from an order of a shop.
  ReturnRequestPosition:
    type: object
    required:
      - positionNumber
      - productNumber
      - quantity
      - reason
    properties:
      positionNumber:
        type: integer
        format: int32
        example: 1
        description: The posistion number as used by the shop.
      productNumber:
        type: string
        example: '20180303_123'
        description: The product number as used by the shop.
        minLength: 1
        maxLength: 50
      reason:
        type: string
        example: RET100
        description: The reason for the return.
      quantity:
        type: integer
        format: int32
        example: 1
        description: The quantity of the related product by the shop.
        minimum: 1
    description: Represents a return request position of a return request from an order of a shop.
  WriteCustomAttribute:
    allOf:
      - $ref: '#/definitions/CustomAttribute'
      - type: object
        properties: {}
        description: Represents a custom attribute (key/value pair) of a return request from an order of a shop.
  WritePickupAddress:
    type: object
    required:
      - city
      - countryCode
      - lastName
      - postCode
      - streetName
    properties:
      company:
        type: string
        example: Intershop Communication AG
        description: The name of the company of the pickup adress.
        minLength: 1
        maxLength: 100
      firstName:
        type: string
        example: John
        description: The first name related to the pickup address.
        minLength: 1
        maxLength: 50
      lastName:
        type: string
        example: Doe
        description: The last name related to the pickup address.
        minLength: 1
        maxLength: 50
      streetName:
        type: string
        example: Alexstraße
        description: The name of the street related to the pickup address.
        minLength: 1
        maxLength: 100
      houseNumber:
        type: string
        example: '28'
        description: The house number related to the pickup address.
        minLength: 1
        maxLength: 20
      postCode:
        type: string
        example: '12053'
        description: The post code related to the pickup address.
        minLength: 1
        maxLength: 25
      city:
        type: string
        example: Berlin
        description: The city name related to the pickup address.
        minLength: 1
        maxLength: 100
      countryCode:
        type: string
        example: DEU
        description: The ISO 3166-1 alpha-3 code for the country name related to the pickup address.
      district:
        type: string
        example: Berlin
        description: The district related to the pickup address.
        minLength: 1
        maxLength: 100
      additionFirstLine:
        type: string
        example: Finanz
        description: The first addition line related to the pickup address.
        minLength: 1
        maxLength: 100
      additionSecondLine:
        type: string
        example: 3.Floor
        description: The second addition line related to the pickup address.
        minLength: 1
        maxLength: 100
    description: Represents a pickup address related to the return request from an order of a shop.
  WriteReturnRequest:
    allOf:
      - $ref: '#/definitions/ReturnRequest'
      - type: object
        required:
          - positions
        properties:
          positions:
            type: array
            items:
              $ref: '#/definitions/WriteReturnRequestPosition'
            maxItems: 2147483647
            minItems: 1
          pickupAddress:
            $ref: '#/definitions/WritePickupAddress'
          customAttributes:
            type: array
            items:
              $ref: '#/definitions/WriteCustomAttribute'
        description: Represents a return request from a shop.
  WriteReturnRequestItem:
    allOf:
      - $ref: '#/definitions/ReturnRequestItem'
      - type: object
        properties: {}
        description: Represents a return request item of a return request from an order of a shop.
  WriteReturnRequestPosition:
    allOf:
      - $ref: '#/definitions/ReturnRequestPosition'
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/definitions/WriteReturnRequestItem'
        description: Represents a return request position of a return request from an order of a shop.
  ContactPerson:
    type: object
    properties:
      links:
        type: array
        items:
          $ref: '#/definitions/Link'
      id:
        type: integer
        format: int64
        example: 10000
        description: The contact person identifier.
      company:
        type: string
        example: Intershop Communication AG
        description: The name of the company of the contact person.
      firstName:
        type: string
        example: John
        description: The first name of the contact person.
      lastName:
        type: string
        example: Doe
        description: The last name of the contact person.
      phoneNumber:
        type: string
        example: 0176 12345677
        description: The phone number of the contact person.
      emailAddress:
        type: string
        example: john.doe@intershop.com
        description: The email address of the contact person.
      language:
        type: string
        example: english
        description: The preferred correspondence language to answer the contact person.
    description: Represents a contact person of the return request from an order of a shop.
  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
  PickupAddress:
    type: object
    required:
      - city
      - countryCode
      - lastName
      - postCode
      - streetName
    properties:
      company:
        type: string
        example: Intershop Communication AG
        description: The name of the company of the pickup adress.
        minLength: 1
        maxLength: 100
      firstName:
        type: string
        example: John
        description: The first name related to the pickup address.
        minLength: 1
        maxLength: 50
      lastName:
        type: string
        example: Doe
        description: The last name related to the pickup address.
        minLength: 1
        maxLength: 50
      streetName:
        type: string
        example: Alexstraße
        description: The name of the street related to the pickup address.
        minLength: 1
        maxLength: 100
      houseNumber:
        type: string
        example: '28'
        description: The house number related to the pickup address.
        minLength: 1
        maxLength: 20
      postCode:
        type: string
        example: '12053'
        description: The post code related to the pickup address.
        minLength: 1
        maxLength: 25
      city:
        type: string
        example: Berlin
        description: The city name related to the pickup address.
        minLength: 1
        maxLength: 100
      countryCode:
        type: string
        example: DEU
        description: The ISO 3166-1 alpha-3 code for the country name related to the pickup address.
      district:
        type: string
        example: Berlin
        description: The district related to the pickup address.
        minLength: 1
        maxLength: 100
      additionFirstLine:
        type: string
        example: Finanz
        description: The first addition line related to the pickup address.
        minLength: 1
        maxLength: 100
      additionSecondLine:
        type: string
        example: 3.Floor
        description: The second addition line related to the pickup address.
        minLength: 1
        maxLength: 100
    description: Represents a pickup address related to the return request from an order of a shop.
  ReadPickupAddress:
    allOf:
      - $ref: '#/definitions/PickupAddress'
      - type: object
        properties:
          links:
            type: array
            items:
              $ref: '#/definitions/Link'
          id:
            type: integer
            format: int64
            example: 10000
            description: The pickup address identifier.
        description: Represents a pickup address related to the return request from an order of a shop.
  Approval:
    type: object
    required:
      - status
    properties:
      status:
        type: string
        example: APPROVED
        description: The status of the approval.
        enum:
          - APPROVED
          - NOT_APPROVED
      comment:
        type: string
        example: The return request reasons are not convincing.
        description: The comment for the approval.
    description: Represents an approval of a return request of an order of a shop.
  WriteApproval:
    allOf:
      - $ref: '#/definitions/Approval'
      - type: object
        properties: {}
        description: Represents an approval of a return request of an order of a shop.