(Quick Reference)
63 Return Operations - Reference Documentation
Version: 2.1
63 Return Operations
63.1 List
Service: List operations (exchange,cancellation and returns)
Description: This web service returns a json list of operations.
URL:
https://BASE_URL/api/VERSION/returns
: GET
Parameters:
Pagination parameters:
| Name | Description | Type | Required | Possible values |
|---|
| max | Limits the number of resources requested to return. | Integer | no | |
| offset | Tells where to start returning records from the entire set of results. | Integer | no | |
| order | Orders ascending or descending. | Integer | no | asc,desc |
| sort | Orders the results by the specified field. | String | no | |
The max parameter is set to 100 by default.
Filters parameters:
| Name | Description | Type | Required | Example values |
|---|
| dateCreated_gt | Filters by the resource's creation date time and operator greater than | Date | no | 2016-08-15T14:52:48Z |
| dateCreated_gte | Filters by the resource's creation date time and operator greater than or equal | Date | no | |
| dateCreated_lt | Filters by the resource's creation date time and operator less than | Date | no | |
| dateCreated_lte | Filters by the resource's creation date time and operator less than or equal | Date | no | |
| lastUpdated_gt | Filters by the resource's last-modified date time and operator greater than | Date | no | |
| lastUpdated_gte | Filters by the resource's last-modified date time and operator greater than or equal | Date | no | |
| lastUpdated_lt | Filters by the resource's last-modified date time and operator less than | Date | no | |
| lastUpdated_lte | Filters by the resource's last-modified date time and operator less than or equal | Date | no | |
| returnType | Search by the operation type | String | no | EXCHANGE, CANCELLATION, RETURN |
| refrence | Wildcard search by the resource's reference | String | no | |
Dates should be formatted as the ISO-8601 format (YYYY-MM-DDTHH:MM:SSZ)
Success Output
Success case: response.status=200
{
"paging": {
"total": 3,
"max": 100,
"offset": 0,
"previous": null,
"next": null
},
"data": [
{
"id": 24,
"reference": "R-R-E-00910",
"latitude": 35.835454,
"longitude": 10.590584,
"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": "serial_number",
"quantity": 2,
"itemUnitId": 2,
"picture": null,
"href": "/api/v1.0/returnDetails/1"
}
],
"organization": "entity1",
"dateCreated": "2016-09-28T09:32:45Z",
"lastUpdated": "2016-09-28T09:32:45Z"
},
{
"id": 25,
"reference": "R-R-E-111",
"latitude": 36.81328,
"longitude": 10.1331903,
"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": 2,
"serialNumber": null,
"quantity": 2,
"itemUnitId": 2,
"picture": null,
"href": "/api/v1.0/returnDetails/2"
}
],
"organization": "entity1",
"dateCreated": "2016-09-28T10:20:11Z",
"lastUpdated": "2016-09-28T10:20:12Z"
},
{
"id": 26,
"reference": "R-R-E-112",
"latitude": 43.7111496,
"longitude": 7.1947483,
"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": 3,
"serialNumber": "serial_number",
"quantity": 2,
"itemUnitId": 2,
"picture": null,
"href": "/api/v1.0/returnDetails/3"
}
],
"organization": "entity1",
"dateCreated": "2016-09-28T10:20:35Z",
"lastUpdated": "2016-09-28T10:20:35Z"
}
]
} Failure Output
Failure case:response.status = 400
{
"error": "invalid_param",
"error_description": "The parameters [dateCreated_gta] you provided are not valid for this request."
}{
"error": "invalid_datetime_format",
"error_description": "Invalid datetime filter (not ISO-8601 formatted): [2016-08-1Z]"
} Failure case:response.status = 500
{
"error": "server_error",
"error_description": "Oops! Something went wrong..."
}63.2 Show
Service: Show an operation (exchange, cancellation or return)
Description: Returns the requested operation in json format when successful. Returns a json response, describing the failure condition when unsuccessful.
URL:
https://BASE_URL/api/VERSION/returns/{id}:
https://BASE_URL/api/VERSION/returns/reference/{id}: GET
Parameters:
| Name | Description | Type | Required | Example values |
|---|
| id | The ID of the desired operation | Long/String | yes | 123 |
Success Output
Success case: response.status=200
{
"id": 5,
"reference": "R-E-005",
"latitude": null,
"longitude": null,
"checkinDate": null,
"type": "RETURN",
"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": [],
"organization": "entity1",
"dateCreated": "2016-09-27T14:08:09Z"
} Failure Output
Failure case:response.status = 400
{
"error": "invalid_param_type",
"error_description": "The type of parameter id you provided is not valid for this request."
} Failure case:response.status = 404
{
"error": "not_found",
"error_description": "The returnOperation with the id 7065 doesn't exist."
}63.3 Save
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 | Integer | yes | |
| itemUnitId | The numerical ID unit of items | Integer | 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..."
}63.4 Delete
Service: Delete a return operation
Description: This web service is used in order to delete a return operation object from the database
URL:
https://BASE_URL/api/VERSION/returns/{id}:
https://BASE_URL/api/VERSION/returns/reference/{id}: DELETE
Parameters:
| Name | Description | Type | Required | Examples values |
|---|
| id | Id of the desired operation to delete | Long/String | Yes | 777 |
Success Output
Success case: response.status=200
{
"success": "true",
"success_description": "Instance deleted successfully"
} Failure Output
Failure case:response.status = 400
{
"error": "invalid_param_type",
"error_description": "The type of parameter id you provided is not valid for this request."
} Failure case:response.status = 404
{
"error": "not_found",
"error_description": "The operation with the id 999 doesn't exist."
} Failure case:response.status = 500
{
"error": "server_error",
"error_description": "Oops! Something went wrong..."
}
