IOM REST API - Return Announcement Service

Personal Library

https://support.intershop.com/kb/2Q7784

URI	servlets/services/rma
Http Method	POST
Short Description	Create a return announcement for one or more shipped products from an order.
Query Parameters	no
HTTP Status Codes	201 Created 400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error
Description	Create Return Announcement - API To create return announcements the IOM provides a REST web service / REST API. The IOM enables shop system to create return announcements via HTTP POST requests with a corresponding JSON payload This service only supports and accepts requests with content-type application/json. A return announcement is always addressed to a single supplier. In a multi-supplier retailer business case, it may be required to send multiple return announcements for multiple-supplier orders.

Product Version	1.1
Product To Version
Status	New Labels

Authorization

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.

JSON

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

Details on Request Data Format

Element

Parent Element

Type

Nullable

Size

Description

rma_number

string

false

Return Merchandise Authorization / Return Material Authorization number

shop_order_number

string

false

Order number from shop

supplier_order_number

string

true

Order number at the supplier

shop_name

string

false

Name of the shop - defined during set up the IOM shop.
Reference to oms."ShopDO" column "shopName".

supplier_name

string

false

Name of the supplier - defined during set up the IOM shop to supplier relationship.
References to oms."Shop2SupplierDO" column "shopSupplierName".

type

string
enum

false

Type of return announcement - possible values:

value	description
return	return by customer
pickup	supplier pick ups the return

contact_person

object

false

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

First name of the contact person / person in charge

last_name

contact_person

string

false

Last name of the contact person / person in charge

phone

contact_person

string

true

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

Product number from shop system

shop_product_name

items

string

false

255

Product name from shop system

serial_number

items

string

true

Serial number of the product to return

return_reason

items

string

false

Return reason - reference to "Shop2ReturnReasonDefDO" column "shopReturnReasonName".
In case of no match the lookup take place at the IOM internal return reasons "ReturnReasonDefDO" column "name"

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

 First name of the person where the return is to be picked up 

last_name

pickup_address

string

false

 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

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

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

Details on Response Data Format - only if a request failed

Response Header Status Code : 500 Internal Server Error

Example - Internal Server Error caused by "Could not find resource"
{ "data": null, "statusCode": 500, "errors": null, "exceptions": [ { "code": "500", "message": "Could not find resource for full path: XYZ" } ] }

Response Header Status Code : 401 Unauthorized

Example - User authorized but missing permission for service
Response Body
Example - Missing `Authorization` header parameter
{ "data": null, "statusCode": 401, "errors": [], "exceptions": [] }
{ "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 Header Status Code : 400 Bad Request

Example - Bad request caused by unknown shop
Response Body
{ "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." } ] }

Disclaimer

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.