Order
Overview
The Order RestAPI allows you to manage orders within the Fleet Management system. You can create, retrieve, update, and delete order records. This RestAPI supports filtering, sorting, and pagination to help manage large datasets efficiently.
Order Object Fields
Field | Type | Description |
---|---|---|
id | Integer | Unique identifier for the order. |
customerInfo | Object | Customer details linked to the order. Cannot be changed once saved. |
location | Object | Location details of the order. |
alias | String | Short name or identifier for the order. |
firstName | String | First name of the customer. |
lastName | String | Last name of the customer. |
address | Object | Address details of the order. |
phoneNumber | String | Contact number for the order. |
customData | String | Additional order-specific data. |
type | Integer | Order type: 0 - Pickup1 - Delivery |
status | Integer | Order status: 0 - Unscheduled1 - Scheduled |
state | Integer | Order state: 0 - None1 - On Route2 - Servicing3 - Rejected4 - Completed5 - Failed |
priority | Integer | Order priority: 0 - Low1 - High |
numberOfPackages | Integer | Number of packages in the order. |
weight | Float | Total weight of the order. |
cube | Float | Total volume of the order. |
timeWindow | Object | Time window during which the order should be serviced. |
serviceTime | Integer | Time (in seconds) required to complete the order. |
revenue | Float | Revenue associated with the order. |
depotId | Integer | Depot associated with the order. |
creationTimestamp | Integer | Timestamp of when the order was created. |
Endpoints
1. Create Order
Description: Adds a list of orders to the database.
- Method:
POST
- Endpoint:
/orders
- Headers:
Authorization: YOUR_API_KEY
Content-Type: application/json
- URL:
https://fleetmanagement.magiclaneapis.com/v1/orders
- Returned error codes:
Error Code | Description |
---|---|
200 Successful | Successful operation. |
400 Bad Request |
|
401 Unauthorized | API key is missing or invalid. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
Note
If the operation is successful, the Order
object will have its id
field populated. If the operation fails, an error code is returned, which can be interpreted as described in the Returned error codes section.
Example:
- Request Body:
[
{
"customerId": 1838721,
"location": [
48.870852,
2.356148
],
"alias": "Magic Order",
"firstName": "Magic",
"lastName": "Order",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555018",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 3,
"weight": 5.1,
"cube": 2.5,
"revenue": 12,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
},
{
"customerId": 1838722,
"location": [
48.827865,
2.379216
],
"alias": "Magic Order2",
"firstName": "Magic2",
"lastName": "Order2",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555019",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 2,
"weight": 4.5,
"cube": 1.1,
"revenue": 16,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
}
]
- Response Body: (error code
200
)
{
"orders": [
{
"id": 879887,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838721,
"alias": "Magic Customer",
"firstName": "Magic",
"lastName": "Customer",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.870852,
2.356148
],
"alias": "Magic Order",
"firstName": "Magic",
"lastName": "Order",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555018",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 3,
"weight": 5.1,
"cube": 2.5,
"revenue": 12,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
},
{
"id": 879888,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838722,
"alias": "Magic Customer2",
"firstName": "Magic",
"lastName": "Customer2",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer2@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.827865,
2.379216
],
"alias": "Magic Order2",
"firstName": "Magic2",
"lastName": "Order2",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555019",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 2,
"weight": 4.5,
"cube": 1.1,
"revenue": 16,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
}
]
}
2. Get All Orders
Description: Fetches a list of all orders with optional filtering.
- Method:
GET
- Endpoint:
/orders
- Headers:
Authorization: YOUR_API_KEY
- URL:
https://fleetmanagement.magiclaneapis.com/v1/orders
- Query Parameters:
search
(string, optional) – General search term across orders.id
(string, optional) – Filter by order ID (id=value:exact
for exact match).alias
(string, optional) – Filter by order alias (alias=value:exact
for exact match).firstName
(string, optional) – Filter by first name (firstName=value:exact
for exact match).lastName
(string, optional) – Filter by last name (lastName=value:exact
for exact match).location
(string, optional) – Filter by location (location=value:exact
for exact match).country
(string, optional) – Filter by country (country=value:exact
for exact match).state
(string, optional) – Filter by state (state=value:exact
for exact match).county
(string, optional) – Filter by county (county=value:exact
for exact match).city
(string, optional) – Filter by city (city=value:exact
for exact match).postalCode
(string, optional) – Filter by postal code (postalCode=value:exact
for exact match).streetName
(string, optional) – Filter by street name (streetName=value:exact
for exact match).streetNumber
(string, optional) – Filter by street number (streetNumber=value:exact
for exact match).extra
(string, optional) – Filter by extra address value (extra=value:exact
for exact match).phoneNumber
(string, optional) – Filter by phone number (phoneNumber=value:exact
for exact match).type
(string, optional) – Filter by order type.status
(string, optional) – Filter by order status.orderState
(string, optional) – Filter by order state.timeWindowStart
(string, optional) – Filter by time window start (timeWindowStart=value:exact
for exact match).timeWindowEnd
(string, optional) – Filter by time window end (timeWindowEnd=value:exact
for exact match).creationTime
(string, optional) – Filter by creation time (creationTime=value:exact
for exact match).priority
(string, optional) – Filter by order priority.customData
(string, optional) – Filter by custom data (customData=value:exact
for exact match).customerId
(string, optional) – Filter by customer ID (customerId=value:exact
for exact match).depotId
(string, optional) – Filter by depot/misc location ID (depotId=value:exact
for exact match).sort
(string, optional) – Sorting format:column1:asc/desc,column2:asc/desc
- Available columns:
id, alias, firstName, lastName, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra, phoneNumber, type, timeWindowStart, timeWindowEnd, creationTime, serviceTime, priority, customData, customerId, depotId
- Available columns:
includeColumns
(string, optional) – Specify which columns to include.- Available columns:
id, alias, firstName, lastName, phoneNumber, type,timeWindowStart, timeWindowEnd, serviceTime, creationTime, packages, revenue, cube, weight, priority, status, orderState, customerId, depotId, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra
- Available columns:
page
(integer, optional) – Page number for pagination.per_page
(integer, optional) – Number of items per page.
- Returned error codes:
Error Code | Description |
---|---|
200 Successful | Successful operation. |
400 Bad Request | The values sent for page and per_page parameters are incorrect; should be greater than 0. |
401 Unauthorized | API key is missing or invalid. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
Example:
- Response Body: (error code
200
)
{
"orders": [
{
"id": 879887,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838721,
"alias": "Magic Customer",
"firstName": "Magic",
"lastName": "Customer",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.870852,
2.356148
],
"alias": "Magic Order",
"firstName": "Magic",
"lastName": "Order",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555018",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 3,
"weight": 5.1,
"cube": 2.5,
"revenue": 12,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
},
{
"id": 879888,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838722,
"alias": "Magic Customer2",
"firstName": "Magic",
"lastName": "Customer2",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer2@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.827865,
2.379216
],
"alias": "Magic Order2",
"firstName": "Magic2",
"lastName": "Order2",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555019",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 2,
"weight": 4.5,
"cube": 1.1,
"revenue": 16,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
}
]
}
3. Get an Order by ID
Description: Retrieves a specific order by ID.
- Method:
GET
- Endpoint:
/orders/{id}
- Headers:
Authorization: YOUR_API_KEY
- URL:
https://fleetmanagement.magiclaneapis.com/v1/orders/{id}
- Path Parameter:
id
(integer, *required) - The unique order ID.
- Returned error codes:
Error Code | Description |
---|---|
200 Successful | Successful operation. |
400 Bad Request | Invalid input or missing required fields. |
401 Unauthorized | API key is missing or invalid. |
404 Not Found | Order not found in database. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
Example:
- Response Body: (error code
200
)
{
"id": 879887,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838721,
"alias": "Magic Customer",
"firstName": "Magic",
"lastName": "Customer",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.870852,
2.356148
],
"alias": "Magic Order",
"firstName": "Magic",
"lastName": "Order",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555018",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 3,
"weight": 5.1,
"cube": 2.5,
"revenue": 12,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
}
4. Update an Order
Description: Updates an existing order record.
- Method:
PUT
- Endpoint:
/orders/{id}
- Headers:
Authorization: YOUR_API_KEY
Content-Type: application/json
- URL:
https://fleetmanagement.magiclaneapis.com/v1/orders/{id}
- Path Parameter:
id
(integer, *required) - The unique order ID.
- Query Parameter:
-autoAssignDepot
(integer, optional) (0
: (default) - No depot will be auto assigned to the current order.1
: The closest depot (depending on time) will be assigned to the current order.) - Returned error codes:
Error Code | Description |
---|---|
200 Successful | Successful operation. |
400 Bad Request |
|
401 Unauthorized | API key is missing or invalid. |
404 Not Found | Order not found in database. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
Example:
- Request Body:
{
"id": 879887,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838721,
"alias": "Magic Customer",
"firstName": "Magic",
"lastName": "Customer",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.870852,
2.356148
],
"alias": "Magic Order",
"firstName": "Magic",
"lastName": "Order",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555018",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 3,
"weight": 5.1,
"cube": 2.5,
"revenue": 12,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
}
- Response Body: (error code
200
)
{
"id": 879887,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838721,
"alias": "Magic Customer",
"firstName": "Magic",
"lastName": "Customer",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.870852,
2.356148
],
"alias": "Magic Order",
"firstName": "Magic",
"lastName": "Order",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555018",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 3,
"weight": 5.1,
"cube": 2.5,
"revenue": 12,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
}
5. Delete Orders
Description: Deletes orders from the system.
- Method:
DELETE
- Endpoint:
/orders
- Headers:
Authorization: YOUR_API_KEY
Content-Type: application/json
- URL:
https://fleetmanagement.magiclaneapis.com/v1/orders
- Returned error codes:
Error Code | Description |
---|---|
200 Successful | Successful operation. |
400 Bad Request | Invalid input or missing required fields. |
401 Unauthorized | API key is missing or invalid. |
404 Not Found | Can't delete orders because at least one of them does not exist or is used in another operation. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
Example:
- Request Body:
{
"ids": [78910, 78911]
}
- Response Body: (error code
200
)
{
"message": "Operation done successfully",
}