(Quick Reference)
Service: Create an operation (exchange, cancellation or return)
Description: Returns the created operation in json format when successful. Returns a json response, describing the failure condition when unsuccessful.
URL:
https://BASE_URL/api/VERSION/returns
: POST
Request content type: application/x-www-form-urlencoded or multipart/form-data
Parameters:
| Name | Description | Type | Required | Example values |
|---|
| reference | | String | yes | |
| returnType | | String | yes | EXCHANGE, CANCELLATION, RETURN |
| customerId | The ID of customer | Long/String | yes | |
| dateCreated | | Date | no | 2016-09-27T11:12:00Z |
| userId | The ID of user. By default, it is set to the current connected user | Long/String | no | |
| latitude | | Double | no | |
| longitude | | Double | no | 10.590584 |
| checkInDate | | Date | no | 2016-09-15T11:30:00Z |
| useExternalId | By default, it is set to false. set it to true if you want to use external ids. | Boolean | no | true , false |
to add a geolocationData related to our return operation we must at least have one of this inputs : latitude, longitude or checkInDate
Return operation lines parameter:
Parameter name: returnLines
Parameter type: a json structure
| Name | Description | Type | Required | Example values |
|---|
| reasonId | The numerical ID of the reason to do a return operation | Long | yes | |
| itemUnitId | The numerical ID unit of items | Long | yes | |
| quantity | | Integer | Yes | |
| picture | | multipart/form-data | no | |
| comment | It contains some comments related to the operation | String | no | |
Success Output
Success case: response.status=201
{
"id": 24,
"reference": "R-R-E-00910",
"latitude": 15.3931,
"longitude": 56.123,
"checkinDate": "2016-09-15T10:30:00Z",
"type": "EXCHANGE",
"userId": 3,
"user": {
"id": 3,
"reference": "RE-002",
"href": "/api/v1.0/users/3"
},
"customerId": 1,
"customer": {
"id": 1,
"reference": "R001",
"name": "CUS1",
"href": "/api/v1.0/customers/1"
},
"returnLines": [
{
"id": 1,
"serialNumber": "serialNumber",
"quantity": 2,
"itemUnitId": 2,
"picture": null,
"href": "/api/v1.0/returnDetails/1"
}
],
"organization": "entity1",
"dateCreated": "2016-09-28T09:32:45Z"
} Failure Output
Failure case:response.status = 400
{
"error": "missing_param",
"error_description": "reference parameter is missing"
}{
"error": "save_failed",
"error_description": "Failed to save instance."
}{
"error": "not_unique",
"error_description": "reference already used"
}{
"error": "invalid_param_type",
"error_description": "An invalid value was specified for parameter: quantity (must be an Integer)"
}{
"error": "quantity_not_available",
"error_description": "Quantity should be less than or equal to the available quantity: [[quantity:16944, item:497, unit:1, itemUnit:2]]"
}{
"error": "not_in_list_error",
"error_description": "Failed to add the Return with the reference R-R-E-00919: returnType can have only these values [ EXCHANGE,CANCELLATION,RETURN ]"
} Failure case:response.status = 404
{
"error": "not_found",
"error_description": "The Customer with the id 10 doesn't exist."
}{
"error": "not_found",
"error_description": "The User with the id 1 doesn't exist."
} Failure case:response.status = 500
{
"error": "server_error",
"error_description": "Oops! Something went wrong..."
}
