Integration of orders and proof of deliveries with SWAT APIs
Most basic integration with API can be done within an hour. This quick reference guide provides required stapes to achieve:
- Sending bookings (orders) to SWAT system for further optimization
- Receiving proof of delivery for the orders
This guide doesn't include additional more complicated scenarios when the orders can be inserted during live operations (live insertion) that might significantly impact operations flow in the field. In addition, this guide assumes, that all project configuration has been implemented prior (for example, by SWAT support team). This guide is addressing only the bare minimum set of fields required, however we recommend to exercise data mapping prior to building integration together with SWAT support team. This guide also assumes single pickup and multiple drop offs for a single vehicle trip scenario.
Authentication
SWAT API backend supports basic authentication. The customer support team will provide relevant username\password pair.
Sending orders (bookings)
Uploading of orders data into SWAT backend can be done by calling a single API that would internally execute all required steps to validate, geocode, process and prepare orders for optimization. The API request requires specifying a number of parameters for orders:
- Bookings data
- Start time and date of delivery operations (for example, time of the first pickup of the day).
- Project identifier to upload orders to (provided by SWAT support team). We recommend having one project per customer, so used as a way to partition independent operations
- Simulation Template ID. Depending on the complexity of operations, in the simplest case, the value will be constant for all orders for a project. Multiple templates are useful when route optimization and\or delivery setting vary on daily basis.
Uploading and processing may take some time depending on amount of orders to be uploaded. If many (5000+ orders) need to be uploaded, we recommend executing multiple POST requests while retaining the same values for all parameters expect for a orders payload.
Example of the basic payload includes two orders. THe second order doesn't include WGS84 coordinates for the drop off, instead setting 0 values for coordinates, but providing data.dropoff_address which will result in API executing automatic geocoding.
Resolution of the actual happens in the following order of fallbacks pickup\dropoff lat\lon in the booking->*_postal_code in the booking (in case of Singapore)->dropoff\pickup address in booking.data field with explicitly set latitude and longitude taking priority over everything else. Geocoder for the project must be configured, and default threshold for successful resolution is geocoding quality of 0.99.
Optionally, dropoff\pickup_city or\and dropoff\pickup_country can be set in addition to the address to improve quality of geocoding process.
If Operations Locations are used, then coordinates of the operations location will be considered first, unless a booking has explicitly set latitude and longitude which will override location coordinates on Operations Locations object.
POST {base_url}/api/v2/microservices/logisticsapi
{
"simulation_clone_parameters": {
"start_time": "{{date_of_service}}T00:00:00+07:00",
"end_time": "{{date_of_service}}T12:00:00+07:00",
"project_id": {{project_id}}
},
"bookings": [
{
"uid": "aa082b4c-e8b3-4caf-a9f2-aba007bdde63", //UUID of the order (customer generated)
"demand": {
"parcel": 1 // Set capacity required on the vehicle to execute the order.
},
"pickup_location_name": "Hub",
"pickup_location_lat": 13.81722301, // Alternatively, postal address can be used
"pickup_location_lon": 100.5124416,
"min_pickup_time": "{{date_of_service}}T10:00:00+07:00",
"max_pickup_time": "{{date_of_service}}T12:00:00+07:00",
"pickup_service_time": 0,
"dropoff_location_name": "Grocery shop",
"dropoff_location_lat": 13.8353723,
"dropoff_location_lon": 100.5732801,
"min_dropoff_time": "{{date_of_service}}T14:00:00+07:00",
"max_dropoff_time": "{{date_of_service}}T20:00:00+07:00",
"dropoff_service_time": 300 //300 seconds or 5 minutes
},
{
"uid": "aa082b4c-e8b3-4caf-a9f2-aba007bdde66", //UUID of the order (customer generated)
"demand": {
"parcel": 1
},
"pickup_location_name": "Hub",
"pickup_location_lat": 13.81722301,
"pickup_location_lon": 100.5124416,
"min_pickup_time": "{{date_of_service}}T10:00:00+07:00",
"max_pickup_time": "{{date_of_service}}T12:00:00+07:00",
"pickup_service_time": 0,
"dropoff_location_name": "Grocery shop",
"min_dropoff_time": "{{date_of_service}}T14:00:00+07:00",
"max_dropoff_time": "{{date_of_service}}T20:00:00+07:00",
"dropoff_service_time": 300, //300 seconds or 5 minutes
"data": {
"external_id": "EXSS2407120009254",
"customer_name": "Best customer",
"customer_phone": "956123123123",
"pickup_customer_name": "Awesome customer",
"dropoff_customer_name": "Customer to deliver to",
"dropoff_customer_phone": "2434234234234",
"dropoff_address": "255 Some Ave, Some city, some country, 00000",
"dropoff_country": "Some country",
"dropoff_city": "Some city",
"remarks": "s60"
}
}
]
}
On successful upload, the API will return HTTP 200 long with the list of created booking_id.
Retrieving scheduled delivery time of orders and assigned vehicle/driver
There are two ways to retrieve scheduled time (both for pickups and drop offs) of orders depending on the needs of the consumer.
Realtime updates with ETAs and scheduled times
If the consuming application needs to retrieve delivery or pickup information in close to real time, the best way to achieve that is to subscribe to vehicle_arrival or vehicle_arrival_grouped webhook messages. These messages contain both the scheduled time and updated ETA information every few minutes for a single order or all orders for that vehicle. The scope of the messages the consumer can subscribe to is a simulation, meaning all live vehicles within the simulation with a configured webhook will send updates as soon as they go online.
Pulling scheduled times through APIs
Scheduled times can also be pulled on demand without using webhook subscriptions.
Since each booking consists of at least from two nodes, scheduled timestamps are maintained in each node of the booking, and not at the booking level. This ensure flexibility to support flexible management nodes within the booking like partial deliveries or partial pickups.
The following API can be used to retrieve scheduled times for a booking from its nodes:
GET {{base_url}}/api/v2/node?booking={{booking_id}}&simulation={{simulation_id}}
or
GET {{base_url}}/api/v2/node?booking_uid={{booking_uid}}&simulation={{simulation_id}}
{
"meta": {
//....
},
"objects": [
{
//...
"booking_uid": "8e251e2b-e57b-11ed-8252-040903d1bd82",
"id": 3585579,
"node_type": "pickup",
"scheduled_ts": "2023-05-09T20:32:20.700000+00:00",
"uid": "a347f610-2c8f-4a77-8d8a-15d5db86e8a6",
//..
},
{
"booking_uid": "8e251e2b-e57b-11ed-8252-040903d1bd82",
"id": 3585604,
"node_type": "dropoff",
"scheduled_ts": "2023-05-09T20:59:40.510000+00:00",
"uid": "581bc301-21e8-49ad-8ab0-9463ff4ca9f1",
//..
}
]
}
Retrieving assigned vehicle/driver
In SWAT model the vehicle has a one-to-one relation with a driver, which has a one-to-one relation to a username. Each node in a booking once a booking has been assigned to a vehicle, will have a filled assigned_vehicle populated. A vehicles is assigned at a node level, and not at booking level to support handvoer scenarios when the vehicle payload can be transferred to another vehicle.
Using the same examples:
GET {{base_url}}/api/v2/node?booking={{booking_id}}&simulation={{simulation_id}}
or
GET {{base_url}}/api/v2/node?booking_uid={{booking_uid}}&simulation={{simulation_id}}
{
"meta": {
//....
},
"objects": [
{
//...
"booking_uid": "8e251e2b-e57b-11ed-8252-040903d1bd82",
"id": 3585579,
"assigned_vehicle": "/api/v2/vehicle/1733134",
"node_type": "pickup",
"scheduled_ts": "2023-05-09T20:32:20.700000+00:00",
"uid": "a347f610-2c8f-4a77-8d8a-15d5db86e8a6",
//..
},
{
"booking_uid": "8e251e2b-e57b-11ed-8252-040903d1bd82",
"id": 3585604,
"assigned_vehicle": "/api/v2/vehicle/1733134",
"node_type": "dropoff",
"scheduled_ts": "2023-05-09T20:59:40.510000+00:00",
"uid": "581bc301-21e8-49ad-8ab0-9463ff4ca9f1",
//..
}
]
}
then vehicle API can be used to retrieve current information about the vehicle and assigned drivers via driver API
Depending on the service usage, sometimes it may be feasible to use vehicle.service_number as a replacement of the driver name if there is a permanent assignment of a vehicle to a driver. In this case, if the consuming application is using webhook with message_type vehicle_arrival_grouped that contains vehicle_id and vehicle_agent_id retrieve current service number of the vehicle or assigned driver using vehicle API or driver API on webhook arrival to the application.
Receiving order status (proof of delivery)
There are two ways to retrieve order status. The first one in by pulling the order data from SWAT APIs and the second one to subscribe to events emitted each time booking changes.
Requesting booking status (polling booking status)
The following can be used to retrieve the status of booking where booking_uid is the original uid used to submit the booking.
GET {base_url}/api/v2/booking?uid=<booking_uid>
Response will include a booking object that contains its state in state field.
Retrieving booking status through messaging
Webhooks can be used to start receiving message about changes in a booking state. Detailed documentation can be found here. In the simple case, the configuration will be done by SWAT support team, and the consumer will start receiving webhooks based on example provided below where booking_uid is the uid of the original booking.
{
"simulation_id": 172571,
"agent_type": "vehicle",
"message_type": "node_status",
"data": {
"node_uid": "a1d1a6ae-9a0d-40c1-a633-3d6ef05cf7b9",
"status": "completed",
"vehicle_id": 17590317,
"node_id": 48332514,
"node_type": "dropoff",
"booking_uid": "e438ab3d-b33a-572d-a114-0a5490e07f40",
"booking_id": 22151625,
"action_data": null,
"is_confirmation": true
},
"current_sim_ts": "2024-11-16T18:26:22+00:00",
"server_ts": "2024-09-10T04:33:23.364180",
"transmit_to_websocket": false,
"agent_id": "daae025f-f21d-4c65-b901-45e139283667",
"user_id": 57638
}
Providing booking tracking to the end customer
The SWAT API offers a shareable tracking link for booking progress visibility.
This endpoint is unauthenticated and is providing a limited set of information.