Introduction to core API
1. Main definitions
Throughout the pages of this user documentation we will be using some key terminology described in the table below.
Definition | Description |
Schedule | A plan for deliveries (or service tasks) for a specific depot and a day. It includes a list of trips, unscheduled orders, and other relevant metadata. |
Trip | Contains all activities planned for a specific vehicle and its shift. It has a starting and ending location and observes all restrictions that are related to orders, shift and vehicle capacity. Activities can be: load, depart, drive, idle, service, break, reload, arrive. |
Route | A path on the road between two locations. |
Execution plan (or Plan) | Very similar to schedule. The key difference is that the trips have all the activities listed with an estimated duration, e.g. load, idle, drive time. Schedule does not have this detail. For your purposes you should only be using plans. |
Reservation | A request to deliver an item to a specified location during a specified time slot. The system supports four types of reservation: drop-off, pick-up, exchange (pick-up & drop-off), and service. Reservation can have multiple visits/stops at the same or different locations with precedence rules. In the Control Room, reservation is called an order. |
Slot | A specific time window during which delivery will be fulfilled at a specified location. In the system, a time slot is configurable and can be of any length, as long as it starts and ends within the same day. |
Service time | Time needed to serve an order when the vehicle has arrived at the specific location. Alternatively it’s known as time at door, doorstep or dwell time. Service time can be uniquely specified for each order. |
Location | The delivery address in the required format of latitude and longitude. |
Constraints (of reservation) | The number of units specifying how much space, weight, and any other unit the delivery takes up in the vehicle. For example, the number of chilled totes, grams, cubic metres, litres etc. Constraints have to be defined for vehicles and the same used for reservations. |
2. Key APIs for Integrations
Core API is used by clients to integrate their systems into Satalia Delivery. Key API endpoints for the integration to fully function are:
Slots - to retrieve available slots.
Reservations - allows you to create, amend, cancel, find orders.
Plans - to retrieve all activities listed with estimated duration, for example load, idle, drive time.
There are some additional APIs that allow you to get statistics of a schedule, check system health, and more. Full documentation of Core APIs can be found here.
Bare minimum Satalia Delivery and client system interactions:
Slot retrieval and order management: While a customer places an order on the client system, most of the above APIs are being used to transfer placed orders to Delivery. Below is a representation of the customer journey and at which steps the two systems interact as a bare minimum.
Plan retrieval: To allow picking, loading, route execution. Your schedules will go through different stages (for example from draft to pre-final to final). You can read more with this article. After your cut offs you can retrieve built plans and start the execution. Below is an example of how to retrieve plans using Core API.
You can read a step by step guide for Core API interactions with client systems here.