SWAT API との注文および配達証明の統合 (Integration of orders and proof of deliveries with SWAT APIs)
API との最も基本的な統合は、1時間以内に完了できます。このクイックリファレンスガイドでは、以下を達成するために必要な手順を提供します。
- さらなる最適化のために SWAT システムへの 予約 (注文) の送信
- 注文の配達証明の受信
このガイドには、ライブ運用中に注文が挿入される場合（ライブ挿入）など、現場での運用フローに大きな影響を与える可能性のある、より複雑なシナリオは含まれていません。さらに、このガイドでは、すべてのプロジェクト構成が事前に（たとえば、SWAT サポートチームによって）実装されていることを前提としています。このガイドでは、最低限必要なフィールドセットのみを扱いますが、SWAT サポートチームと一緒に統合を構築する前にデータマッピングを実行することをお勧めします。このガイドでは、単一の車両トリップシナリオでの単一のピックアップと複数のドロップオフも想定しています。
認証 (Authentication)
SWAT API バックエンドは Basic認証をサポートしています。カスタマーサポートチームは、関連するユーザー名/パスワードのペアを提供します。
注文（予約）の送信 (Sending orders (bookings))
SWAT バックエンドへの注文データのアップロードは、最適化のために注文を検証、ジオコーディング、処理、および準備するために必要なすべ ての手順を内部的に実行する単一の API を呼び出すことで行うことができます。API リクエストでは、注文に対していくつかのパラメーターを指定する必要があります。
- 予約 データ
- 配達運用の開始日時（たとえば、その日の最初のピックアップ時間）。
- 注文をアップロードするプロジェクト識別子（SWAT サポートチームによって提供されます）。顧客ごとに1つのプロジェクトを持つことをお勧めします。これにより、独立した運用を分割する方法として使用されます。
- シミュレーションテンプレート ID。運用の複雑さに応じて、最も単純なケースでは、値はプロジェクトのすべての注文に対して一定になります。複数のテンプレートは、ルート最適化や配達設定が日ごとに異なる場合に役立ちます。
アップロードと処理には、アップロードする注文の量によっては時間がかかる場合があります。多数（5000件以上の注文）をアップロードする必要がある場合は、注文のペイロードを除くすべてのパラメーターの値を同じに保ちながら、複数の POST リクエストを実行することをお勧めします。
基本的なペイロードの例には、2つの注文が含まれています。2番目の注文には、ドロップオフの WGS84 座標が含まれておらず、代わりに座標に0の値を設定していますが、data.dropoff_address を提供することで、API が自動ジオコーディングを実行します。
実際の解決は、予約内のピックアップ/ドロップオフの緯度/経度 -> 予約内の *_postal_code（シンガポールの場合） -> booking.data フィールド内のドロップオフ/ピックアップ住所 のフォールバック順序で行われ、明示的に設定された緯度と経度が他のすべてよりも優先されます。プロジェクトのジオコーダーを構成する必要があり、解決に成功するためのデフォルトのしきい値は、ジオコーディング品質0.99です。
オプションで、住所に加えて dropoff\pickup_city または/および dropoff\pickup_country を設定して、ジオコーディングプロセスの品質を向上させることができます。
運用場所 が使用されている場合、予約に明示的に設定された緯度と経度がない限り、運用場所の座標が最初に考慮されます。明示的に設定された緯度と経度は、運用場所オブジェクトの場所座標を上書きします。
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"
}
}
]
}
アップロードが成功すると、API は作成された booking_id のリストとともに HTTP 200 を返します。
注文の予定配達時間と割り当てられた車両/ドライバーの取得 (Retrieving scheduled delivery time of orders and assigned vehicle/driver)
コンシューマーのニーズに応じて、注文の予定時間（ピックアップとドロップオフの両方）を取得する方法は2つあります。
ETA と予定時間によるリアルタイム更新 (Realtime updates with ETAs and scheduled times)
消費アプリケーションが配達またはピックアップ情報をほぼリアルタイムで取得する必要がある場合、それを達成する最善の方法は、vehicle_arrival または vehicle_arrival_grouped ウェブフックメッセージ をサブスクライブすることです。これらのメッセージには、単一の注文またはその車両のすべての注文について、数分ごとに予定時間と更新された ETA情報の両方が含まれています。コンシューマーがサブスクライブできるメッセージの範囲はシミュレーションです。つまり、ウェブフックが構成されたシミュレーション内のすべてのライブ車両は、オンラインになるとすぐに更新を送信します。
API を介した予定時間の取得 (Pulling scheduled times through APIs)
予定時間は、ウェブフックサブスクリプションを使用せずにオンデマンドで取得することもできます。
各予約は少なくとも2つの ノード で構成されているため、予定のタイムスタンプは予約レベルではなく、予約の各ノードで維持されます。これにより、部分的な配達や部分的なピックアップなどの予約内の柔軟な管理ノードをサポートする柔軟性が確保されます。
次の API を使用して、ノード から予約の 予定時間 を取得できます。
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)
SWAT モデルでは、車両はドライバーと1対1の関係にあり、ドライバーはユーザー名と1対1の関係にあります。予約が車両に割り当てられると、予約内の各ノードには、assigned_vehicle が入力されます。車両の積載物を別の車両に転送できるハンドオーバーシナリオをサポートするために、車両は予約レベルではなく、ノードレベルで割り当てられます。
同じ例を使用すると：
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",
//..
}
]
}
次に、vehicle API を使用して、車両に関する現在の情報を取得し、driver API を介して割り当てられたドライバーを取得できます。
サービスの使用法によっては、車両がドライバーに永続的に割り当てられている場合、vehicle.service_number をドライバー名の代わりに使用することが可能な場合があります。この場合、消費アプリケーションが vehicle_id と vehicle_agent_id を含む vehicle_arrival_grouped というメッセージタイプを持つウェブフックを使用している場合、アプリケーションへのウェブフック到着時に vehicle API または driver API を使用して、車両または割り当てられたドライバーの現在のサービス番号を取得します。
注文ステータスの受信（配達証明） (Receiving order status (proof of delivery))
注文ステータスを取得するには2つの方法があります。1つ目は SWAT API から注文データをプルする方法、2つ目は予約が変更されるたびに発行されるイベントをサブスクライブする方法です。
予約ステータスのリクエスト（予約ステータスのポーリング） (Requesting booking status (polling booking status))
以下を使用して、booking_uid が予約の送信に使用された元の uid である予約のステータスを取得できます。
GET {base_url}/api/v2/booking?uid=<booking_uid>
応答には、state フィールドにその状態を含む予約オブジェクトが含まれます。
メッセージングによる予約ステータスの取得 (Retrieving booking status through messaging)
ウェブフックを使用して、予約状態の変更に関するメッセージの受信を開始できます。詳細なドキュメントは こちら にあります。単純なケースでは、構成は SWAT サポートチームによって行われ、コンシューマーは、booking_uid が元の予約の uid である以下の例に基づいてウェブフックの受信を開始します。
{
"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)
SWAT API は、予約の進捗状況を可視化するための共有可能な 追跡リンク を提供します。
このエンドポイントは認証されておらず、限られた情報のセットを提供しています。