Orders

_|

The Order class provides functionalities for managing orders within the VRP system. An order represents a pickup or delivery request and contains information such as location, customer details, time constraints, and priority settings. The API allows users to:

• Create new orders with relevant details.
• Retrieve existing orders by ID or list all orders.
• Update order information such as address, time window, or priority.
• Delete orders when no longer needed.

Order Structure

Each order object consists of the following attributes:

Name	Type	Description	Setter	Getter
Id	LargeInteger	Unique identifier for the order.	❌	✅
Coordinates	Coordinates	Geographical coordinates of the order.	✅	✅
Address	AddressInfo	Address information of the order.	✅	✅
Customer	ICustomer	Customer who placed the order.	✅	✅
Alias	String	Alias name of the order.	✅	✅
FirstName	String	First name associated with the order.	✅	✅
LastName	String	Last name associated with the order.	✅	✅
PhoneNumber	String	Phone number associated with the order.	✅	✅
Type	EOrderType	Type of the order. Possible values: • OT_PickUp (0): Order is for pickup. • OT_Delivery (1): Order is for delivery.	✅	✅
TimeWindow	std::pair<const Time*, const Time*>	Time window for delivery or pickup.	✅	✅
ServiceTime	unsigned int	Service time at the delivery or pickup location (in seconds).	✅	✅
NumberOfPackages	unsigned int	Number of packages to be delivered or picked up.	✅	✅
Weight	float	Weight of the goods to be delivered or picked up.	✅	✅
Cube	float	Cubic volume of the goods to be delivered or picked up.	✅	✅
Revenue	float	Revenue associated with the order.	✅	✅
Priority	EOrderPriority	Priority of the order. Possible values: • OP_Low (0): Low priority. • OP_High (1): High priority.	✅	✅
Status	EOrderStatus	Status of the order. Possible values: • OS_Unscheduled (0): Order is not part of a route. • OS_Scheduled (1): Order is part of a route.	❌	✅
State	EOrderState	State of the order. Possible values: • OS_Failed (-2): The order has encountered a failure or error during the delivery or pick-up process. • OS_Rejected (-1): The order has been rejected and will not be processed. • OS_Completed (0): The order has been successfully completed. • OS_New (1):The order has not yet been assigned to any route. • OS_OnRoute (2): The order is currently in transit or en route to its destination. • OS_Servicing (3): The order is in the process of being serviced or fulfilled. • OS_Skipped (4): The order has been skipped by the driver.	❌	✅
CreationTime	Time	Creation time of the order.	❌	✅
DepotId	LargeInteger	Depot ID to which the order belongs.	✅	✅
CustomData	CustomDataList	Custom data associated with the order.	✅	✅

Managing Orders

Creating an Order

Orders must be created before they can be processed in optimizations.

Note

If the operation is successful, the order will have an id assigned; which can be retrieved using the method order.getId(), if not, an error code is returned which can be interpreted as mentioned at the end of the page.

How it works

1. Create a vrp::Order and set the desired fields.
2. Create a ProgressListener and vrp::Service.
3. Call the addOrder() method from the vrp::Service using the vrp::Order and ProgressListener and wait for the operation to be done.

Example

ProgressListener listener;
gem::vrp::Service service;

// Retrieve an existing customer by id
gem::vrp::Customer customer;
gem::LargeInteger customerId = 0; // Set your customer id  
int res = service.GetCustomer(&listener, customer, customerid);
WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 20000);

// Define order coordinates
gem::Coordinates coords(48.853543, 2.265137);

// Define order address
gem::AddressInfo address;
address.setField("France", gem::EAddressField::Country);
address.setField("Île-de-France", gem::EAddressField::County);
address.setField("Paris", gem::EAddressField::City);
address.setField("75016", gem::EAddressField::PostalCode);
address.setField("Rue du Dr Blanche", gem::EAddressField::StreetName);
address.setField("38", gem::EAddressField::StreetNumber);

// Create a `vrp::Order` and set the desired fields.
gem::vrp::Order order;
order.setCustomer(customer);
order.setAlias("Package");
order.setFirstName("John");
order.setLastName("Doe");
order.setPhoneNumber("+1234567890");
order.setCoordinates(coords);
order.setAddress(address);
order.setNumberOfPackages(5);
order.setWeight(12.5);
order.setCube(1.2);
order.setPriority(gem::vrp::EOrderPriority::OP_High);
order.setType(gem::vrp::EOrderType::OT_PickUp);

// Call the addOrder method
int res = service.addOrder(&listener, order);

if (res == gem::KNoError)
{
    // Wait for completion
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);    

    // Check operation success
    if (listener.IsFinished() && listener.GetError() == gem::KNoError) 
        std::cout << "Order added successfully. ID: " << order.getId() << std::endl;
    else
        std::cout << "Failed to add order: Operation timed out or server returned an error." << std::endl;
}
else
  	std::cout << "Failed to send addOrder request." << std::endl;

Retrieving Orders

There are two ways to retrieve order data:

a) Get an Order by ID

Get a certain Order by ID.

How it works

1. Create a ProgressListener, a vrp::Service and a vrp::Order.
2. Call the getOrder() method from the vrp::Service using the vrp::Order from 1.), the ID of the order that you want to retrieve and the ProgressListener.
3. Once the operation completes, the vrp::Order from 1.) will be populated.

// Retrieve a specific order by id
ProgressListener listener;
gem::vrp::Service service;

gem::vrp::Order order;
LargeInteger orderId = 0; // Set your order id  
int res = service.getOrder(listener, order, orderId);
if (res == gem::KNoError)
{
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);
    if (listener.IsFinished() && listener.GetError() == gem::KNoError)
        std::cout << "Order returned successfully" << std::endl;
    else
        std::cout << "Failed to retrive order: Operation timed out or server returned an error." << std::endl;
}
else
  	std::cout << "Failed to send getOrder request." << std::endl;

b) Get All Orders (with optional filtering)

Returns all orders of the API user (which contain the search term).

How it works

1. Create a ProgressListener and vrp::Serviceand a vrp::OrderList.
2. Call the getOrders() method from the vrp::Service and the ProgressListener.
3. Once the operation completes, the list from 1.) will be populated with orders that match the search criteria.

// Retrieve all orders, optionally filtering by a search term
ProgressListener listener;
gem::vrp::Service service;

gem::vrp::OrderList orders;
gem::String searchTerm = "John";
int res = service.getOrders(listener, orders, searchTerm);
if (res == gem::KNoError)
{
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 20000);
    if (listener.IsFinished() && listener.GetError() == gem::KNoError)
        std::cout << orders.size() << " orders returned successfully" << std::endl;
    else
        std::cout << "Failed to retrive orders: Operation timed out or server returned an error." << std::endl;
}
else
  	std::cout << "Failed to send getOrders request." << std::endl;

Updating an Order

Saves the updates made to a order. Orders can be updated with new addresses, contact details, or other relevant information.

Note

Once an order is created, the customer associated with the order cannot be changed.

How it works

1. Create a ProgressListener and a vrp::Service.
2. Retrieve the order you want to update (see Get Order) in a vrp::Order.
3. Change the desired fields of the vrp::Order.
4. Call the updateOrder() method from the vrp::Service using the vrp::Order from 2.) and ProgressListener and wait for the operation to be done.

Example

ProgressListener listener;
gem::vrp::Service service;

// Retrieve an existing order by id
gem::vrp::Order order;
LargeInteger orderId =  0; // Set your order id  
int res = service.getOrder(listener, order, orderId);
if (res == gem::KNoError)
{
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 20000);

    if(listener.IsFinished() && listener.GetError() == gem::KNoError)
    {
        // Update order properties
        order.setNumberOfPackages(10);
        order.setWeight(25.0);
        order.setPriority(gem::vrp::EOrderPriority::OP_High);

        // Save the updated details
        res = service.updateOrder(listener, order);
        if (res == gem::KNoError)
        {
            WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);
            if (listener.IsFinished() && listener.GetError() == gem::KNoError)
                std::cout << "Order was updated successfully." << std::endl;
            else
                std::cout << "Failed to update order: Operation timed out or server returned an error." << std::endl;
        }
        else
            std::cout << "Failed to send updateOrder request." << std::endl;
    }
    else
        std::cout << "Failed to fetch order: Operation timed out or server returned an error." << std::endl;
}
else
    std::cout << "Failed to send getOrder request." << std::endl;

Deleting an Order

Orders can be deleted individually or in bulk.

How it works

1. Create a ProgressListener and vrp::Service.
2. Call the deleteOrder() method from the vrp::Service using the order object and ProgressListener and wait for the operation to be done.

Note

When orders are deleted, they will also be removed from any optimizations they were used in.

ProgressListener listener;
gem::vrp::Service service;

// Remove multiple orders by IDs
LargeIntList ordersToDelete = {101, 202, 303};
int res = service.deleteOrder(listener, ordersToDelete);
if (res == gem::KNoError)
{
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);
    if (listener.IsFinished() && listener.GetError() == gem::KNoError)
        std::cout << "Order deleted successfully" << std::endl;
    else
        std::cout << "Failed to delete order: Operation timed out or server returned an error." << std::endl;
}
else
      std::cout << "Failed to send deleteOrder request." << std::endl;

Error Handling

The API provides specific error codes to identify potential issues. Below is a summary of common errors and their solutions:

| Error Code | Description | Solution | ||-|-| | KInvalidInput | Missing required fields or invalid data. | Ensure all mandatory fields are filled. | | KNotFound | The specified order ID does not exist. | Verify that the correct order ID is used. | | KInternalAbort | Server-side issue or unexpected error. | Retry the request or check API status. |