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