IOM supports "basic http authentication" only. Please configure your clients to use this authentication method.
It is Important that the permission REST_CREATE_RETURN ANNOUNCEMENT (oms.RightDefDO
with ID = 131 and name " Return Announcement REST service ") is assigned to the requesting user. The user also needs this permission for the requested shop and supplier, specified by the request parameters shop_name and supplier_name. The permission is a part of the class bakery.persistence.dataobject.configuration.common.RightDefDO
.
Request data format | application/json |
---|---|
Request data example type = return | { "rma_number": "Example9201290", "shop_order_number": "Example2003", "supplier_order_number": "Example983498342", "shop_name": "Test Shop", "supplier_name": "Test Supplier", "type": "return", "contact_person": { "first_name": "Conni", "last_name": "Contact", "email": "example@ex.com", "phone": "030-13939212", "preferred_correspondence_language": "en" }, "items": [ { "shop_product_number": "4004557", "return_reason": "RET040", "shop_product_name": "Example product 4004557" }, { "shop_product_number": "4004556", "return_reason": "RET100", "shop_product_name": "Example product 4004556", "serial_number": "8683237312" } ], "property_groups": [ { "name": "DEMO-group", "properties": [ { "key": "key", "value": "value" } ] } ] } |
Request data example type = pickup | { "rma_number": "Example9201290", "shop_order_number": "Example2003", "supplier_order_number": "Example983498342", "shop_name": "Test Shop", "supplier_name": "Test Supplier", "type": "return", "contact_person": { "first_name": "Conni", "last_name": "Contact", "email": "example@ex.com", "phone": "030-13939212", "preferred_correspondence_language": "en" }, "items": [ { "shop_product_number": "4004557", "return_reason": "RET040", "shop_product_name": "Example product 4004557" }, { "shop_product_number": "4004556", "return_reason": "RET100", "shop_product_name": "Example product 4004556", "serial_number": "8683237312" } ], "property_groups": [ { "name": "DEMO-group", "properties": [ { "key": "key", "value": "value" } ] } ], "pickup_address": { "first_name": "Claus", "last_name": "Return", "street": "Example Str.", "street_no": "12a", "city": "Bonn", "zip_code": "50935", "district": "Mitte", "country": "DEU" } } |
Response data format | application/json |
Response data example | No payload in case of a successful service call |
Element | Parent Element | Type | Nullable | Size | Description | |||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
rma_number | string | false | 50 | Return Merchandise Authorization / Return Material Authorization number | ||||||||
shop_order_number | string | false | 50 | Order number from shop | ||||||||
supplier_order_number | string | true | 50 | Order number at the supplier | ||||||||
shop_name | string | false | 50 | Name of the shop - defined during set up the IOM shop. Reference to oms."ShopDO" column "shopName". | ||||||||
supplier_name | string | false | 50 | Name of the supplier - defined during set up the IOM shop to supplier relationship. | ||||||||
type | string enum | false | Type of return announcement - possible values:
| |||||||||
contact_person | object | false | 1 | Contact person / person in charge | ||||||||
company | contact_person | string | true | 100 | Contact person / person in charge is acting for this company | |||||||
first_name | contact_person | string | true | 50 | First name of the contact person / person in charge | |||||||
last_name | contact_person | string | false | 50 | Last name of the contact person / person in charge | |||||||
phone | contact_person | string | true | 25 | Phone number of contact person / person in charge | |||||||
email | contact_person | string | false | 100 | Email address of contact person / person in charge | |||||||
preferred_correspondence_language | contact_person | string | true | fix = 2 | Language the customer should be notified in (ISO-639-1 format) | |||||||
items | array | false | 1..n | Array of products / items to be returned | ||||||||
shop_product_number | items | string | false | 50 | Product number from shop system | |||||||
shop_product_name | items | string | false | 255 | Product name from shop system | |||||||
serial_number | items | string | true | 70 | Serial number of the product to return | |||||||
return_reason | items | string | false | 50 | Return reason - reference to "Shop2ReturnReasonDefDO" column "shopReturnReasonName". | |||||||
pickup_address | object | true | 0..1 | Address for picking up the items to return - only necessary if type = pickup | ||||||||
company | pickup_address | string | true | 100 | Company name where the return is to be picked up | |||||||
first_name | pickup_address | string | true | 50 | First name of the person where the return is to be picked up | |||||||
last_name | pickup_address | string | false | 50 | Last name of the person where the return is to be picked up | |||||||
street | pickup_address | string | false | 100 | Street name where the return is to be picked up - without street number | |||||||
street_no | pickup_address | string | true | 20 | Street number where the return is to be picked up | |||||||
city | pickup_address | string | false | 100 | City where the return is to be picked up | |||||||
zip_code | pickup_address | string | false | 25 | Post code / ZIP code where the return is to be picked up | |||||||
district | pickup_address | string | true | 100 | District where the return is to be picked up | |||||||
country | pickup_address | string | false | fix = 3 | Country where the return is to be picked up (ISO 3166-1 alpha-3 code) | |||||||
addition_one | pickup_address | string | true | 100 | Addition one to address where the return is to be picked up | |||||||
addition_two | pickup_address | string | true | 100 | Addition two to address where the return is to be picked up | |||||||
Note The following extensions are valid since version 2.6 | ||||||||||||
property_groups | array | true | 1..n | Array of return announcement properties | ||||||||
name | property_groups | string | false | 250 | The name that represents a property group | |||||||
properties | property_groups | array | false | 0..n | Data transfer object (DTO) that represents a property (key/value pair) | |||||||
key | properties | string | false | 250 | A unique identifier for the property data | |||||||
value | properties | string | false | 1000 | The data that is identified |
Example - Internal Server Error caused by "Could not find resource" |
---|
{ |
Response Body |
Example - Missing Authorization header parameter |
{ |
Example - User authorized but missing permission for service |
---|
{ "data": null, "statusCode": 401, "errors": null, "exceptions": [ { "code": "401", "message": "User 'XYZ' is not authorized to use this service. Missing right with id: 131 (Return Announcement REST service)" } ] } |
Example - User authorized for service but not for the related shop (request element shop_name ) |
{ "data": null, "statusCode": 401, "errors": null, "exceptions": [ { "code": "401", "message": "User 'XYZ' is not authorized to use this service for shop 'Example Shop'" } ] } |
Example - User authorized for service but not for the related supplier (request element supplier_name ) |
{ "data": null, "statusCode": 401, "errors": null, "exceptions": [ { "code": "401", "message": "User 'XYZ' is not authorized to use this service for supplier 'Example-Supplier'" } ] } |
Response Body |
Example - Bad request caused by unknown shop |
---|
{ "data": null, "statusCode": 400, "errors": null, "exceptions": [ { "code": "Unknown_Shop", "message": "Unknown shop 'Test Shop X'" } ] } |
Example - Bad request caused by unknown supplier |
{ "data": null, "statusCode": 400, "errors": null, "exceptions": [ { "code": "Unknown_Supplier", "message": "Unknown supplier 'Test Supplier X'" } ] } |
Example - Bad request caused by unknown order |
{ "data": null, "statusCode": 400, "errors": null, "exceptions": [ { "code": "Unknown_Order", "message": "Could not find order with shop order number 'Example2003' for shop 'Test Shop'." } ] } |
Example - Bad request caused by unknown product |
{ "data": null, "statusCode": 400, "errors": null, "exceptions": [ { "code": "Unknown_Product", "message": "The product to return 'SKU-XYZ' is not part of the order 'Example-Order'." } ] } |
Example - Bad request caused by product not returnable |
{ "data": null, "statusCode": 400, "errors": null, "exceptions": [ { "code": "Product_Not_Returnable", "message": "The product to return 'SKU-XYZ' is not returnable - product not shipped or already returned." } ] } |
Example - Bad request caused by more products to return as currently shipped |
{ "data": null, "statusCode": 400, "errors": null, "exceptions": [ { "code": "Too_Much_Products", "message": "More products 'SKU-XYZ' to return requested as currently shipped." } ] } |
Example - Bad request caused by unknown language code |
{ "data": null, "statusCode": 400, "errors": null, "exceptions": [ { "code": "Unknown_Language_Code", "message": "Unknown language code 'XX' at correspondence language." } ] } |
Example - Bad request caused by unknown return reason |
{ "data": null, "statusCode": 400, "errors": null, "exceptions": [ { "code": "Unknown_Return_Reason", "message": "Unknown return reason 'RET101'." } ] } |
Example - Bad request caused by missing "pickup_address" in case of a return announcement with type "pickup" |
{ "data": null, "statusCode": 400, "errors": null, "exceptions": [ { "code": "Missing_Pickup_Address", "message": "Missing pickup address because type is 'PICKUP'." } ] } |
Example - Bad request caused by unknown country code |
{ "data": null, "statusCode": 400, "errors": null, "exceptions": [ { "code": "Unknown_Country_Code", "message": "Unknown country code 'XYZ' at pickup address." } ] } |
Example - Bad request caused by missing required fields |
{ "data": null, "statusCode": 400, "errors": [ { "sourceField": "items[0].shopProductName", "message": "Invalid value 'null' in field 'items[0].shopProductName' - shop_product_name is required" }, { "sourceField": "items[0].returnReason", "message": "Invalid value 'null' in field 'items[0].returnReason' - return_reason is required" } ], "exceptions": null } |
Note Since version 2.6 Example - Bad request caused by ambiguous/ property key |
{ "data": null, "statusCode": 400, "errors": null, "exceptions":[ { "code": "Duplicate_Property_Key", "message": "Property key 'key' at property group 'DEMO-group' is ambiguous." } ] } |
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.