The final article in our EasyCargo API series provides a comprehensive, step-by-step guide to load planning using the API. We’ll walk you through the entire process from the initial setup to obtaining loading plan reports, demonstrating the API interactions and their corresponding representation in the EasyCargo interface. This guide builds on fundamental concepts while introducing advanced functionalities for optimizing cargo shipment planning operations.

Before diving into the implementation details, build a solid foundation with the following two essential resources. Our comprehensive API Theory Guide covers all of the fundamentals you need to know about APIs, while our Practical Guide to API Requests and Testing with ReqBin walks you through setting up an API client as well as testing endpoints. Together, these articles establish essential groundwork and provide crucial context for the topics covered in this article.

Step-by-step load planning process

To use the following API requests, you’ll need to include an authentication token in your request header. You can find detailed authentication procedures in our previous article. To obtain an authentication token, you must have an API key associated with your user account. Contact our support team to request an API key. Please note that authentication tokens are only valid for 1.5 hours and will expire afterward for security purposes.

Setting Up User Access

The first and one of the most crucial steps in our load planning process is to create an account, for example, for warehouse personnel. Using the /api/v1/users endpoint, you can create new user accounts with specific permissions. You need to provide certain user details, as shown in the API request below. The EasyCargo panel immediately reflects this addition, confirming the user’s access to the company account. This streamlined process properly ensures both access management and security controls for your load planning operations while maintaining operational efficiency.

In the code snippet below, we will send a request to the /api/v1/users endpoint with a body containing details about a user for whom we want to create an account. We want to specify a first name, last name, email address for signing in, and a user role. The user role can either be an administrator (represented by a 1 in the request body) or a regular user (represented by a 2).

See the full template of the API request: https://reqbin.com/duacb1ye

Defining Cargo Spaces

Before initiating any load planning operations, defining cargo spaces is essential. The /api/v1/cargospaces endpoint enables you to specify container dimensions where items will be placed. Each cargo space definition requires important specifications including length, width, height, and maximum load capacity. Currently, the API only supports container-type cargo spaces for user creation, with the potential to support other types of cargo spaces in future updates. The system validates all of the specifications to ensure that they meet operational requirements and safety standards. Once defined, the cargo space appears in the EasyCargo interface, confirming a successful creation and enabling immediate use for load planning.

In the code snippet below, we will send a request to the /api/v1/cargospaces endpoint with a body containing details about the container, with the goal of creating a new cargo space. We specify the name, width, height, length, and maximum loading weight. We will also indicate the measurement system used to define the values (1 for the metric system and 2 for the imperial system) and the type of cargo space, which is set to 1, representing a container. As mentioned earlier, only this type of cargo space is supported.

See the full template of the API request: https://reqbin.com/8ieqp8ey

Managing Items to be Loaded

With the cargo spaces defined, the next step is to create a new shipment through the /api/v1/shipment-inputs endpoint. This process involves specifying both the shipment details and the individual items to be loaded. Each item requires comprehensive attributes including precise dimensions, weight specifications, handling requirements, and stacking constraints. The EasyCargo interface provides a visual confirmation of successful shipment creation, displaying all items and their specifications. This detailed input ensures accurate load planning and optimal space utilization in subsequent steps while maintaining compliance with safety regulations and handling protocols.

In the code snippet below, we will create a new shipment with 82 pieces of one type of item using the /api/v1/shipment-inputs endpoint. In the request body, we will specify the shipment name, measurement system, and stored items. For items, we can specify their details like measurements and packing restrictions. In this example, we will keep the goods in a priority group called Berlin, as this is where we want to deliver refrigerators. We will allow them to be rotatable and stackable when packing them in the cargo space. Keep in mind that it’s currently not possible to choose the color or control whether the item label is displayed or not through the API.

See the full template of the API request: https://reqbin.com/ozixloob

Load Plan Optimization Process

Once the shipment details are established, EasyCargo’s optimization engine takes over to generate efficient loading plans. While triggering the optimization process directly through the API is currently under development, users can access this functionality through the EasyCargo interface by clicking the Load button. EasyCargo considers multiple factors including weight distribution, the loading sequence, and delivery requirements to create optimal arrangements. After the initial optimization, users retain the flexibility to make manual adjustments or modify cargo space selections, ensuring the final plan meets specific operational requirements and constraints while maximizing efficiency.

Generating Loading Plan Reports

After finalizing the loading plan, comprehensive documentation becomes available through the /api/v1/shipment-reports/{id} endpoint. These detailed load plan reports encompass loading arrangements, 3D visualizations, and precise loading instructions. Each report provides critical metrics including space utilization, weight distribution data, and specific handling guidelines for loading personnel. The system generates both interactive 3D models and downloadable PDF instructions, ensuring accessibility for all stakeholders such as warehouse employees and your customers. These reports serve as essential references during the physical loading process, helping maintain consistency between planned and actual loading arrangements. Check out the shipment report for full details.

In the code snippet below, we will retrieve all of the shipment report details using the /api/v1/shipment-report/{id} endpoint. First, we need to get the shipment report ID by sending a GET request to /api/v1/shipments. Take the shipment report ID from this response and include it in the URL path of your next request (/api/v1/shipment-report/{id}). The response will contain all of the details that you see in the image below in the printable PDF report.

See the full template of the API request: https://reqbin.com/ust8mrq2

Sharing and Collaborating

The final phase involves distributing the loading plan information to relevant stakeholders through the /api/v1/shipments endpoint. This functionality provides access to comprehensive shipment details and associated reports, including interactive 3D representations of the loading plan. Stakeholders can access the plan through a public URL, enabling real-time visualization and verification of the loading arrangement. This collaborative approach ensures all participants in the loading process have immediate access to necessary information, facilitating efficient coordination and accurate implementation of the loading plan. You can access the public URL of the loading plan in EasyCargo to view the placement of goods yourself.

In the code snippet below, we will retrieve all of the details for our previously created shipment using the /api/v1/shipments/{id} endpoint. To get the shipment ID, first send a GET request to /api/v1/shipments. Once you have identified your shipment ID, make a GET request to /api/v1/shipments/{id} to receive comprehensive shipment details, including the public link, shipment report link, and other information shown below.

See the full template of the API request: https://reqbin.com/y5p3zysj

In conclusion, the impact of APIs on the IT industry cannot be overstated – they have become fundamental building blocks of modern software architecture and business operations. The EasyCargo API exemplifies how well-designed interfaces can streamline complex logistics operations while maintaining precision and efficiency. We hope this comprehensive series has provided valuable insights into leveraging the EasyCargo API for your logistics needs. Whether you’re new to APIs or an experienced developer, the possibilities for integration are extensive. For a personalized consultation on implementing EasyCargo into your operations, reach out to us through our contact form. Our team is ready to help you explore our solution to match your specific requirements.