Customers

The Customer class is a core component of the Fleet Management SDK, allowing users to create, manage, and retrieve customer data. Customers represent entities that place orders and serve as primary points for delivery or pickup. Each customer has a unique identity and a defined location, ensuring accurate routing and logistics optimization.

Using this API, developers can:

Add new customers to the system.
Retrieve and update customer details such as address, contact information, and custom attributes.
Delete customers when they are no longer needed.
Access historical order data for a customer.

By integrating this API, businesses can streamline their customer management and optimize logistics operations effectively.

Customer Structure

Each customer object consists of the following attributes:

Name	Type	Description	Setter	Getter
Id	`LargeInteger`	Unique identifier for the customer.	❌	✅
Coordinates	`Coordinates`	Coordinates representing the location of the customer.	✅	✅
Address	`AddressInfo`	Address information of the customer.	✅	✅
Alias	`String`	Alias name for the customer.	✅	✅
FirstName	`String`	First name of the customer.	✅	✅
LastName	`String`	Last name of the customer.	✅	✅
Email	`String`	Email address of the customer.	✅	✅
PhoneNumber	`String`	Phone number of the customer.	✅	✅
CustomData	`CustomDataList`	Custom data associated with the customer.	✅	✅

Managing Customers

Creating a Customer

Add a customer to the agenda to create orders for this customer and to use them in optimizations.

Note

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

How it works

Create a vrp::Customer and set the desired fields.
Create a ProgressListener and vrp::Service.
Call the addCustomer() method from the vrp::Service using the vrp::Customer and ProgressListener and wait for the operation to be done.

Example

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

// Define customer 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::Customer` and set the desired fields.
gem::vrp::Customer customer;
customer.setCoordinates(coords);
customer.setAlias("Auteuil");
customer.setAddress(address);
customer.setEmail("example@example.com");
customer.setPhoneNumber("+1234567890");

// Initialize Service and Listener
ProgressListener listener;
gem::vrp::Service service;

// Call the `addCustomer()` method from the `vrp::Service` using the `vrp::Customer` and `ProgressListener` and wait for the operation to be done.
int res = service.addCustomer(&listener, customer);

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

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

Retrieving Customers

There are two ways to retrieve customer data:

a) Get a Customer by ID

Get a certain Customer by ID.

How it works

Create a ProgressListener, a vrp::Service and a vrp::Customer.
Call the getCustomer() method from the vrp::Service using the vrp::Customer from 1.), the ID of the customer that you want to retrieve and the ProgressListener.
Once the operation completes, the vrp::Customer from 1.) will be populated.

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

gem::vrp::Customer customer;
gem::LargeInteger customerId = 0; // Set your customer id  
int res = service.getCustomer(&listener, customer, customerId);

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

  if (listener.IsFinished() && listener.GetError() == gem::KNoError)
      std::cout << "Customer returned successfully" << std::endl;
  else
      std::cout << "Failed to retrive customer: Operation timed out or server returned an error." << std::endl;
}
else
	std::cout << "Failed to send getCustomer request." << std::endl;

b) Get All Customers (with optional filtering)

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

How it works

Create a ProgressListener and vrp::Serviceand a vrp::CustomerList.
Call the getCustomers() method from the vrp::Service and the ProgressListener.
Once the operation completes, the list from 1.) will be populated with customers that match the search criteria.

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

gem::vrp::CustomerList customers;
gem::String searchTerm = "John";
int res = service.getCustomers(listener, customers, searchTerm);

if (res == gem::KNoError)
{   
  WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 20000);
  if (listener.IsFinished() && listener.GetError() == gem::KNoError)
      std::cout << customers.size() << " customers returned successfully" << std::endl;
  else
      std::cout << "Failed to retrive customers: Operation timed out or server returned an error." << std::endl;
}
else
	std::cout << "Failed to send getCustomers request." << std::endl;

Updating a Customer

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

How it works

Create a ProgressListener and a vrp::Service.
Retrieve the customer you want to update (see Get Customer) in a vrp::Customer.
Change the desired fields of the vrp::Customer.
Call the updateCustomer() method from the vrp::Service using the vrp::Customer from 2.) 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);
if (res == gem::KNoError)
{
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 20000);
    if(listener.IsFinished() && listener.GetError() == gem::KNoError)
    {
        // Update an existing customer's information
        customer.setEmail("newemail@example.com");
        customer.setPhoneNumber("+9876543210");
        customer.setAddress(newAddress);

        // Call the update method
        int res = service.updateCustomer(listener, customer);

        if (res == gem::KNoError)
        {   
          WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);
          if (listener.IsFinished() && listener.GetError() == gem::KNoError)
              std::cout << "Customer updated successfully" << std::endl;
          else
              sstd::cout << "Failed to update customer: Operation timed out or server returned an error." << std::endl;
        }
        else
            std::cout << "Failed to send updateCustomer request." << std::endl;
    }
    else
       std::cout << "Failed to fetch customer: Operation timed out or server returned an error." << std::endl;

}
else
    std::cout << "Failed to send getCustomer request." << std::endl;

Deleting a Customer

Customers can be deleted individually or in bulk.

Note

If orders are created based on a customer, deleting the customer will also delete the associated orders.

How it works

Create a ProgressListener and vrp::Service.
Call the deleteCustomer() method from the vrp::Service using the customer object and ProgressListener and wait for the operation to be done.

Example

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

// Remove multiple customers by IDs
LargeIntList customersToDelete = {123, 456, 789};
int res = service.deleteCustomer(listener, customersToDelete);  

if (res == gem::KNoError)
{   
  WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);
  if (listener.IsFinished() && listener.GetError() == gem::KNoError)
      std::cout << "Customer deleted successfully" << std::endl;
  else
      std::cout << "Failed to delete customer: Operation timed out or server returned an error." << std::endl;
}
else
	std::cout << "Failed to send deleteCustomer request." << std::endl;

Retrieving Customer Order History

Get in which optimizations and routes has the customer made order.

How it works

Create a ProgressListener, a vrp::Service and a vrp::CustomerOrderList.
Call the getCustomerOrdersHistory() method from the vrp::Service using the vrp::CustomerOrderList from 1.), the ID of the customer and the ProgressListener.
Once the operation completes, the vrp::CustomerOrderList from 1.) will be populated.

note

A vrp::CustomerOrder is an object that contains an order and a map that contains all the optimizations and routes associated with this order.

ProgressListener listener;
gem::vrp::Service serv;
gem::vrp::Customer customer;
gem::LargeInteger customerId = 0;  // Set your customer id

int res = serv.getCustomer(&listener, customer, customerId);
if (res == gem::KNoError)
{
    WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);

    if (listener.IsFinished() && listener.GetError() == gem::KNoError)
    {
        gem::vrp::CustomerOrderList history;
        res = serv.getCustomerOrdersHistory(&listener, history, customer);

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

            if (!listener.IsFinished() || listener.GetError() != gem::KNoError)
                std::cout << "Failed to get customer orders history: Operation timed out or server returned an error." << std::endl;
        }
        else
            std::cout << "Failed to send getCustomerOrdersHistory request." << std::endl;
    }
    else
       std::cout << "Failed to fetch customer: Operation timed out or server returned an error." << std::endl;

}
else
    std::cout << "Failed to send getCustomer request." << std::endl;

Error Handling

This API returns specific error codes to indicate potential issues. Below is a summary of common errors and how to resolve them:

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

Customer Structure​

Managing Customers​

Creating a Customer​

How it works​

Example​

Retrieving Customers​

a) Get a Customer by ID​

How it works​

b) Get All Customers (with optional filtering)​

How it works​

Updating a Customer​

How it works​

Example​

Deleting a Customer​

How it works​

Example​

Retrieving Customer Order History​

How it works​

Error Handling​

Customer Structure

Managing Customers

Creating a Customer

How it works

Example

Retrieving Customers

a) Get a Customer by ID

How it works

b) Get All Customers (with optional filtering)

How it works

Updating a Customer

How it works

Example

Deleting a Customer

How it works

Example

Retrieving Customer Order History

How it works

Error Handling