Document Properties
Kbid
2Q7784
Last Modified
31-May-2022
Added to KB
20-Jul-2016
Public Access
Everyone
Status
Online
Doc Type
References
Product
  • IOM 2.0
  • IOM 2.1
  • IOM 2.2
  • IOM 2.9
  • IOM 2.16
  • IOM 2.17
  • IOM 3.0
  • IOM 3.1
  • IOM 3.2
  • IOM 3.3
  • IOM 3.4
  • IOM 3.5
  • IOM 3.6
  • IOM 3.7
  • IOM 4.0

IOM REST API - Return Announcement Service


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

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

ElementParent ElementTypeNullableSizeDescription
rma_number
 stringfalse50Return Merchandise Authorization / Return Material Authorization number
shop_order_number
 stringfalse50Order number from shop
supplier_order_number
 stringtrue50Order number at the supplier
shop_name
 stringfalse50Name of the shop - defined during set up the IOM shop.
Reference to oms."ShopDO" column "shopName".
supplier_name
 stringfalse50

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:

valuedescription
returnreturn by customer
pickupsupplier pick ups the return
contact_person
 

object

false1Contact person / person in charge
company
contact_person
stringtrue100Contact person / person in charge is acting for this company
first_name
contact_person
stringtrue50First name of the contact person / person in charge
last_name
contact_person
stringfalse50Last name of the contact person / person in charge
phone
contact_person
stringtrue25Phone number of contact person / person in charge
email
contact_person
stringfalse100Email address of contact person / person in charge
preferred_correspondence_language
contact_person
stringtruefix = 2Language the customer should be notified in (ISO-639-1 format)
items
 arrayfalse1..n

Array of products / items to be returned

shop_product_number
items
stringfalse50

Product number from shop system

shop_product_name
items
stringfalse255Product name from shop system
serial_number
items
stringtrue70Serial number of the product to return
return_reason
items
stringfalse50

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
 objecttrue0..1Address for picking up the items to return - only necessary if type = pickup
company
pickup_address
stringtrue100 Company name where the return is to be picked up
first_name
pickup_address
stringtrue50 First name of the person where the return is to be picked up
last_name
pickup_address
stringfalse50 Last name of the person where the return is to be picked up
street
pickup_address
stringfalse100 Street name where the return is to be picked up - without street number
street_no
pickup_address
stringtrue20Street number where the return is to be picked up
city
pickup_address
stringfalse100City where the return is to be picked up
zip_code
pickup_address
stringfalse25Post code / ZIP code where the return is to be picked up
district
pickup_address
stringtrue100District where the return is to be picked up
country
pickup_address
stringfalsefix = 3Country where the return is to be picked up (ISO 3166-1 alpha-3 code)
addition_one
pickup_address
stringtrue100Addition one to address where the return is to be picked up
addition_two
pickup_address
string

true

100Addition two to address where the return is to be picked up

Note

The following extensions are valid since version 2.6

property_groups
arraytrue1..nArray of return announcement properties
nameproperty_groups
stringfalse250The name that represents a property group
propertiesproperty_groupsarrayfalse0..nData transfer object (DTO) that represents a property (key/value pair)

keypropertiesstringfalse250A unique identifier for the property data

valuepropertiesstringfalse1000The 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

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

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."
    }
  ]
}

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.

Customer Support
Knowledge Base
Product Resources
Tickets