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.